Filtern & Sortieren auf Kategorien

WEBSALE | search auf Kategorieseiten einbinden: Filtern und Sortieren nach Farbe, Preis oder Verfügbarkeit per WebComponents und JavaScript-Skripten.

Das Modul WEBSALE | search ermöglicht nicht nur die klassische Produktsuche, sondern kann auch zur Filterung und Sortierung auf Kategorieseiten genutzt werden. Dadurch können Kunden die angezeigten Produkte gezielt nach Kriterien wie Farbe, Preis oder Verfügbarkeit eingrenzen und in einer gewünschten Reihenfolge anzeigen lassen.

Diese Dokumentation beschreibt, wie die Filter- und Sortierfunktion für Kategorien in den Shop integriert wird. Dabei wird zwischen zwei Szenarien unterschieden:

• Falls die Suche & Suchergebnisseite bereits in den Shop integriert wurde, sind viele erforderliche Komponenten bereits vorhanden, und es sind nur gezielte Anpassungen für die Kategorie-Templates erforderlich.
• Falls keine WEBSALE Suche genutzt wird (z. B. weil ein externer Dienstleister wie Findologic oder FACT Finder für die Suche zuständig ist), müssen die notwendigen Komponenten und Skripte vollständig für die Kategorieseiten eingebunden werden.

In den folgenden Abschnitten wird erläutert, welche Anpassungen für die verschiedenen Szenarien erforderlich sind und welche WebComponents und Skripte für eine reibungslose Integration genutzt werden müssen.

---

​

Szenario: Suche & Suchergebnisseite bereits integriert

​

Bereits vorhandene Komponenten

Falls die Suche bereits im Shop implementiert wurde, dann sind die folgenden Komponenten bereits in allen Templates eingebunden und müssen nicht erneut integriert werden:

• WEBSALE JavaScript Bibliothek
• JavaScript Bundle (ws-search-component-<Versionskennung>.js)
• Kommunikationskomponente (ws-search)
• Sucheingabefeld mit optionaler Suggestfunktion (ws-search-box)
• Such-Event-Dispatcher & Weiterleitung von Suchanfragen (wsResultDispatcher.subscribe)

​

Anpassungen für die Kategorie-Seite (ws_category.htm)

Für das Kategorietemplate ws_category.htm müssen dann nur die folgenden zusätzlichen Anpassungen vorgenommen werden:

• Einbindung der Komponente ws-search-result
• Template-Platzhalter für die Produktbox (<template id="resultItemTemplate">)
• Filterung der Kategorie-Produkte über ws-filter
• Optional: Include/Exclude-Umschaltung einzelner Filter über ws-filter-toggle
• JavaScript zum Rendering der Filter
• Sortierung der Kategorie-Produkte über ws-sort-box
• Paginierung / Blättern der Kategorie-Produkte über ws-pagination

​

Erweiterung der bestehenden Kommunikationskomponente

Die Komponente <ws-search> darf im Template nur einmal vorkommen. Da sie bereits für die Suche & Suchergebnisseite eingebunden wurde, muss für die Kategorieseite lediglich der Parameter category="" mit einer Breadcrumb-Ausgabe ohne Trennzeichen ergänzt werden.

{ST-CatPage}
  {CAT-PathData}
  ~DC-FPparamList_set~

	~DC-Counter1_reset~
	{@CAT-PathRegular}
		{!DC-Counter1(0)}~DC-FPparamList_append(/)~{/!DC-Counter1(0)}
		~DC-FPparamList_append($CAT-Name$)~
		~DC-Counter1_inc~
	{/@CAT-PathRegular}
  {/CAT-PathData}
{/ST-CatPage}

<ws-search url="https://~WS-ShopID~.search.websale.net/api" subshop="~WS-SubShopID~" version="1.0" {ST-CatPage}category="~DC-FPparamList_urlencoding~"{/ST-CatPage}></ws-search>

---

​

Szenario: Keine bestehende Suchintegration

Falls die Shop-Suche über externe Anbieter wie Findologic oder FACT Finder läuft, dann ist die WEBSALE Suche nicht integriert. In diesem Fall müssen für die Filter- und Sortierfunktionen auf Kategorieseiten alle erforderlichen Komponenten explizit für das Kategorietemplate (ws_category.htm) eingebunden werden.

Die folgende Anleitung beschreibt die notwendigen Anpassungen, um die Filterung und Sortierung über das WEBSALE Such-Modul korrekt zu integrieren.

​

Bereitstellung der benötigten Ressourcen

Damit das Such-Modul auf der Kategorieseite funktioniert, müssen folgende Ressourcen eingebunden werden:

​

WEBSALE JavaScript-Bibliothek

