DfCustomCodeManager: guia completo

O DfCustomCodeManager traz uma resposta simples a um problema universal das lojas Shopware: onde colocar, como versionar e como proteger o CSS e o JavaScript personalizado que se acaba sempre por acrescentar a um tema? A extensão oferece um editor de código integrado na administração, um sistema de contentores que agrupam snippets SCSS ou JavaScript, e sobretudo uma injeção direta na compilação do tema através dos eventos nativos do Shopware. Consequência: nenhum ficheiro servido a mais, nenhum pedido HTTP adicional para o visitante, e os seus snippets SCSS herdam automaticamente as variáveis e mixins do tema ativo. Este guia cobre a instalação, a configuração, a criação de contentores e snippets, a compilação do tema, o histórico de versões, o modo seguro, a biblioteca de presets, a importação e exportação e a resolução de problemas.

Instalação

1. Transfira o arquivo DfCustomCodeManager-1.0.0.zip a partir da sua área DataFirefly.
2. Instale-o em Administração → Extensões → As minhas extensões → Carregar uma extensão, ou descomprima a pasta DfCustomCodeManager em custom/plugins/.
3. Execute a instalação e a ativação:

   bin/console plugin:refresh
   bin/console plugin:install --activate DfCustomCodeManager
   bin/console cache:clear

4. Na instalação, a extensão cria as suas 4 tabelas (df_ccm_container, df_ccm_container_sales_channel, df_ccm_snippet, df_ccm_snippet_version) e regista os seus subscribers nos eventos de compilação do tema.
5. Recompile o tema para que tenha a extensão em conta:

   bin/console theme:compile

Onde encontrar a extensão na administração

Depois da ativação, aparece uma entrada Custom Code Manager no menu Catálogos da administração (ícone laranja, posição 100). É o ecrã central: lista dos contentores, pesquisa, filtros, e as ações globais Importar, Exportar, Presets e Compilar o tema. Toda a configuração de baixo nível (modo seguro, minificação, banner) faz-se em Extensões → As minhas extensões → DfCustomCodeManager → ⋯ → Configurar.

Configuração da extensão

O cartão de configuração da extensão no Shopware expõe três interruptores simples mas essenciais:

• Modo seguro (DfCustomCodeManager.config.safeMode): desativado por predefinição. Quando está ativo, todos os contentores são ignorados na próxima compilação, como se estivessem todos inativos. É a rede de segurança descrita mais abaixo.
• Minificar JS (DfCustomCodeManager.config.minifyJs): minificação básica do JavaScript injetado. Útil em produção, a deixar desativada em desenvolvimento para poder ler os snippets no bundle compilado.
• Acrescentar um banner (DfCustomCodeManager.config.addBanner): acrescenta um comentário /* DataFirefly Custom Code Manager */ no início do código injetado. Prático para localizar rapidamente os seus snippets no bundle compilado.

O modelo mental: contentores e snippets

A extensão organiza-se em dois níveis:

• Um contentor é um agrupamento lógico: Promoção de verão 2026, GTM analytics, Modo escuro opcional, Teste A/B do botão CTA, e por aí fora. Cada contentor tem um nome, uma descrição, uma prioridade, um interruptor de ativo ou inativo e um âmbito por canal de venda.
• Um snippet é uma unidade de código dentro de um contentor. Tipo SCSS ou JavaScript, nome, código, prioridade, interruptor de ativo ou inativo, notas em Markdown, e um interruptor para ativar ou não a injeção das variáveis do tema.

Um contentor pode conter vários snippets de tipos misturados. É útil para agrupar logicamente os snippets que andam juntos: por exemplo um contentor Modo escuro opcional com um snippet SCSS para os estilos e um snippet JavaScript para a alternância da classe em html.

Criar o primeiro contentor

