DataFirefly Page Builder per Shopware 6.7 — Installazione, configurazione e documentazione tecnica

Panoramica

Il DataFirefly Page Builder è un editor di pagine visuale autonomo per Shopware 6.7. Include un proprio motore di rendering storefront (Twig) e funziona indipendentemente dal CMS nativo «Shopping Experiences». Componi le pagine tramite sezioni e colonne, quindi riempi quelle colonne con blocchi in drag & drop, senza scrivere codice.

L’editor gira nell’amministrazione in Vue 3 / Pinia (build Vite della 6.7) e offre drag & drop, sposta su/giù, duplicazione e annulla/ripeti. Il contenuto è salvato come JSON versionato: una bozza di lavoro separata dalla versione pubblicata, una cronologia delle versioni creata a ogni pubblicazione, pubblicazione pianificata e link di anteprima firmati e condivisibili. Le pagine pubblicate sono servite su /p/{slug} con la cache HTTP di Shopware attiva, e supportano multilingua e multi-canale.

Requisiti

• Shopware ≥ 6.7.0 (shopware/core, shopware/storefront e shopware/administration in ~6.7.0)
• PHP ≥ 8.2
• MySQL 8 / MariaDB 10.11+
• Accesso alla riga di comando per installare il plugin, compilare gli asset e svuotare la cache
• Variabile d’ambiente APP_SECRET definita — serve a firmare i link di anteprima

Installazione

1. Copia la cartella DataFireflyPageBuilder in custom/plugins/ della tua istanza (oppure carica lo ZIP da Estensioni → Le mie estensioni → Carica estensione).
2. Aggiorna l’elenco dei plugin, installa e attiva l’estensione.
3. Compila l’amministrazione e lo storefront, poi svuota la 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

Creare e modificare una pagina

Apri l’amministrazione, vai su Contenuti → Page Builder e clicca su «Crea pagina». La modifica è suddivisa in due schede.

Scheda Editor

Aggiungi prima una sezione (con scelta della disposizione delle colonne), poi rilascia i blocchi nelle colonne. Ogni blocco può essere trascinato, spostato su o giù, duplicato o eliminato, e tutte le azioni sono annullabili/ripetibili. Il canvas mostra anteprime visive in tempo reale: immagini, miniature della galleria, testo formattato, pulsanti, nomi dei prodotti e campi del modulo.

Scheda Impostazioni e SEO

Qui definisci il nome della pagina, il suo slug, lo stato, la pianificazione, i canali di vendita assegnati, il meta titolo, la meta descrizione e l’opzione noindex. Lo slug è generato automaticamente dal nome, la sua univocità è validata per lingua, e qualsiasi modifica dello slug crea un redirect 301 automatico dal vecchio URL.

Blocchi disponibili

Il builder include 15 tipi di blocco, dichiarati nel BlockRegistry:

• Struttura e testo: titolo, testo formattato (modifica WYSIWYG tramite sw-text-editor), divisore, spaziatore, citazione.
• Media: immagine, galleria (selettore multi-immagine), video (facciata GDPR YouTube/Vimeo), HTML/embed.
• Interazione: pulsante, accordion (editor visuale degli elementi), conto alla rovescia, modulo (editor visuale dei campi).
• E-commerce: prodotto singolo ed elenco prodotti.

Pubblicare, pianificare e versionare

Una pagina ha quattro stati: draft (bozza), scheduled (pianificata), published (pubblicata) e archived (archiviata).

• Salva bozza aggiorna il contenuto di lavoro (draftContent) senza toccare la versione online.
• Pubblica copia la bozza nella versione pubblicata (publishedContent) e crea una versione di cronologia. La pubblicazione dall’amministrazione elabora tutte le lingue in una volta, con un avviso se manca una traduzione.
• Pianifica: imposta la pagina sullo stato «Pianificata» con una data; un’attività pianificata viene eseguita ogni 5 minuti per pubblicare automaticamente le pagine scadute (tutte le lingue).

Anteprima

Il pulsante Anteprima apre lo storefront tramite un link firmato e con scadenza (/dfpb/preview/{pageId}?token=…): la bozza è visibile senza account amministratore, la pagina non viene mai memorizzata in cache e restituisce un header X-Robots-Tag: noindex, nofollow.

Multilingua e multi-canale

Nome, slug, campi SEO e contenuto sono traducibili per lingua Shopware. Una pagina si assegna a uno o più canali di vendita; viene servita su /p/{slug} solo per i canali a cui è associata, nella lingua del contesto corrente.

SEO

Per pagina e per lingua gestisci il meta titolo, la meta descrizione e l’indicizzazione (noindex). Il controller storefront inietta questi metadati nella pagina renderizzata e forza noindex,nofollow in anteprima. Le modifiche dello slug generano redirect 301 per preservare il posizionamento.

Configurazione

Vai su Estensioni → Le mie estensioni → DataFirefly Page Builder → Configurazione. La scheda Generale espone due impostazioni:

• Validità del link di anteprima (previewTokenLifetime, predefinito: 3600 secondi).
• Conservazione degli invii dei moduli (submissionRetentionDays, predefinito: 90 giorni; 0 = conservazione illimitata).

Moduli

Il blocco modulo si configura con un editor visuale dei campi e integra protezione anti-spam tramite honeypot e trappola temporale, oltre a un consenso GDPR obbligatorio. Gli invii sono memorizzati nel database con pulizia automatica in base alla conservazione configurata. A ogni invio viene emesso un evento FormSubmittedEvent per collegare le tue integrazioni (Flow Builder, email, webhook, ecc.).