Die WEBSALE JavaScript-Bibliothek stellt alle relevanten JavaScript-Module für das Such-Modul sowie weitere Standard-Shop-Funktionen bereit.

Es gibt zwei Varianten der Bibliothek:

• ws-system-<Versionskennung>.js - WEBSALE JavaScript-Module inklusive der jQuery-Bibliothek.
• ws-core-<Versionskennung>.js - WEBSALE JavaScript-Module ohne jQuery. In diesem Fall muss jQuery separat eingebunden werden.

Weitere Informationen finden Sie in der Dokumentation zur WEBSALE JavaScript-Bibliothek sowie in der Übersicht der verfügbaren Versionen und Module.

Falls die WEBSALE JavaScript-Bibliothek bereits für andere Shop-Funktionen eingebunden ist, muss sie nicht erneut integriert werden.

​

JavaScript-Bundle

WEBSALE stellt das JavaScript-Bundle ws-search-component-<Versionskennung>.js bereit. Dieses ist erforderlich für die Funktionalität der Filter- und Sortierkomponenten.

Sie können das Bundle über das WEBSALE PageSpeed-Tool einbinden oder direkt herunterladen unter:

http://<ihre-domain>/$WS/ws_sysdata/js/ws-search-component-<Versionskennung>.js

Falls Sie individuelle Anpassungen an der Filter- oder Sortierlogik vornehmen möchten, kann das JavaScript-Bundle modifiziert werden.

​

Kommunikationskomponente

Zusätzlich zum JavaScript-Bundle ist die ws-search-Komponente erforderlich. Sie wird von WEBSALE bereitgestellt und dient der Kommunikation zwischen dem Frontend, dem Backend sowie den eingebundenen WebComponents. Diese Komponente darf nur einmal pro Template vorkommen.

{ST-CatPage}
  {CAT-PathData}
  ~DC-FPparamList_set~

	~DC-Counter1_reset~
	{@CAT-PathRegular}
		{!DC-Counter1(0)}~DC-FPparamList_append(/)~{/!DC-Counter1(0)}
		~DC-FPparamList_append($CAT-Name$)~
		~DC-Counter1_inc~
	{/@CAT-PathRegular}
  {/CAT-PathData}
{/ST-CatPage}

<ws-search url="https://~WS-ShopID~.search.websale.net/api" subshop="~WS-SubShopID~" version="1.0" {ST-CatPage}category="~DC-FPparamList_urlencoding~"{/ST-CatPage}></ws-search>

Weitere Details zur Kommunikationskomponente finden Sie in der detaillierten Dokumentation zur Komponente ws-search.

​

Einbindung der Suchbox-Komponente

Damit die Filter- und Sortierfunktionen korrekt genutzt werden können, muss die ws-search-box-Komponente technisch eingebunden werden - auch wenn sie nicht aktiv für die Suche genutzt wird.

<ws-search-box></ws-search-box>

Weitere Details zur Komponente finden Sie in der detaillierten Dokumentation zu ws-search-box.

​

Such-Event-Dispatcher für Filter & Sortierung

Das folgende Skript sorgt für das korrekte Rendering der Filter- und Sortierfunktionen und sollte im <head> des Templates eingebunden werden.

<script>
	// Abonniert das Suchergebnis-Event und verarbeitet die Ergebnisse
	wsResultDispatcher.subscribe("result", function(resultData) {
		console.log(resultData); // Gibt die JSON-Antwort in der Konsole aus
		var wsPayload = "ws_loadtpl_pl=y";
		var wsResultList = resultData.results;
		var wsPayloadIds = "";

		// Produktnummern auslesen und für weitere Verarbeitung vorbereiten
		for (var i = 0; i < wsResultList.length; i++) {
            var productId = wsResultList[i]._id;
            var containerId = "wsProductWebComponent-" + productId;
            var container = document.getElementById(containerId);

          // Container existiert UND enthält KEINE bereits geladene Produktbox
          if (container && !container.querySelector('[id^="wsProductBox-"]')) {
              wsPayloadIds += "&ws_pl_" + (i + 1) + "=";
    		  wsPayloadIds += wsResultList[i]._id;
          }
		}

		// Falls Produktnummern gefunden wurden, AJAX-Request ausführen
		if (wsPayloadIds !== "") {
			ws_AJAXloadTemplatePOST(
				"~WS-AJAXLoadTpl(incl_productbox.htm)~",
				"~WS-Charset~",
				ws_AJAXloadProductBoxStart,
				ws_AJAXloadProductBoxError,
				'ws_AJAXloadProductBoxResponseSuccess()',
				'ws_AJAXloadProductBoxResponseError()',
				wsPayload+wsPayloadIds
			);
		}
	});

	// Leere Funktionen für AJAX-Events (können bei Bedarf überschrieben werden)
	function ws_AJAXloadProductBoxStart() {};
	function ws_AJAXloadProductBoxResponseSuccess(parent) {};
	function ws_AJAXloadProductBoxError() {};
	function ws_AJAXloadProductBoxResponseError() {};

    ~DC-FPTemplate_set($WS-TemplateName$)~
    {!DC-FPTemplate(ws_search.htm)}
		// Event-Listener für neue Suchanfragen (leitet zur Suchergebnisseite weiter)
	document.addEventListener("wsPerformSearch", function (event) {
    	event.preventDefault();
      if(event.detail.query !== undefined && event.detail.query !== "") {
         location.href = "~URl-Homepage~?act=search&query=" + encodeURIComponent(event.detail.query);
      }
		return false;
	});
	{/!DC-FPTemplate(ws_search.htm)}
