# DataFirefly Page Builder for Shopware 6.7 — Installation, configuration and technical documentation

> Overview The DataFirefly Page Builder is a standalone visual page editor for Shopware 6.7. It ships its own Twig storefront rendering engine and works independently of the native "Shopping Experiences"…

- Page: <https://www.datafirefly.com/en/documentation/datafirefly-page-builder-shopware/>
- Language: en
- Last updated: 2026-07-08
- Other languages: [fr](https://www.datafirefly.com/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), [pt](https://www.datafirefly.com/pt/documentation/datafirefly-page-builder-shopware/index.md)
- Index: <https://www.datafirefly.com/en/documentation/llms.txt>

## Overview

The **DataFirefly Page Builder** is a **standalone** visual page editor for Shopware 6.7. It ships its own Twig storefront rendering engine and works independently of the native "Shopping Experiences" CMS. You compose pages from **sections** and **columns**, then fill those columns with **blocks** via drag & drop — no code required.

The editor runs in the administration in **Vue 3 / Pinia** (the 6.7 Vite build) and offers drag & drop, move up/down, duplication and **undo/redo**. Content is stored as **versioned JSON**: a working draft separate from the published version, a version history created on every publish, scheduled publishing and shareable signed preview links. Published pages are served on `/p/{slug}` with Shopware's **HTTP cache** active, and support multilingual and multi-sales-channel setups.

This module is a **plugin** (PHP code). It therefore installs on **self-hosted** and **PaaS** Shopware — not on Shopware Cloud (SaaS), which is reserved for apps.

## Requirements

- Shopware **≥ 6.7.0** (`shopware/core`, `shopware/storefront` and `shopware/administration` at `~6.7.0`)
- PHP **≥ 8.2**
- MySQL 8 / MariaDB 10.11+
- Command-line access to install the plugin, build assets and clear the cache
- The `APP_SECRET` environment variable set — it is used to sign preview links

## Installation

1. Copy the `DataFireflyPageBuilder` folder into `custom/plugins/` of your instance (or upload the ZIP via **Extensions → My extensions → Upload extension**).
2. Refresh the plugin list, install and activate the extension.
3. Build the administration and storefront, then clear the 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
```

After installing or updating, also clear your browser cache (Ctrl+F5) on the administration page to reload the module.

## Create and edit a page

Open the administration, go to **Content → Page Builder** and click **"Create page"**. Editing is split across two tabs.

### Editor tab

First add a **section** (with a choice of column layout), then drop **blocks** into the columns. Each block can be dragged, moved up or down, duplicated or deleted, and every action is undoable/redoable. The canvas shows **live visual previews**: images, gallery thumbnails, rich text, buttons, product names and form fields.

### Settings & SEO tab

Here you set the page **name**, **slug**, **status**, **scheduling**, assigned **sales channels**, **meta title**, **meta description** and the **noindex** option. The slug is **generated automatically** from the name, its **uniqueness is validated per language**, and any slug change creates an automatic **301 redirect** from the old URL.

## Available blocks

The builder ships **15 block types**, declared in the `BlockRegistry`:

- **Structure & text**: heading, rich text (WYSIWYG editing via `sw-text-editor`), divider, spacer, quote.
- **Media**: image, gallery (multi-image picker), video (GDPR facade YouTube/Vimeo), HTML/embed.
- **Interaction**: button, accordion (visual item editor), countdown, form (visual field editor).
- **E-commerce**: single product and product listing.

The **HTML** block allows free code: it is restricted to a dedicated ACL privilege (`editor_html`) and its content passes through server-side sanitization.

## Publish, schedule and version

A page has four statuses: `draft`, `scheduled`, `published` and `archived`.

- **Save draft** updates the working content (`draftContent`) **without** touching the live version.
- **Publish** copies the draft to the published version (`publishedContent`) and creates a **history version**. Publishing from the administration processes **all languages at once**, with a warning if a translation is missing.
- **Schedule**: set the page to "Scheduled" status with a date; a **scheduled task runs every 5 minutes** to automatically publish pages that are due (all languages).

## Preview

The **Preview** button opens the storefront via a **signed, expiring link** (`/dfpb/preview/{pageId}?token=…`): the draft is visible without an admin account, the page is never cached and returns an `X-Robots-Tag: noindex, nofollow` header.

The preview link opens on the administration host. If your storefront is on a different domain, copy the link onto the correct domain. The link lifetime is set in the configuration (default: 3600 s).

## Multilingual and multi-sales-channel

The name, slug, SEO fields and content are **translatable** per Shopware language. A page is assigned to one or more **sales channels**; it is served on `/p/{slug}` only for the channels it is attached to, in the current context language.

## SEO

Per page and per language you manage the meta title, meta description and indexing (`noindex`). The storefront controller injects this metadata into the rendered page and forces `noindex,nofollow` in preview. Slug changes generate 301 redirects to preserve rankings.

## Configuration

Go to **Extensions → My extensions → DataFirefly Page Builder → Configuration**. The _General_ card exposes two settings:

- **Preview link lifetime** (`previewTokenLifetime`, default: **3600** seconds).
- **Form submission retention** (`submissionRetentionDays`, default: **90** days; `0` = keep forever).

## Forms

The form block is configured with a **visual field editor** and includes anti-spam protection via **honeypot** and **time trap**, plus a **mandatory GDPR consent**. Submissions are stored in the database with **automatic cleanup** according to the configured retention. On each submission a `FormSubmittedEvent` is dispatched so you can wire up your integrations (Flow Builder, email, webhook, etc.).

## Technical architecture

The plugin follows Shopware 6.7 conventions: entities declared via the Data Abstraction Layer (DAL), content stored as versioned JSON, storefront and API controllers, Messenger scheduled tasks and SQL migrations.

### Entities and Data Abstraction Layer

The main entity `datafirefly_pb_page` (`PageDefinition`) carries the status, the `publishedAt`/`scheduledAt` dates, the `noIndex` option, and the translatable fields `name`, `slug`, `metaTitle`, `metaDescription`, `draftContent` and `publishedContent`. It is associated `ManyToMany` to sales channels and `OneToMany` to its versions (with `CascadeDelete`). The plugin's six entities use the `datafirefly_pb_` prefix:

- `datafirefly_pb_page` and `datafirefly_pb_page_translation`: the page and its translations.
- `datafirefly_pb_page_sales_channel`: sales channel assignment.
- `datafirefly_pb_page_version`: content snapshots created on publish.
- `datafirefly_pb_saved_block`: reusable saved blocks.
- `datafirefly_pb_form_submission`: form submissions.

Page content is **structured, versioned JSON** (`schemaVersion`) to allow future migrations. Two migrations initialize the schema: `Migration1781222400InitialSchema` and `Migration1781222402SlugRedirect` (slug redirect table).

### Routes

Controllers are imported by attributes (`Resources/config/routes.xml`).

- `GET /p/{slug}` → `frontend.dfpb.page.detail`: renders the published page (HTTP cache active). If the slug no longer matches, a **301** redirect is issued to the new slug via the redirect table.
- `GET /dfpb/preview/{pageId}?token=…` → `frontend.dfpb.page.preview`: renders the draft with a signed token, uncached, as `noindex,nofollow`.
- `GET /api/_action/dfpb/preview-token/{pageId}`: generates a preview token (ACL `datafirefly_pb_page:read`).
- `POST /api/_action/dfpb/publish/{pageId}`: publishes the page (ACL `datafirefly_pb_page:update`).

### Scheduled tasks

- **PublishScheduledPagesTask**: publishes due scheduled pages (runs every 5 minutes).
- **CleanupFormSubmissionsTask**: purges form submissions beyond the configured retention.

### Access control (ACL)

The plugin declares privileges around the page entity: `datafirefly_pb_page.viewer`, `.editor`, `.creator` and `.deleter`, plus a separate `editor_html` privilege required to edit the HTML block. Shopware composes admin roles from these privileges.

### Security and sanitization

All rich content is sanitized server-side via the Twig filter `dfpb_sanitize` (tag whitelist), block types are themselves subject to a whitelist, and inline styles are filtered by regular expression. Page JSON can never inject raw Twig; Twig's default escaping applies at render time. Preview tokens are signed (HMAC via `APP_SECRET`) and expiring.

### Extension by third-party plugins

To add a custom block, decorate the `DataFirefly\PageBuilder\Service\BlockRegistry` service and call `register(type, template, label)` to register the type and its Twig render template, then declare the matching type on the administration side (Vue editing component).

## Privacy (GDPR)

Third-party content blocks use a **consent facade**: YouTube (`youtube-nocookie`) or Vimeo (`dnt=1`) video is only loaded after an explicit click — no third-party call on page load. Forms require GDPR consent, and submissions are subject to **automatic cleanup** according to the configured retention.

## Known v1 limitations

- The administration editor is **structural** (block canvas), not an iframe WYSIWYG of the real storefront.
- Manual publishing copies the draft to the published version; scheduled publishing covers all languages.
- Not yet included: ready-made page templates, synchronized global blocks, visibility rules (Rule Builder), import/export, per-breakpoint responsive overrides and an AI assistant.

## Uninstall

On uninstall, the plugin tables (`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`) are dropped — **unless** the "keep user data" option is checked.

## Troubleshooting

- **A published page returns 404**: check that the page is in "published" status, that its slug is correct and that it is assigned to the current sales channel.
- **The administration module does not load**: re-run `bin/build-administration.sh`, `assets:install` then `cache:clear`, and force a browser reload (Ctrl+F5).
- **The preview link is invalid or expired**: regenerate it; verify that `APP_SECRET` is set and, if needed, increase the token lifetime in the configuration.
- **Scheduled publishing does not trigger**: make sure the Shopware worker (Messenger / scheduled tasks) is running; the task runs every 5 minutes.
- **Form submissions are not purged**: check the retention value in the configuration (`0` = unlimited) and that the cleanup task is scheduled.