AJAX Facetfilters voor PrestaShop: documentatie

Deze handleiding behandelt de installatie, configuratie en het gebruik van de module AJAX Facetfilters voor PrestaShop 8 en 9. De module vervangt het native facetzoeken door snellere AJAX-navigatie, een prijsschuif met histogram en fijnmazige controle over de SEO-indexering van gefilterde pagina’s.

Installatie

Open in je back-office Modules > Modulebeheer, klik op Een module uploaden en sleep het bestand dffacetedfilter.zip erin. Bij de installatie voert de module automatisch drie acties uit:

• ze maakt haar tabellen en haar beheertab aan;
• ze synchroniseert een eerste keer de facetten vanuit je catalogus;
• ze warmt de prijsindex op (binnen enkele seconden).

Eerste configuratie

Ga naar Catalogus > Facetfilters. Daar vind je de lijst met facetten, een overzichtsdashboard en de algemene en SEO-instellingen.

Facetten synchroniseren

De knop Synchroniseren vanuit de catalogus maakt automatisch de ontbrekende facetten aan op basis van je attribuutgroepen, je kenmerken en de ingebouwde facetten (prijs, merk, aanbiedingen, beschikbaarheid, staat). Bestaande facetten worden nooit gewijzigd: je kunt de synchronisatie zonder risico opnieuw uitvoeren nadat je een attribuut of kenmerk hebt toegevoegd.

De prijsindex opnieuw opbouwen

De knop Prijsindex opnieuw opbouwen herberekent de prijsgrenzen van alle producten, in batches, met een voortgangsbalk. Voer hem uit na de installatie en na elke massale productimport.

Facetten beheren

Elke rij in de lijst kan met slepen en neerzetten worden herschikt (de volgorde bepaalt zowel de weergavevolgorde in de front-office als de genormaliseerde URL-volgorde), in- of uitgeschakeld en bewerkt.

Opties van een facet

• Label: de weergegeven naam, vertaalbaar per taal.
• Weergave: selectievakjes, kleur-/textuurstalen of eenvoudige links. Kleurgroepen erven automatisch de weergave met stalen.
• Meervoudige selectie: staat toe om meerdere waarden van hetzelfde facet tegelijk te selecteren, gecombineerd met een OF.
• Tellers tonen: toont het aantal producten naast elke waarde.
• Lege waarden verbergen: verbergt waarden met nul producten in plaats van ze grijs weer te geven.
• Standaard ingeklapt: het facet wordt gesloten weergegeven en de bezoeker klapt het open met een klik.
• Waarden vóór “Meer tonen”: aantal zichtbare waarden vóór de uitklapknop (0 = alles tonen).

De prijsschuif en zijn index

Het facet Prijs verschijnt als een dubbele schuifregelaar. Erboven helpt een histogram van de productverdeling over twaalf klassen de bezoeker om de prijzen in te schatten. Deze gegevens komen uit een eigen prijsindex, gescheiden van de PrestaShop-tabellen, om snel te blijven, ook bij een grote catalogus.

Onderhoud van de index

De index wordt in realtime bijgewerkt door hooks zodra een product, een specifieke prijs of een combinatie verandert. Gebruik voor een geplande volledige heropbouw het cron-endpoint dat in de back-office wordt getoond:

/module/dffacetedfilter/cron?token=JOUW_TOKEN

De aanroep verwerkt de index in delen met een tijdslimiet van ongeveer 20 seconden; als er producten overblijven, geeft het antwoord de vervolg-URL om opnieuw aan te roepen. Eén nachtelijke aanroep per dag volstaat in de meeste gevallen.

Het facet Aanbiedingen

Het facet In de aanbieding filtert de producten die momenteel zijn afgeprijsd: producten gemarkeerd als “in de uitverkoop” of gedekt door een actieve specifieke prijs (een lopende korting, binnen het datumbereik, voor de huidige valuta, het land en de groep). Het wordt bij de synchronisatie standaard ingeschakeld aangemaakt.

Beschikbaarheid en staat

Twee aanvullende ingebouwde facetten worden uitgeschakeld aangemaakt, in te schakelen naar behoefte:

• Beschikbaarheid: een waarde “Op voorraad” die rekening houdt met je instelling voor bestellen bij uitverkochte voorraad.
• Staat: nieuw, gebruikt, refurbished.

Een facet beperken tot categorieën

