AJAX-Facettenfilter für PrestaShop — Dokumentation

Diese Anleitung behandelt Installation, Konfiguration und Betrieb des Moduls AJAX-Facettenfilter für PrestaShop 8 und 9. Das Modul ersetzt die native Facettensuche durch eine schnellere AJAX-Navigation, einen Preis-Slider mit Histogramm und eine feingranulare Kontrolle über die SEO-Indexierbarkeit gefilterter Seiten.

Installation

Öffnen Sie im Back-Office Module > Modul-Manager, klicken Sie auf Modul hochladen und legen Sie die Datei dffacetedfilter.zip ab. Bei der Installation führt das Modul automatisch Folgendes aus:

• es legt seine Tabellen und seinen Admin-Tab an;
• es führt eine erste Facetten-Synchronisation aus Ihrem Katalog durch;
• es wärmt den Preisindex vor (innerhalb weniger Sekunden).

Erste Konfiguration

Gehen Sie zu Katalog > Facettenfilter. Dort finden Sie die Facettenliste, ein Übersichts-Dashboard sowie die allgemeinen und die SEO-Einstellungen.

Facetten synchronisieren

Die Schaltfläche Facetten aus dem Katalog synchronisieren erstellt automatisch die fehlenden Facetten aus Ihren Attributgruppen, Ihren Merkmalen und den integrierten Facetten (Preis, Marke, Sale, Verfügbarkeit, Zustand). Bestehende Facetten werden nie verändert: Sie können die Synchronisation nach dem Hinzufügen eines Attributs oder Merkmals bedenkenlos erneut ausführen.

Preisindex neu aufbauen

Die Schaltfläche Preisindex neu aufbauen berechnet die Preisgrenzen aller Produkte in Stapeln neu, mit einer Fortschrittsanzeige. Führen Sie sie nach der Installation und nach jedem Massenimport von Produkten aus.

Facetten verwalten

Jede Zeile lässt sich per Drag-and-drop neu anordnen (die Reihenfolge steuert sowohl die Anzeige im Frontend als auch die normalisierte URL-Reihenfolge), aktivieren oder deaktivieren und bearbeiten.

Optionen einer Facette

• Bezeichnung: der angezeigte Name, pro Sprache übersetzbar.
• Anzeige: Checkboxen, Farb-/Textur-Swatches oder einfache Links. Farbgruppen erben automatisch die Swatch-Anzeige.
• Mehrfachauswahl: erlaubt die gleichzeitige Auswahl mehrerer Werte derselben Facette, per ODER kombiniert.
• Zähler anzeigen: zeigt die Produktanzahl neben jedem Wert.
• Leere Werte ausblenden: blendet Werte ohne Produkte aus, statt sie ausgegraut anzuzeigen.
• Standardmäßig eingeklappt: die Facette wird geschlossen angezeigt und vom Besucher per Klick aufgeklappt.
• Werte vor „Mehr anzeigen“: Anzahl der Werte vor der Aufklapp-Schaltfläche (0 = alle anzeigen).

Der Preis-Slider und sein Index

Die Preis-Facette erscheint als doppelter Schieberegler. Darüber hilft ein Produktverteilungs-Histogramm über zwölf Klassen dem Besucher, die Preise einzuordnen. Diese Daten stammen aus einem dedizierten Preisindex, getrennt von den PrestaShop-Tabellen, um auch bei großem Katalog schnell zu bleiben.

Wartung des Index

Der Index wird in Echtzeit durch Hooks aktualisiert, sobald sich ein Produkt, ein spezifischer Preis oder eine Kombination ändert. Für einen geplanten vollständigen Neuaufbau nutzen Sie den im Back-Office angezeigten Cron-Endpunkt:

/module/dffacetedfilter/cron?token=IHR_TOKEN

Der Aufruf verarbeitet den Index in Abschnitten mit einer Zeitgrenze von etwa 20 Sekunden; wenn Produkte übrig bleiben, liefert die Antwort die Fortsetzungs-URL zum erneuten Aufruf. Ein nächtlicher Aufruf reicht in den meisten Fällen aus.

Die Sale-Facette

