# Filtry Fasetowe AJAX do PrestaShop: dokumentacja
> Ten przewodnik opisuje instalację, konfigurację i obsługę modułu Filtry fasetowe AJAX (dffacetedfilter) 2.0 w PrestaShop 1.7.8, 8 i 9, z motywami Classic i Hummingbird oraz ich motywami potomnymi. Moduł zastępuje…
- Strona:
- Język: pl
- Zaktualizowano: 2026-11-04
- Inne języki: [fr](https://www.datafirefly.com/documentation/filtres-facettes-ajax-prestashop/index.md), [en](https://www.datafirefly.com/en/documentation/ajax-faceted-filters-prestashop/index.md), [es](https://www.datafirefly.com/es/documentation/filtros-facetas-ajax-prestashop/index.md), [de](https://www.datafirefly.com/de/documentation/ajax-facettenfilter-prestashop/index.md), [it](https://www.datafirefly.com/it/documentation/filtri-faccette-ajax-prestashop/index.md), [pt](https://www.datafirefly.com/pt/documentation/filtres-facettes-ajax-prestashop/index.md), [nl](https://www.datafirefly.com/nl/documentation/filtres-facettes-ajax-prestashop/index.md)
- Indeks:
Ten przewodnik opisuje instalację, konfigurację i obsługę modułu **Filtry fasetowe AJAX** (dffacetedfilter) 2.0 w PrestaShop 1.7.8, 8 i 9, z motywami Classic i Hummingbird oraz ich motywami potomnymi. Moduł zastępuje natywne wyszukiwanie fasetowe na wszystkich listach produktów: natychmiastowe filtrowanie AJAX, suwak ceny z histogramem, szuflada filtrów na telefonie i precyzyjna kontrola SEO filtrowanych stron.
## Instalacja i aktualizacja
W **Moduły > Menedżer modułów** kliknij _Prześlij moduł_ i upuść plik `dffacetedfilter-2.0.0.zip`. Podczas instalacji moduł tworzy swoje tabele, dodaje **Katalog > Filtry fasetowe** do menu, tworzy fasety z katalogu (grupy atrybutów, cechy, marka, cena, promocje, podkategorie, dostępność, stan) i buduje pierwszy indeks cen.
Aktualizacja z wersji 1.x przebiega tak samo, na zainstalowanym module. Fasety, pozycje, reguły kategorii, strony SEO, statystyki i ustawienia zostają zachowane, łącznie z tokenem crona. Nowe ustawienia otrzymują bezpieczne wartości; opisowy tytuł filtrowanych stron pozostaje po aktualizacji wyłączony, aby nie zmieniać opublikowanych tytułów.
Moduł odpowiada pierwszy na hooku `productSearchProvider`. Natywny moduł `ps_facetedsearch` może pozostać włączony: jego wyłączenie oszczędza tylko pracę indeksowania. Żaden plik motywu nie jest nadpisywany.
## Panel i przewodnik pierwszych kroków
Górna część **Katalog > Filtry fasetowe** pokazuje stan modułu na czterech kartach: aktywne fasety, pokrycie indeksu cen (z przyciskiem _Przebuduj_ i paskiem postępu), czy natywne wyszukiwanie fasetowe jest nadal włączone lub inny moduł odpowiada pierwszy, oraz wyświetlenia filtrowanych stron w ciągu 30 dni.
Przewodnik **Pierwsze kroki** zawiera pięć kroków, które same się odhaczają: fasety utworzone z katalogu, zbudowany indeks cen, wybrane i uporządkowane fasety, sprawdzona polityka SEO, filtry wypróbowane w sklepie. Można go ukryć i przywrócić z zakładki Pomoc. Poniżej zakładki _Fasety, Wygląd, Działanie, SEO, Wydajność, Statystyki_ i _Pomoc_ grupują wszystkie ustawienia.
Panel DF Faceted Filter: stan modułu i przewodnik pierwszych kroków
## Zarządzanie fasetami
Zakładka **Fasety** wyświetla każdą fasetę z jej źródłem (atrybut, cecha, cena, marka…), sposobem wyświetlania, kategoriami, na których się pojawia, wielokrotnym wyborem i statusem SEO. Przeciągaj wiersze, aby ustalić kolejność w kolumnie, włączaj i wyłączaj fasety pojedynczo lub zbiorczo i kliknij fasetę, aby ją edytować. Nowe grupy atrybutów i cechy automatycznie stają się fasetami; fasety usuniętych grup i cech są usuwane.
Lista faset z kolejnością ustawianą metodą przeciągnij i upuść, wyświetlaniem i statusem SEO
### Opcje fasety
- **Nazwa widoczna dla klientów**, w każdym języku. Jest też slugiem fasety w filtrowanych adresach URL tego języka.
- **Wyświetlanie**: pola wyboru, **przyciski** (idealne dla rozmiarów i pojemności, proponowane automatycznie dla krótkich wartości), próbki kolorów w siatce lub na liście z nazwami albo zwykłe linki. Cena jest zawsze suwakiem; Promocja i Dostępność to przełączniki.
- **Wielokrotny wybór**: kilka wartości łączonych przez LUB; po wyłączeniu wybór wartości zastępuje poprzednią (zachowanie radio).
- **Indeksowalna przez wyszukiwarki**, **Pokazuj liczbę produktów**, **Ukryj puste wartości**, **Domyślnie zwinięta**, **Wartości przed „Pokaż więcej”** i **Sortuj wartości według** (pozycja w katalogu, nazwa lub liczba produktów).
- **Reguła kategorii** i **Kategorie**: zobacz _Ograniczenie fasety do kategorii_.
Ustawienia fasety: przyciski, wielokrotny wybór, indeksowanie SEO i reguła kategorii
## Wygląd
Zakładka **Wygląd** zawiera **podgląd na żywo** kolumny, etykiet aktywnych filtrów i szuflady mobilnej, aktualizowany przy każdej zmianie:
- **Kolor akcentu** zaznaczonych pól, przełączników, suwaka, plakietek i przycisku szuflady. Pozostawiony pusty oznacza główny kolor motywu (Hummingbird), a kontrast tekstu jest obliczany automatycznie.
- **Etykiety aktywnych filtrów**: faseta i wartość („Kolor: Czerwony”) lub tylko wartość. Czytniki ekranu zawsze otrzymują obie informacje.
- **Histogram cen**, **Pole wyszukiwania od N wartości** (domyślnie 10) i **Ukryj fasety z jedną wartością**.
- **Przyklejona kolumna** na komputerze, **Szuflada filtrów poniżej (px)** (767 dla telefonów, 1024 z tabletami), strona, z której otwiera się szuflada, oraz **pływający przycisk „Filtry”** na telefonie.
Ustawienia wyglądu z podglądem na żywo kolumny, etykiet i szuflady mobilnej
## Co widzą Twoi klienci
Na komputerze filtry znajdują się w lewej kolumnie motywu. Każda faseta to dostępny akordeon; liczniki są **rozłączne** (każda faseta jest liczona ze wszystkimi innymi wyborami poza własnym: wybór Czerwonego nigdy nie zeruje Niebieskiego). Aktywne filtry pojawiają się jako etykiety nad produktami, z linkiem „Wyczyść wszystko”. Każde kliknięcie odświeża produkty, liczniki i adres URL bez przeładowania strony; przycisk Wstecz przeglądarki, pozycja przewijania i fokus klawiatury są zachowywane.
**Dopasowanie na tej samej kombinacji** (zakładka Działanie, domyślnie włączone): Rozmiar 42 + Czerwony + Dostępny pokazuje tylko produkty z czerwonym wariantem w rozmiarze 42 na stanie, a nie czerwony 40 i niedostępny niebieski 42. Liczniki wszystkich faset stosują tę samą zasadę.
Kategoria filtrowana według rozmiaru, koloru i dostępności z etykietami aktywnych filtrów
Suwak ceny łączy dwa uchwyty, pola minimum i maksimum do dokładnego wpisania kwoty oraz histogram wyróżniający wybrany zakres. Dopisek informuje, czy ceny są brutto czy netto.
Kolumna filtrów: suwak ceny z histogramem, rozmiary jako przyciski i próbki kolorów
## Na telefonie: szuflada filtrów
Poniżej ustawionej szerokości kolumnę zastępuje przycisk „Filtruj” motywu (Classic i Hummingbird) lub przycisk modułu, z plakietką pokazującą liczbę aktywnych filtrów. Otwiera on dostępną szufladę (fokus pozostaje wewnątrz, Escape zamyka), której przycisk na dole pokazuje liczbę wyników na żywo: „Pokaż produkty: 12”. Pływający przycisk sprawia, że filtrowanie jest na wyciągnięcie palca także niżej na liście.
Telefon: lista z przyciskiem Filtruj, liczbą aktywnych filtrów i etykietami
Telefon: szuflada filtrów z przyciskami, próbkami, przełącznikami i przyciskiem Pokaż produkty
## Obsługiwane strony i wyniki wyszukiwania
Filtry działają na stronach kategorii, marek, dostawców, nowości, bestsellerów, promocji i **wyników wyszukiwania**, z trafnością natywnej wyszukiwarki. W układach bez kolumny, jak strona wyszukiwania w Classic i Hummingbird, przycisk „Filtry” nad produktami otwiera filtry w szufladzie, także na komputerze. Produkty z widocznością „tylko wyszukiwanie” są uwzględniane w wynikach, tak jak w natywnej wyszukiwarce.
Wyniki wyszukiwania filtrowane z szuflady w układzie na pełną szerokość
## Indeks cen i zaplanowane zadanie
Suwak i sortowanie po cenie korzystają z osobnego indeksu z najniższą i najwyższą ceną każdego produktu, brutto i netto. Jest aktualizowany przy każdej zmianie produktu, kombinacji lub ceny specjalnej. Ustawienie **Ceny na suwaku** (zakładka Działanie) ma domyślnie wartość _Automatycznie_: każda grupa klientów widzi ceny tak, jak pokazuje je sklep (brutto dla klientów indywidualnych, netto dla grup B2B).
Promocje z datą rozpoczęcia i zakończenia wymagają nocnej przebudowy. Zakładka **Wydajność** podaje adres URL crona z przyciskiem kopiowania; przebudowa działa partiami i **nigdy nie opróżnia indeksu**, więc filtr ceny działa w tym czasie dalej.
```
0 3 * * * curl -s "https://twoj-sklep.pl/module/dffacetedfilter/cron?token=TWOJ_TOKEN" > /dev/null
```
Ta sama zakładka czyści pamięć podręczną liczników i generuje nowy adres crona, jeśli obecny wyciekł.
Indeks cen, adres URL crona i ustawienia pamięci podręcznej liczników
## Ograniczenie fasety do kategorii
Domyślnie faseta pojawia się na wszystkich listach. W jej formularzu zmieniają to **reguła kategorii** i drzewo kategorii:
- **Pokazuj tylko w kategoriach zaznaczonych poniżej**: na przykład „Rozmiar buta” tylko w Obuwiu.
- **Pokazuj wszędzie oprócz kategorii zaznaczonych poniżej**: na przykład ukryj „Rodzaj wina” w Winach czerwonych i Winach białych.
Odznaczenie kategorii nigdy nie ukrywa fasety: gdy nic nie jest zaznaczone, faseta pozostaje globalna. Reguła dla kategorii obejmuje też jej podkategorie.
## SEO filtrowanych stron
Adresy URL filtrów są czytelne i znormalizowane: jedna kombinacja ma zawsze jeden adres.
```
/obuwie?dff=rozmiar-buta:42/kolor:czarny,czerwony
```
W zakładce **SEO** decydujesz, co mogą indeksować wyszukiwarki. Filtrowana strona jest indeksowalna tylko wtedy, gdy wszystkie wybrane fasety są indeksowalne, a liczba wybranych wartości mieści się w limicie (domyślnie 1); strony posortowane i wyniki wyszukiwania nigdy nie są indeksowalne. Decyzja jest zapisywana w samej stronie: **jeden znacznik robots i jeden canonical**, łącznie z paginacją.
- **Canonical wskazujący na siebie** na indeksowalnych filtrowanych stronach.
- **Przetłumaczone linki hreflang**: alternatywy językowe wskazują tę samą filtrowaną stronę w każdym języku (`kolor:czerwony`, `colour:red`, `couleur:rouge`…).
- **Opisowy tytuł**: „Obuwie – Kolor Czerwony”.
- **Linki filtrów dostępne dla robotów**: przy opcji _Tylko indeksowalne fasety_ pozostałe fasety używają linków obsługiwanych skryptem, które odwiedzający klikają jak zwykle, ale roboty już ich nie odkrywają.
- **Stare natywne adresy filtrów (?q=)**: wyświetlane bez filtrów, obsługiwane odpowiedzią 410 przed jakimkolwiek zapytaniem do katalogu lub przekierowywane kodem 301.
SEO filtrowanych stron: reguły noindex, canonical, opisowy tytuł i hreflang
## Strony SEO filtrów
Strona SEO zamienia kombinację filtrów, np. „Obuwie, wodoodporne, Nordkamm”, w prawdziwą stronę: tytuł meta, opis meta, H1 i wstęp redakcyjny w każdym języku. Przefiltruj listę w sklepie, skopiuj wartość parametru `dff` z jej adresu URL i wklej ją do formularza wraz z językiem. Aktywna strona SEO jest zawsze indeksowalna i znajduje się w mapie witryny filtrów z alternatywami hreflang: `/module/dffacetedfilter/sitemap`.
Edytor strony SEO: kombinacja filtrów, tytuł meta, H1 i wstęp redakcyjny
Strona SEO w sklepie: własny H1 i wstęp dla kombinacji filtrów
## Creative Elements
W zakładce **Działanie** tryb zgodności z Creative Elements decyduje, kto wyświetla filtry. _Pełny_: widżety Filtry, Aktywne filtry i przycisk mobilny Creative Elements wyświetlają fasety modułu z własnymi ustawieniami wyglądu, a filtrowane adresy używają `q` (stare adresy `dff` są przekierowywane kodem 301). _Częściowy_: adresy zachowują `dff`, a bloki modułu umieszczasz widżetem **Moduł** i hookami `displayDffFacets`, `displayDffActiveFilters` i `displayDffFiltersButton`. Każdy element z klasą CSS `dff-open-filters` również otwiera szufladę.
## Statystyki
Zakładka **Statystyki** pokazuje z ostatnich 30 dni wyświetlenia filtrowanych stron, liczbę stron podanych jako noindex, udział trzymany poza indeksem i najczęściej używane fasety. Roboty nigdy nie są liczone i nie są zapisywane żadne dane osobowe.
Statystyki użycia filtrów: filtrowane wyświetlenia, udział noindex i najczęściej używane fasety
## Wydajność i pamięć podręczna
Zapytania liczące są przechowywane w pamięci podręcznej przez krótki czas (domyślnie 300 sekund) i czyszczone automatycznie przy każdej zmianie katalogu. Kombinacje ponad trzech faset lub sześciu wartości, generowane przez roboty, są obliczane, ale nie zapisywane. Identyfikatory wyszukiwania trafiają do tej samej pamięci: zawężanie wyszukiwania filtrami nie uruchamia natywnej wyszukiwarki przy każdym kliknięciu.
## Rozwiązywanie problemów
- **Filtry się nie wyświetlają**: sprawdź, czy co najmniej jedna faseta jest aktywna i czy jesteś na obsługiwanej liście. W układzie bez kolumny użyj przycisku „Filtry” nad produktami.
- **Brakuje suwaka ceny lub pokazuje błędne ceny**: przebuduj indeks cen (zakładka Wydajność) i zaplanuj crona dla promocji z datami.
- **Nowy atrybut się nie pojawia**: faseta jest wyświetlana tylko wtedy, gdy co najmniej dwie jej wartości pasują do produktów na liście, chyba że wyłączono „Ukryj fasety z jedną wartością”.
- **Strona się nie odświeża**: ustaw **Odświeżanie strony** na _Samodzielnie_, jeśli motyw zepsuł natywne zdarzenia list.
- **Inny moduł odpowiada pierwszy**: panel to sygnalizuje; ustaw DF Faceted Filter na pierwszym miejscu na hooku productSearchProvider w Wygląd > Pozycje.
- **Za dużo zaindeksowanych stron**: obniż limit indeksowalnych wartości, ustaw fasety z wieloma wartościami jako nieindeksowalne lub ustaw linki dla robotów na _Tylko indeksowalne fasety_.
## Nowości w wersji 2.0
- Nowy panel administracyjny: karty stanu, przewodnik pierwszych kroków, zakładki, podgląd na żywo, adres crona z kopiowaniem i odnawianiem, zbiorcze włączanie i wyłączanie, tłumaczenie na 8 języków.
- Nowy front: dostępne akordeony, przyciski, zaznaczone próbki, wyszukiwanie w wartościach, pola ceny, pasek etykiet, szuflada mobilna z liczbą wyników na żywo, pływający przycisk, zachowany fokus i historia przeglądarki.
- Dopasowanie na tej samej kombinacji, ceny brutto lub netto według grupy klientów, obsługa PrestaShop 1.7.8.
- SEO zapisywane w zmiennych strony: jeden znacznik robots, jeden canonical, przetłumaczone linki hreflang, opcjonalny opisowy tytuł.
- Poprawki: linki filtrów gubione przy aktywnym sortowaniu, panel mobilny Hummingbird otwierający się pusty, filtry nigdy niewyświetlane na stronie wyszukiwania, produkty „tylko wyszukiwanie” pomijane w wynikach, indeks cen opróżniany przy każdej przebudowie, etykiety wbudowanych faset tylko w jednym języku.
Wcześniejsze wersje przyniosły zgodność z Creative Elements i ochronę przed robotami (1.3 i 1.4), strony SEO i mapę witryny filtrów (1.2), obsługę strony wyszukiwania i ograniczenie do kategorii (1.1). Kod źródłowy jest dostarczany bez szyfrowania, z 12 miesiącami aktualizacji i wsparciem w ciągu 24 h.