Standaard verschijnt een facet op alle listingpagina’s. Het bewerkingsformulier biedt twee velden om dat te wijzigen: een categorieregel en de categorieënboom waarop die van toepassing is.

• Alleen tonen op onderstaande categorieën: het facet verschijnt uitsluitend op de aangevinkte categorieën en hun subcategorieën. Dit is de juiste instelling om “Schoenmaat” alleen onder Schoenen te tonen, of “Schermformaat” alleen onder Elektronica.
• Overal tonen behalve op onderstaande categorieën: het facet verschijnt in de hele winkel, behalve op de aangevinkte categorieën en hun subcategorieën. Dit is de juiste instelling om “Wijnsoort” te verbergen op Rode wijnen en Witte wijnen, waar het facet niets toevoegt, terwijl je het overal elders behoudt.

De SEO van de facetten

Dit is een van de sterke punten van de module: jij bepaalt precies welke gefilterde pagina’s geïndexeerd mogen worden. De filter-URL’s zijn leesbaar en volgen dit formaat:

/categorie?dff=kleur:rood,marineblauw/prijs:10,50/merk:nike

De parameter heet q in plaats van dff in de volledige Creative Elements-modus; het formaat zelf blijft identiek. Facetten worden gescheiden door een schuine streep, de slug van het facet en zijn waarden door een dubbele punt, en de waarden onderling door een komma. De facetvolgorde en de sortering van de waarden zijn genormaliseerd, zodat eenzelfde combinatie altijd één canonieke URL oplevert.

SEO-instellingen

• Indexeerbaar (per facet): een niet-indexeerbaar facet dwingt de gefilterde pagina naar noindex, follow en voegt rel="nofollow" toe aan zijn links.
• Max. aantal indexeerbare waarden: boven deze drempel van geselecteerde waarden gaat de pagina naar noindex, follow. De waarde 1 is het veiligst tegen een explosie van het crawlbudget.
• Automatische canonical op indexeerbare pagina’s: indexeerbare pagina’s krijgen een canonical-tag die naar hun eigen genormaliseerde filter-URL wijst. De canonical van het thema wordt aan de front-office-kant verwijderd om duplicaten te vermijden.
• Alles op noindex: dwingt noindex, follow af op alle gefilterde pagina’s, ongeacht de instellingen per facet.

AJAX-modi

De instelling AJAX-modus bepaalt hoe de pagina zich vernieuwt bij een klik op een filter:

• Thema (native events), aanbevolen: de module verstuurt het native event van PrestaShop en laat de kern en het thema de lijst, de facetten en de browsergeschiedenis vernieuwen. Dit is de modus die het meest compatibel is met op classic gebaseerde thema’s.
• Zelfstandig: voor niet-standaardthema’s haalt de module de pagina zelf op via AJAX en vervangt ze de betrokken blokken. Alleen gebruiken als de Thema-modus de pagina niet correct vernieuwt.

Bots weghouden van de filters

Een noindex-tag verhindert indexering, niet het laden: de bot moet de pagina eerst ophalen om de tag te lezen. Wil je dat hij filtercombinaties niet meer laadt, dan mag hij ze niet ontdekken. Twee instellingen zorgen daarvoor, in Catalogus > Facetfilters.

• Crawlbare filterlinks: Alleen indexeerbare facetten behoudt een echte link op de facetten die je als indexeerbaar hebt aangeduid en maakt van de overige door JavaScript aangestuurde links. Je klanten klikken precies zoals voorheen, maar bots vinden die combinaties niet meer in de pagina.
• Oude native filter-URL’s (?q=): URL’s die de native facetzoekfunctie van PrestaShop achterlaat, zoals ?q=Merk-..., kunnen een 410 Gone-antwoord krijgen nog voor er een catalogusquery start, of een 301-omleiding naar de ongefilterde listing. De 410 is het goedkoopste antwoord voor de server en degene waardoor zoekmachines de URL loslaten. Deze instelling geldt niet in de volledige Creative Elements-modus, waar q de parameter van de module is, en evenmin op de zoekpagina.

Mobiel filterpaneel en actieve filters

Onder een bepaalde schermbreedte wordt de filterbalk verborgen en opent ze als paneel via een knop „Filters”. De instelling Filterpaneel onder (px) legt die drempel vast: 767 komt overeen met telefoons, 1024 past wanneer je lay-out de filterkolom ook op tablet verplaatst. Het paneel sluit met zijn knop „Resultaten tonen”, met een klik ernaast of met de Escape-toets.

