Ajax-filtrering

Alla Shoporama-butiker har en inbyggd /ajax endpoint som returnerar produkter i JSON-format. Detta gör det möjligt att bygga dynamisk filtrering, lazy loading och infinite scroll utan att ladda om sidan, vilket ger kunden en snabb och modern upplevelse.

Den här artikeln är främst skriven för utvecklare och de som bygger eller anpassar sitt eget tema. Om du använder Delaware-temat har du redan ajax-filtrering direkt och behöver inte anropa endpointen själv.

Hur man anropar slutpunkten

Ett enkelt anrop som hämtar produkter från en eller flera kategorier:

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

Som standard returnerar slutpunkten en JSON-array med produkter. Om du vill inkludera metadata och paginering lägger du till include_meta=1 och include_pagination=1. Du får då ett objekt med produkter, meta och paginering istället.

Tillgängliga parametrar

Flera av parametrarna tar pipeseparerade värden, så att du kan filtrera på flera saker samtidigt. Till exempel categories=12|34|56.

Exempel: Kategori, prisintervall och färg

Hämta röda produkter mellan 100 och 500 kr. från två kategorier, sorterade efter stigande pris:

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));

Exempel: Filtrera med extra fält och hämta metadata

Tilläggsfält anges med tilläggsfältets ID inom parentes. Du hittar ID:t under Inställningar → Utökade fält i admin. Exempel där tilläggsfält 5 (t.ex. "material") ska vara antingen "bomull" eller "linne":

// extension[5]=cotton|linen fetch('/ajax?categories=12&extension[5]=' + encodeURIComponent('cotton|linen') + '&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); });

Fält för varje produkt i svaret

Varje produkt i products-arrayen har bland annat följande fält

• product_id, own_id, name, description, list_description
• price, real_price, sale_price, price_dk (dansk formatering)
• lager, attr_lager, variant_lager, lager_string_en
• brand_name, supplier_id, supplier_name, profile_name
• kategori_id, kategori_namn
• thumbnail (200x200 fit), thumbnails (array av alla bilder i 200x200), url
• avg_rating, online_since, delivery_time, delivery_time_not_in_stock, approx_shipping
• har_kampanjer, kampanj_info
• meta_values (fylls bara i om du skickar meta=...)

Om handlaren har aktiverat "dölj lager via ajax" kommer lager, attr_stock och lagerkvantiteter i variant_stock att vara null, så att lagernumren inte läcker ut offentligt.

Cachelagring

Slutpunkten cachelagras på servern i 12 timmar per unik URL. Svaret skickas också med korrekta Last-Modified- och Expires-rubriker, så att webbläsare och mellanliggande cacher kan returnera en snabb 304 Not Modified om innehållet är oförändrat. Detta gör svarstiderna snabba, men innebär också att ändringar i en produkt inte träder i kraft förrän cacheminnet har löpt ut. Du kan tvinga fram en cache-återuppbyggnad för en specifik URL genom att lägga till rebuild=1.

Läs mer i artikeln Cache i Shoporama, som går igenom cachelagren i allmänhet.

Implementera i ditt tema

För att bygga en komplett ajax-filtrerad produktlista behöver utvecklaren vanligtvis

1. Bygga filtergränssnittet med kryssrutor eller rullgardinsmenyer baserat på meta.attributes, meta.brands och meta.categories
2. Lyssna på ändringar i filtren och sammanställa dem till en frågesträng
3. Anropa /ajax med de valda parametrarna
4. Uppdatera produktlistan dynamiskt och visa paginering baserat på pagination .total

Vanliga frågor och svar

Var hittar jag ID:t för ett extra fält eller attributvärde?

I admin under Inställningar → Ut ökade fält för extra fält och under Inställningar → Profiler för attributvärden. ID:n visas i listan eller i URL:en när du redigerar ett fält.

Varför får jag inga resultat när jag använder category_id=123?

För att parametern inte finns. Ändra till categories=123 (plural). Det här är ett av de vanligaste misstagen när man bygger ajax-filtrering för första gången. Kontrollera också att du inte använder price_from/price_to eller extra_field[...], som inte heller finns.

Mina ändringar i en produkt återspeglas inte i /ajax. Vad ska jag göra?

Slutpunkten cachelagras i 12 timmar. Vänta eller hämta URL:en med &rebuild=1 för att tvinga fram en ny generering av just den URL:en.

Påverkar många ajax-anrop hastigheten på min webbplats? (Mikkel, utvecklare)

Cachen ser till att upprepade anrop går snabbt. Var dock försiktig så att du inte gör ett nytt anrop för varje tangenttryckning i en sökruta. Använd "debounce" så att du bara anropar när användaren gör en paus på 200-300 ms. Webbläsaren använder också If-Modified-Since, så oförändrade svar kommer som 304 och nästan ingen bandbredd används.

Får jag samma resultat som på kategorisidan?

I stort sett. /ajax respekterar samma regler som ProductFactory använder på kategorisidor, så filtrering, sortering och synlighet (t.ex. dolda produkter) beter sig på samma sätt.

Kan jag göra en sökning ovanpå /ajax? (Sofie, nyanställd)

/ajax tar inte en fritextsökningsparameter. För sökning, använd Shoporamas dedikerade sökändpunkt i temat (vanligtvis /search) eller filtrera på product_ids om du gör sökningen själv och bara vill hämta data på en känd lista med produkter.

Hur många produkter kan jag hämta i ett samtal? (Jonas, skala)

Det finns ingen hård gräns i koden, men för att hålla JSON-nyttolasten liten och svaret snabbt bör du hålla det praktiskt under några hundra per anrop. Använd limit och offset för att räkna sidor, eller hämta bara nästa batch när användaren scrollar.

Kommer mina kunders lagerantal att exponeras offentligt? (Malene, Marknadsföring)

I grund och botten innehåller svaret lagerantalet. Om du vill dölja det (så att konkurrenter eller robotar inte kan se hur mycket du har i lager) kan din utvecklare aktivera "dölj lager via ajax" i webbshoppen, varefter lagerfälten skickas som null.

Kan jag använda /ajax som ett "riktigt" REST API? (Mikkel, utvecklare)

Nej, det är en offentlig cache-vänlig produktändpunkt för front-end-användning. Om du behöver skapa, uppdatera eller integrera på en djupare nivå ska du använda det faktiska REST API:et istället, vilket kräver en API-nyckel.

Bör jag vara orolig för att filtreringen fungerar olika för kunder på olika språk?

Endpointen körs i samma webbshopskontext som förstasidan, så priser, valuta och synlighet följer den webbshop som anropet ramar in. Om du har flera webbshoppar eller språk, kom ihåg att varje webbshop har sin egen URL, och därmed sin egen /ajax-cache.

Vill du att vi ska hjälpa dig att bygga in ajax-filtrering i ditt tema eller har du tekniska frågor? Skriv till support@shoporama.dk.