DataFirefly Page Builder dla Shopware 6.7: instalacja, konfiguracja i dokumentacja techniczna

Wprowadzenie

DataFirefly Page Builder to samodzielny wizualny edytor stron dla Shopware 6.7. Posiada własny silnik renderowania storefrontu (Twig) i działa niezależnie od natywnego CMS “Shopping Experiences”. Strony budujesz z sekcji i kolumn, a następnie wypełniasz kolumny blokami metodą przeciągnij i upuść, bez pisania kodu.

Edytor działa w administracji na Vue 3 / Pinia (build Vite z 6.7) i oferuje przeciąganie, przesuwanie w górę/dół, duplikowanie oraz undo/redo. Treść jest zapisywana jako wersjonowany JSON: szkic roboczy odrębny od wersji opublikowanej, historia wersji tworzona przy każdej publikacji, publikacja planowana i podpisane, udostępnialne linki podglądu. Opublikowane strony są serwowane pod /p/{slug} z aktywnym cache HTTP Shopware i obsługują wielojęzyczność oraz wiele kanałów sprzedaży.

Wymagania

• Shopware ≥ 6.7.0 (shopware/core, shopware/storefront i shopware/administration w ~6.7.0)
• PHP ≥ 8.2
• MySQL 8 / MariaDB 10.11+
• Dostęp do wiersza poleceń w celu instalacji pluginu, kompilacji zasobów i czyszczenia cache
• Zdefiniowana zmienna środowiskowa APP_SECRET: służy do podpisywania linków podglądu

Instalacja

1. Skopiuj katalog DataFireflyPageBuilder do custom/plugins/ swojej instancji (lub prześlij ZIP przez Rozszerzenia → Moje rozszerzenia → Prześlij rozszerzenie).
2. Odśwież listę pluginów, zainstaluj i aktywuj rozszerzenie.
3. Skompiluj administrację i storefront, a następnie wyczyść 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

Tworzenie i edycja strony

Otwórz administrację, potem Treści → Page Builder i kliknij “Utwórz stronę”. Edycja jest podzielona na dwie zakładki.

Zakładka Edytor

Najpierw dodaj sekcję (z wyborem układu kolumn), a następnie upuść bloki w kolumnach. Każdy blok można przeciągnąć, przesunąć w górę lub w dół, zduplikować albo usunąć, a wszystkie akcje są odwracalne (undo/redo). Canvas pokazuje wizualne podglądy na żywo: obrazy, miniatury galerii, tekst sformatowany, przyciski, nazwy produktów i pola formularzy.

Zakładka Ustawienia i SEO

Definiujesz tam nazwę strony, jej slug, status, planowanie, przypisane kanały sprzedaży, meta title, meta description i opcję noindex. Slug jest generowany automatycznie z nazwy, jego unikalność jest walidowana per język, a każda zmiana sluga tworzy automatyczne przekierowanie 301 ze starego adresu.

Dostępne bloki

Builder dostarcza 15 typów bloków, zadeklarowanych w BlockRegistry:

• Struktura i tekst: nagłówek, tekst sformatowany (edycja WYSIWYG przez sw-text-editor), separator, odstęp, cytat.
• Media: obraz, galeria (selektor wielu obrazów), wideo (fasada RODO YouTube/Vimeo), HTML/embed.
• Interakcja: przycisk, akordeon (wizualny edytor pozycji), licznik odliczający, formularz (wizualny edytor pól).
• E-commerce: pojedynczy produkt i listing produktów.

Publikacja, planowanie i wersjonowanie

Strona ma cztery statusy: draft (szkic), scheduled (zaplanowana), published (opublikowana) i archived (zarchiwizowana).

