DataFirefly Page Builder voor Shopware 6.7: installatie, configuratie en technische documentatie

Overzicht

De DataFirefly Page Builder is een zelfstandige visuele pagina-editor voor Shopware 6.7. Hij beschikt over een eigen storefront-renderengine (Twig) en werkt onafhankelijk van het native CMS “Shopping Experiences”. U stelt pagina’s samen uit secties en kolommen en vult die kolommen met blokken via drag and drop, zonder code te schrijven.

De editor draait in de administration op Vue 3 / Pinia (Vite-build van 6.7) en biedt drag and drop, omhoog of omlaag verplaatsen, dupliceren en undo/redo. De inhoud wordt opgeslagen als geversioneerde JSON: een werkconcept los van de gepubliceerde versie, een versiegeschiedenis die bij elke publicatie wordt aangemaakt, geplande publicatie en deelbare ondertekende voorbeeldlinks. Gepubliceerde pagina’s worden geserveerd op /p/{slug} met de HTTP-cache van Shopware actief, en ondersteunen meerdere talen en meerdere verkoopkanalen.

Vereisten

• Shopware ≥ 6.7.0 (shopware/core, shopware/storefront en shopware/administration in ~6.7.0)
• PHP ≥ 8.2
• MySQL 8 / MariaDB 10.11+
• Toegang tot de commandoregel om de plugin te installeren, de assets te compileren en de cache te legen
• De omgevingsvariabele APP_SECRET ingesteld, die de voorbeeldlinks ondertekent

Installatie

1. Kopieer de map DataFireflyPageBuilder naar custom/plugins/ van uw instantie (of upload de ZIP via Extensies → Mijn extensies → Extensie uploaden).
2. Ververs de pluginlijst, installeer en activeer daarna de extensie.
3. Compileer de administration en de storefront en leeg vervolgens de 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

Een pagina maken en bewerken

Open de administration, ga naar Content → Page Builder en klik op “Pagina aanmaken”. Het bewerken is verdeeld over twee tabbladen.

Tabblad Editor

Voeg eerst een sectie toe (met een keuze aan kolomindelingen) en sleep daarna blokken in de kolommen. Elk blok kan worden versleept, omhoog of omlaag verplaatst, gedupliceerd of verwijderd, en alle handelingen zijn ongedaan te maken en opnieuw uit te voeren (undo/redo). Het canvas toont live visuele voorbeelden: afbeeldingen, galerijminiaturen, rijke tekst, knoppen, productnamen en formuliervelden.

Tabblad Instellingen en SEO

Hier bepaalt u de naam van de pagina, haar slug, haar status, de planning, de toegewezen verkoopkanalen, de metatitel, de metabeschrijving en de optie noindex. De slug wordt automatisch gegenereerd op basis van de naam, de uniciteit wordt per taal gevalideerd, en elke wijziging van de slug maakt automatisch een 301-redirect aan vanaf de oude URL.

Beschikbare blokken

De builder levert 15 bloktypes, gedeclareerd in de BlockRegistry:

• Structuur en tekst: titel, rijke tekst (WYSIWYG-bewerking via sw-text-editor), scheidingslijn, tussenruimte, citaat.
• Media: afbeelding, galerij (selectie van meerdere afbeeldingen), video (AVG-façade YouTube/Vimeo), HTML/embed.
• Interactie: knop, accordeon (visuele itemeditor), afteller, formulier (visuele veldeditor).
• E-commerce: enkel product en productlijst.

Publiceren, plannen en versioneren

Een pagina kent vier statussen: draft (concept), scheduled (gepland), published (gepubliceerd) en archived (gearchiveerd).

• Concept opslaan werkt de werkinhoud bij (draftContent) zonder de online versie aan te raken.
• Publiceren kopieert het concept naar de gepubliceerde versie (publishedContent) en maakt een historische versie aan. Publiceren vanuit de administration verwerkt alle talen in één keer, met een waarschuwing als een vertaling ontbreekt.
• Plannen: zet de pagina op de status “Gepland” met een datum; een geplande taak draait elke 5 minuten om pagina’s waarvan de datum bereikt is automatisch te publiceren (alle talen).

