Ajax-Filterung

Alle Shoporama-Shops verfügen über einen integrierten /ajax-Endpunkt, der Produkte im JSON-Format zurückgibt. Dies ermöglicht die Implementierung von dynamischer Filterung, Lazy Loading und unendlichem Scrollen, ohne dass die Seite neu geladen werden muss, sodass der Kunde ein schnelles und modernes Erlebnis erhält.

Dieser Artikel richtet sich in erster Linie an Entwickler und alle, die ihr eigenes Theme erstellen oder anpassen. Wenn Sie das Delaware-Theme verwenden, steht Ihnen die Ajax-Filterung bereits standardmäßig zur Verfügung, sodass Sie den Endpunkt nicht selbst aufrufen müssen.

So rufen Sie den Endpunkt auf

Ein einfacher Aufruf, der Produkte aus einer oder mehreren Kategorien abruft:

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

Standardmäßig gibt der Endpunkt ein JSON-Array mit Produkten zurück. Wenn du zusätzlich Metadaten und Paginierung erhalten möchtest, füge include_meta=1 und include_pagination=1 hinzu. Dann erhältst du stattdessen ein Objekt mit den Elementen „products“, „meta“ und „pagination“.

Verfügbare Parameter

Viele der Parameter akzeptieren durch Pipe-Zeichen getrennte Werte, sodass du nach mehreren Kriterien gleichzeitig filtern kannst. Z. B. categories=12|34|56.

Filterung mit AND (match=all)

Wenn du mehrere Kategorien oder Attributwerte übermittelst, führt der Endpunkt standardmäßig eine OR-Vergleichsoperation durch: Ein Produkt wird berücksichtigt, wenn es mindestens einem der Werte entspricht. Das eignet sich gut für umfassende Übersichten, aber bei der Facettenfilterung ist oft das Gegenteil gewünscht, nämlich nur die Produkte, die allen ausgewählten Werten gleichzeitig entsprechen.

Fügen Sie „match=all“ hinzu, um zur UND-Logik zu wechseln. Dann muss das Produkt jeden einzelnen der angegebenen Werte aufweisen, um berücksichtigt zu werden. Genau das benötigen Sie, wenn ein Kunde in Ihrem Filter sowohl eine Farbe als auch eine Größe auswählt:

// Nur Produkte, die SOWOHL den Wert 401815 ALS AUCH 401822 haben
fetch('/ajax?attribute_values=401815|401822&match=all&limit=50')
  .then(response => response.json())
  .then(products => { /* ... */ });

„match=all“ wirkt sowohl auf „categories“ als auch auf „attribute_values“. Ohne diesen Parameter wird wie bisher „OR“ verwendet.

Beispiel: Kategorie, Preisbereich und Farbe

Rufe rote Produkte zwischen 100 und 500 DKK aus zwei Kategorien ab, sortiert nach aufsteigendem Preis:

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

Beispiel: Nach Zusatzfeldern filtern und Metadaten abrufen

Zusatzfelder (auf Englisch „extension fields“) werden durch die ID des Zusatzfeldes in eckigen Klammern angegeben. Die ID findest du unter „Einstellungen“ → „Erweiterte Felder“ im Admin-Bereich. Beispiel, bei dem das Erweiterungsfeld 5 (z. B. „Material“) entweder „Baumwolle“ oder „Leinen“ sein muss:

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

Felder jedes Produkts in der Antwort

Jedes Produkt im „products“-Array verfügt unter anderem über folgende Felder:

• product_id, own_id, name, description, list_description
• price, real_price, sale_price, price_dk (im dänischen Format)
• stock, attr_stock, variant_stock, stock_string_da
• brand_name, supplier_id, supplier_name, profile_name
• category_ids, category_names
• thumbnail (200x200), thumbnails (Array aller Bilder im Format 200x200), url
• Durchschnittliche Bewertung, seit wann online, Lieferzeit, Lieferzeit bei Nichtverfügbarkeit, ungefähre Versandzeit
• has_campaigns, campaign_info
• meta_values (wird nur ausgefüllt, wenn Sie meta=... senden)

Wenn im Webshop die Option „Lagerbestand über Ajax ausblenden“ aktiviert ist, sind stock, attr_stock und die Lagerbestände in variant_stock null, damit die Lagerbestände nicht öffentlich sichtbar sind.

Caching

Der Endpunkt wird auf dem Server für 12 Stunden pro eindeutiger URL zwischengespeichert. Die Antwort wird zudem mit korrekten „Last-Modified“- und „Expires“-Headern gesendet, sodass Browser und Zwischenspeicher schnell einen 304 Not Modified-Status zurückgeben können, wenn der Inhalt unverändert ist. Das sorgt für schnelle Antwortzeiten, bedeutet aber auch, dass Änderungen an einem Produkt erst nach Ablauf des Caches wirksam werden. Du kannst einen Neuaufbau des Caches für eine bestimmte URL erzwingen, indem du „rebuild=1“ hinzufügst.

Weitere Informationen finden Sie im Artikel „Cache in Shoporama“, der die Cache-Ebenen allgemein erläutert.

Implementierung in Ihrem Theme

Um eine vollständige, per Ajax gefilterte Produktliste zu erstellen, muss der Entwickler in der Regel:

1. Erstellen einer Filter-Benutzeroberfläche mit Kontrollkästchen oder Dropdown-Menüs auf Basis von „meta.attributes“, „meta.brands“ und „meta.categories“
2. Änderungen an den Filtern überwachen und diese zu einer Abfragezeichenfolge zusammenfassen
3. /ajax mit den ausgewählten Parametern aufrufen
4. Die Produktliste dynamisch aktualisieren und die Paginierung basierend auf ` pagination.total` anzeigen

Häufig gestellte Fragen

Wo finde ich die ID eines Zusatzfeldes oder eines Attributwertes?

Im Admin-Bereich unter „Einstellungen“ → „Erweiterte Felder“ für Zusatzfelder und unter „Einstellungen“ → „Profile“ für Attributwerte. Die IDs werden in der Liste oder in der URL angezeigt, wenn du ein Feld bearbeitest.

Warum erhalte ich keine Ergebnisse, wenn ich „category_id=123“ verwende?

Weil der Parameter nicht existiert. Wechsle zu categories=123 (im Plural). Das ist einer der häufigsten Fehler, wenn man zum ersten Mal eine Ajax-Filterung erstellt. Überprüfe gleichzeitig, ob du nicht„price_from/price_to“ oder „extra_field[..]“ verwendest, da diese ebenfalls nicht existieren.

Meine Änderungen an einem Produkt werden unter /ajax nicht übernommen. Was soll ich tun?

Der Endpunkt wird 12 Stunden lang zwischengespeichert. Warte ab oder rufe die URL mit &rebuild=1 auf, um eine Neugenerierung genau dieser URL zu erzwingen.

Beeinträchtigen viele AJAX-Aufrufe die Geschwindigkeit meiner Website? (Mikkel, Entwickler)

Der Cache sorgt dafür, dass wiederholte Aufrufe schnell erfolgen. Achte jedoch darauf, nicht bei jedem einzelnen Tastendruck in ein Suchfeld einen neuen Aufruf zu generieren. Verwende „Debounce“, damit der Aufruf erst erfolgt, wenn der Nutzer 200–300 ms lang pausiert. Der Browser nutzt außerdem „If-Modified-Since“, sodass unveränderte Antworten als 304 zurückgegeben werden und fast keine Bandbreite verbraucht wird.

Erhalte ich das gleiche Ergebnis wie auf der Kategorieseite?

Im Großen und Ganzen. /ajax befolgt dieselben Regeln, die ProductFactory auf Kategorieseiten anwendet, sodass Filterung, Sortierung und Sichtbarkeit (z. B. ausgeblendete Produkte) sich gleich verhalten.

Kann ich eine Suche über /ajax durchführen? (Sofie, neue Mitarbeiterin)

/ajax akzeptiert keinen Freitext-Suchparameter. Für die Suche musst du den dedizierten Such-Endpunkt von Shoporama im Theme verwenden (typischerweise /search) oder nach product_ids filtern, wenn du die Suche selbst durchführst und lediglich Daten zu einer bekannten Liste von Produkten abrufen möchtest.

Wie viele Produkte darf ich in einem Aufruf abrufen? (Jonas, Skalierung)

Du kannst bis zu 1.000 Produkte in einem Aufruf abrufen. Wenn du mehr anforderst, wird die Antwort automatisch auf 1.000 begrenzt, und der Shop erhält gleichzeitig eine Benachrichtigung im Admin-Bereich unter „Benachrichtigungen“, damit du dies bemerken kannst. In der Praxis solltest du dich etwas darunter bewegen. Ein paar Hundert pro Aufruf halten die JSON-Nutzlast klein und die Antwort schnell, was insbesondere für Kunden auf Mobilgeräten wichtig ist. Verwende „limit“ und „offset“, um die Seiten zu nummerieren, oder rufe den nächsten Stapel erst ab, wenn der Nutzer scrollt.

Werden die Lagerbestände meiner Kunden öffentlich angezeigt? (Malene, Marketing)

Grundsätzlich enthält die Antwort die Lagerbestände. Soll dies verborgen werden (damit Konkurrenten oder Bots nicht sehen können, wie viel ihr auf Lager habt), kann euer Entwickler im Webshop die Option „Lagerbestand über Ajax verbergen“ aktivieren, woraufhin die Lagerbestandsfelder als „null“ gesendet werden.

Kann ich /ajax als „echte“ REST-API verwenden? (Mikkel, Entwickler)

Nein, es handelt sich um einen öffentlichen, cache-freundlichen Produkt-Endpunkt für die Frontend-Nutzung. Wenn du auf einer tieferen Ebene Daten anlegen, aktualisieren oder integrieren möchtest, verwende stattdessen die eigentliche REST-API, für die ein API-Schlüssel erforderlich ist.

Muss ich mir Sorgen machen, dass die Filterung für Kunden in verschiedenen Sprachen unterschiedlich funktioniert?

Der Endpunkt läuft im selben Webshop-Kontext wie die Startseite, sodass Preise, Währung und Sichtbarkeit den Rahmenbedingungen des jeweiligen Webshops folgen. Wenn du mehrere Webshops oder Sprachen hast, denke daran, dass jeder Webshop seine eigene URL und somit seinen eigenen /ajax-Cache hat.

Sollen wir Ihnen dabei helfen, die Ajax-Filterung in Ihr Theme zu integrieren, oder haben Sie technische Fragen? Schreiben Sie an support@shoporama.dk.