Ajax-filtrering

Alle Shoporama-butikker har et innebygd /ajax-endepunkt som returnerer produkter i JSON-format. Dette gjør det mulig å implementere dynamisk filtrering, lazy loading og uendelig rulling uten å måtte laste inn siden på nytt, slik at kunden får en rask og moderne opplevelse.

Denne artikkelen er primært skrevet for utviklere og de som bygger eller tilpasser sitt eget tema. Hvis du bruker Delaware-temaet, har du allerede ajax-filtrering inkludert og trenger ikke å kalle opp endepunktet selv.

Slik kaller du opp endepunktet

Et enkelt kall som henter produkter fra én eller flere kategorier:

fetch('/ajax?categories=123&limit=24')
  .then(response => response.json())
  .then(products => {
    products.forEach(p => console.log(p.name, p.price));
  });

Som standard returnerer endepunktet en JSON-matrise med produkter. Hvis du også vil ha med metadata og paginering, legger du til include_meta=1 og include_pagination=1. Da får du i stedet et objekt med products, meta og pagination.

Tilgjengelige parametere

Flere av parametrene tar pipe-separerte verdier, slik at du kan filtrere på flere ting samtidig. For eksempel categories=12|34|56.

Filtrering med AND (match=all)

Når du sender flere kategorier eller attributtverdier, bruker endepunktet som standard OR-sammenligning: et produkt inkluderes hvis det samsvarer med minst én av verdiene. Dette er fint for brede oversikter, men for fasettfiltrering vil du ofte ønske det motsatte, nemlig kun de produktene som samsvarer med alle de valgte verdiene samtidig.

Legg til match=all for å bytte til AND-logikk. Da må produktet ha hver eneste av de angitte verdiene for å bli inkludert. Det er nettopp dette du trenger når en kunde velger både en farge og en størrelse i filteret ditt:

// Kun produkter som har BÅDE verdien 401815 OG 401822
fetch('/ajax?attribute_values=401815|401822&match=all&limit=50')
  .then(response => response.json())
  .then(products => { /* ... */ });

match=all virker både på categories og attribute_values. Uten denne parameteren brukes OR som før.

Eksempel: Kategori, prisintervall og farge

Hent røde produkter mellom 100 og 500 kr. fra to kategorier, sortert etter pris i stigende rekkefølge:

const params = new URLSearchParams({
  categories: '12|34',
  price_range: '100|500',
  attribute_tags: 'red',
  sort: 'price',
  sort_order: 'asc',
  limit: 24
});

fetch('/ajax?' + params)
  .then(r => r.json())
  .then(products => renderProducts(products));

Eksempel: Filtrer med tilleggsfelt og hent metadata

Ekstra felt (på engelsk «extension fields») angis med feltets ID i klammer. Du finner ID-en under Innstillinger → Utvidede felt i admin. Eksempel der tilleggsfelt 5 (f.eks. «materiale») skal være enten «bomull» eller «lin»:

// extension[5]=bomull|lin
fetch('/ajax?categories=12&extension[5]=' + encodeURIComponent('bomull|lin') + '&include_meta=1&include_pagination=1&limit=24')
  .then(r => r.json())
  .then(data => {
    console.log(data.products);
    console.log(data.meta.attributes);
    console.log(data.pagination);
  });

Felter for hvert produkt i svaret

Hvert produkt i products-arrayet har blant annet følgende felt:

• product_id, own_id, name, description, list_description
• price, real_price, sale_price, price_dk (formateret på dansk)
• stock, attr_stock, variant_stock, stock_string_da
• brand_name, supplier_id, supplier_name, profile_name
• category_ids, category_names
• thumbnail (200x200), thumbnails (matrise med alle bilder i 200x200), url
• avg_rating, online_since, leveringstid, leveringstid_ikke_på_lager, omtrentlig_frakt
• har_kampanjer, kampanjeinfo
• meta_values (fylles kun ut hvis du sender meta=...)

Hvis nettbutikken har aktivert «skjul lager via ajax», vil stock, attr_stock og lagermengder i variant_stock være null, slik at lagertallene ikke blir offentliggjort.

Caching

Endepunktet lagres i cachen på serveren i 12 timer per unik URL. Svaret sendes også med korrekte Last-Modified- og Expires-headere, slik at nettlesere og mellomliggende cacher kan returnere et raskt 304 Not Modified-svar dersom innholdet er uendret. Dette gir raske responstider, men betyr også at endringer på et produkt først trer i kraft etter at cachen har utløpt. Du kan tvinge en gjenoppbygging av cachen for en bestemt URL ved å legge til rebuild=1.

