Jak to działa

To jest najważniejsza strona w dokumentacji. Przeczytaj ją zanim zaczniesz konfigurować — niemal każde pytanie “plugin nie działa” okazuje się nieporozumieniem opisanego tu modelu.

Model myślowy: zastępowanie, nie przypisanie

Shopware natywnie wspiera jeden layout CMS per kategoria, per produkt, per strona docelowa. Plugin tego nie zmienia — nie pozwala przypisać wielu layoutów do jednej kategorii. Zamiast tego działa w czasie requesta jako warstwa zastępowania:

1. Shopware ładuje stronę i ustala bazowy layout w normalny sposób — ten, który ustawiłeś na kategorii (lub produkcie, lub stronie docelowej).
2. Plugin patrzy na każdy layout, do którego przypisane są reguły.
3. Jeśli reguła pasuje do bieżącego requesta (kanał sprzedaży, klient, data itd.), plugin podmienia bazowy layout na tę alternatywę i renderuje alternatywę.
4. Jeśli żadna reguła nie pasuje, bazowy layout jest renderowany jak zwykle.

Kluczowa konsekwencja: każda kategoria, produkt lub strona docelowa, na którą plugin ma reagować, musi już mieć przypisany bazowy layout przez normalne UI Shopware. Jeśli kategoria nie ma layoutu CMS, plugin nie ma czego zastąpić, a strona nie wyrenderuje się poprawnie.

Uwaga

Usunięcie layoutu z kategorii nie oznacza “pozwól pluginowi wybrać”. Oznacza “brak layoutu”. Plugin zastępuje bazę — nie wybiera jej z niczego.

Trzy gałki

Dla każdego z trzech rodzajów stron — Produkt, Kategoria (nawigacja), Strona docelowa — plugin udostępnia trzy gałki:

1. Tryb zastępowania (Replacement mode) — kiedy bazowy layout kwalifikuje się do zastąpienia?
2. Wymienne layouty (Replaceable layouts) — (istotne tylko dla trybu “Assigned to replaceable layouts”) jawna lista bazowych layoutów dopuszczonych do zastąpienia.
3. Typy zastępowania (Replacement types) — jakie typy stron CMS mogą działać jako zastępstwo? (np. czy layout typu landingpage może zastąpić bazę typu product_list?)

Wszystkie trzy znajdziesz w Settings → Extensions → Advanced Layouts Assigner.

Tryby zastępowania

Tryb kontroluje czy plugin w ogóle próbuje zastąpić dany bazowy layout. Opcje różnią się nieco zależnie od rodzaju strony:

Rodzaj strony	Opcje
Product page	Without assigned layout · Assigned to replaceable layouts · Without assigned layout or assigned to replaceable layouts · All
Category page	With default layout · Assigned to replaceable layouts · All
Landing page	With default layout · Assigned to replaceable layouts · All

• Without assigned layout (tylko Product page) — zastąp tylko gdy produkt sam nie ma przypisanego specyficznego layoutu (i Shopware użyłby layoutu domyślnego).
• With default layout (Category / Landing page) — zastąp tylko gdy strona używa skonfigurowanego layoutu domyślnego Shopware (ustawionego w Settings → Shopping Experiences → Default layouts). Niestandardowe layouty per-kategoria nie są ruszane.
• Assigned to replaceable layouts — zastąp tylko gdy bazowy layout jest na liście Replaceable layouts for … jawnie pod selektorem trybu.
• All — zastąp dowolny bazowy layout, gdy reguła pasuje. Najprostsze i właściwe gdy chcesz, by wszystkie strony kategorii w danym kanale sprzedaży używały innego layoutu. To tryb zalecany przez przepis na wiele kanałów sprzedaży.

Zobacz Tryby zastępowania dla pełnej macierzy i przykładów.

Typy zastępowania

Nawet gdy bazowy layout kwalifikuje się do zastąpienia, plugin musi zdecydować, które alternatywne layouty rozważyć. Ta decyzja jest ograniczona kartą Replacement types na dole strony ustawień. Dla każdego “przychodzącego” rodzaju strony listujesz typy stron CMS, które mogą być alternatywami:

Strona przychodząca	Domyślne typy zastępowania	Można rozszerzyć do
Product page	product_detail	page, landingpage, product_list
Shop page (page)	page	landingpage, product_list
Landing page	landingpage	page, product_list
Listing page (product_list)	product_list	page, landingpage