Die Facette Im Sale filtert aktuell reduzierte Produkte: als „reduziert“ gekennzeichnete Artikel oder solche mit einem aktiven spezifischen Preis (eine laufende Reduzierung, innerhalb ihres Datumsbereichs, für die aktuelle Währung, das Land und die Gruppe). Sie wird bei der Synchronisation standardmäßig aktiviert erstellt.

Verfügbarkeit und Zustand

Zwei ergänzende integrierte Facetten werden deaktiviert erstellt und können nach Bedarf aktiviert werden:

• Verfügbarkeit: ein Wert „Auf Lager“, der Ihre Einstellung für Bestellungen bei Nichtverfügbarkeit berücksichtigt.
• Zustand: neu, gebraucht, generalüberholt.

Eine Facette auf Kategorien beschränken

Standardmäßig erscheint eine Facette auf jeder Listing-Seite. Das Bearbeitungsformular bietet dafür zwei Felder: eine Kategorieregel und den Kategorienbaum, auf den sie angewandt wird.

• Nur auf den unten gewählten Kategorien anzeigen: die Facette erscheint ausschließlich auf den angehakten Kategorien und ihren Unterkategorien. Das ist die richtige Einstellung, um „Schuhgröße“ nur unter Schuhe oder „Bildschirmgröße“ nur unter Technik zu zeigen.
• Überall außer auf den unten gewählten Kategorien anzeigen: die Facette erscheint im ganzen Shop, nur nicht auf den angehakten Kategorien und ihren Unterkategorien. Das ist die richtige Einstellung, um „Weintyp“ auf Rotweine und Weißweine auszublenden, wo die Facette nichts beiträgt, sie aber sonst überall zu behalten.

Facetten-SEO

Dies ist eine der Stärken des Moduls: Sie entscheiden präzise, welche gefilterten Seiten indexiert werden dürfen. Filter-URLs sind lesbar und folgen diesem Format:

/kategorie?dff=farbe:rot,marineblau/preis:10,50/marke:nike

Der Parameter heißt q statt dff, im Creative-Elements-Vollmodus; das Format selbst bleibt identisch. Facetten werden durch einen Schrägstrich getrennt, ein Facetten-Slug und seine Werte durch einen Doppelpunkt, und die Werte untereinander durch ein Komma. Die Facettenreihenfolge und die Wertsortierung sind normalisiert, damit eine bestimmte Kombination immer eine einzige kanonische URL ergibt.

SEO-Einstellungen

• Indexierbar (pro Facette): eine nicht indexierbare Facette zwingt die gefilterte Seite auf noindex, follow und fügt rel="nofollow" an ihren Links hinzu.
• Max. indexierbare Werte: über dieser Zahl ausgewählter Werte wechselt die Seite auf noindex, follow. Der Wert 1 ist am sichersten gegen eine Explosion des Crawl-Budgets.
• Selbst-Canonical auf indexierbaren Seiten: indexierbare Seiten erhalten ein Canonical-Tag, das auf ihre eigene normalisierte Filter-URL zeigt. Das Theme-Canonical wird im Frontend entfernt, um Duplikate zu vermeiden.
• Alle auf noindex: erzwingt noindex, follow auf allen gefilterten Seiten, unabhängig von den Einstellungen pro Facette.

AJAX-Modi

Die Einstellung AJAX-Modus bestimmt, wie sich die Seite beim Klick auf einen Filter aktualisiert:

• Theme (native Events) — empfohlen: das Modul löst das native Event von PrestaShop aus und überlässt es dem Kern und dem Theme, die Liste, die Facetten und den Browserverlauf zu aktualisieren. Das ist der kompatibelste Modus mit classic-basierten Themes.
• Selbstverwaltet: für Nicht-Standard-Themes holt das Modul die Seite selbst per AJAX und tauscht die betreffenden Blöcke aus. Nur verwenden, wenn der Theme-Modus die Seite nicht korrekt aktualisiert.

Bots von den Filtern fernhalten

Ein noindex-Tag verhindert die Indexierung, nicht das Laden: der Bot muss die Seite erst abrufen, um das Tag zu lesen. Damit er Filterkombinationen nicht mehr lädt, darf er sie gar nicht erst entdecken. Zwei Einstellungen kümmern sich darum, unter Katalog > Facettenfilter.

