InstantFilter documentatie

Snelstartgids

InstantFilter draait binnen WooCommerce. Je configureert filters in WP Admin → InstantFilter, indexeert je catalogus en plaatst vervolgens een shortcode op een shop- of landingspagina.

1. Start je proefperiode en installeer

1. Start een 14-daagse proefperiode op onze prijzenpagina. Voeg je kaartgegevens toe bij het afrekenen — er wordt pas afgeschreven wanneer de proefperiode afloopt.
2. Download de plugin-zip vanuit je Lemon Squeezy bevestigingsmail.
3. In WordPress: Plugins → Nieuwe toevoegen → Plugin uploaden, activeer InstantFilter.
4. Open InstantFilter → Licentie en plak je licentiecode. Andere tabbladen blijven vergrendeld totdat de code is gevalideerd.

2. “Producten herladen”

Klik op “Producten herladen” in de admin-header. Dit vult de wp_if_items tabel met je WooCommerce-catalogus. Na deze eerste run houdt InstantFilter de tabel automatisch synchroon wanneer je producten opslaat, bijwerkt of verwijdert — je hoeft alleen handmatig te herladen na grote imports of als je een verschil ziet tussen WooCommerce en het aantal items.

3. Filters toevoegen

Ga naar het tabblad Eigenschappen en klik op “Filter toevoegen”. De dialoog bevat bron, referentie, label en weergavetype:

• Bron — waar de data staat (taxonomy, attribuut, meta, ACF of een Loop-bron die filters voor alle attributen tegelijk aanmaakt).
• Referentie — het specifieke veld of attribuut (bijv. pa_color, product_cat).
• Filternaam — wat shoppers in de zijbalk zien.
• Weergavetype — checkbox, kleurstaal, bereik-slider, dropdown…

Sla op en herhaal dit voor elk filter dat je in de zijbalk wilt hebben. Zie Eigenschappen voor de volledige veldreferentie.

4. “Filters bijwerken”

Klik op “Filters bijwerken” in de admin-header. InstantFilter indexeert elke ingeschakelde eigenschap tegen je catalogus en bouwt (met Auto Build Exports ingeschakeld, de standaardinstelling) de JSON-export zodat de frontend client-side kan filteren.

5. Plaats een shortcode

Voeg dit toe aan een pagina, categorie-template of page builder-blok:

[instant_archive]

Dat rendert het volledige archief: filter-zijbalk, productoverzicht, sorteerbalk en paginering. De eerste pagina-laadbeurt wordt op de server gerenderd voor SEO; nadat de export is gehydrateerd, worden filterklikken in de browser afgehandeld.

Ga verder met Eigenschappen voor de filterinstallatie, Listings voor aangepaste collecties en Shortcodes voor plaatsingsopties.

Hoe indexering werkt

InstantFilter scheidt welke producten er bestaan van waarop shoppers kunnen filteren en wat de browser laadt. Drie lagen, elk met zijn eigen admin-actie:

Delta sync — je hoeft “Producten herladen” zelden opnieuw uit te voeren

Zodra “Producten herladen” voor de eerste keer is uitgevoerd, houdt InstantFilter de itemtabel synchroon via WordPress-hooks. Het opslaan, bijwerken, verwijderen of herstellen van een product activeert een delta-update die alleen de betreffende rijen raakt — geen volledige herbouw.

Voer “Producten herladen” handmatig uit wanneer:

• Je een grote batch producten hebt geïmporteerd buiten de normale opslagflow om (CSV, WP All Import, REST API bulk).
• Je een verschil ziet tussen het aantal WooCommerce-producten en het aantal InstantFilter-items.
• Je de variatie-splitsingsregels hebt gewijzigd en wilt bevestigen dat alles klopt.

Voor dagelijkse cataloguswijzigingen houdt de delta de index actueel zonder dat je iets hoeft te doen.

Statusindicator in de header

De pill naast de actieknoppen weerspiegelt de huidige status:

