DataFirefly Page Builder para Shopware 6.7 — Instalación, configuración y documentación técnica

Presentación

El DataFirefly Page Builder es un editor de páginas visual autónomo para Shopware 6.7. Incluye su propio motor de renderizado del storefront (Twig) y funciona con independencia del CMS nativo «Shopping Experiences». Compone páginas mediante secciones y columnas, y luego rellena esas columnas con bloques mediante arrastrar y soltar, sin escribir código.

El editor se ejecuta en la administración en Vue 3 / Pinia (build Vite de la 6.7) y ofrece arrastrar y soltar, subir/bajar, duplicación y deshacer/rehacer. El contenido se guarda como JSON versionado: un borrador de trabajo separado de la versión publicada, un historial de versiones creado en cada publicación, publicación programada y enlaces de vista previa firmados y compartibles. Las páginas publicadas se sirven en /p/{slug} con la caché HTTP de Shopware activa, y admiten multilingüe y multicanal.

Requisitos

• Shopware ≥ 6.7.0 (shopware/core, shopware/storefront y shopware/administration en ~6.7.0)
• PHP ≥ 8.2
• MySQL 8 / MariaDB 10.11+
• Acceso a la línea de comandos para instalar el plugin, compilar los assets y vaciar la caché
• Variable de entorno APP_SECRET definida — se usa para firmar los enlaces de vista previa

Instalación

1. Copie la carpeta DataFireflyPageBuilder en custom/plugins/ de su instancia (o suba el ZIP en Extensiones → Mis extensiones → Subir extensión).
2. Actualice la lista de plugins, instale y active la extensión.
3. Compile la administración y el storefront, y vacíe la caché:

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

Crear y editar una página

Abra la administración, vaya a Contenidos → Page Builder y haga clic en «Crear página». La edición se reparte en dos pestañas.

Pestaña Editor

Añada primero una sección (con elección de disposición de columnas) y luego suelte bloques en las columnas. Cada bloque se puede arrastrar, subir o bajar, duplicar o eliminar, y todas las acciones son deshacer/rehacer. El lienzo muestra vistas previas visuales en directo: imágenes, miniaturas de galería, texto enriquecido, botones, nombres de productos y campos de formulario.

Pestaña Ajustes y SEO

Aquí define el nombre de la página, su slug, su estado, la programación, los canales de venta asignados, el meta título, la meta descripción y la opción noindex. El slug se genera automáticamente a partir del nombre, su unicidad se valida por idioma, y cualquier cambio de slug crea una redirección 301 automática desde la URL antigua.

Bloques disponibles

El builder incluye 15 tipos de bloques, declarados en el BlockRegistry:

• Estructura y texto: título, texto enriquecido (edición WYSIWYG mediante sw-text-editor), separador, espaciador, cita.
• Multimedia: imagen, galería (selector multiimagen), vídeo (fachada RGPD YouTube/Vimeo), HTML/embed.
• Interacción: botón, acordeón (editor de elementos visual), cuenta atrás, formulario (editor de campos visual).
• E-commerce: producto único y listado de productos.

Publicar, programar y versionar

Una página tiene cuatro estados: draft (borrador), scheduled (programada), published (publicada) y archived (archivada).

• Guardar borrador actualiza el contenido de trabajo (draftContent) sin tocar la versión en línea.
• Publicar copia el borrador a la versión publicada (publishedContent) y crea una versión de historial. La publicación desde la administración procesa todos los idiomas a la vez, con un aviso si falta una traducción.
• Programar: ponga la página en estado «Programada» con una fecha; una tarea programada se ejecuta cada 5 minutos para publicar automáticamente las páginas vencidas (todos los idiomas).

Vista previa

El botón Vista previa abre el storefront mediante un enlace firmado y caducable (/dfpb/preview/{pageId}?token=…): el borrador es visible sin cuenta de administrador, la página nunca se cachea y devuelve una cabecera X-Robots-Tag: noindex, nofollow.

Multilingüe y multicanal

El nombre, el slug, los campos SEO y el contenido son traducibles por idioma de Shopware. Una página se asigna a uno o varios canales de venta; solo se sirve en /p/{slug} para los canales a los que está asociada, en el idioma del contexto actual.

SEO

Por página e idioma gestiona el meta título, la meta descripción y la indexación (noindex). El controlador del storefront inyecta estos metadatos en la página renderizada y fuerza noindex,nofollow en la vista previa. Los cambios de slug generan redirecciones 301 para preservar el posicionamiento.

Configuración

Vaya a Extensiones → Mis extensiones → DataFirefly Page Builder → Configuración. La tarjeta General expone dos ajustes:

• Validez del enlace de vista previa (previewTokenLifetime, por defecto: 3600 segundos).
• Retención de las entradas de formularios (submissionRetentionDays, por defecto: 90 días; 0 = conservar indefinidamente).

Formularios

El bloque de formulario se configura con un editor de campos visual e integra protección antispam mediante honeypot y trampa temporal, además de un consentimiento RGPD obligatorio. Las entradas se almacenan en la base de datos con purga automática según la retención configurada. En cada envío se dispara un evento FormSubmittedEvent para conectar sus integraciones (Flow Builder, correo, webhook, etc.).

