# Grupowanie Produktów jako Warianty w PrestaShop: Dokumentacja Modułu (dfproductlinker)

> Moduł DF ProductLinker (dfproductlinker) łączy osobne karty produktów, aby wyświetlały się jako jeden artykuł z wyborem koloru, rozmiaru lub innego atrybutu. Każdy wariant pozostaje pełnym produktem z własnym URL. To…

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

Moduł **DF ProductLinker** (dfproductlinker) łączy osobne karty produktów, aby wyświetlały się jako jeden artykuł z wyborem koloru, rozmiaru lub innego atrybutu. Każdy wariant pozostaje pełnym produktem z własnym URL. To ruch odwrotny do [DF ProductSplitter](https://www.datafirefly.com/pl/produkt/separer-declinaisons-en-produits-prestashop/), który dzieli produkt z kombinacjami na osobne produkty.

## Instalacja

1. Pobierz plik ZIP z konta klienta DataFirefly.
2. W panelu administracyjnym przejdź do _Moduły > Menedżer modułów > Załaduj moduł_ i wyślij plik ZIP.
3. Podczas instalacji moduł tworzy swoje tabele i zakładkę _Katalog > Powiązane warianty_.
4. Otwórz konfigurację modułu, aby sprawdzić pozycję wyboru.

Moduł działa na PrestaShop 8.0 do 9.x z tym samym plikiem ZIP, w trybie multistore i wielojęzycznym. Teksty są dostarczane po francusku, angielsku, hiszpańsku, niemiecku, włosku, niderlandzku, polsku i portugalsku.

Przy aktualizacji moduł czyści pamięć podręczną Smarty. Jeśli sklep ma ustawienie _Nigdy nie kompiluj ponownie szablonów_, a wyświetlanie się nie zmienia, wyczyść pamięć podręczną w _Zaawansowane > Wydajność_.

## Zasada działania: grupy i osie

**Grupa** łączy kilka produktów. **Oś** to natywna grupa atrybutów PrestaShop, na przykład Kolor lub Rozmiar: wartości, kolory szesnastkowe, tekstury i tłumaczenia wprowadzone w _Katalog > Atrybuty i cechy_ są używane bez zmian. Każdy produkt grupy otrzymuje wartość na każdej osi.

Produkt może należeć tylko do jednej grupy. Same produkty nie są modyfikowane: grupa jest zapisywana w tabelach modułu.

## Tworzenie grupy

Przejdź do _Katalog > Powiązane warianty_, a następnie _Dodaj grupę_.

1. Wpisz **nazwę grupy**. Służy wewnętrznie oraz jako nazwa zastępcza w danych strukturalnych.
2. W sekcji **Osie** kliknij _Dodaj oś_. Moduł najpierw proponuje grupę atrybutów typu kolor. Dla każdej osi wybierz **sposób wyświetlania** (automatyczny, próbka koloru, miniatura zdjęcia produktu, przycisk tekstowy, lista rozwijana) oraz **właściwość danych strukturalnych** (kolor, rozmiar, materiał, wzór lub niedeklarowana).
3. W sekcji **Produkty grupy** wyszukaj produkty po nazwie, indeksie lub ID. Strzałki i klawisz Enter wybierają wynik. Produkty należące już do innej grupy są wyszarzone.
4. Dla każdego produktu sprawdź wartość każdej osi. Jest uzupełniana automatycznie, gdy występuje w nazwie produktu. Brakująca wartość jest podświetlona na pomarańczowo, a wiersz stanu pod tabelą pokazuje, ilu produktów to dotyczy lub czy dwa produkty mają te same wartości.
5. Zapisz. Moduł ostrzega, jeśli opuszczasz stronę z niezapisanymi zmianami.

Kolejność wierszy grupy to kolejność próbek w sklepie. Przycisk _Sortuj według kolejności atrybutów_ ustawia wiersze w kolejności z katalogu, przydatne dla rozmiarów S, M, L, XL.

## Co widzi klient

Na każdej karcie grupy wybór pokazuje nazwę osi i bieżącą wartość, na przykład _Kolor: Czerwony_, a potem dostępne wartości. Po najechaniu etykieta pokazuje wskazaną wartość. Bieżąca wartość jest obramowana; pozostałe to linki do odpowiednich kart.

- Przy kilku osiach kliknięcie koloru otwiera produkt z bieżącym rozmiarem. Jeśli taka kombinacja nie istnieje, moduł otwiera najbliższy wariant, preferując produkt dostępny w magazynie, a próbka otrzymuje przerywaną ramkę.
- Wariant niedostępny jest wyszarzony i przekreślony lub ukryty, zależnie od ustawienia.
- Wartość koloru bez kodu szesnastkowego i bez tekstury jest wyświetlana jako tekst w wydłużonej próbce.
- Wybór pojawia się także w szybkim podglądzie na stronach kategorii, nad przyciskiem dodania do koszyka.

## Ustawienia modułu

- **Pozycja wyboru**: przed natywnym blokiem kombinacji (zalecane), po nim, w hooku `displayProductAdditionalInfo` lub tylko w hooku motywu `displayDfProductLinker`.
- **Selektor CSS natywnego bloku kombinacji**: domyślnie `.product-variants, .product__variants`. Jeśli nic nie pasuje w Twoim motywie, wybór zostaje w hooku.
- **Etykieta osi**, **cena każdego wariantu** (tryby obrazu i przycisku), **format obrazu** miniatur.
- **Warianty niedostępne**: wyszarzone lub ukryte.
- **Kolor akcentu**, **kształt** (okrągły lub kwadratowy z zaokrąglonymi rogami) i **rozmiar** próbek. Średni rozmiar daje strefę dotyku 44 px, zalecaną na urządzeniach mobilnych.
- **Próbki na listach produktów**, maksymalna liczba próbek i **zmiana zdjęcia po najechaniu**.
- **Jeden produkt z grupy**, widoczność pozostałych produktów i wyświetlany produkt: patrz następna sekcja.
- **Kanoniczny URL wariantów** i **dane strukturalne ProductGroup**: patrz sekcja SEO.

Aby umieścić wybór w dowolnym miejscu, wybierz pozycję _hook motywu_ i dodaj ten wiersz w szablonie produktu motywu: `{hook h='displayDfProductLinker' product=$product}`.

## Jeden produkt z grupy w kategoriach

Ta opcja wyświetla na listach kategorii tylko jedną miniaturę na grupę. Pozostałe produkty grupy otrzymują widoczność _Tylko wyszukiwanie_ (lub _Nigdzie_, zależnie od ustawienia): ich karty pozostają online pod własnym URL, a próbki miniatury prowadzą do nich.

- **Wyświetlany produkt**: pierwszy z grupy lub pierwszy dostępny w magazynie. W drugim przypadku jest przeliczany przy każdej zmianie stanu magazynowego.
- Pierwotna widoczność każdego produktu jest zapisywana. Zostaje przywrócona po wyłączeniu opcji, dezaktywacji grupy, usunięciu produktu z grupy lub odinstalowaniu modułu.
- Jeśli ręcznie zmienisz widoczność ukrytego produktu, Twoja wartość staje się nową wartością pierwotną.
- Przycisk _Ponownie zsynchronizuj widoczność_ w konfiguracji stosuje regułę ponownie do wszystkich grup. Użyj go, jeśli produkty edytował pracownik bez uprawnień do modułu, ponieważ PrestaShop nie wywołuje wtedy hooków modułu.

Przed włączeniem opcji sprawdź, czy generator mapy witryny uwzględnia produkty z widocznością _Tylko wyszukiwanie_; w przeciwnym razie ukryte warianty wypadną z mapy witryny.

## SEO: dane strukturalne i kanoniczny URL

Moduł dodaje na każdej karcie grupy blok JSON-LD `ProductGroup` z `hasVariant` i `variesBy`. Każdy wariant zawiera nazwę, URL, indeks, EAN13 jeśli jest poprawny, zdjęcie, wartość na każdej osi, cenę wyświetlaną klientowi i dostępność. Nazwa grupy pochodzi z nazwy produktu bez jego wartości, w języku odwiedzającego. Wyłącz opcję, jeśli inny moduł już generuje ten blok.

Domyślnie każdy wariant zachowuje kanoniczny URL wskazujący na siebie: każdy kolor jest indeksowany osobno. Jeśli karty kolorów są prawie identyczne, opcja _Kanoniczny do głównego produktu grupy_ kieruje canonical wszystkich wariantów do produktu głównego, czyli produktu wyświetlanego na listach, gdy opcja jednego produktu z grupy jest włączona, a w przeciwnym razie pierwszego aktywnego produktu grupy.

## Kreator automatycznego grupowania

Na liście grup kliknij _Kreator automatycznego grupowania_. Wyszukuje produkty, które są tym samym artykułem w kilku kolorach lub rozmiarach.

1. Wybierz kategorię lub cały katalog.
2. Zaznacz grupy atrybutów do wykrycia, na przykład Kolor i Rozmiar. Wartości muszą istnieć jako wartości atrybutów i występować w nazwie produktu.
3. Wybierz regułę: identyczne nazwy po usunięciu wartości lub indeksy o wspólnym rdzeniu (TSH01-RED i TSH01-BLUE).
4. Kliknij _Podgląd_, odznacz grupy do pominięcia, a następnie _Utwórz zaznaczone grupy_.

Produkty należące już do grupy są pomijane, a analiza obejmuje 5000 produktów na przebieg.

## Import i eksport CSV

Przycisk _Import / eksport CSV_ otwiera dedykowaną stronę. Eksport zapisuje jeden wiersz na produkt, w tym samym formacie co import. Kolumny:

```
group_id;group_name;group_active;axes;product_id;product_reference;product_name;values
;T-shirt Basic;1;Kolor|Rozmiar;;TSH01-NAVY-M;;Kolor:Granatowy|Rozmiar:M
```

- Grupa jest rozpoznawana po `group_id`, a w przeciwnym razie po dokładnej nazwie. Każda grupa obecna w pliku jest zastępowana swoimi wierszami; grupy nieobecne pozostają bez zmian.
- Produkt jest wyszukiwany po `product_id`, a w przeciwnym razie po `product_reference`, który musi być unikalny w katalogu. `product_name` ma charakter informacyjny.
- `values` zawiera pary Oś:Wartość oddzielone znakiem `|`, z nazwami grup atrybutów i wartości w dowolnym języku sklepu.
- Separator `;` lub `,` jest wykrywany automatycznie. Plik UTF-8, maksymalnie 5 MB.

Import przebiega w dwóch krokach: _Analizuj plik_ pokazuje tworzone lub zastępowane grupy, wartości atrybutów, które zostaną utworzone, i każdy odrzucony wiersz z powodem; _Uruchom import_ go wykonuje. Dwie opcje: _Przenieś produkty należące już do innej grupy_ i _Utwórz brakujące wartości atrybutów_ (ich kolor pozostaje pusty, do uzupełnienia w katalogu).

## Karta produktu w panelu administracyjnym

W zakładce Moduły karty produktu panel DF ProductLinker pokazuje grupę produktu i wartość każdego produktu grupy, z linkiem do edycji grupy. Jeśli produkt nie należy do żadnej grupy, link tworzy grupę z tego produktu.

## Najczęstsze pytania

### Wybór nie pojawia się na karcie

Sprawdź, czy grupa jest aktywna, czy karta należy do grupy, czy co najmniej dwa produkty grupy są aktywne i czy co najmniej jedna oś ma dwie różne wartości. Jeśli wybrano pozycję hook motywu, hook `displayDfProductLinker` musi znajdować się w szablonie produktu.

### Wybór pojawia się pod przyciskiem koszyka

Selektor CSS natywnego bloku kombinacji nie pasuje do żadnego elementu Twojego motywu. Wpisz w konfiguracji klasę bloku kombinacji Twojego motywu.

### Na listach nie ma próbek

Opcja musi być włączona, a pierwsza oś grupy musi być wyświetlana jako próbka koloru lub miniatura zdjęcia. Motyw musi wywoływać natywny hook `displayProductListReviews` w miniaturze produktu, tak jak robi to motyw Classic.

### Czy mogę łączyć moduł z natywnymi kombinacjami?

Tak. Częsty przypadek: jeden produkt dla każdego koloru, każdy z kombinacjami rozmiarów. Wybór modułu obsługuje kolory, a natywny blok rozmiary.