• Geen producten geladen — eerste run; klik op “Producten herladen”.
• X van Y filters actief — sommige eigenschappen moeten opnieuw worden geïndexeerd; klik op “Filters bijwerken”.
• X filters actief — klaar voor de frontend.
• Geen filters aangemaakt — voeg ten minste één filter toe op het tabblad Eigenschappen.

Wanneer “Filters bijwerken” uitvoeren

• Na het toevoegen, bewerken, uitschakelen of herordenen van filters.
• Na het genereren van Loop-eigenschappen (het scant je catalogus voor elk attribuut).
• Na het wijzigen van variatie-splitsingsregels zodat de optie-aantallen de nieuwe kaartstructuur weerspiegelen.

De export wordt automatisch opnieuw opgebouwd wanneer Auto Build Exports is ingeschakeld (aanbevolen). De handmatige “Export bouwen”-knop verschijnt alleen wanneer de WordPress debug-modus is ingeschakeld.

First paint vs client-side filtering

Shoppers zien een volledig HTML-productoverzicht bij het eerste verzoek (SSR), zodat zoekmachines en schermlezers dezelfde content krijgen. De export laadt op de achtergrond; eenmaal gehydrateerd, belasten filter- en pagineringsklikken je server niet voor de filterverwerking. Daarom moeten items, eigenschappen en export allemaal actueel zijn voordat je de prestaties op een staging-omgeving beoordeelt.

Licentie

Ga naar InstantFilter → Licentie (admin.php?page=if-admin&tab=license).

Activeer je code

1. Plak de licentiecode uit je Lemon Squeezy aankoop- of proefperiode-e-mail.
2. Klik op “Activeren”. De plugin valideert tegen de InstantStack-servers en ontgrendelt Eigenschappen, Variaties, Listings, Kaarten en Instellingen.
3. Zonder een geldige licentie is alleen het tabblad Licentie bruikbaar — andere tabbladen zijn grijs gemaakt.

Proefperiode-flow

Proefperiodes worden uitgegeven via Lemon Squeezy (14 dagen op de website; de plugin kan een langere proefperiode tonen afhankelijk van de reactie van de licentieserver). Na het afrekenen ontvang je per e-mail een downloadlink en licentiecode.

Wat je niveau bepaalt

Sitelimieten uit de Founders prijzen. Als je een product- of listinglimiet overschrijdt, tonen de indexeringsknoppen “Limiet bereikt” totdat je upgradet.

Deactiveren of sites verplaatsen

Gebruik de deactiveringsoptie op het tabblad Licentie voordat je naar een ander domein migreert en activeer vervolgens opnieuw op de nieuwe site. Voor vragen over facturatie of restitutie zie de FAQ.

Eigenschappen (Filterdefinities)

InstantFilter → Eigenschappen is waar je definieert welke filters in de zijbalk verschijnen. Elke rij is één filter. Ingeschakelde filters worden geïndexeerd wanneer je op “Filters bijwerken” klikt.

Eigenschappentabel

• Actief — schakelaar om een filter op te nemen in of uit te sluiten van indexering en de frontend.
• Filternaam — het label dat shoppers in de zijbalk zien.
• Bron — waar de data vandaan komt (Algemeen, Taxonomy, Attribuut, Loop, etc.).
• Type — weergavetype (checkbox, bereik, kleurstaal, …).
• Acties — bewerken, verwijderen, shortcode kopiëren [instant_filter prop="…"].

Sleep rijen om filters te herordenen. Door Loop gegenereerde attributen verschijnen genest onder hun Loop-parent.

Loop-eigenschappen

In plaats van handmatig één filter per attribuut aan te maken, kun je een Loop-bron gebruiken:

• Loop Globale Attributen — scant de catalogus en maakt een onderliggend filter aan voor elk globaal attribuut (pa_*).
• Loop Aangepaste Attributen — hetzelfde voor aangepaste productattributen.