• Zapisz szkic aktualizuje treść roboczą (draftContent) bez dotykania wersji online.
• Publikuj kopiuje szkic do wersji opublikowanej (publishedContent) i tworzy wersję w historii. Publikacja z administracji obejmuje wszystkie języki naraz, z ostrzeżeniem, gdy brakuje tłumaczenia.
• Planuj: przełącz stronę w status “Zaplanowana” z datą; zadanie cykliczne uruchamiane co 5 minut automatycznie publikuje strony, których termin nadszedł (wszystkie języki).

Podgląd

Przycisk Podgląd otwiera storefront przez podpisany i wygasający link (/dfpb/preview/{pageId}?token=…): szkic jest widoczny bez konta administratora, strona nigdy nie trafia do cache i zwraca nagłówek X-Robots-Tag: noindex, nofollow.

Wielojęzyczność i wiele kanałów

Nazwa, slug, pola SEO i treść są tłumaczalne per język Shopware. Stronę przypisuje się do jednego lub wielu kanałów sprzedaży; jest serwowana pod /p/{slug} tylko dla kanałów, do których należy, w języku bieżącego kontekstu.

SEO

Per strona i per język zarządzasz meta title, meta description i indeksowaniem (noindex). Kontroler storefrontu wstrzykuje te metadane do renderowanej strony i wymusza noindex,nofollow w podglądzie. Zmiany sluga generują przekierowania 301, aby zachować pozycjonowanie.

Konfiguracja

Przejdź do Rozszerzenia → Moje rozszerzenia → DataFirefly Page Builder → Konfiguracja. Karta Ogólne udostępnia dwa ustawienia:

• Czas życia linku podglądu (previewTokenLifetime, domyślnie: 3600 sekund).
• Retencja zgłoszeń z formularzy (submissionRetentionDays, domyślnie: 90 dni; 0 = przechowywanie bezterminowe).

Formularze

Blok formularza konfiguruje się wizualnym edytorem pól i zawiera ochronę antyspamową przez honeypot i pułapkę czasową oraz obowiązkową zgodę RODO. Zgłoszenia są zapisywane w bazie z automatycznym czyszczeniem według skonfigurowanej retencji. Przy każdym wysłaniu wyzwalane jest zdarzenie FormSubmittedEvent, do którego możesz podpiąć swoje integracje (Flow Builder, e-mail, webhook itd.).

Architektura techniczna

Plugin trzyma się konwencji Shopware 6.7: encje deklarowane przez Data Abstraction Layer (DAL), treść przechowywana jako wersjonowany JSON, kontrolery storefrontu i API, zadania cykliczne Messenger i migracje SQL.

Encje i Data Abstraction Layer

Główna encja datafirefly_pb_page (PageDefinition) zawiera status, daty publishedAt/scheduledAt, opcję noIndex oraz pola tłumaczalne name, slug, metaTitle, metaDescription, draftContent i publishedContent. Jest powiązana relacją ManyToMany z kanałami sprzedaży i OneToMany ze swoimi wersjami (z CascadeDelete). Sześć encji pluginu używa prefiksu datafirefly_pb_:

• datafirefly_pb_page i datafirefly_pb_page_translation: strona i jej tłumaczenia.
• datafirefly_pb_page_sales_channel: przypisanie do kanałów sprzedaży.
• datafirefly_pb_page_version: snapshoty treści tworzone przy publikacji.
• datafirefly_pb_saved_block: zapisane bloki wielokrotnego użytku.
• datafirefly_pb_form_submission: zgłoszenia z formularzy.

Treść strony to strukturalny, wersjonowany JSON (schemaVersion) umożliwiający przyszłe migracje. Schemat inicjalizują dwie migracje: Migration1781222400InitialSchema i Migration1781222402SlugRedirect (tabela przekierowań slugów).

Trasy

Kontrolery są importowane przez atrybuty (Resources/config/routes.xml).