Architettura tecnica

Il plugin segue le convenzioni di Shopware 6.7: entità dichiarate tramite la Data Abstraction Layer (DAL), contenuto memorizzato come JSON versionato, controller storefront e API, attività pianificate Messenger e migrazioni SQL.

Entità e Data Abstraction Layer

L’entità principale datafirefly_pb_page (PageDefinition) porta lo stato, le date publishedAt/scheduledAt, l’opzione noIndex, e i campi traducibili name, slug, metaTitle, metaDescription, draftContent e publishedContent. È associata ManyToMany ai canali di vendita e OneToMany alle sue versioni (con CascadeDelete). Le sei entità del plugin usano il prefisso datafirefly_pb_:

• datafirefly_pb_page e datafirefly_pb_page_translation: la pagina e le sue traduzioni.
• datafirefly_pb_page_sales_channel: assegnazione ai canali di vendita.
• datafirefly_pb_page_version: snapshot del contenuto creati alla pubblicazione.
• datafirefly_pb_saved_block: blocchi salvati riutilizzabili.
• datafirefly_pb_form_submission: invii dei moduli.

Il contenuto della pagina è JSON strutturato e versionato (schemaVersion) per consentire migrazioni future. Due migrazioni inizializzano lo schema: Migration1781222400InitialSchema e Migration1781222402SlugRedirect (tabella dei redirect di slug).

Route

I controller sono importati per attributi (Resources/config/routes.xml).

• GET /p/{slug} → frontend.dfpb.page.detail: renderizza la pagina pubblicata (cache HTTP attiva). Se lo slug non corrisponde più, viene emesso un redirect 301 al nuovo slug tramite la tabella dei redirect.
• GET /dfpb/preview/{pageId}?token=… → frontend.dfpb.page.preview: renderizza la bozza con token firmato, senza cache, come noindex,nofollow.
• GET /api/_action/dfpb/preview-token/{pageId}: genera un token di anteprima (ACL datafirefly_pb_page:read).
• POST /api/_action/dfpb/publish/{pageId}: pubblica la pagina (ACL datafirefly_pb_page:update).

Attività pianificate

• PublishScheduledPagesTask: pubblica le pagine pianificate scadute (viene eseguita ogni 5 minuti).
• CleanupFormSubmissionsTask: elimina gli invii dei moduli oltre la conservazione configurata.

Controllo degli accessi (ACL)

Il plugin dichiara privilegi attorno all’entità pagina: datafirefly_pb_page.viewer, .editor, .creator e .deleter, più un privilegio separato editor_html richiesto per modificare il blocco HTML. Shopware compone i ruoli di amministrazione a partire da questi privilegi.

Sicurezza e sanitizzazione

Tutto il contenuto formattato viene sanitizzato lato server tramite il filtro Twig dfpb_sanitize (whitelist di tag), i tipi di blocco sono a loro volta soggetti a una whitelist, e gli stili inline sono filtrati tramite espressione regolare. Il JSON della pagina non può mai iniettare Twig grezzo; l’escaping predefinito di Twig si applica al rendering. I token di anteprima sono firmati (HMAC tramite APP_SECRET) e scadono.

Estensione tramite plugin di terze parti

Per aggiungere un blocco personalizzato, decora il servizio DataFirefly\PageBuilder\Service\BlockRegistry e chiama register(type, template, label) per registrare il tipo e il suo template Twig di rendering, quindi dichiara il tipo corrispondente lato amministrazione (componente di modifica Vue).

Privacy (GDPR)

I blocchi con contenuti di terze parti usano una facciata di consenso: il video di YouTube (youtube-nocookie) o Vimeo (dnt=1) viene caricato solo dopo un clic esplicito — nessuna chiamata a terzi al caricamento della pagina. I moduli richiedono il consenso GDPR, e gli invii sono soggetti a pulizia automatica in base alla conservazione configurata.

Limitazioni note della v1

• L’editor di amministrazione è strutturale (canvas a blocchi), non un WYSIWYG in iframe dello storefront reale.
• La pubblicazione manuale copia la bozza nella versione pubblicata; la pubblicazione pianificata copre tutte le lingue.
• Non ancora inclusi: template di pagina pronti all’uso, blocchi globali sincronizzati, regole di visibilità (Rule Builder), import/export, override responsive per breakpoint e assistente IA.

Disinstallazione

Alla disinstallazione, le tabelle 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) vengono eliminate — salvo che sia selezionata l’opzione «conserva i dati utente».

Risoluzione dei problemi

• Una pagina pubblicata restituisce 404: verifica che la pagina sia in stato «pubblicata», che il suo slug sia corretto e che sia assegnata al canale di vendita corrente.
• Il modulo di amministrazione non si carica: riesegui bin/build-administration.sh, assets:install e poi cache:clear, e forza il ricaricamento del browser (Ctrl+F5).
• Il link di anteprima è non valido o scaduto: rigeneralo; verifica che APP_SECRET sia definito e, se necessario, aumenta la validità del token nella configurazione.
• La pubblicazione pianificata non si attiva: assicurati che il worker di Shopware (Messenger / attività pianificate) sia in esecuzione; l’attività viene eseguita ogni 5 minuti.
• Gli invii dei moduli non vengono eliminati: verifica il valore di conservazione nella configurazione (0 = illimitato) e che l’attività di pulizia sia pianificata.