# Kreator Zestawów (Mix and Match): kompletny przewodnik

> Wprowadzenie Box Builder (Mix and Match) (dfboxbuilder) dodaje stronę, na której klienci składają własny zestaw z wybranych przez Ciebie produktów. Wybierają pozycje w siatce, śledzą pasek postępu, widzą aktualizowaną cenę…

- Strona: <https://www.datafirefly.com/pl/documentation/dfboxbuilder/>
- Język: pl
- Zaktualizowano: 2026-10-13
- Inne języki: [fr](https://www.datafirefly.com/documentation/dfboxbuilder/index.md), [en](https://www.datafirefly.com/en/documentation/dfboxbuilder/index.md), [es](https://www.datafirefly.com/es/documentation/dfboxbuilder/index.md), [de](https://www.datafirefly.com/de/documentation/dfboxbuilder/index.md), [it](https://www.datafirefly.com/it/documentation/dfboxbuilder/index.md), [nl](https://www.datafirefly.com/nl/documentation/dfboxbuilder/index.md), [pt](https://www.datafirefly.com/pt/documentation/dfboxbuilder/index.md)
- Indeks: <https://www.datafirefly.com/pl/documentation/llms.txt>

## Wprowadzenie

**Box Builder (Mix and Match)** (`dfboxbuilder`) dodaje stronę, na której klienci **składają własny zestaw** z wybranych przez Ciebie produktów. Wybierają pozycje w siatce, śledzą pasek postępu, widzą aktualizowaną cenę zestawu i oszczędność, a następnie dodają zestaw do koszyka. Zestaw wypełnia się według liczby sztuk lub na wagę. Każdy zestaw to jedna linia koszyka z własną ceną; jego zawartość jest czytelna w koszyku, w zamówieniu i na fakturze.

Twórz tyle zestawów, ile potrzebujesz, każdy z własnymi produktami, zasadami, modelem ceny i okresem sprzedaży. Ten sam katalog może zasilać bardzo różne zestawy (zestaw na aperitif, zestaw świąteczny, pudełko czekoladek na wagę, pakiet próbny...).

## Zgodność

- PrestaShop 8.x i 9.x
- PHP 7.4 do 8.x
- Pojedynczy sklep i multistore
- Interfejs modułu po francusku, angielsku, hiszpańsku, niemiecku i włosku; w pozostałych językach teksty modułu wyświetlają się po angielsku (można je przetłumaczyć w PrestaShop)
- Motyw Classic, Hummingbird i motywy własne (konfigurator w czystym JavaScript, bez jQuery)
- Brak zależności (bez Composera i frameworków)

## Instalacja i aktualizacja

1. W panelu otwórz **Moduły > Menedżer modułów**.
2. Kliknij **Załaduj moduł** i wybierz `dfboxbuilder.zip`.
3. Otwórz pozycję **Box Builder** dodaną do menu, aby utworzyć pierwszy zestaw.

Aby zaktualizować, załaduj nowy plik ZIP w ten sam sposób: skrypty aktualizacji uruchomią się automatycznie (nowe kolumny, nowe hooki, przyjazne adresy URL wygenerowane z nazw zestawów). Istniejące zestawy nadal wypełniają się według liczby sztuk.

Przy pierwszym zapisie zestawu moduł tworzy **produkt techniczny**, który przenosi zestaw w koszyku. Domyślnie jest ukryty; możesz go pokazać w kategoriach (zobacz _Wyświetlanie w katalogu_). Jego karta produktu zawsze przekierowuje do konfiguratora. Usunięcie zestawu usuwa też ten produkt.

## Ustawienia modułu

Panel **Settings** nad listą zestawów zawiera trzy opcje:

- **Zestawy na stronie głównej**: blok w hooku `displayHome`.
- **Kolor akcentu**: kolor paska postępu, zakładek kroków i wyróżnień. Wpisz główny kolor motywu (na przykład `#8a5a2b`); pozostaw puste dla domyślnego niebieskiego. Kolor tekstu na tym tle jest dobierany automatycznie, aby był czytelny.
- **Po dodaniu zestawu do koszyka**: przejście do strony koszyka (domyślnie) lub pozostanie w konfiguratorze. W drugim przypadku blok koszyka motywu odświeża się i otwiera okno potwierdzenia, a klient może skomponować kolejny zestaw.

Na liście zestawów menu każdego wiersza zawiera **Open the builder page** (otwarcie strony konfiguratora) i **Duplicate** (duplikowanie). Kopia przejmuje ceny, stawki malejące, sloty, źródła, szablony, ograniczenia i grupy; jest tworzona jako nieaktywna. Dla zestawu na wagę kolumny Min i Max pokazują wagi.

## Tworzenie zestawu

Formularz zestawu ma sześć zakładek.

### Ogólne

- **Nazwa, opis, etykieta przycisku**: dla każdego języka.
- **Przyjazny URL**: dla każdego języka, generowany z nazwy, jeśli pole jest puste. Przy włączonych przyjaznych adresach URL strona zestawu ma adres `/box/ID-przyjazny-url`.
- **Sposób wypełniania** (_Fill the box by_): liczba pozycji (_Number of items_, domyślnie) lub waga (_Weight_), zobacz _Zestawy na wagę_.
- **Minimalna / maksymalna liczba pozycji** (wypełnianie według liczby sztuk): granice zestawu (0 = brak maksimum).
- **Waga minimalna / maksymalna** (wypełnianie na wagę): w jednostce wagi sklepu; 0 = brak maksimum, ta sama wartość oznacza dokładną wagę.
- **Zezwolenie na tę samą pozycję kilka razy** i **maksymalna liczba sztuk na pozycję**.
- **Ukrywanie produktów niedostępnych**: w przeciwnym razie są widoczne, ale nie można ich dodać.
- **Losowe wypełnienie**, **zapis i udostępnianie**, **aktywność** zestawu.

### Dostępność

- **Dostępny od / do**: okres sprzedaży. Przed datą rozpoczęcia strona zestawu informuje o dacie dostępności; po dacie zakończenia zestaw jest usuwany z koszyków, które jeszcze go zawierają.
- **Limitowany nakład (zestawy)**: maksymalna liczba sprzedanych zestawów we wszystkich sklepach, bez anulowanych zamówień (0 = bez limitu). Formularz pokazuje liczbę sprzedanych i pozostałych; strona zestawu pokazuje liczbę pozostałych sztuk.
- **Wyświetlanie w katalogu**: nigdzie (domyślnie), kategorie i wyszukiwarka, tylko kategorie lub tylko wyszukiwarka, z listą **kategorii**, w których ma się pojawić zestaw.
- **Grupy klientów**: brak zaznaczonej grupy = wszyscy. W przeciwnym razie tylko zaznaczone grupy widzą i zamawiają zestaw.
- **Proponowanie zestawu na kartach produktów**: dodaje propozycję zestawu na karcie każdego produktu, który zestaw zawiera.

### Ceny

Wszystkie ceny wpisuje się **netto**, w walucie domyślnej. Zestaw ma własną **regułę podatkową**, stosowaną w koszyku zgodnie z adresem klienta.

- **Cena stała**: jedna cena niezależnie od zawartości.
- **Progi ilościowe**: cena zależy od liczby pozycji (np. od 3 pozycji: 100 zł, od 6: 180 zł). Klient widzi, ile pozycji brakuje do niższej ceny.
- **Suma produktów z rabatem**: suma cen pozycji minus procent. Ceny pozycji są wtedy widoczne w siatce.
- **Cena za slot**: każdy slot ma cenę za pozycję (wymaga slotów).
- **Cena na wagę** (_Price per weight_): łączna waga pozycji razy **cena za jednostkę wagi** (za kg, jeśli sklep używa kg). Opcjonalne **stawki malejące** zmieniają tę cenę od określonej wagi zestawu, a cały zestaw jest wtedy liczony według nowej stawki: przy 120 zł za kg i 105 zł za kg od 1 kg zestaw o wadze 1,05 kg kosztuje 110,25 zł. Klient widzi bieżącą cenę za kilogram i to, ile gramów brakuje do niższej stawki. Ten model działa też z zestawami wypełnianymi według liczby sztuk.

**Wyświetlanie oszczędności** porównuje cenę zestawu z ceną produktów kupowanych osobno, według aktualnych cen katalogu.

**Nagrody za skompletowanie**: produkt gratis i/lub darmowa dostawa, przyznawane przez regułę koszyka z tajnym kodem, jednorazową i ważną tylko wtedy, gdy zestaw jest w koszyku. **Etykieta nagrody** jest widoczna w konfiguratorze.

**Opcje prezentowe**:

- **Wiadomość prezentowa** z maksymalną długością (1 do 500 znaków). Wiadomość pojawia się w zamówieniu w panelu i na fakturze.
- **Opakowanie prezentowe** z ceną netto (0 = bezpłatne), doliczaną do ceny zestawu.

### Skład

**Produkty do wyboru** pochodzą z produktów dodawanych pojedynczo (wyszukiwanie po nazwie, indeksie lub ID) albo z całych kategorii. Każda kombinacja produktu jest osobną pozycją z własnym stanem, ceną i wagą.

**Sloty** nadają zestawowi strukturę, na przykład "2 słone + 1 słodkie". Każdy slot ma nazwę w każdym języku, minimum, maksimum, cenę za pozycję (model za slot) i własne źródła. W sklepie sloty stają się **ponumerowanymi krokami**.

### Szablony

Gotowe zestawy, które klient stosuje jednym kliknięciem, a potem dopasowuje. Produkty szablonu muszą być również dostępne w zestawie.

### Ograniczenia

Pary produktów, które nie mogą znaleźć się w tym samym zestawie. Konfigurator blokuje takie połączenie, a serwer je odrzuca.

## Zestawy na wagę

W przypadku pudełka czekoladek, zestawu herbat czy produktów na wagę klient wypełnia zestaw do określonej wagi zamiast liczyć sztuki.

1. Zakładka **Ogólne**: sposób wypełniania = _Weight_, następnie **waga minimalna** i/lub **maksymalna**. Przykład: 1 i 1,2 dla zestawu od 1 do 1,2 kg; 1 i 1 dla dokładnie 1 kg. Co najmniej jedna z wartości jest wymagana.
2. Zakładka **Ceny**: działają wszystkie modele cen. **Cena na wagę** wycenia zestaw za kilogram, w razie potrzeby ze stawkami malejącymi; **cena stała** sprawdzi się przy pudełku sprzedawanym za 139 zł niezależnie od zawartości.
3. Sprawdź **wagę produktów**: karta produktu, zakładka Wysyłka, oraz wpływ każdej kombinacji na wagę.

- **Waga pozycji**: waga produktu + wpływ kombinacji, ta sama wartość, której PrestaShop używa przy wysyłce.
- **Produkty bez wagi**: nie są proponowane w zestawie na wagę ani w zestawie z ceną na wagę, a blok na kartach produktów nie proponuje zestawu na ich stronie. Formularz zestawu pokazuje, ilu produktów to dotyczy.
- **Konfigurator**: waga na każdej karcie, w podsumowaniu i w szybkim podglądzie; licznik i pasek postępu w g / kg ("800 g / 1,2 kg", z zaznaczonym minimum); pozycja, która przekroczyłaby maksimum, jest wyłączona z informacją o przekroczeniu pozostałej wagi; dopóki minimum nie zostanie osiągnięte, klient widzi, ile gramów brakuje.
- **Zasady pozycji**: w trybie wagi minimalna i maksymalna liczba pozycji zestawu nie obowiązuje; sloty, duplikaty, maksymalna liczba sztuk na pozycję i niezgodności nadal działają.
- **Losowe wypełnienie** uzupełnia zestaw w zakresie wagi.
- **Koszyk, zamówienie i faktura**: łączna waga jest wyświetlana przy zawartości.
- **Wyświetlanie wag**: w gramach poniżej 1 kg, w kilogramach powyżej, z separatorem dziesiętnym języka odwiedzającego.

## W sklepie

### Konfigurator

- **Kroki**: przy slotach ponumerowane zakładki pokazują postęp. Gdy krok jest pełny, konfigurator przechodzi do następnego; przycisk następnego kroku pojawia się, gdy krok jest kompletny.
- **Siatka**: powyżej 8 produktów pojawia się wyszukiwarka (ignorująca znaki diakrytyczne), filtr kategorii i sortowanie po nazwie lub cenie. Kliknięcie zdjęcia lub nazwy otwiera **szybki podgląd** (zdjęcie, opis, link do karty, przycisk dodania). Wybrane pozycje mają przycisk "-".
- **Podsumowanie**: licznik z zasadą (min. 5, max. 6, lub w wadze dla zestawu na wagę), pasek postępu z zaznaczonym minimum, **wizualny podgląd pudełka** (pole na każdą pozycję), cena, oszczędność, nagroda do odblokowania i opcje prezentowe. To, czego brakuje, jest pokazane na niebiesko; kolor czerwony jest zarezerwowany dla rzeczywistych blokad.
- **Telefon**: siatka w dwóch kolumnach, przewijane poziomo szablony i kroki, stały pasek z liczbą pozycji (lub wagą) i ceną, który zamienia się w przycisk dodania do koszyka, gdy zestaw jest poprawny.
- **Losowe wypełnienie** uzupełnia zestaw zgodnie z zasadami; **zapis i udostępnienie** tworzy link, który ponownie wczytuje zestaw.

Cena jest zawsze przeliczana przez serwer na podstawie katalogu; zestaw wysłany przez przeglądarkę jest ponownie sprawdzany (produkty, kombinacje, sloty, waga, stany) przed dodaniem do koszyka.

### Edycja zestawu z koszyka

W koszyku i podczas składania zamówienia po zawartości zestawu pojawia się link edycji (**Edit this box**, jeśli interfejs jest po angielsku). Otwiera on konfigurator z zawartością i opcjami prezentowymi. Po zatwierdzeniu zestaw jest zastępowany w tym samym miejscu, z tą samą ilością. W motywie Classic zawartość i link znajdują się w oknie personalizacji linii koszyka.

## Wyświetlanie i pozyskiwanie klientów

- **Strona zestawu**: link do strony konfiguratora w formularzu i na liście. Adres `/box/ID-przyjazny-url` przy przyjaznych adresach, tag canonical, przełącznik języka kierujący na adres w wybranym języku.
- **Strona główna**: blok z dostępnymi zestawami (ustawienie modułu).
- **Widżet**: blok można podpiąć pod dowolny hook wyświetlania (Wygląd > Pozycje) lub umieścić w szablonie: `{widget name='dfboxbuilder'}`, `{widget name='dfboxbuilder' id_dfbox=3}` albo `{widget name='dfboxbuilder' title='Nasze zestawy'}`.
- **Karty produktów**: blok z propozycją zestawu (do 3 zestawów), który otwiera konfigurator z już dodanym produktem.
- **Katalog**: po włączeniu wyświetlania w katalogu zestaw pojawia się w wybranych kategoriach i/lub wyszukiwarce. Wyświetlana jest cena "od" (najtańszy poprawny zestaw, z podatkiem i rabatem grupy; dla zestawu na wagę przy wadze minimalnej lub przy najkorzystniejszej stawce malejącej); zestaw o stałej cenie pokazuje swoją cenę. Link prowadzi do konfiguratora i nie ma przycisku dodania do koszyka.

Filtr cen nawigacji fasetowej i sortowanie po cenie korzystają z zapisanej ceny produktu technicznego, czyli 0: widoczny zestaw pojawia się na początku przy sortowaniu rosnąco po cenie.

W blokach pojawiają się tylko zestawy aktywne, w okresie sprzedaży, niewyprzedane i dostępne dla grupy odwiedzającego. Wyłączenie zestawu wyłącza też jego produkt techniczny, który znika z list.

## Koszyk, zamówienia i stany

- **Cena w linii**: cena zestawu jest zapisana w jego linii koszyka; dwa zestawy o różnej zawartości zachowują własne ceny. Rabaty grup klientów działają; reguły cenowe katalogu i rabaty ilościowe nie dotyczą zestawów.
- **Stany składników**: sprawdzane przy dodaniu w całym koszyku (inne zestawy i produkty kupowane osobno). Jeśli klient zwiększy ilość zestawu ponad stan, na stronie koszyka zostanie ona obniżona do maksimum, z komunikatem.
- **Zamówienia**: stan każdego składnika jest zdejmowany przy zatwierdzeniu zamówienia, zwracany przy przejściu w status anulowane lub błąd płatności i ponownie zdejmowany po reaktywacji. Zamówienie utworzone od razu w statusie błędu nie zdejmuje stanu.
- **Niedostępne zestawy**: zestaw usunięty, wyłączony, zakończony, jeszcze nierozpoczęty lub zarezerwowany dla innej grupy jest usuwany z koszyka na stronach koszyka i zamówienia, także po ponownym zamówieniu.
- **Panel i faktura**: zawartość (według slotów), opakowanie, wiadomość prezentowa oraz, dla zestawu na wagę, łączna waga są widoczne w zamówieniu i na fakturze.

## Statystyki

Przycisk **Analytics** na liście otwiera panel z wyborem okresu (7, 30, 90 lub 365 dni):

- zamówione zestawy, przychód netto, średnia liczba pozycji w zestawie, konwersja (zamówienia / wyświetlenia);
- dla każdego zestawu: wyświetlenia konfiguratora, dodania do koszyka, zamówienia, zestawy, wskaźnik dodań, konwersja, przychód i średnia cena;
- najczęściej wybierane produkty i najczęściej zamawiane kombinacje.

Wyświetlenia i dodania są liczone od wersji 1.2.0, bez robotów; anulowane zamówienia są wyłączone.

## Śledzenie Google Analytics 4

Po dodaniu zestawu konfigurator wysyła zdarzenie `add_to_cart` do `window.dataLayer` (jeśli jest Google Tag Manager lub gtag.js) z polami `currency`, `value` i pozycją `dfbox-ID`. Dodatkowo na `document` wywoływane jest zdarzenie `dfbox:added` z tymi samymi danymi, dla innych narzędzi.

## FAQ i rozwiązywanie problemów

### Przyciski nie działają lub strona jest pusta

Wyczyść pamięć podręczną PrestaShop (Zaawansowane > Wydajność) i na czas testów wyłącz łączenie plików JS/CSS. Sprawdź, czy zestaw jest aktywny, przypisany do sklepu i ma co najmniej jedno źródło produktów.

### Siatka jest pusta

Źródła muszą zawierać produkty aktywne i dostępne do zamówienia w bieżącym sklepie. Przy włączonym ukrywaniu produktów niedostępnych produkty bez stanu się nie pojawiają. W zestawie na wagę lub z ceną na wagę nie pojawiają się też produkty bez wagi.

### Produkt nie pojawia się w zestawie na wagę

Nie ma wagi. Uzupełnij ją na karcie produktu w zakładce Wysyłka albo we wpływie na wagę jego kombinacji. Ostrzeżenie na górze formularza zestawu pokazuje, ilu produktów to dotyczy.

### Zestaw widoczny w kategorii pokazuje 0,00

Zaktualizuj moduł do wersji 1.2.1 lub nowszej: listy pokażą wtedy cenę "od".

### Zestaw nie pojawia się dla klienta

Sprawdź daty sprzedaży, limitowany nakład i grupy klientów w zakładce dostępności.

### Link edycji zestawu się nie pojawia

Jest widoczny tylko w koszyku i podczas składania zamówienia, dla zestawu, który jest nadal dostępny. W motywie Classic otwórz okno personalizacji linii.

### Stan składników nie maleje

Jest zdejmowany przy zatwierdzeniu zamówienia, a nie przy dodaniu do koszyka, i tylko przy włączonym zarządzaniu stanami. Anulowane zamówienie zwraca stan.