</script>

Funktion des Skripts

• Erkennt, wenn neue Suchergebnisse oder Filter-Ergebnisse vorliegen.
• Lädt die Produktboxen über AJAX nach.
• Ermöglicht eine reibungslose Filter- und Sortierungserfahrung.

​

Integration der Produkte

Die Integration für die Produkte auf dem Kategorietemplate muss wie folgt angepasst werden:

​

Verwendung der Komponente ws-search-result

Die Komponente <ws-search-result> verarbeitet die Daten aus dem Such-Modul und stellt die gefilterten Produkte auf der Kategorieseite dar.

<ws-search-result use-ajax="yes"></ws-search-result>

Details zur Funktionsweise dieser Komponente finden Sie in der detaillierten Dokumentation zu ws-search-result.

​

Template-Platzhalter für die Produktbox

Damit es nicht zu Höhenverschiebungen beim Laden der Produktboxen kommt, kann innerhalb von ws-search-result ein <template> angegeben werden. Dieses wird angezeigt, sobald die Produktbox geladen wird.

Um das Template für die Platzhalter zu definieren, muss beim slot result-placeholder angegeben werden:

<ws-search-result use-ajax="yes">
  <template slot="result-placeholder">

      ...

  </template>
</ws-search-result>

Details zu den Template-Platzhaltern finden Sie in der detaillierten Dokumentation zu Template Placeholdern.

​

Template für die WEBSALE Produktbox (incl_productbox.htm)

Um die Produktbox nachzuladen, muss ein zusätzliches Template erstellt und im Template-Verzeichnis des Shops gespeichert werden (Standard: translation- Templateverzeichnis).

Falls sich der Name des Templates von incl_productbox.htm unterscheidet, muss das zugehörige JavaScript-Skript (siehe Such-Event-Dispatcher & Weiterleitung von Suchanfragen) entsprechend angepasst werden.

{WS-PRListFromLoadTplLink_data}
    {@WS-PRListFromLoadTplLink_data}
        {PR-LoadData($WS-PRListFromLoadTplLink_id$,1)}
            <WS-Ajax-wsProductWebComponent-~WS-PRListFromLoadTplLink_id~>

                ~WS-Fast_Include(Incl-ProductBoxCategory)~

            </WS-Ajax-wsProductWebComponent-~WS-PRListFromLoadTplLink_id~>
        {/PR-LoadData($WS-PRListFromLoadTplLink_id$,1)}
    {/@WS-PRListFromLoadTplLink_data}
{/WS-PRListFromLoadTplLink_data}

• ~WS-Fast_Include(Incl-ProductBoxCategory)~: Dies ist der Include-Bereich, der die vollständige Produktbox mit allen Shop-Funktionen lädt.

Incl-ProductBoxCategory stammt üblicherweise aus der Datei incl_fast_includes.htm, kann aber je nach Shop anders lauten. Achten Sie darauf, den korrekten Include-Namen einzutragen. Innerhalb der Productbox sollte die Klasse wsProductBox-XX (XX mit Produktnummer ersetzen) vorhanden sein, damit diese Produkte, sofern vorhanden, bei einer Sortierung oder Filterung nicht erneut geladen werden.

​

Filterung der Produkte

Bevor Filter im Frontend verfügbar sind, müssen die Produktdatenfelder, die für eine Filterung verwendet werden können, in der Konfiguration des Such-Moduls definiert werden. Diese Konfiguration legt fest, welche Filterarten (z. B. Checkboxen, Slider) für bestimmte Felder genutzt werden können.

​

Filter-Komponenten

Beispiel für die Integration der Filter-Komponenten:

<ws-filters>

  <ws-filter type="range" display-type="slider-fields" name="price" tag="~WS-Currency~" combined="true" show-labels="true"></ws-filter>

  <ws-filter type="checkbox" multiple="true" name="color" disable-style="disable-style"></ws-filter>
  <ws-filter type="checkbox" multiple="true" name="salesrank" disable-style="disable-style"></ws-filter>
  <ws-filter type="checkbox" multiple="true" name="rating" disable-style="disable-style"></ws-filter>
  <ws-filter type="checkbox" multiple="true" name="new_field" disable-style="disable-style"></ws-filter>
  <ws-filter type="checkbox" multiple="true" name="inventory" disable-style="disable-style"></ws-filter>
  <ws-filter type="checkbox" multiple="true" name="reduced_field" disable-style="disable-style"></ws-filter>

</ws-filters>

<ws-filter-chip btn-class="btn btn-secondary"></ws-filter-chip>

<ws-filter-reset>
    <button>Alle Filter entfernen</button>
</ws-filter-reset>

Die Filter-Komponenten arbeiten dynamisch und werden basierend auf der Konfiguration des Such-Moduls gerendert.

Soll der Nutzer einen Filter zwischen Include (eq) und E (neq) umschalten können, kann zusätzlich die Komponente ws-filter-toggle vor dem jeweiligen Filter eingebunden werden:

<ws-filter-toggle name="color" label-on="Enthalten" label-off="Nicht enthalten"></ws-filter-toggle>
<ws-filter type="checkbox" multiple="true" name="color" disable-style="disable-style"></ws-filter>

Weitere Details zur Nutzung und Konfiguration finden Sie in den detaillierten Dokumentationen:

• ws-filter
• ws-filter-toggle
• ws-filter-chip
• ws-filter-reset

​

JavaScript zum Rendering der Filter

Ab ws-search-component-1.9.1.js ist diese Funktionalität nativ in den WebComponents enthalten: Filter werden beim Seitenaufruf automatisch aus den URL-Parametern und dem Kategorie-Pfad gesetzt (siehe Automatische Filter-Initialisierung). Das folgende Skript ist nur noch für ältere Bundle-Versionen erforderlich.

Beim Laden der Produkte oder nach einer Filterung werden die aktiven Filter an die WebComponents weitergegeben, um die korrekten Filterwerte anzuzeigen.

<script>
    document.addEventListener('DOMContentLoaded', () => {
      const url = new URL(window.location.href);
      const searchParams = new URLSearchParams(url.search);

      // Kategorie-Filter auslesen
      const categoryFilter = url.pathname.slice(1).replace(/\//g, '%2f');

      // Aktive Filter auslesen
      const appliedFilters = {};
      for (const [key, value] of searchParams.entries()) {
          if (key.startsWith('filter_eq[')) {
              const filterKey = key.slice(10, -1); // Extract the key inside filter_eq[]
              appliedFilters[filterKey] = appliedFilters[filterKey] || [];
              appliedFilters[filterKey].push({
              op_type: 'eq',
              value: [value],
              field: filterKey
              });
          }
      }

      // Event für wsSearchBox.js dispatchen
      if (Object.keys(appliedFilters).length > 0) {
          const filterUpdateEvent = new CustomEvent('filterUpdate', {
              detail: {
                  applied_filters: appliedFilters,
                  category_filter: categoryFilter
              },
              bubbles: true,
              composed: true
          });
          document.dispatchEvent(filterUpdateEvent);
      }
    });
</script>

​

Sortierung der Produkte

Die Sortierung wird über die Komponente <ws-sort-box> gesteuert:

<ws-sort-box></ws-sort-box>

Weitere Details zur Komponente finden Sie in der detaillierten Dokumentation zu ws-sort-box.

​

Paginierung / Blättern der Produkte

Die Paginierung ermöglicht es Nutzern, die Ergebnisseite zu steuern, indem die Anzahl der angezeigten Produkte pro Seite ausgewählt und zwischen den Seiten navigiert werden kann. Dies erfolgt durch eine Kombination aus mehreren Komponenten für die Ergebnisanzeige, Seitengröße und Blätterfunktion.

Beispiel für die Integration der Paginierungs-Komponenten:

<ws-page-size-selector type="dropdown" mode="select" default="16" options='[16, 32, 48, 64, 80]'></ws-page-size-selector>

<ws-pagination max-pages="5">
  <button slot="prev"><</button>
  <button slot="current" style="font-weight: bold;"></button>
  <button slot="standard"></button>
  <button slot="next">></button>
</ws-pagination>

Weitere Details zur Nutzung und Konfiguration finden Sie in den detaillierten Dokumentationen:

• ws-page-size-selector
• ws-pagination
• result.from, result.to & result.total