• GET /p/{slug} → frontend.dfpb.page.detail: renderuje opublikowaną stronę (aktywny cache HTTP). Jeśli slug już nie pasuje, następuje przekierowanie 301 na nowy slug przez tabelę przekierowań.
• GET /dfpb/preview/{pageId}?token=… → frontend.dfpb.page.preview: renderowanie szkicu z podpisanym tokenem, bez cache, z noindex,nofollow.
• GET /api/_action/dfpb/preview-token/{pageId}: generuje token podglądu (ACL datafirefly_pb_page:read).
• POST /api/_action/dfpb/publish/{pageId}: publikuje stronę (ACL datafirefly_pb_page:update).

Zadania cykliczne

• PublishScheduledPagesTask: publikuje zaplanowane strony, których termin nadszedł (wykonanie co 5 minut).
• CleanupFormSubmissionsTask: czyści zgłoszenia z formularzy starsze niż skonfigurowana retencja.

Kontrola dostępu (ACL)

Plugin deklaruje uprawnienia wokół encji strony: datafirefly_pb_page.viewer, .editor, .creator i .deleter, plus odrębne uprawnienie editor_html wymagane do edycji bloku HTML. Shopware składa role administratorów z tych uprawnień.

Bezpieczeństwo i sanityzacja

Każda treść sformatowana jest oczyszczana po stronie serwera przez filtr Twig dfpb_sanitize (whitelist tagów), same typy bloków podlegają whiteliście, a style inline są filtrowane wyrażeniem regularnym. JSON strony nigdy nie może wstrzyknąć surowego Twiga; przy renderowaniu obowiązuje domyślne escapowanie Twig. Tokeny podglądu są podpisane (HMAC przez APP_SECRET) i wygasające.

Rozszerzanie przez pluginy firm trzecich

Aby dodać własny blok, udekoruj serwis DataFirefly\PageBuilder\Service\BlockRegistry i wywołaj register(type, template, label), aby zarejestrować typ i jego szablon renderujący Twig, a następnie zadeklaruj odpowiedni typ po stronie administracji (komponent edycji Vue).

Prywatność (RODO)

Bloki z treścią firm trzecich używają fasady zgody: wideo YouTube (youtube-nocookie) lub Vimeo (dnt=1) ładuje się dopiero po jawnym kliknięciu, bez żadnego wywołania zewnętrznego przy ładowaniu strony. Formularze wymuszają zgodę RODO, a zgłoszenia podlegają automatycznemu czyszczeniu według skonfigurowanej retencji.

Znane ograniczenia wersji 1

• Edytor administracji jest strukturalny (canvas z bloków), a nie WYSIWYG w iframe rzeczywistego storefrontu.
• Publikacja ręczna kopiuje szkic do wersji opublikowanej; publikacja planowana obejmuje wszystkie języki.
• Nie są jeszcze dostępne: gotowe szablony stron, zsynchronizowane bloki globalne, reguły widoczności (Rule Builder), import/eksport, nadpisania responsywne per breakpoint i asystent AI.

Odinstalowanie

Przy odinstalowaniu tabele pluginu (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ą usuwane, chyba że zaznaczono opcję “zachowaj dane użytkownika”.

Rozwiązywanie problemów

• Opublikowana strona zwraca 404: sprawdź, czy strona ma status “opublikowana”, czy jej slug jest poprawny i czy jest przypisana do bieżącego kanału sprzedaży.
• Moduł administracji się nie ładuje: uruchom ponownie bin/build-administration.sh, assets:install, potem cache:clear i wymuś przeładowanie przeglądarki (Ctrl+F5).
• Link podglądu jest nieprawidłowy lub wygasł: wygeneruj go ponownie; sprawdź, czy APP_SECRET jest zdefiniowany, i w razie potrzeby zwiększ czas życia tokena w konfiguracji.
• Publikacja planowana się nie uruchamia: upewnij się, że worker Shopware (Messenger / scheduled tasks) działa; zadanie wykonuje się co 5 minut.
• Zgłoszenia z formularzy nie są czyszczone: sprawdź wartość retencji w konfiguracji (0 = bezterminowo) oraz czy zadanie czyszczące jest zaplanowane.