Voorbeeldweergave

De knop Voorbeeld opent de storefront via een ondertekende en verlopende link (/dfpb/preview/{pageId}?token=…): het concept is zichtbaar zonder beheerdersaccount, de pagina wordt nooit gecachet en geeft de header X-Robots-Tag: noindex, nofollow terug.

Meertaligheid en meerdere verkoopkanalen

De naam, de slug, de SEO-velden en de inhoud zijn vertaalbaar per Shopware-taal. Een pagina wordt toegewezen aan een of meer verkoopkanalen; ze wordt alleen op /p/{slug} geserveerd voor de kanalen waaraan ze gekoppeld is, in de taal van de huidige context.

SEO

Per pagina en per taal beheert u de metatitel, de metabeschrijving en de indexering (noindex). De storefront-controller voegt deze metadata toe aan de gerenderde pagina en forceert noindex,nofollow in de voorbeeldweergave. Wijzigingen van de slug genereren 301-redirects om de vindbaarheid te behouden.

Configuratie

Ga naar Extensies → Mijn extensies → DataFirefly Page Builder → Configuratie. De kaart Algemeen biedt twee instellingen:

• Levensduur van de voorbeeldlink (previewTokenLifetime, standaard: 3600 seconden).
• Bewaartermijn van formulierinzendingen (submissionRetentionDays, standaard: 90 dagen; 0 = onbeperkt bewaren).

Formulieren

Het formulierblok configureert u met een visuele veldeditor en bevat antispambescherming via een honeypot en een tijdsval, evenals een verplichte AVG-toestemming. De inzendingen worden in de database opgeslagen met een automatische opschoning volgens de ingestelde bewaartermijn. Bij elke verzending wordt een event FormSubmittedEvent afgevuurd om uw integraties aan te koppelen (Flow Builder, e-mail, webhook, enzovoort).

Technische architectuur

De plugin volgt de conventies van Shopware 6.7: entiteiten gedeclareerd via de Data Abstraction Layer (DAL), inhoud opgeslagen als geversioneerde JSON, storefront- en API-controllers, geplande Messenger-taken en SQL-migraties.

Entiteiten en Data Abstraction Layer

De hoofdentiteit datafirefly_pb_page (PageDefinition) bevat de status, de data publishedAt/scheduledAt, de optie noIndex, evenals de vertaalbare velden name, slug, metaTitle, metaDescription, draftContent en publishedContent. Ze is via ManyToMany aan de verkoopkanalen gekoppeld en via OneToMany aan haar versies (met CascadeDelete). De zes entiteiten van de plugin gebruiken het voorvoegsel datafirefly_pb_:

• datafirefly_pb_page en datafirefly_pb_page_translation: de pagina en haar vertalingen.
• datafirefly_pb_page_sales_channel: toewijzing aan de verkoopkanalen.
• datafirefly_pb_page_version: momentopnamen van de inhoud die bij publicatie worden aangemaakt.
• datafirefly_pb_saved_block: herbruikbare opgeslagen blokken.
• datafirefly_pb_form_submission: formulierinzendingen.

De pagina-inhoud is gestructureerde, geversioneerde JSON (schemaVersion) om toekomstige migraties mogelijk te maken. Twee migraties zetten het schema op: Migration1781222400InitialSchema en Migration1781222402SlugRedirect (tabel met slug-redirects).

Routes

De controllers worden via attributen geïmporteerd (Resources/config/routes.xml).