De instelling Label van de actieve filters kiest wat elk actief filter toont: het facet en de waarde („Kleur: Rood”) of alleen de waarde („Rood”). Schermlezers krijgen altijd beide.

Creative Elements-compatibiliteit

Creative Elements (WebshopWorks) leest het facetblok dat een module rendert niet. Zijn widgets Filters en Actieve filters, en zijn mobiele Filters-knop, bouwen hun eigen opmaak op uit de native facetcollectie die het zoekresultaat meedraagt. Sinds versie 1.3 publiceert de module die collectie: alle drie de widgets werken en behouden al hun ontwerpinstellingen, kleurstalen en prijsschuif inbegrepen.

De twee instellingen

In Catalogus > Facetfilters > Creative Elements-compatibiliteit:

• Compatibiliteitsmodus: Volledig, wanneer Creative Elements is geïnstalleerd, Volledig, altijd, Gedeeltelijk of Uit. De volledige modus gebruikt de filterwidgets van Creative Elements en URL’s met ?q=; de gedeeltelijke modus behoudt URL’s met ?dff= en gebruikt de blokken van de module (zie hieronder).
• Filterblok gerenderd door: Automatisch geeft de zijbalk aan Creative Elements op de listings waarvan het het sjabloon aanstuurt, en behoudt het blok van de module overal elders. Kies Deze module als je Creative Elements-listingsjabloon geen Filters-widget bevat en je de DataFirefly-zijbalk verkiest.

In de volledige modus wordt de URL-parameter q

Creative Elements heeft de parameter q hard ingebakken, zowel in zijn widgets als in het script van zijn prijsschuif. In de volledige modus richt de module zich dus naar q in plaats van dff:

/categorie?q=kleur:rood,marineblauw/prijs:10,50/merk:nike

Het formaat zelf verandert niet, alleen de naam van de parameter. Reeds gegenereerde dff-URL’s worden met een 301 doorgestuurd naar hun q-tegenhanger: niets van wat geïndexeerd of als favoriet bewaard is, gaat verloren.

Gedeeltelijke modus: dff-URL’s behouden

In de gedeeltelijke modus publiceert de module haar facetten niet voor de filterwidgets van Creative Elements, die leeg blijven, en behouden de URL’s de parameter ?dff=. In plaats daarvan plaats je de blokken van de module in je listingsjabloon met het Module-widget van Creative Elements: selecteer de module en typ een van deze hooknamen.

• displayDffFacets: de filterbalk (ook wat verschijnt als het hookveld leeg blijft);
• displayDffActiveFilters: de actieve filters en de link „Alles wissen”;
• displayDffFiltersButton: een knop „Filters” die het mobiele paneel opent.

Om zelf het ontwerp van de knop te bepalen, kun je ook een Knop-widget van Creative Elements gebruiken en die in het tabblad Geavanceerd de CSS-klasse dff-open-filters geven: hij opent dan hetzelfde paneel. De widgets van Creative Elements voor productlijst, paginering, sortering en teller blijven gewoon werken. Daar staat tegenover dat je het uiterlijk van de filters instelt met de accentkleur van de module en je eigen CSS, niet met het tabblad Stijl van Creative Elements.

Goed om te weten

• Behoud de AJAX-modus “Thema”. Creative Elements steunt op het native event van PrestaShop en geeft zijn eigen gerenderde blokken terug; de zelfstandige modus zou ze niet kunnen vervangen.
• Vanaf Creative Elements 3.x zijn facetlinks geen echte links meer, maar door JavaScript aangestuurde elementen. Dat is goed nieuws voor je crawlbudget: filtercombinaties zijn niet langer vindbaar voor een bot. Daar staat tegenover dat het filteren in zijn interface strikt afhankelijk wordt van JavaScript.
• Vermijd het teken / in het label van je facet Prijs: de schuif van Creative Elements bouwt zijn URL in de browser op uit dat label.

Tellercache

Het berekenen van de disjunctieve tellers kan kostbaar zijn bij een grote catalogus. De module bewaart het resultaat in een cache voor een korte, instelbare duur (standaard 300 seconden). Deze cache wordt automatisch ongeldig gemaakt bij elke wijziging van de catalogus en elke bewerking van een facet. In de back-office is een knop Tellercache legen beschikbaar.

Gebruiksstatistieken