Arquitectura técnica

El plugin sigue las convenciones de Shopware 6.7: entidades declaradas mediante la Data Abstraction Layer (DAL), contenido almacenado como JSON versionado, controladores de storefront y API, tareas programadas con Messenger y migraciones SQL.

Entidades y Data Abstraction Layer

La entidad principal datafirefly_pb_page (PageDefinition) lleva el estado, las fechas publishedAt/scheduledAt, la opción noIndex, y los campos traducibles name, slug, metaTitle, metaDescription, draftContent y publishedContent. Se asocia ManyToMany a los canales de venta y OneToMany a sus versiones (con CascadeDelete). Las seis entidades del plugin usan el prefijo datafirefly_pb_:

• datafirefly_pb_page y datafirefly_pb_page_translation: la página y sus traducciones.
• datafirefly_pb_page_sales_channel: asignación a canales de venta.
• datafirefly_pb_page_version: instantáneas del contenido creadas al publicar.
• datafirefly_pb_saved_block: bloques guardados reutilizables.
• datafirefly_pb_form_submission: entradas de formularios.

El contenido de la página es JSON estructurado y versionado (schemaVersion) para permitir futuras migraciones. Dos migraciones inicializan el esquema: Migration1781222400InitialSchema y Migration1781222402SlugRedirect (tabla de redirecciones de slug).

Rutas

Los controladores se importan por atributos (Resources/config/routes.xml).

• GET /p/{slug} → frontend.dfpb.page.detail: renderiza la página publicada (caché HTTP activa). Si el slug ya no coincide, se emite una redirección 301 al nuevo slug mediante la tabla de redirecciones.
• GET /dfpb/preview/{pageId}?token=… → frontend.dfpb.page.preview: renderiza el borrador con token firmado, sin caché, como noindex,nofollow.
• GET /api/_action/dfpb/preview-token/{pageId}: genera un token de vista previa (ACL datafirefly_pb_page:read).
• POST /api/_action/dfpb/publish/{pageId}: publica la página (ACL datafirefly_pb_page:update).

Tareas programadas

• PublishScheduledPagesTask: publica las páginas programadas vencidas (se ejecuta cada 5 minutos).
• CleanupFormSubmissionsTask: purga las entradas de formularios más allá de la retención configurada.

Control de acceso (ACL)

El plugin declara privilegios en torno a la entidad página: datafirefly_pb_page.viewer, .editor, .creator y .deleter, además de un privilegio aparte editor_html requerido para editar el bloque HTML. Shopware compone los roles de administración a partir de estos privilegios.

Seguridad y sanitización

Todo el contenido enriquecido se sanea en el servidor mediante el filtro Twig dfpb_sanitize (lista blanca de etiquetas), los tipos de bloque están sujetos a su vez a una lista blanca, y los estilos inline se filtran por expresión regular. El JSON de la página nunca puede inyectar Twig en bruto; el escapado por defecto de Twig se aplica al renderizar. Los tokens de vista previa están firmados (HMAC mediante APP_SECRET) y caducan.

Extensión por plugins de terceros

Para añadir un bloque personalizado, decore el servicio DataFirefly\PageBuilder\Service\BlockRegistry y llame a register(type, template, label) para registrar el tipo y su plantilla Twig de renderizado, y luego declare el tipo correspondiente en la administración (componente de edición Vue).

Privacidad (RGPD)

Los bloques con contenido de terceros usan una fachada de consentimiento: el vídeo de YouTube (youtube-nocookie) o Vimeo (dnt=1) solo se carga tras un clic explícito — sin llamadas a terceros al cargar la página. Los formularios exigen consentimiento RGPD, y las entradas se someten a purga automática según la retención configurada.

Limitaciones conocidas de la v1

• El editor de administración es estructural (lienzo por bloques), no un WYSIWYG en iframe del storefront real.
• La publicación manual copia el borrador a la versión publicada; la publicación programada cubre todos los idiomas.
• Aún no incluidos: plantillas de página listas para usar, bloques globales sincronizados, reglas de visibilidad (Rule Builder), importación/exportación, sobreescrituras responsive por punto de ruptura y asistente de IA.

Desinstalación

Al desinstalar, las tablas del plugin (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) se eliminan — salvo que esté marcada la opción «conservar los datos del usuario».

Resolución de problemas

• Una página publicada devuelve 404: compruebe que la página está en estado «publicada», que su slug es correcto y que está asignada al canal de venta actual.
• El módulo de administración no carga: vuelva a ejecutar bin/build-administration.sh, assets:install y luego cache:clear, y fuerce la recarga del navegador (Ctrl+F5).
• El enlace de vista previa es inválido o ha caducado: regenérelo; verifique que APP_SECRET está definido y, si es necesario, aumente la validez del token en la configuración.
• La publicación programada no se dispara: asegúrese de que el worker de Shopware (Messenger / tareas programadas) está en ejecución; la tarea se ejecuta cada 5 minutos.
• Las entradas de formularios no se purgan: compruebe el valor de retención en la configuración (0 = ilimitado) y que la tarea de limpieza está programada.