Les mer i artikkelen «Cache i Shoporama», som gir en generell gjennomgang av cache-lagene.

Implementering i temaet ditt

For å lage en komplett AJAX-filtrert produktliste må utvikleren vanligvis:

1. Lage et filtergrensesnitt med avmerkingsbokser eller rullegardinmenyer basert på meta.attributes, meta.brands og meta.categories
2. Overvåke endringer i filtrene og samle dem til en spørringsstreng
3. Kalle /ajax med de valgte parametrene
4. Oppdatere produktlisten dynamisk og vise paginering basert på pagination.total

Ofte stilte spørsmål

Hvor finner jeg ID-en til et tilleggsfelt eller en attributtverdi?

I admin under Innstillinger → Utvidede felt for tilleggsfelt og under Innstillinger → Profiler for attributtverdier. ID-ene vises i listen eller i URL-en når du redigerer et felt.

Hvorfor får jeg ingen resultater når jeg bruker category_id=123?

Fordi parameteren ikke finnes. Bytt til categories=123 (i flertall). Dette er en av de vanligste feilene når man setter opp AJAX-filtrering for første gang. Sjekk samtidig at du ikke brukerprice_from/price_to eller extra_field[..], som heller ikke finnes.

Endringene mine på et produkt vises ikke på /ajax. Hva skal jeg gjøre?

Endepunktet lagres i 12 timer. Vent, eller hent URL-en med &rebuild=1 for å tvinge frem en ny generering av akkurat den URL-en.

Påvirker mange AJAX-kall hastigheten på nettstedet mitt? (Mikkel, utvikler)

Cachen sørger for at gjentatte forespørsler blir raske. Vær imidlertid forsiktig med å sende en ny forespørsel for hvert eneste tastetrykk i et søkefelt. Bruk «debounce», slik at du først sender forespørselen når brukeren holder en pause på 200–300 ms. Nettleseren utnytter også If-Modified-Since, slik at uendrede svar kommer som 304 og nesten ingen båndbredde brukes.

Får jeg det samme resultatet som på kategorisiden?

I stor grad. /ajax følger de samme reglene som ProductFactory bruker på kategorisidene, så filtrering, sortering og synlighet (f.eks. skjulte produkter) fungerer på samme måte.

Kan jeg utføre søk på /ajax? (Sofie, nyansatt)

/ajax godtar ikke en fritekst-søkeparameter. For søk må du bruke Shoporamas dedikerte søke-endepunkt i temaet (vanligvis /search) eller filtrere på product_ids, hvis du selv står for søket og bare vil hente data om en kjent liste med produkter.

Hvor mange produkter kan jeg hente i ett forespørsel? (Jonas, skala)

Du kan hente opptil 1000 produkter i ett anrop. Hvis du ber om flere, blir svaret automatisk begrenset til 1000, og nettbutikken får samtidig en melding i admin under Meldinger, slik at du kan oppdage det. I praksis bør du holde deg noe lavere. Et par hundre per forespørsel holder JSON-payloaden liten og responsen rask, noe som er spesielt viktig for mobilbrukere. Bruk «limit» og «offset» til å telle sider, eller hent bare neste batch når brukeren skroller.

Blir lagerbeholdningen til kundene mine offentliggjort? (Malene, markedsføring)

Som utgangspunkt inneholder svaret lagerbeholdningen. Skal dette skjules (slik at konkurrenter eller roboter ikke kan se hvor mye dere har på lager), kan utvikleren din aktivere «skjul lager via ajax» i nettbutikken, hvoretter lagerfeltene sendes som null.

Kan jeg bruke /ajax som et «ekte» REST-API? (Mikkel, utvikler)

Nei, det er et offentlig, cache-vennlig produkt-endepunkt for bruk i frontend. Hvis du skal opprette, oppdatere eller integrere på et dypere nivå, må du i stedet bruke den egentlige REST-API-en, som krever en API-nøkkel.

Må jeg være bekymret for at filtreringen fungerer forskjellig for kunder på ulike språk?

Endepunktet kjører i samme nettbutikkontekst som forsiden, så priser, valuta og synlighet følger den aktuelle nettbutikken, kalt rammer. Har du flere nettbutikker eller språk, må du huske at hver nettbutikk har sin egen URL og dermed sin egen /ajax-cache.

Skal vi hjelpe deg med å bygge inn AJAX-filtrering i temaet ditt, eller har du tekniske spørsmål? Skriv til support@shoporama.dk.