Wanneer je een Loop-eigenschap opslaat, genereert de plugin automatisch veel onderliggende filters. Voer “Filters bijwerken” opnieuw uit na het genereren. Gebruik Attributen uitsluiten (één sleutel per regel) om attributen over te slaan die je niet in de zijbalk wilt tonen.

Resultaat in de webshop: elk opgenomen attribuut wordt een eigen filter blok in de zijbalk, gesorteerd volgens jouw sleepvolgorde.

“Filter toevoegen”-dialoog — veldreferentie

Klik op “Filter toevoegen” om de modal te openen. Belangrijkste velden:

Zie ook Variaties voor catalogusbrede splitsingsregels en Instellingen voor zijbalklimieten.

Variaties

Variabele producten zijn de manier van WooCommerce om één hoofdproduct in meerdere smaken te verkopen — maten, kleuren, afwerkingen. Standaard toont de webshop het hoofdproduct als een enkele kaart met een prijsbereik. Het splitsen (exploding) van een variatie-attribuut splitst die ene kaart in meerdere kaarten, één per variatie. Dit is het verschil tussen “Nike Air Force 1” als een enkele tegel of drie tegels voor zwart, wit en blauw.

Visueel voorbeeld

Eén variabel product met drie kleurvariaties. De bovenste rij is de standaard weergave van het hoofdproduct; de onderste rij is hetzelfde product waarbij kleur is gesplitst:

Weergavemodi

Waar je dit configureert

Op twee plaatsen — beide schrijven naar dezelfde centrale lijst met splitsingsregels:

1. Eigenschappen → Filter toevoegen/bewerken → Geavanceerde instellingen. Wanneer de filterbron een attribuut is (bijv. pa_color), toont de modal een veld Variatie-weergavemodus. Gebruik dit wanneer je het attribuut zowel als zijbalkfilter wilt gebruiken als wilt bepalen hoe het variaties splitst.
2. Tabblad Variaties → Attribuut toevoegen. Gebruik dit wanneer je een attribuut wilt splitsen zonder het als filter in de zijbalk te tonen. Voorbeeld: splits producten in afzonderlijke kaarten op kleur, maar laat shoppers nooit op een kleurfilter klikken.

Een attribuut dat via een eigenschap wordt beheerd, toont een Via eigenschap badge op het tabblad Variaties en blijft synchroon wanneer je het filter bewerkt. Handmatige items worden alleen op het tabblad Variaties bewerkt.

Sub-parents bij gedeeltelijke splitsing

Schoenen hebben vaak twee attributen: kleur en maat. Als je splitst op kleur maar niet op maat, maakt InstantFilter één kaart per kleur — een sub-parent die elke maat voor die kleur groepeert:

• Rood — maten 1, 2, 3
• Blauw — maten 1, 2, 3
• etc.

Deze sub-parents zijn geen WooCommerce-variaties. Ze bestaan alleen in de index van InstantFilter zodat het overzicht één tegel per gesplitst attribuut kan tonen. In WooCommerce zijn de echte variaties nog steeds de individuele combinaties:

• Rood, maat 1
• Rood, maat 2
• Rood, maat 3

Elk daarvan heeft zijn eigen variatierecord in WooCommerce — inclusief een eigen afbeeldingsveld. De sub-parent kaart heeft geen afbeelding in Woo; InstantFilter kiest er een uit de onderliggende variaties wanneer de tegel wordt gerenderd. Welke afbeelding je ziet, hangt af van wat je op die variatierijen hebt geüpload.

Wat te doen in WooCommerce: stel de variatie-afbeelding in op elke rij en kies een foto die het attribuut benadrukt waarop je hebt gesplitst — niet degene die je gegroepeerd hebt gelaten. Voor kleur-splitsing + maat-gegroepeerd krijgt elke rode variatie een foto van de rode schoen, ongeacht de maat:

• Rood, maat 1 → rode schoen (geen maatspecifieke opname)
• Rood, maat 2 → rode schoen
• Rood, maat 3 → rode schoen