1. A partir de Catálogos → Custom Code Manager, clique em Novo contentor no canto superior direito.
2. Dê-lhe um nome expressivo (por exemplo Promoção de verão 2026: header fixo e selo).
3. Defina a prioridade (deixe 0 por predefinição, suba o valor se quiser que este contentor seja injetado mais tarde no bundle e portanto sobreponha outros estilos).
4. (Opcional) Ative Limitar a canais de venda e selecione um ou vários canais. Se a opção estiver desativada, o contentor aplica-se a todos os canais.
5. Preencha uma descrição (notas internas, contexto, ticket associado); nunca será injetada no bundle.
6. Guarde. Está agora pronto para acrescentar snippets.

Acrescentar um snippet SCSS ou JavaScript

No cartão Excertos de código da página do contentor, dois botões: Acrescentar SCSS e Acrescentar JavaScript. Cada snippet acrescentado aparece como um cartão com:

• Um selo SCSS (info) ou JS (warning).
• Um campo de nome (visível apenas em edição).
• Um interruptor de ativo ou inativo.
• Um botão Validar a sintaxe (✓).
• Um botão Histórico (relógio), disponível a partir da primeira gravação.
• Um botão Duplicar.
• Um botão Eliminar.
• Um editor de código com coloração sintática adaptada ao tipo.
• Uma zona de Notas em Markdown para documentar o que o snippet faz.

Compilar o tema

Um snippet guardado ainda não está visível no storefront enquanto o tema não for recompilado. Duas formas de o fazer:

• A partir da administração, botão Compilar o tema (no canto superior direito da lista, ou na página do contentor). Uma notificação confirma o fim da operação.
• A partir da linha de comandos:

  bin/console theme:compile

Na compilação, a extensão escuta três eventos do Shopware e injeta aí os seus snippets:

• ThemeCompilerEnrichScssVariablesEvent: capta o mapa das variáveis SCSS do tema ativo. É o que permite aos seus snippets SCSS usar $sw-color-brand-primary, $font-family-base e outras.
• ThemeCompilerConcatenatedStylesEvent: concatena o seu SCSS compilado no fim da folha de estilos principal.
• ThemeCompilerConcatenatedScriptsEvent: concatena o seu JavaScript no fim do bundle de scripts principal.

Resultado: zero pedidos HTTP adicionais servidos ao visitante, e o seu código passa por toda a cadeia de otimização do Shopware (concatenação, minificação, fingerprinting de cache).

Herança das variáveis e mixins do tema

Por predefinição, cada snippet SCSS beneficia de um preâmbulo automático que contém todas as variáveis e todos os mixins expostos pelo tema ativo e pelas suas extensões de tema. Pode portanto escrever num snippet:

.header {
    background: $sw-color-brand-primary;
    font-family: $font-family-base;
    transition: $transition-base;
}

sem importar nada manualmente, exatamente como num ficheiro SCSS do tema. Se por alguma razão específica (conflito de variável, snippet autónomo) quiser desativar essa herança num snippet concreto, desmarque o interruptor Variáveis do tema disponíveis no rodapé do cartão do snippet.

Âmbito multicanal

No cartão Âmbito e canais do contentor, ative Limitar a canais de venda e selecione os canais em causa. O contentor só será injetado nas compilações de tema desses canais. Muito prático para:

• Um banner promocional reservado a uma loja de marca secundária.
• Um script de tracking específico de um mercado.
• Um teste A/B num único canal para medir o impacto.

Prioridade de carregamento

A prioridade é um inteiro (0 por predefinição) que controla a ordem de injeção no bundle compilado: quanto mais alto o valor, mais tarde o código é injetado, e portanto mais pode sobrepor o que o precede. A prioridade existe a dois níveis:

• Ao nível do contentor: ordem entre contentores.
• Ao nível do snippet: ordem entre snippets dentro do mesmo contentor.

A ordem final é (prioridade do contentor, prioridade do snippet) por ordem crescente. Conselho simples: deixe tudo a 0 por predefinição e só use a prioridade se precisar explicitamente de sobrepor algo.

Histórico de versões

