# 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…

- Página: <https://www.datafirefly.com/pt/documentation/datafirefly-page-builder-shopware/>
- Idioma: pt
- Atualizado em: 2026-09-02
- Outros idiomas: [fr](https://www.datafirefly.com/documentation/datafirefly-page-builder-shopware/index.md), [en](https://www.datafirefly.com/en/documentation/datafirefly-page-builder-shopware/index.md), [es](https://www.datafirefly.com/es/documentation/datafirefly-page-builder-shopware/index.md), [de](https://www.datafirefly.com/de/documentation/datafirefly-page-builder-shopware/index.md), [it](https://www.datafirefly.com/it/documentation/datafirefly-page-builder-shopware/index.md), [pl](https://www.datafirefly.com/pl/documentation/datafirefly-page-builder-shopware/index.md), [nl](https://www.datafirefly.com/nl/documentation/datafirefly-page-builder-shopware/index.md)
- Índice: <https://www.datafirefly.com/pt/documentation/llms.txt>

## 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.

Este módulo é uma **extensão** (código PHP). Instala-se portanto em Shopware **self-hosted** e **PaaS**, não no Shopware Cloud (SaaS), reservado às apps.

## 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
```

Depois de uma instalação ou de uma atualização, limpe também a cache do navegador (Ctrl+F5) na página de administração para recarregar o módulo.

## 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.

O bloco **HTML** permite inserir código livre: está reservado a um privilégio ACL dedicado (`editor_html`) e o seu conteúdo passa pela sanitização no servidor.

## 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`.

A ligação de pré-visualização abre no host da administração. Se o seu storefront estiver noutro domínio, copie a ligação para o domínio certo. A validade da ligação define-se na configuração (predefinição: 3600 s).

## 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.