• Crawlbare Filterlinks: Nur indexierbare Facetten behält einen echten Link auf den Facetten, die Sie als indexierbar markiert haben, und macht die übrigen zu JavaScript-gesteuerten Links. Ihre Kunden klicken genau wie vorher, aber Bots finden diese Kombinationen nicht mehr in der Seite.
• Alte native Filter-URLs (?q=): URLs der nativen PrestaShop-Facettensuche wie ?q=Marke-... können eine 410 Gone-Antwort erhalten, noch bevor eine Katalogabfrage startet, oder eine 301-Weiterleitung auf das ungefilterte Listing. Die 410 ist die günstigste Antwort für den Server und diejenige, mit der Suchmaschinen die URL aufgeben. Diese Einstellung greift weder im Creative-Elements-Vollmodus, wo q der Parameter des Moduls ist, noch auf der Suchseite.

Mobiles Filterpanel und aktive Filter

Unterhalb einer bestimmten Bildschirmbreite wird die Filterleiste ausgeblendet und öffnet sich als Panel über einen Button „Filter“. Die Einstellung Filterpanel unterhalb von (px) legt diese Schwelle fest: 767 entspricht Smartphones, 1024 passt, wenn Ihr Layout die Filterspalte auch auf Tablets verschiebt. Das Panel schließt sich über seinen Button „Ergebnisse anzeigen“, per Klick daneben oder mit der Escape-Taste.

Die Einstellung Beschriftung der aktiven Filter wählt, was jeder aktive Filter anzeigt: Facette und Wert („Farbe: Rot“) oder nur den Wert („Rot“). Screenreader erhalten immer beides.

Creative-Elements-Kompatibilität

Creative Elements (WebshopWorks) liest den von einem Modul gerenderten Facettenblock nicht. Seine Widgets Filter und Aktive Filter sowie sein mobiler Filter-Button bauen ihr eigenes Markup aus der nativen Facettensammlung auf, die das Suchergebnis mitführt. Seit Version 1.3 veröffentlicht das Modul diese Sammlung: alle drei Widgets funktionieren und behalten sämtliche Design-Einstellungen, Farb-Swatches und Preis-Slider inbegriffen.

Die beiden Einstellungen

Unter Katalog > Facettenfilter > Creative-Elements-Kompatibilität:

• Kompatibilitätsmodus: Voll, wenn Creative Elements installiert ist, Voll, immer, Teilweise oder Aus. Der Vollmodus nutzt die Filter-Widgets von Creative Elements und URLs mit ?q=; der Teilmodus behält URLs mit ?dff= und nutzt die Blöcke des Moduls (siehe unten).
• Filterblock gerendert von: Automatisch überlässt die Seitenleiste Creative Elements auf den Listings, deren Vorlage es steuert, und behält den Block des Moduls überall sonst. Wählen Sie Dieses Modul, wenn Ihre Creative-Elements-Listing-Vorlage kein Filter-Widget enthält und Sie die DataFirefly-Seitenleiste bevorzugen.

Im Vollmodus wird der URL-Parameter zu q

Creative Elements kodiert den Parameter q fest, sowohl in seinen Widgets als auch im Skript seines Preis-Sliders. Im Vollmodus richtet sich das Modul daher nach q statt dff:

/kategorie?q=farbe:rot,marineblau/preis:10,50/marke:nike

Das Format selbst ändert sich nicht, nur der Name des Parameters. Bereits erzeugte dff-URLs werden per 301 auf ihr q-Äquivalent weitergeleitet: nichts Indexiertes oder als Lesezeichen Gespeichertes geht verloren.

Teilmodus: dff-URLs behalten

Im Teilmodus veröffentlicht das Modul seine Facetten nicht für die Filter-Widgets von Creative Elements, die leer bleiben, und die URLs behalten den Parameter ?dff=. Stattdessen setzen Sie die Blöcke des Moduls mit dem Modul-Widget von Creative Elements in Ihre Listing-Vorlage: wählen Sie das Modul und geben Sie einen dieser Hook-Namen ein.