A cada gravação de um snippet, a extensão cria automaticamente uma versão na tabela df_ccm_snippet_version. São conservadas as 5 últimas versões por snippet (a mais antiga é eliminada quando o limite é atingido). Para consultar e restaurar uma versão:

1. No cartão do snippet, clique no ícone Histórico (relógio).
2. Abre-se uma janela com a lista das versões, data, autor, comentário e pré-visualização.
3. Clique em Restaurar à direita da versão pretendida; o código do snippet é imediatamente substituído pelo dessa versão. É criada uma nova versão para registar o restauro.
4. Guarde o contentor e recompile para ver o efeito.

Modo seguro: a rede de segurança de emergência

O modo seguro é um interruptor global na configuração da extensão. Ativo, faz com que todos os contentores sejam ignorados na próxima compilação, sem alterar qualquer dado. Utilização típica:

1. Um snippet mal testado parte algo em produção às 22h.
2. Vá a Extensões → As minhas extensões → DfCustomCodeManager → ⋯ → Configurar.
3. Ative o interruptor Modo seguro e guarde.
4. Recompile o tema: bin/console theme:compile.
5. O storefront volta ao estado nativo (sem qualquer snippet injetado). Pode agora identificar e corrigir o snippet culpado com calma.
6. Depois de corrigido, desative o modo seguro e recompile de novo.

Biblioteca de presets

O botão Presets (a partir da lista dos contentores) abre uma biblioteca de 8 contentores prontos a instalar num clique:

• Sticky header: header que se transforma no scroll (classe is-sticky acrescentada a partir de um limiar).
• Back to top: botão de voltar ao topo, visível a partir de um certo scroll.
• Cookie banner skin: nova aparência para o banner de cookies nativo, alinhada com a sua identidade.
• Product badge Novo: selo «Novo» nos produtos criados recentemente.
• Free shipping bar: barra de progresso de portes grátis no topo da página.
• Rounded buttons: botões arredondados em toda a loja.
• GTM DOM-ready event: dispara um evento personalizado quando o DOM está pronto, para arrancar as suas data layers.
• Fade-in on scroll: aparecimento progressivo dos elementos ao fazer scroll.

Clicar em Instalar cria o contentor e os seus snippets na base de dados. Só falta recompilar o tema para os ver online. Os contentores criados a partir de um preset são contentores como os outros: pode editá-los, enriquecê-los, desativá-los, eliminá-los.

Importação e exportação JSON

Para migrar snippets entre ambientes (desenvolvimento, staging, produção) ou entre lojas:

1. Exportação: selecione um ou vários contentores na lista (caixas de seleção) e clique em Exportar. É transferido um ficheiro JSON com todos os contentores selecionados, os seus snippets, a sua prioridade, as suas notas, e o número de versão do formato (EXPORT_VERSION = 1) para a retrocompatibilidade.
2. Importação: no ambiente de destino, clique em Importar e selecione o ficheiro JSON. Os contentores e snippets são recriados de forma idêntica.

Validação sintática

O botão ✓ Validar a sintaxe em cada cartão de snippet aciona uma validação do lado do servidor sem guardar nada. Consoante o tipo:

• SCSS: a extensão faz uma compilação de teste com o scssphp/scssphp injetando o preâmbulo das variáveis do tema. Se a compilação passar, o snippet é válido. Caso contrário, os erros aparecem numa zona de erro no cartão (número de linha, mensagem).
• JavaScript: a extensão limpa o código de cadeias e comentários, e depois verifica o equilíbrio das chavetas {}, parênteses () e parênteses retos []. Esta verificação não substitui um verdadeiro parser ECMAScript, mas apanha 90 % dos erros de copiar e colar (chaveta esquecida, cadeia mal fechada). Para ir mais longe, valide o seu JavaScript numa ferramenta dedicada antes de colar.

Arquitetura técnica

Para os programadores que querem compreender ou estender a extensão:

• Namespace PHP raiz: DataFirefly (subnamespace: CustomCodeManager, classes em src/).
• Classe da extensão: DfCustomCodeManager (estende ShopwareCoreFrameworkPlugin).
• Prefixo do SystemConfig: DfCustomCodeManager.config.*.
• Tabelas: df_ccm_container, df_ccm_container_sales_channel, df_ccm_snippet, df_ccm_snippet_version.
• Migrações: Migration1779580800CreateCcmContainerTable, Migration1779580801CreateCcmSnippetTable, Migration1779580802CreateCcmSnippetVersionTable.
• Serviços: CodeCompiler (orquestração e cache), SnippetExporter (importação e exportação JSON), SnippetValidator (validação sintática), VersionTracker (snapshot, restauro e limpeza).
• Subscribers: ThemeCompilerSubscriber (os 3 eventos de compilação), SnippetWrittenSubscriber (snapshot automático na escrita).
• Rotas de API privadas em /api/_action/df-ccm/ (scope api): validate, export, import, restore-version, recompile, presets.

Todas as declarações de serviços são explícitas no services.xml (sem autowiring) para manter o alinhamento com as convenções DataFirefly.

Estender o módulo de administração

O módulo de administração está compilado e colocado em Resources/public/administration/js/df-custom-code-manager.js. Vem pré-compilado no ZIP e não exige qualquer build local. Para o estender, use os componentes (df-ccm-list, df-ccm-detail, df-ccm-snippet-card, df-ccm-code-field, df-ccm-preset-modal, df-ccm-version-modal) e personalize através do sistema de override normal do Shopware (Component.override).

FAQ e resolução de problemas

Os meus snippets não aparecem no storefront. Recompilou o tema? Enquanto o theme:compile não correr depois de uma alteração, nada muda. Verifique também que o contentor e o snippet estão ativos, que o canal de venda em causa está no âmbito (se o âmbito estiver restringido), e que o modo seguro não está ativo.

Erro de compilação SCSS na consola depois do theme:compile. Na maioria dos casos, é uma variável do tema que não existe (erro de escrita) ou um snippet SCSS que abre um bloco sem o fechar. Desative o snippet em causa, recompile para confirmar e depois corrija com calma. A validação sintática no cartão do snippet apanha a maioria destes casos antes da gravação.

O menu Custom Code Manager não aparece na administração. Execute bin/console assets:install && bin/console cache:clear e recarregue a administração com Ctrl+Shift+R. O módulo está no grupo Catálogos.

O editor de código mostra um textarea sem coloração. É a alternativa quando nem o mt-code-editor (6.7) nem o sw-code-editor (6.6) estão disponíveis. Verifique a sua versão do Shopware e que o módulo de administração está mesmo carregado.

Quero desativar temporariamente todos os snippets sem eliminar nada. É exatamente o modo seguro. Interruptor na configuração da extensão, recompilação, e está feito.

O botão «Compilar o tema» gira sem parar. Verifique os logs do Shopware. A compilação pode demorar num tema grande; em caso de bloqueio real, a causa habitual é um snippet SCSS que entra em ciclo ou contém uma variável desconhecida. Ative o modo seguro, recompile, e depois reative os snippets um a um para identificar o culpado.

O meu snippet JavaScript não dispara. Não se esqueça de que o código injetado é executado no bundle global, portanto num contexto diferente do das extensões JavaScript clássicas do Shopware. Para interagir com as extensões JavaScript do storefront, escute antes document.addEventListener('DOMContentLoaded', …) ou os eventos globais que o storefront emite.

O que acontece na desinstalação? Durante o plugin:uninstall, o Shopware mostra a caixa normal Conservar os dados do utilizador. Se estiver desmarcada, a extensão elimina as suas 4 tabelas e todos os dados associados (contentores, snippets, versões, ligações a canais). Se estiver marcada, as tabelas mantêm-se e pode recuperar os seus snippets se reinstalar a extensão mais tarde.