# 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…

- Strona: <https://www.datafirefly.com/pl/documentation/datafirefly-page-builder-shopware/>
- Język: pl
- Zaktualizowano: 2026-07-29
- Inne języki: [fr](https://www.datafirefly.com/documentation/datafirefly-page-builder-shopware/index.md), [en](https://www.datafirefly.com/en/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), [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)
- Indeks: <https://www.datafirefly.com/pl/documentation/llms.txt>

## 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.

Ten moduł jest **pluginem** (kod PHP). Instaluje się więc na Shopware **self-hosted** i **PaaS**, nie na Shopware Cloud (SaaS), zarezerwowanym dla appek.

## 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
```

Po instalacji lub aktualizacji wyczyść także cache przeglądarki (Ctrl+F5) na stronie administracji, aby przeładować moduł.

## 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.

Blok **HTML** pozwala wstawiać dowolny kod: jest zarezerwowany dla dedykowanego uprawnienia ACL (`editor_html`), a jego zawartość przechodzi przez sanityzację serwerową.

## 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`.

Link podglądu otwiera się na hoście administracji. Jeśli Twój storefront działa na innej domenie, przenieś link na właściwą domenę. Czas ważności linku ustawiasz w konfiguracji (domyślnie: 3600 s).

## 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.