• displayDffFacets: die Filterleiste (auch das, was bei leerem Hook-Feld erscheint);
• displayDffActiveFilters: die aktiven Filter und der Link „Alle löschen“;
• displayDffFiltersButton: ein Button „Filter“, der das mobile Panel öffnet.

Um das Design des Buttons selbst zu steuern, können Sie auch ein Button-Widget von Creative Elements verwenden und ihm im Tab Erweitert die CSS-Klasse dff-open-filters geben: es öffnet dann dasselbe Panel. Die Creative-Elements-Widgets für Produktliste, Seitennavigation, Sortierung und Zähler funktionieren weiterhin normal. Im Gegenzug stellen Sie das Aussehen der Filter über die Akzentfarbe des Moduls und Ihr eigenes CSS ein, nicht über den Stil-Tab von Creative Elements.

Gut zu wissen

• Behalten Sie den AJAX-Modus „Theme“ bei. Creative Elements stützt sich auf das native PrestaShop-Event und liefert seine eigenen gerenderten Blöcke zurück; der selbstverwaltete Modus könnte sie nicht austauschen.
• Ab Creative Elements 3.x sind Facettenlinks keine echten Links mehr, sondern per JavaScript gesteuerte Elemente. Das ist eine gute Nachricht für Ihr Crawl-Budget: Filterkombinationen sind für einen Bot nicht mehr auffindbar. Im Gegenzug hängt das Filtern in seiner Oberfläche strikt von JavaScript ab.
• Vermeiden Sie das Zeichen / in der Bezeichnung Ihrer Preis-Facette: der Slider von Creative Elements baut seine URL im Browser aus dieser Bezeichnung.

Zähler-Cache

Die Berechnung der disjunktiven Zähler kann bei großem Katalog aufwendig sein. Das Modul speichert ihr Ergebnis für eine kurze, konfigurierbare Zeit im Cache (standardmäßig 300 Sekunden). Dieser Cache wird bei jeder Katalogänderung und jeder Facettenbearbeitung automatisch invalidiert. Im Back-Office steht eine Schaltfläche Zähler-Cache leeren zur Verfügung.

Nutzungsstatistiken

Das Dashboard oben auf der Admin-Seite fasst die letzten 30 Tage zusammen: indexierte Produkte, Anzahl der Aufrufe gefilterter Seiten, Anteil des aus dem Index gehaltenen Crawl-Budgets (als noindex ausgelieferte gefilterte Seiten) und eine Rangliste der meistgenutzten Facetten. Bot-Traffic wird aus diesen Zahlen ausgeschlossen, sie beschreiben also das Verhalten Ihrer Kunden. Sie können die Statistikerfassung in den Leistungseinstellungen deaktivieren.

Unterstützte Seiten

Facetten gelten für Kategorie-, Marken-, Lieferanten-, Neuheiten-, Bestseller-, Sale- und Suchergebnisseiten (unter Beachtung des nativen PrestaShop-Rankings). Die Marken-Facette wird auf einer Markenseite automatisch ausgeblendet, ebenso kategoriebeschränkte Facetten auf einer Suchseite.

Die native Facettensuche deaktivieren

Das Modul hat Vorrang vor ps_facetedsearch, wir empfehlen jedoch, Letzteres zu deaktivieren, um doppelte Indexierungsarbeit zu vermeiden. Eine Warnung im Back-Office erinnert Sie daran, falls es noch aktiv ist.

Fehlerbehebung