Hetzelfde geldt voor blauw, groen, enzovoort. Als maat-1 en maat-2 van dezelfde kleur verschillende foto's gebruiken, kan de sub-parent de variatie tonen die InstantFilter als eerste tegenkomt — houd ze dus consistent op het attribuut dat je belangrijk vindt.

Resultaat in de webshop: het productoverzicht toont hoofdkaarten, sub-parents of individuele variatiekaarten, afhankelijk van je regels; filteraantallen weerspiegelen de gesplitste items, niet alleen de hoofd-SKU's.

Listings

Een listing is a productcollectie met een eigen shortcode en (optioneel) een eigen filterset. Gebruik listings wanneer één shoppagina niet genoeg is — landingspagina's voor aanbiedingen, merkwinkels, overzichten met alleen voorraad of B2B-subsets.

Universeel Archief (systeem-listing, ID -1)

Elke installatie bevat een ingebouwde listing die de WooCommerce-archiefcontext weerspiegelt. Plaats de shortcode op een Woo-archiefpagina en deze weet waar hij zich bevindt:

• Op de hoofdshop — alle geïndexeerde producten en de volledige filterset.
• Op een categorie-archief — alleen producten in die categorie, met filters en aantallen aangepast aan de context.
• Op een tag-archief — hetzelfde, beperkt tot de tag-term.

Shortcode: [instant_archive]

Aangepaste listings

Klik op “Listing toevoegen” op het tabblad Listings. De dialoog komt overeen met het screenshot hieronder:

Configureer:

• Naam — admin-label.
• Slug — URL-veilige identificatie die intern wordt gebruikt.
• Product Query — combineer nul of meer van:
  • Meta Query condities (post meta key + vergelijking + waarde).
  • Taxonomy Query condities (taxonomy + term ID's/slugs).
  • Post ID's (komma-gescheiden) voor expliciete selecties.
  Gebruik “Voorbeeld” om te zien hoeveel producten overeenkomen voordat je opslaat.
• Producten sorteren — standaard sorteervolgorde; bezoekers kunnen dit overschrijven via het sorteermenu in de webshop.
• Status — Actief of Inactief.
• Context-gevoelig — indien ingeschakeld, respecteert de listing bovendien de WordPress-archiefcontext (categorie, tag) van de pagina. Laat dit uitgeschakeld als je wilt dat de listing dezelfde producten rendert, ongeacht waar de shortcode is geplaatst.

Shortcode voor listing-ID 42:

[instant_archive listing_id="42"]

De aliassen listing="42" en id="42" werken ook.

Voorbeeld: listing met alleen voorraad

Toon alleen producten die momenteel op voorraad zijn — geen “breng me op de hoogte” of nabestelling-rijen in het overzicht.

1. “Listing toevoegen” → Naam: Op voorraad.
2. Voeg onder Meta Query een conditie toe: sleutel _stock_status, vergelijking =, waarde instock.
3. Klik op “Voorbeeld” om te bevestigen dat het aantal producten klopt.
4. Sla op en plaats de shortcode op je “Nu beschikbaar” pagina:

[instant_archive listing_id="42"]

Variatie-splitsingsregels zijn nog steeds van toepassing, dus een variabel product dat gedeeltelijk niet op voorraad is, kan alleen de voorradige variaties als kaarten tonen.

Werkwijze

1. Maak de filters aan die je beschikbaar wilt hebben op het tabblad Eigenschappen.
2. Maak een listing aan en configureer de query.
3. Voer “Filters bijwerken” uit als je eigenschappen hebt gewijzigd.
4. Plak de shortcode op een WordPress-pagina of page builder-blok.

Listing-limieten hangen af van je licentieniveau — zie Licentie.

Card Builder

InstantFilter → Kaarten (Pro en Agency) vervangt de standaard productkaart-template door een visuele lay-out die je ontwerpt in de Card Builder.

Wanneer te gebruiken

• Je hebt aangepaste kaart-HTML/CSS nodig zonder thema-templates te bewerken.
• Verschillende listings moeten verschillende kaart-lay-outs tonen.
• Je wilt badges, swatches of extra velden gekoppeld aan productdata.

Het Basic-niveau gebruikt de ingebouwde PHP-kaarttemplate — geen toegang tot de Card Builder.

Een kaart maken

1. Open het tabblad Kaarten en klik om een kaart te maken of te bewerken.
2. De builder opent op het volledige scherm (admin.php?page=if-cards-builder).
3. Ontwerp de lay-out, koppel velden (titel, prijs, afbeelding, attributen, etc.), sla op.
4. Noteer de kaart-slug die in de lijst wordt getoond.
5. Herindexeer na elke publicatie. Klik op “Filters bijwerken” zodat de data waaraan je kaart is gekoppeld in de eigenschappentabellen wordt geschreven en door de export wordt opgepikt. Zonder deze stap kunnen gekoppelde velden verouderde of ontbrekende waarden tonen op de frontend.

Toewijzen aan een listing of shortcode

[instant_archive card="jouw-kaart-slug"]
[instant_archive listing_id="42" card="jouw-kaart-slug"]

Resolutievolgorde: expliciet card attribuut → listing-standaard in opties → eerste actieve site-kaart → terugval naar legacy template.

Thema-overrides (geavanceerd)

Je kunt nog steeds PHP-templates in je thema overschrijven onder instantfilter/ als je de voorkeur geeft aan code boven de builder. De builder is het ondersteunde pad voor agencies die een UI willen.

Upgrade op de prijzenpagina als de Card Builder vergrendeld is.

Instellingen

InstantFilter → Instellingen — globale instellingen voor indexering, export, zijbalk en weergave. Wijzigingen hier hebben invloed op elke listing, tenzij deze per shortcode worden overschreven.

Index & export

Prestaties (batchgroottes)

• Batchgrootte items — producten per batch tijdens “Producten herladen” (standaard 200).
• Batchgrootte eigenschappen — producten per batch tijdens “Filters bijwerken” (standaard 50, meestal lager dan items).
• Batchgrootte Loop-generatie — grootte van de catalogus-scan bij het genereren van Loop-eigenschappen (standaard 50).

Verlaag de batches als je host een time-out geeft; verhoog ze op dedicated servers voor snellere volledige herindexeringen.

Zijbalkgedrag

• Max. uitgeklapte eigenschappen — hoeveel filters volledig geopend starten; de rest wordt ingeklapt in accordeon-stijl (0 = alles ingeklapt).
• Max. zijbalk-eigenschappen — beperkt het totaal aantal gerenderde filters (standaard 25, 0 = onbeperkt). Voorkomt een enorme DOM bij shops met tientallen Loop-onderdelen.

Labels voor kaartweergave

• Prijsweergave variabel product — Vanaf vs Bereik voor variabele hoofdproducten.
• Weergave aanbiedingsprijs — toon doorgestreepte prijs + aanbiedingsprijs, of alleen de aanbiedingsprijs.
• Placeholder voor verborgen prijs — tekst wanneer een product de prijs verbergt in WooCommerce.
• Labels voor voorraadstatus — pas de teksten voor In voorraad / Niet op voorraad / In nabestelling aan op de kaarten.

Debug

Debug-modus en Debug-log (indien aanwezig) maken uitgebreide logging en de handmatige “Export bouwen”-knop in de header mogelijk. Schakel dit uit op productie, tenzij je een probleem aan het diagnosticeren bent.

Het admin-tabblad Exports verschijnt alleen wanneer WordPress WP_DEBUG is ingeschakeld — dit is voor inspectie door developers, niet voor dagelijkse installatie.

Shortcodes

InstantFilter registreert vier shortcodes. Allemaal vereisen ze een geldige licentie en een voltooide indexering.

instant_archive

Volledige shop-ervaring: filters + productoverzicht + paginering. Het meest gebruikte startpunt.

[instant_archive]
[instant_archive listing_id="42"]
[instant_archive card="my-card" per_page="24"]

Context-gevoelig op Woo-archieven. Zonder een listing_id rendert deze shortcode de Universele Archief-listing. Op een echte WooCommerce-archiefpagina (shop, productcategorie, product-tag) beperkt de listing automatisch de filters en producten tot de pagina waarop je je bevindt — dezelfde shortcode toont verschillende voorraad op /shop/, /product-categorie/sneakers/ en /product-tag/sale/.

Op een aangepaste WordPress-pagina (elke URL die geen archief is: landingspagina, builder-template, contentpagina) is er geen archiefcontext om te detecteren. Het Universele Archief valt dan terug op alle producten. Om een aangepaste pagina te beperken, maak je een aangepaste listing aan op het tabblad Listings en geef je het ID door:

[instant_archive listing_id="42"]

instant_filter

Rendert een enkel filter buiten de standaard zijbalk-lay-out.

[instant_filter prop="pa_color"]

Gebruik de eigenschapssleutel uit de Eigenschappentabel (ook te kopiëren via de acties in de admin-rij).

instant_filters

Alleen de filter-zijbalk — plaats filters elders in de pagina-lay-out.

[instant_filters]
[instant_filters group="my-group"]

instant_all

Alle beschikbare filters voor de huidige context.

[instant_all]
[instant_all style="interface"]

stijl: sidebar (standaard) of interface.

Probleemoplossing

Geen producten in het overzicht

• Voer “Producten herladen” uit — de status-pill mag niet “Geen producten geladen” zeggen.
• Bevestig dat WooCommerce-producten zijn gepubliceerd en binnen je licentie-productlimiet vallen.
• Controleer bij aangepaste listings of de query ID's retourneert (kolom Items op het tabblad Listings).

Filters zijn leeg of aantallen staan op nul

• Voer “Filters bijwerken” uit na het aanmaken of inschakelen van eigenschappen.
• Zorg ervoor dat de eigenschap Referentie overeenkomt met echte productdata (bijv. attribuut heeft waarden op producten).
• Loop-eigenschappen: wacht tot het genereren is voltooid; controleer de lijst met uitgesloten attributen.

Filters werken in de admin-preview maar niet op de site

• Bevestig dat Auto Build Exports is ingeschakeld, of bouw de export opnieuw in debug-modus.
• Leeg de paginacache (WP Rocket, LiteSpeed, etc.) na het indexeren.
• Controleer of de shortcode op de pagina staat die je test — niet alleen in de admin-listing preview.

Filterklikken herladen de pagina of voelen traag aan

• Open DevTools → Netwerk: na de eerste interactie mogen filterklikken geen nieuwe admin-ajax filteraanroepen activeren.
• Als de export niet is geladen, controleer dan de browserconsole op 404-fouten bij exportbestanden.
• Probeer Exportstrategie → Auto in de Instellingen voordat je handmatig overschakelt naar FX of inverted.

Variatiekaarten zijn onjuist of ontbreken

• Voer “Producten herladen” opnieuw uit na wijzigingen in de splitsingsregels.
• explode_unique verbergt variaties zonder eigen afbeelding — dit is verwacht gedrag.
• Controleer zowel het tabblad Variaties als de Geavanceerde instellingen van eigenschappen op conflicterende splitsingsregels.

Licentie- / limietfouten

• Activeer de code opnieuw op het tabblad Licentie; deactiveer deze voordat je van domein wisselt.
• “Limiet bereikt” op knoppen betekent een product-, listing- of site-cap — upgrade via de prijzenpagina.

Kom je er nog niet uit?

Zie de FAQ voor informatie over de proefperiode, facturatie en het restitutiebeleid. Voor hulp bij de implementatie kun je mailen naar support@instantfilter.nl met je listing-ID, shortcode-URL en een screenshot van de status-pill in de admin.

Developer-hooks en diepgaande architectuurgidsen zijn gepland voor de sectie Gidsen — deze worden hier pas gelinkt zodra die pagina's bestaan.