Jeśli odpowiedni wpis jest pusty, plugin w ogóle nie szuka alternatyw dla tego rodzaju strony — nawet jeśli reguły pasują. Procedura post-install seeduje oczywisty typ jako domyślny dla każdego rodzaju, więc tę listę zazwyczaj rozszerzasz tylko gdy chcesz np. żeby layout strony docelowej zastąpił listing.

Reguły przypisane do layoutu

Właściwe dopasowanie wykonuje się przez reguły przypisane do alternatywnego layoutu, a nie do kategorii lub produktu. Aby przypisać reguły:

1. Content → Shopping Experiences → otwórz layout
2. Layout assignment w prawym sidebar
3. Przycisk Assign layout
4. Zakładka Rules (dodana przez ten plugin, znajduje się obok Categories / Products / Landing pages)
5. Wybierz reguły i Confirm.

Layout jest kandydatem na zastępstwo tylko jeśli wszystkie jego przypisane reguły pasują do bieżącego requesta (reguły są łączone AND-em). Wewnątrz pojedynczej reguły obowiązuje standardowa logika kontenerów Shopware (kontenery AND, OR itp.).

Pętla dopasowania, krok po kroku

Konkretnie, gdy klient trafia na stronę kategorii w danym kanale sprzedaży:

1. Shopware ładuje stronę i bazowy layout przypisany do kategorii.
2. Plugin oblicza typy zastępowania dozwolone dla tego typu bazy (np. dla product_list → wpis Listing page w Replacement types).
3. Plugin sprawdza tryb zastępowania dla stron kategorii:
   • With default layout → kontynuuj tylko jeśli bazowy layout to layout domyślny Shopware.
   • Assigned to replaceable layouts → kontynuuj tylko jeśli bazowy layout jest na liście Replaceable layouts for category pages.
   • All → kontynuuj.
   • W przeciwnym razie → wróć, brak zastąpienia.
4. Plugin ładuje każdą stronę CMS z przypisanymi regułami, posortowane po rule.priority (najniższy priorytet pierwszy, zgodnie z własnym sortowaniem reguł Shopware). Przechodzi je w stronach po 100 (do twardego limitu — zobacz Wydajność).
5. Dla każdego kandydata ewaluuje wszystkie przypisane reguły względem bieżącego requesta (kanał sprzedaży, navigation id, klient, data itd.).
6. Pierwszy kandydat, którego reguły wszystkie pasują, zostaje użyty. Plugin re-renderuje layout dla strony i przekazuje go Shopware.
7. Jeśli nic nie pasuje, bazowy layout pozostaje.

Ta sama pętla działa dla produktów (przez ProductPageLoadedEvent) i stron docelowych (przez LandingPageLoadedEvent), z ich odpowiednimi trybami zastępowania i typami.

Trzy własne warunki reguł

Oprócz natywnych warunków reguł Shopware, plugin dodaje trzy własne:

• Is homepage [P2Lab Layouts Assigner] — pasuje tylko na navigation root kanału sprzedaży (jego stronie głównej). Zobacz ostrzeżenie o łączeniu go z innymi warunkami.
• Item in category [P2Lab Layouts Assigner] — pasuje, gdy oglądany produkt lub kategoria jest jedną z wymienionych kategorii (lub się w nich znajduje).
• Item in category with children [P2Lab Layouts Assigner] — to samo, ale matchuje też kategorie potomne (używa path kategorii do przejścia drzewa).

Zobacz Własne warunki reguł dla szczegółów.

Konfiguracja per kanał sprzedaży

Każde ustawienie w formularzu konfiguracji plugina jest per kanał sprzedaży. Użyj przełącznika kanału sprzedaży na górze Settings → Extensions → Advanced Layouts Assigner, aby utrzymywać różne tryby zastępowania, wymienne layouty i typy zastępowania per kanał — z fallbackiem do scope’u “All sales channels” dla wspólnych wartości domyślnych.

W ten sposób plugin pozwala temu samemu drzewu kategorii być używanemu przez dwa kanały sprzedaży z zupełnie różnymi strategiami layoutów.

Dalej: przejdź to praktycznie

Skoro model jest jasny, przejdź minimalny przykład: Pierwsze zastąpienie layoutu.