• GET /p/{slug} → frontend.dfpb.page.detail: rendert de gepubliceerde pagina (HTTP-cache actief). Klopt de slug niet meer, dan wordt via de redirecttabel een 301 naar de nieuwe slug gestuurd.
• GET /dfpb/preview/{pageId}?token=… → frontend.dfpb.page.preview: weergave van het concept met een ondertekend token, zonder cache, in noindex,nofollow.
• GET /api/_action/dfpb/preview-token/{pageId}: genereert een voorbeeldtoken (ACL datafirefly_pb_page:read).
• POST /api/_action/dfpb/publish/{pageId}: publiceert de pagina (ACL datafirefly_pb_page:update).

Geplande taken

• PublishScheduledPagesTask: publiceert de geplande pagina’s waarvan de datum bereikt is (uitvoering elke 5 minuten).
• CleanupFormSubmissionsTask: verwijdert de formulierinzendingen die de ingestelde bewaartermijn overschrijden.

Toegangscontrole (ACL)

De plugin declareert rechten rond de pagina-entiteit: datafirefly_pb_page.viewer, .editor, .creator en .deleter, plus een afzonderlijk recht editor_html dat vereist is om het HTML-blok te bewerken. Shopware stelt de beheerdersrollen samen op basis van deze rechten.

Beveiliging en sanitisatie

Alle rijke inhoud wordt server-side opgeschoond via het Twig-filter dfpb_sanitize (whitelist van tags), de bloktypes zijn zelf aan een whitelist onderworpen en inline stijlen worden met een reguliere expressie gefilterd. De JSON van een pagina kan nooit ruwe Twig injecteren; de standaard Twig-escaping geldt bij het renderen. De voorbeeldtokens zijn ondertekend (HMAC via APP_SECRET) en verlopen.

Uitbreiding door plugins van derden

Om een eigen blok toe te voegen, decoreert u de service DataFirefly\PageBuilder\Service\BlockRegistry en roept u register(type, template, label) aan om het type en het bijbehorende Twig-rendertemplate te registreren; declareer daarna het overeenkomstige type aan de kant van de administration (Vue-bewerkingscomponent).

Privacy (AVG)

De blokken met inhoud van derden gebruiken een toestemmingsfaçade: de video van YouTube (youtube-nocookie) of Vimeo (dnt=1) wordt pas na een expliciete klik geladen, er is dus geen enkele externe aanroep bij het laden van de pagina. Formulieren vereisen een AVG-toestemming en de inzendingen worden automatisch opgeschoond volgens de ingestelde bewaartermijn.

Bekende beperkingen van v1

• De editor in de administration is structureel (canvas met blokken), geen WYSIWYG in een iframe van de echte storefront.
• Handmatig publiceren kopieert het concept naar de gepubliceerde versie; geplande publicatie dekt alle talen.
• Nog niet inbegrepen: kant-en-klare paginasjablonen, gesynchroniseerde globale blokken, zichtbaarheidsregels (Rule Builder), import en export, responsieve overschrijvingen per breekpunt en een AI-assistent.

Verwijderen

Bij het verwijderen worden de tabellen van de 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) verwijderd, behalve wanneer de optie “gebruikersgegevens behouden” is aangevinkt.

Probleemoplossing

• Een gepubliceerde pagina geeft 404: controleer of de pagina daadwerkelijk de status “gepubliceerd” heeft, of haar slug juist is en of ze aan het huidige verkoopkanaal is toegewezen.
• De administratiemodule laadt niet: voer bin/build-administration.sh, assets:install en daarna cache:clear opnieuw uit, en forceer het herladen van de browser (Ctrl+F5).
• De voorbeeldlink is ongeldig of verlopen: genereer hem opnieuw; controleer of APP_SECRET is ingesteld en verhoog zo nodig de levensduur van het token in de configuratie.
• De geplande publicatie start niet: controleer of de Shopware-worker (Messenger / scheduled tasks) draait; de taak wordt elke 5 minuten uitgevoerd.
• De formulierinzendingen worden niet opgeschoond: controleer de waarde van de bewaartermijn in de configuratie (0 = onbeperkt) en of de opschoontaak daadwerkelijk is ingepland.