Zum Hauptinhalt springen
Diese Dokumentation beschreibt die Integration und Nutzung der Suchfunktionen des Moduls WEBSALE | search in einen WEBSALE Onlineshop. Sie umfasst die Einrichtung des Sucheingabefeldes (mit oder ohne Suggestfunktion), die Anzeige von Suchergebnissen sowie die After-Search-Navigation zur Filterung und Sortierung der Ergebnisse. Diese Dokumentation beschreibt die Standardintegration des WEBSALE | search Moduls, basierend auf dem gängigen Shop-Setup, bei dem das Sucheingabefeld auf jeder Seite des Shops verfügbar ist. In den meisten Fällen wird das Sucheingabefeld im Header des Shops platziert, sodass die Suchfunktion dem Nutzer jederzeit zur Verfügung steht.

​
Globale Einbindung auf allen Templates

In den meisten Fällen wird das Sucheingabefeld (ws-search-box) im Header des Shops integriert, sodass die Suche von jeder Seite aus erreichbar ist. Damit die Suche auf allen Seiten funktioniert, müssen bestimmte Komponenten und Skripte in allen Templates eingebunden werden, auf denen das Sucheingabefeld angezeigt wird. Diese sorgen für die Kommunikation mit dem Such-Backend und die Verarbeitung der Suchanfragen. Falls die Komponenten und Skripte nicht direkt in jedem Template eingebunden werden sollen, kann ein Include-Bereich in der FastInclude-Datei (incl_fast_includes.htm) erstellt und dann in den benötigten Templates referenziert werden. Im Folgenden werden die erforderlichen Komponenten und Skripte beschrieben.

​
WEBSALE JavaScript-Bibliothek

Für die Integration wird die WEBSALE JavaScript-Bibliothek benötigt. Diese stellt alle relevanten JavaScript-Module für das Such-Modul sowie weitere Standard-Shop-Funktionen bereit. Je nach Anforderungen können zwei Varianten der Bibliothek eingebunden werden:
  • 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.
Die WEBSALE JavaScript-Bibliothek wird nur einmal pro Template benötigt. Falls sie bereits in den Templates für andere Shop-Funktionen eingebunden ist, ist keine erneute Integration erforderlich.

​
JavaScript-Bundle

WEBSALE stellt ein JavaScript-Bundle mit dem Namen ws-search-component-<Versionskennung>.js über die WEBSALE JavaScript-Bibliothek bereit. Dieses Bundle wird auch über das WEBSALE PageSpeed-Tool verwaltet und ist für die Integration und Funktionalität der Suchkomponente erforderlich. Sie können das Bundle direkt in Ihre Templates einbinden, wie alle anderen von WEBSALE bereitgestellten JavaScript-Komponenten, indem Sie es über das PageSpeed-Tool konfigurieren. Falls Sie das Bundle individualisieren oder anpassen möchten, steht Ihnen die Datei zum Download unter folgender URL zur Verfügung: 
http://<ihre-domain>/$WS/ws_sysdata/js/ws-search-component-<Versionskennung>.js
Durch diese Möglichkeit können Sie spezifische Anpassungen für Ihre Shop-Templates vornehmen, beispielsweise Änderungen am Verhalten der Suche oder Filterlogik.

​
Kommunikationskomponente

Die Kommunikationskomponente wird überall benötigt, wo das Sucheingabefeld (ws-search-box) verwendet wird, jedoch nur einmal pro Seite. Sie stellt sicher, dass Suchanfragen korrekt verarbeitet und an das Backend übermittelt werden. 
<ws-search url="https://<ihre-shopid>.search.websale.net/api" subshop="~WS-SubShopID~" page-size="24" keep-query="yes"></ws-search>
Weitere Details zur Kommunikationskomponente finden Sie in der detaillierten Dokumentation zur Komponente ws-search.

​
Sucheingabefeld mit optionaler Suggestfunktion

Das Sucheingabefeld wird über die <ws-search-box> Komponente eingebunden. Diese Komponente bildet das Frontend-Eingabefeld ab und kann optional mit einer Suggestfunktion ergänzt werden. Zusätzlich kann ein Button zur Absendung der Suchanfrage über die <ws-search-button> Komponente integriert werden. 
<ws-search-box use-suggest="true">
    <input type="search" name="query" placeholder="Artikel suchen">
    <ws-search-button>
        <button type="button" title="Suche abschicken"></button>
    </ws-search-button>
</ws-search-box>
Weitere Details zur Nutzung der Komponenten finden Sie in den detaillierten Dokumentationen zur Komponente ws-search-box und ws-search-button.

​
Such-Event-Dispatcher & Weiterleitung von Suchanfragen

Das folgende Skript ist erforderlich, um Suchanfragen korrekt zu verarbeiten, Suchergebnisse global im Shop bereitzustellen und neue Suchanfragen auf die Suchergebnisseite weiterzuleiten. Es 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)}
		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>
Das Skript hat die folgenden Aufgaben:
  • Verarbeitung der Suchergebnisse (wsResultDispatcher.subscribe)
    • Überwacht die JSON-Antwort des Such-Moduls und gibt die erhaltenen Daten in der Konsole aus.
    • Erstellt eine Liste der Produktnummern und bereitet sie für eine AJAX-Anfrage zum Laden der Produktboxen vor.
    • Wenn Suchergebnisse vorliegen, wird ws_AJAXloadTemplatePOST() ausgeführt, um die Produktboxen nachzuladen.
  • AJAX-Methoden für den Produktbox-Request
    • Stellt leere Funktionen für die AJAX-Events start, success, error und failure bereit.
    • Diese können bei Bedarf mit eigenen Funktionen überschrieben oder erweitert werden.
  • Event-Listener für neue Suchanfragen (wsPerformSearch Event)
    • Sorgt dafür, dass Suchanfragen auf die Suchergebnisseite weitergeleitet werden.
    • Sobald eine neue Suchanfrage gestartet wird, wird die URL entsprechend angepasst und der Benutzer wird auf die Ergebnisseite weitergeleitet.
  • Extrahiert Suchparameter aus der URL (DOMContentLoaded Event)
    • Lädt beim Seitenaufbau die aktuellen Suchparameter aus der URL.
    • Bereitet die Parameter für weitere Funktionen oder Filtermechanismen vor.

​
Integration auf der Suchergebnisseite (ws_search.htm)

Das Standard-Template für die Anzeige der Suchergebnisseite ist ws_search.htm.

​
Verwendung der Komponente ws-search-result

Die Komponente <ws-search-result> liefert die Produktliste basierend auf dem eingegebenen Suchbegriff, den gewählten Filtern und Sortieroptionen. 
<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 Abschnitt 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 Suchergebnisse

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. 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. Weitere Details zur Nutzung und Konfiguration finden Sie in den detaillierten Dokumentationen:

​
Sortierung der Suchergebnisse

Die Sortierung wird über die Komponente <ws-sort-box> gesteuert: 
<ws-sort-box use-api="true"></ws-sort-box>
Weitere Details zur Komponente finden Sie in der detaillierten Dokumentation zu ws-sort-box.

​
Paginierung / Blättern der Suchergebnisse

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: