DataFirefly Page Builder para Shopware 6.7: instalação, configuração e documentação técnica

Apresentação

O DataFirefly Page Builder é um editor visual de páginas autónomo para Shopware 6.7. Tem o seu próprio motor de renderização no storefront (Twig) e funciona independentemente do CMS nativo «Shopping Experiences». Compõe as páginas por secções e colunas, e preenche essas colunas com blocos por arrastar e largar, sem escrever código.

O editor corre na administração em Vue 3 / Pinia (build Vite da 6.7) e oferece arrastar e largar, subir e descer, duplicação e anular/refazer. O conteúdo é guardado em JSON versionado: um rascunho de trabalho distinto da versão publicada, um histórico de versões criado a cada publicação, publicação agendada e ligações de pré-visualização assinadas e partilháveis. As páginas publicadas são servidas em /p/{slug} com a cache HTTP do Shopware ativa, e suportam multilingue e multicanal.

Pré-requisitos

• Shopware ≥ 6.7.0 (shopware/core, shopware/storefront e shopware/administration em ~6.7.0)
• PHP ≥ 8.2
• MySQL 8 / MariaDB 10.11+
• Acesso à linha de comandos para instalar a extensão, compilar os recursos e limpar a cache
• Variável de ambiente APP_SECRET definida, usada para assinar as ligações de pré-visualização

Instalação

1. Copie a pasta DataFireflyPageBuilder para custom/plugins/ da sua instância (ou carregue o ZIP em Extensões → As minhas extensões → Carregar extensão).
2. Atualize a lista de extensões, instale e ative a extensão.
3. Compile a administração e o storefront, e depois limpe a cache:

bin/console plugin:refresh
bin/console plugin:install --activate DataFireflyPageBuilder
bin/build-administration.sh
bin/build-storefront.sh
bin/console assets:install
bin/console cache:clear

Criar e editar uma página

Abra a administração e depois Conteúdos → Page Builder e clique em «Criar uma página». A edição divide-se em dois separadores.

Separador Editor

Acrescente primeiro uma secção (com escolha de disposição de colunas) e depois largue blocos nas colunas. Cada bloco pode ser arrastado e largado, subido ou descido, duplicado ou eliminado, e todas as ações podem ser anuladas ou refeitas. O canvas mostra pré-visualizações visuais em direto: imagens, miniaturas de galeria, texto formatado, botões, nomes de produtos e campos de formulário.

Separador Definições e SEO

Aqui define o nome da página, o seu slug, o seu estado, o agendamento, os canais de venda de atribuição, o meta título, a meta descrição e a opção noindex. O slug é gerado automaticamente a partir do nome, a sua unicidade é validada por idioma, e qualquer mudança de slug cria um redirecionamento 301 automático a partir do URL antigo.

Blocos disponíveis

O builder inclui 15 tipos de blocos, declarados no BlockRegistry:

• Estrutura e texto: título, texto formatado (edição WYSIWYG com sw-text-editor), separador, espaçador, citação.
• Média: imagem, galeria (seletor de várias imagens), vídeo (fachada RGPD YouTube/Vimeo), HTML/embed.
• Interação: botão, acordeão (editor visual de itens), contagem decrescente, formulário (editor visual de campos).
• Comércio eletrónico: produto único e listagem de produtos.

Publicar, agendar e versionar

Uma página tem quatro estados: draft (rascunho), scheduled (agendada), published (publicada) e archived (arquivada).

• Guardar o rascunho atualiza o conteúdo de trabalho (draftContent) sem tocar na versão online.
• Publicar copia o rascunho para a versão publicada (publishedContent) e cria uma versão no histórico. A publicação a partir da administração trata todos os idiomas de uma vez, com um aviso se faltar uma tradução.
• Agendar: passe a página ao estado «Agendada» com uma data; uma tarefa agendada corre a cada 5 minutos para publicar automaticamente as páginas que chegaram à data (todos os idiomas).

Pré-visualização

O botão Pré-visualizar abre o storefront através de uma ligação assinada e com prazo (/dfpb/preview/{pageId}?token=…): o rascunho fica visível sem conta de administrador, a página nunca é colocada em cache e devolve um cabeçalho X-Robots-Tag: noindex, nofollow.

Multilingue e multicanal

O nome, o slug, os campos de SEO e o conteúdo são traduzíveis por idioma do Shopware. Uma página atribui-se a um ou vários canais de venda; só é servida em /p/{slug} nos canais a que está associada, no idioma do contexto atual.

SEO

Por página e por idioma, gere o meta título, a meta descrição e a indexação (noindex). O controlador do storefront injeta estes metadados na página renderizada e força noindex,nofollow em pré-visualização. As mudanças de slug geram redirecionamentos 301 para preservar o posicionamento.

Configuração

Vá a Extensões → As minhas extensões → DataFirefly Page Builder → Configuração. O cartão Geral expõe duas definições:

• Tempo de vida da ligação de pré-visualização (previewTokenLifetime, predefinição: 3600 segundos).
• Retenção das submissões de formulário (submissionRetentionDays, predefinição: 90 dias; 0 = conservação ilimitada).

Formulários

O bloco de formulário configura-se com um editor visual de campos e integra uma proteção antispam por honeypot e armadilha temporal, além de um consentimento RGPD obrigatório. As submissões são guardadas na base de dados com limpeza automática segundo a retenção configurada. A cada envio, é acionado um evento FormSubmittedEvent para ligar as suas integrações (Flow Builder, email, webhook e outras).

Arquitetura técnica

A extensão segue as convenções do Shopware 6.7: entidades declaradas através da Data Abstraction Layer (DAL), conteúdo guardado em JSON versionado, controladores de storefront e de API, tarefas agendadas Messenger e migrações SQL.

Entidades e Data Abstraction Layer

A entidade principal datafirefly_pb_page (PageDefinition) tem o estado, as datas publishedAt/scheduledAt, a opção noIndex, e os campos traduzíveis name, slug, metaTitle, metaDescription, draftContent e publishedContent. Está associada em ManyToMany aos canais de venda e em OneToMany às suas versões (com CascadeDelete). As seis entidades da extensão usam o prefixo datafirefly_pb_:

• datafirefly_pb_page e datafirefly_pb_page_translation: a página e as suas traduções.
• datafirefly_pb_page_sales_channel: atribuição aos canais de venda.
• datafirefly_pb_page_version: snapshots do conteúdo criados na publicação.
• datafirefly_pb_saved_block: blocos guardados reutilizáveis.
• datafirefly_pb_form_submission: submissões de formulário.

O conteúdo da página é um JSON estruturado e versionado (schemaVersion) para permitir migrações futuras. Duas migrações inicializam o esquema: Migration1781222400InitialSchema e Migration1781222402SlugRedirect (tabela de redirecionamentos de slug).

Rotas

Os controladores são importados por atributos (Resources/config/routes.xml).

• GET /p/{slug} → frontend.dfpb.page.detail: renderiza a página publicada (cache HTTP ativa). Se o slug já não corresponder, é emitido um redirecionamento 301 para o novo slug através da tabela de redirecionamentos.
• GET /dfpb/preview/{pageId}?token=… → frontend.dfpb.page.preview: renderização do rascunho com token assinado, sem cache, em noindex,nofollow.
• GET /api/_action/dfpb/preview-token/{pageId}: gera um token de pré-visualização (ACL datafirefly_pb_page:read).
• POST /api/_action/dfpb/publish/{pageId}: publica a página (ACL datafirefly_pb_page:update).

Tarefas agendadas

• PublishScheduledPagesTask: publica as páginas agendadas que chegaram à data (execução a cada 5 minutos).
• CleanupFormSubmissionsTask: elimina as submissões de formulário para além da retenção configurada.

Controlo de acessos (ACL)

A extensão declara privilégios em torno da entidade página: datafirefly_pb_page.viewer, .editor, .creator e .deleter, mais um privilégio distinto editor_html exigido para editar o bloco HTML. O Shopware compõe os papéis de administrador a partir destes privilégios.

Segurança e sanitização

Todo o conteúdo formatado é sanitizado do lado do servidor através do filtro Twig dfpb_sanitize (lista branca de etiquetas), os próprios tipos de bloco estão sujeitos a uma lista branca, e os estilos inline são filtrados por expressão regular. O JSON da página nunca pode injetar Twig em bruto; o escape Twig por predefinição aplica-se na renderização. Os tokens de pré-visualização são assinados (HMAC com APP_SECRET) e com prazo.

Extensão por extensões de terceiros

Para acrescentar um bloco próprio, decore o serviço DataFirefly\PageBuilder\Service\BlockRegistry e chame register(type, template, label) para registar o tipo e o seu template Twig de renderização, e depois declare o tipo correspondente do lado da administração (componente de edição em Vue).

Privacidade (RGPD)

Os blocos com conteúdo de terceiros usam uma fachada com consentimento: o vídeo do YouTube (youtube-nocookie) ou do Vimeo (dnt=1) só é carregado depois de um clique explícito, sem qualquer chamada a terceiros no carregamento da página. Os formulários impõem um consentimento RGPD, e as submissões são objeto de limpeza automática segundo a retenção configurada.

Limites conhecidos da v1

• O editor de administração é estrutural (canvas por blocos), e não um WYSIWYG em iframe do storefront real.
• A publicação manual copia o rascunho para a versão publicada; a publicação agendada cobre todos os idiomas.
• Ainda não estão incluídos: templates de página prontos a usar, blocos globais sincronizados, regras de visibilidade (Rule Builder), importação e exportação, sobreposições responsivas por ponto de rutura e assistente de IA.

Desinstalação

Na desinstalação, as tabelas da extensão (datafirefly_pb_slug_redirect, datafirefly_pb_form_submission, datafirefly_pb_saved_block, datafirefly_pb_page_version, datafirefly_pb_page_sales_channel, datafirefly_pb_page_translation, datafirefly_pb_page) são eliminadas, exceto se a opção «conservar os dados do utilizador» estiver marcada.

Resolução de problemas

• Uma página publicada devolve 404: verifique que a página está mesmo no estado «publicada», que o slug está correto e que está atribuída ao canal de venda atual.
• O módulo de administração não carrega: execute de novo bin/build-administration.sh, assets:install e cache:clear, e force o recarregamento do navegador (Ctrl+F5).
• A ligação de pré-visualização é inválida ou expirou: gere-a de novo; verifique que APP_SECRET está definido e, se necessário, aumente o tempo de vida do token na configuração.
• A publicação agendada não é acionada: confirme que o worker do Shopware (Messenger / scheduled tasks) está a correr; a tarefa executa a cada 5 minutos.
• As submissões de formulário não são eliminadas: verifique o valor de retenção na configuração (0 = ilimitado) e que a tarefa de limpeza está mesmo agendada.