• Facetten erscheinen nicht: führen Sie eine Synchronisation aus, prüfen Sie, dass mindestens eine Facette aktiv ist und dass Sie sich auf einer unterstützten Listing-Seite befinden.
• Der Preis-Slider fehlt: bauen Sie den Preisindex neu auf; die Preis-Facette blendet sich aus, solange der Index für die angezeigte Kategorie leer ist.
• Die Seite aktualisiert sich nicht per AJAX: stellen Sie den AJAX-Modus auf „Selbstverwaltet“, wenn Ihr Theme dem PrestaShop-Standard nicht folgt.
• Nach einem Klick haken sich die Kästchen nicht an und ein zweiter Filter ersetzt den ersten: in 1.4.3 behoben. Der Facettenblock wurde nach dem AJAX-Filtern nicht aktualisiert. In der Browserkonsole muss dffFaceted.listening() den Wert true liefern.
• Die Filter erscheinen auf Mobilgeräten unter der Produktliste: in 1.4.1 für Bootstrap-5-Themes wie Hummingbird behoben. Prüfen Sie auch die Einstellung der Panelschwelle.
• Die Facettenreihenfolge wird nicht gespeichert: in 1.3.1 behoben. Vor dieser Version sendete PrestaShop die Drag-and-drop-Daten unter einem Schlüssel, den das Modul nicht auslas; die Meldung zeigte Erfolg an, geschrieben wurde aber nichts.
• Eine Facette erscheint auf einer Kategorie, die ich abgewählt habe: Abwählen blendet nicht aus. Haken Sie diese Kategorie an und wählen Sie die Regel „Überall außer auf den unten gewählten Kategorien anzeigen“.
• Die Creative-Elements-Widgets bleiben leer: prüfen Sie im Vollmodus, dass der Kompatibilitätsmodus auf eine der Optionen „Voll“ steht und das Modul im AJAX-Modus „Theme“ läuft. Im Teilmodus ist das normal: diese Widgets werden durch die per Modul-Widget platzierten Blöcke des Moduls ersetzt.
• Die Filterleiste erscheint doppelt: Ihre Creative-Elements-Vorlage enthält ein Filter-Widget und das Modul rendert zusätzlich sein eigenes. Stellen Sie Filterblock gerendert von auf Automatisch oder Creative-Elements-Widget.
• Zu viele indexierte Seiten: senken Sie die max. indexierbaren Werte, machen Sie Facetten mit hoher Kardinalität (Farbe, Größe) nicht indexierbar oder aktivieren Sie „Alle auf noindex“, während Sie die Kontrolle zurückgewinnen.

Der Quellcode wird unverschlüsselt geliefert. Sie erhalten 12 Monate Kompatibilitäts-Updates und Support innerhalb von 24 Stunden.

Neu in Version 1.4

Teilmodus für Creative Elements

Die URLs behalten ?dff=, und Filter, aktive Filter und mobiler Button des Moduls werden mit dem Modul-Widget von Creative Elements ins Layout gesetzt. Siehe den Abschnitt Creative-Elements-Kompatibilität.

Crawl-Kontrolle

Facettenlinks können den indexierbaren Facetten vorbehalten werden, und alte ?q=-URLs der nativen Suche können noch vor jeder Katalogabfrage eine 410 erhalten. Siehe den Abschnitt Bots von den Filtern fernhalten.

Mobiles Panel und aktive Filter

Das mobile Filterpanel hängt nicht mehr von den Hilfsklassen des Themes ab, die Bootstrap-5-Themes wie Hummingbird fehlen, und folgt einer einstellbaren Breitenschwelle. Aktive Filter können nur den Wert anzeigen.

AJAX-Aktualisierung

Das Modul aktualisiert seine Facetten und aktiven Filter nach jedem Filtern selbst, ohne sich auf die Selektoren des Themes zu verlassen. Zwei Fehler, die diese Aktualisierung verhinderten, sind behoben: das Abonnement der PrestaShop-Events erfolgte zu früh, um zu greifen (1.4.3), und der automatische Wechsel in den selbstverwalteten Modus nach 900 ms ließ Page-Builder-Widgets im vorherigen Zustand (1.4.1).

Neu in Version 1.3.1

Zwei im Produktivbetrieb gemeldete Korrekturen.

Die Facettenreihenfolge wird gespeichert. PrestaShop sendet die Drag-and-drop-Daten unter der Kennung ohne ihr id_-Präfix, also facet, und nicht unter dem Tabellennamen. Das Modul las den falschen Schlüssel und schrieb nichts, während der Browser weiterhin eine Bestätigung anzeigte. Die Reihenfolge wird nun vollständig aus der empfangenen Liste neu aufgebaut, was den Schreibvorgang idempotent macht, und der Aufruf liefert einen echten Status.