Het dashboard bovenaan de beheerpagina vat de laatste 30 dagen samen: geïndexeerde producten, aantal weergaven van gefilterde pagina’s, aandeel van het crawlbudget dat buiten de index wordt gehouden (gefilterde pagina’s geserveerd als noindex) en een rangschikking van de meest gebruikte facetten. Bottraffic wordt uit deze cijfers gehouden, zodat ze het gedrag van je klanten beschrijven. Je kunt het registreren van statistieken uitschakelen in de prestatie-instellingen.

Ondersteunde pagina’s

De facetten gelden voor de pagina’s categorie, merk, leverancier, nieuwe producten, bestsellers, aanbiedingen en zoekresultaten (met respect voor de native rangschikking van PrestaShop). Het facet Merk wordt automatisch verborgen op een merkpagina, en categoriegebonden facetten op een zoekpagina.

Het native facetzoeken uitschakelen

De module heeft voorrang op ps_facetedsearch, maar we raden aan om die laatste uit te schakelen om dubbel indexeringswerk te vermijden. Een waarschuwing in de back-office herinnert je eraan als hij nog actief is.

Probleemoplossing

• De facetten verschijnen niet: start een synchronisatie, controleer of minstens één facet actief is en of je op een ondersteunde listingpagina bent.
• De prijsschuif ontbreekt: bouw de prijsindex opnieuw op; het facet Prijs verbergt zichzelf zolang de index leeg is voor de weergegeven categorie.
• De pagina vernieuwt niet via AJAX: zet de AJAX-modus op “Zelfstandig” als je thema de PrestaShop-standaard niet volgt.
• Na een klik worden de vakjes niet aangevinkt en vervangt een tweede filter het eerste: opgelost in 1.4.3. Het facettenblok werd na de AJAX-filtering niet ververst. In de browserconsole moet dffFaceted.listening() true teruggeven.
• Op mobiel verschijnen de filters onder de productlijst: opgelost in 1.4.1 voor Bootstrap 5-thema’s zoals Hummingbird. Controleer ook de instelling van de paneeldrempel.
• De volgorde van de facetten wordt niet opgeslagen: opgelost in 1.3.1. Vóór die versie verstuurde PrestaShop de sleepgegevens onder een sleutel die de module niet uitlas; de melding gaf succes aan maar er werd niets weggeschreven.
• Een facet verschijnt op een categorie die ik heb afgevinkt: afvinken verbergt niet. Vink die categorie aan en kies de regel “Overal tonen behalve op onderstaande categorieën”.
• De Creative Elements-widgets blijven leeg: controleer in de volledige modus of de compatibiliteitsmodus op een van de opties “Volledig” staat en of de module in de AJAX-modus “Thema” staat. In de gedeeltelijke modus is dat normaal: die widgets worden vervangen door de blokken van de module, geplaatst met het Module-widget.
• De filterbalk verschijnt dubbel: je Creative Elements-sjabloon bevat een Filters-widget en de module rendert daarnaast het hare. Zet Filterblok gerenderd door op Automatisch of Creative Elements-widget.
• Te veel geïndexeerde pagina’s: verlaag het max. aantal indexeerbare waarden, maak facetten met hoge kardinaliteit (kleur, maat) niet-indexeerbaar, of schakel “Alles op noindex” in terwijl je de controle terugneemt.

De broncode wordt onversleuteld geleverd. Je krijgt 12 maanden compatibiliteitsupdates en support binnen 24 uur.

Nieuw in versie 1.4

Gedeeltelijke Creative Elements-modus

De URL’s behouden ?dff=, en de filters, actieve filters en mobiele knop van de module worden met het Module-widget van Creative Elements in de lay-out geplaatst. Zie de sectie Creative Elements-compatibiliteit.

Crawlbeheersing

Facetlinks kunnen voorbehouden worden aan indexeerbare facetten, en oude ?q=-URL’s van de native zoekfunctie kunnen een 410 krijgen nog voor enige catalogusquery. Zie de sectie Bots weghouden van de filters.

Mobiel paneel en actieve filters

Het mobiele filterpaneel hangt niet langer af van de hulpklassen van het thema, die ontbreken in Bootstrap 5-thema’s zoals Hummingbird, en volgt een instelbare breedtedrempel. Actieve filters kunnen alleen de waarde tonen.

AJAX-verversing

De module ververst haar facetten en actieve filters na elke filtering zelf, zonder te steunen op de selectors van het thema. Twee gebreken die dat verhinderden zijn opgelost: het abonnement op de PrestaShop-events gebeurde te vroeg om te slagen (1.4.3), en de automatische omschakeling naar de zelfsturende modus na 900 ms liet paginabouwer-widgets in de vorige staat (1.4.1).