Kategorieregel „außer“. Die Kategorie-Einschränkung war nur eine Whitelist: eine Facette ließ sich auf bestimmte Kategorien begrenzen, nie aber von ihnen ausschließen. Siehe den Abschnitt Eine Facette auf Kategorien beschränken weiter oben.

Neu in Version 1.3

Creative-Elements-Kompatibilität

Das Modul veröffentlicht seine Facetten nun als native Sammlung, also in der Struktur, die der Page Builder erwartet. Seine Widgets Filter, Aktive Filter und Zurücksetzen sowie sein mobiler Filter-Button funktionieren mit dem Modul und behalten alle Design-Einstellungen. Siehe den Abschnitt Creative-Elements-Kompatibilität weiter oben, insbesondere die Änderung des URL-Parameternamens.

Performance unter Bot-Traffic

Facettennavigation bricht unter automatisiertem Traffic ein, weil jede einzelne Kombination ein Cache-Miss ist. Diese Version entfernt die Arbeit pro Anfrage, die nicht von der Auswahl abhängt:

• Gebündelte Wertelisten: die möglichen Werte jeder Facette hängen vom Katalog ab, nicht von der Auswahl. Sie werden aus einem einzigen Cache-Eintrag geladen statt mit einer Abfrage und mehreren Dateizugriffen pro Facette auf jeder Seite.
• Geschützter Zähler-Cache: ab drei Facetten oder sechs Werten wird eine Kombination zwar berechnet, aber nicht mehr gespeichert. Genau solche erzeugen Bots, sie werden nie wieder gelesen, und ihr Speichern blähte nur die Tabelle auf. Beide Schwellen sind konfigurierbar.
• Katalogsichtbarkeit: die Unterabfrage zur Kundengruppenprüfung, zuvor in jeder Zählabfrage wiederholt, entfällt auf Kategorieseiten, wenn keine aktive Kategorie für die Gruppen des Besuchers eingeschränkt ist.
• Landingpages ohne Abfrage: die Menge der aktiven Ziele wird als kompakter Index vorgehalten, sodass die negative Antwort, der mit Abstand häufigste Fall, nichts kostet.
• Statistiken: keinerlei Schreibvorgänge für Bots.

Neu in Version 1.2

SEO-Landingpages

Unter Katalog > Facettenfilter > SEO-Landingpages verwandeln Sie eine bestimmte Filterkombination (etwa Schuhe × Farbe: Rot × Marke: Nike) in eine echte Zielseite: Meta-Title, Meta-Description, H1 und redaktionelles Intro, pro Sprache. Um eine Kombination anzuvisieren, kopieren Sie den Wert des Parameters dff (oder q im Creative-Elements-Vollmodus) aus einer gefilterten URL Ihres Shops und fügen ihn in das Formular ein.

Alle aktiven Landingpages werden in einer eigenen XML-Sitemap mit hreflang-Alternates gelistet, bereit für die Search Console:

/module/dffacetedfilter/sitemap

Weitere Neuerungen

• Unterkategorien-Facette: bietet die direkten Unterkategorien der angezeigten Kategorie an; das Listing schließt dann automatisch den gesamten Teilbaum ein.
• Wertsortierung pro Facette: Katalogposition, alphabetisch oder absteigende Produktanzahl.
• Farb-Swatches als Raster oder Liste: jede Farbfacette kann als horizontales Swatch-Raster oder als vertikale Liste mit Bezeichnungen und Zählern erscheinen.
• Facetten mit nur einem Wert ausblenden: eine Facette, deren einziger Wert das gesamte Listing abdeckt, bietet keine Filterwirkung; diese Einstellung entfernt sie automatisch.
• Akzentfarbe: wählen Sie per Farbwähler die Farbe der angehakten Kästchen, Schalter, des Sliders und der Badges; der Textkontrast wird automatisch berechnet.
• Resilientes AJAX: reagiert das Theme nicht auf das native Event, wechselt das Modul automatisch in den selbstverwalteten Modus; die Scrollposition bleibt nach jedem Filtern erhalten und die mobilen Filter öffnen sich in einem Vollbild-Modal.
• 8 Front-Office-Sprachen: DE, EN, FR, ES, IT, PL, PT, NL im Modul enthalten.