Nieuw in versie 1.3.1

Twee correcties die in productie werden gemeld.

De volgorde van de facetten wordt opgeslagen. PrestaShop verstuurt de sleepgegevens onder de identifier zonder zijn id_-prefix, dus facet, en niet onder de tabelnaam. De module las de verkeerde sleutel uit en schreef niets weg, terwijl de browser toch een bevestiging toonde. De volgorde wordt nu volledig opnieuw opgebouwd uit de ontvangen lijst, waardoor het wegschrijven idempotent wordt, en de aanroep geeft een echte status terug.

Categorieregel “behalve”. De categoriebeperking was uitsluitend een whitelist: een facet kon tot bepaalde categorieën worden beperkt, maar er nooit van worden uitgesloten. Zie de sectie Een facet beperken tot categorieën hierboven.

Nieuw in versie 1.3

Creative Elements-compatibiliteit

De module publiceert haar facetten nu als native collectie, de structuur die de paginabouwer verwacht. Zijn widgets Filters, Actieve filters en Wissen, en zijn mobiele Filters-knop, werken met de module en behouden al hun ontwerpinstellingen. Zie de sectie Creative Elements-compatibiliteit hierboven, in het bijzonder de naamswijziging van de URL-parameter.

Prestaties onder bottraffic

Facetnavigatie bezwijkt onder geautomatiseerd verkeer omdat elke afzonderlijke combinatie een cachemisser is. Deze versie schrapt het werk per aanvraag dat niet van de selectie afhangt:

• Gebundelde waardelijsten: de mogelijke waarden van elk facet hangen af van de catalogus, niet van de selectie. Ze worden uit één cache-invoer geladen in plaats van één query en meerdere schijftoegangen per facet op elke pagina.
• Beschermde tellercache: boven drie facetten of zes waarden wordt een combinatie wel berekend maar niet langer bewaard. Dat zijn net de combinaties die bots genereren, ze worden nooit opnieuw gelezen en het bewaren ervan deed de tabel alleen maar opzwellen. Beide drempels zijn instelbaar.
• Cataloguszichtbaarheid: de subquery die de klantgroepen controleert, voorheen herhaald in elke telquery, verdwijnt op categoriepagina’s wanneer geen enkele actieve categorie beperkt is voor de groepen van de bezoeker.
• Landingspagina’s zonder query: de verzameling actieve doelen wordt als compacte index bijgehouden, zodat het negatieve antwoord, veruit het vaakst voorkomende geval, niets kost.
• Statistieken: geen enkele schrijfactie meer voor bots.

Nieuw in versie 1.2

SEO-landingspagina’s

Maak in Catalogus > Facetfilters > SEO-landingspagina’s van een precieze filtercombinatie (bijvoorbeeld Schoenen × Kleur: rood × Merk: Nike) een echte landingspagina: meta title, meta description, H1 en redactionele intro, per taal. Om een combinatie te kiezen, kopieer je de waarde van de parameter dff (of q in de volledige Creative Elements-modus) uit een gefilterde URL van je winkel en plak je die in het formulier.

Alle actieve landingspagina’s staan in een eigen XML-sitemap met hreflang-alternates, klaar om in Search Console in te dienen:

/module/dffacetedfilter/sitemap

Overige verbeteringen

• Facet Subcategorieën: biedt de directe subcategorieën van de weergegeven categorie aan; de listing omvat dan automatisch de hele substructuur.
• Waardesortering per facet: cataloguspositie, alfabetisch of aflopend aantal producten.
• Kleurstalen als raster of lijst: elk kleurfacet kan verschijnen als horizontaal stalenraster of als verticale lijst met labels en tellers.
• Facetten met één waarde verbergen: een facet waarvan de enige waarde de hele listing dekt, voegt geen filterkracht toe; deze instelling verwijdert het automatisch.
• Accentkleur: kies met de kleurkiezer de kleur van aangevinkte vakjes, schakelaars, de schuif en de badges; het tekstcontrast wordt automatisch berekend.
• Veerkrachtige AJAX: reageert het thema niet op het native event, dan schakelt de module automatisch over naar de zelfstandige modus; de scrollpositie blijft na elke filteractie behouden en de mobiele filters openen in een modal op volledig scherm.
• 8 front-office-talen: NL, EN, FR, ES, DE, IT, PL, PT meegeleverd met de module.