> ## Documentation Index
> Fetch the complete documentation index at: https://dokumentation.websale.de/llms.txt
> Use this file to discover all available pages before exploring further.

# Suche & Suchergebnisseite

> Sucheingabefeld ws-search-box, Suggest-Vorschläge und Suchergebnisseite mit After-Search-Navigation in den WEBSALE Shop-Templates einrichten.

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](https://doku.websale.net/index.html?guide_jsjq.html) sowie in der Übersicht der [verfügbaren Versionen und Module](https://doku.websale.net/index.html?mats_wsjsbibliothek.html).

<Info>
  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.
</Info>

### 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](https://doku.websale.net/index.html?guide_jsjq.html) 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](https://doku.websale.net/index.html?guide_jsjq.html) konfigurieren.

Falls Sie das Bundle individualisieren oder anpassen möchten, steht Ihnen die Datei zum Download unter folgender URL zur Verfügung:

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
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.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
<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](/ws-search/integration-in-die-templates-storefront/webcomponents/ui-komponenten/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.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
<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](/ws-search/integration-in-die-templates-storefront/webcomponents/ui-komponenten/ws-search-box) und [ws-search-button](/ws-search/integration-in-die-templates-storefront/webcomponents/ui-komponenten/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.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
<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.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
<ws-search-result use-ajax="yes"></ws-search-result>
```

Details zur Funktionsweise dieser Komponente finden Sie in der detaillierten Dokumentation zu [ws-search-result](/ws-search/integration-in-die-templates-storefront/webcomponents/ui-komponenten/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:

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
<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](/ws-search/integration-in-die-templates-storefront/webcomponents/template-placeholder).

### 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](#such-event-dispatcher-weiterleitung-von-suchanfragen)) entsprechend angepasst werden.

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{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.

<Info>
  `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.
</Info>

### 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](/ws-search/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:

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
<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](/ws-search/integration-in-die-templates-storefront/webcomponents/ui-komponenten):

* [ws-filter](/ws-search/integration-in-die-templates-storefront/webcomponents/ui-komponenten/ws-filter)
* [ws-filter-chip](/ws-search/integration-in-die-templates-storefront/webcomponents/ui-komponenten/ws-filter-chip)
* [ws-filter-reset](/ws-search/integration-in-die-templates-storefront/webcomponents/ui-komponenten/ws-filter-reset)

### Sortierung der Suchergebnisse

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

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
<ws-sort-box use-api="true"></ws-sort-box>
```

Weitere Details zur Komponente finden Sie in der detaillierten Dokumentation zu [ws-sort-box](/ws-search/integration-in-die-templates-storefront/webcomponents/ui-komponenten/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:

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
<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-search/integration-in-die-templates-storefront/webcomponents/ui-komponenten):

* [ws-page-size-selector](/ws-search/integration-in-die-templates-storefront/webcomponents/ui-komponenten/ws-page-size-selector)
* [ws-pagination](/ws-search/integration-in-die-templates-storefront/webcomponents/ui-komponenten/ws-pagination)
* [result.from, result.to & result.total](/ws-search/integration-in-die-templates-storefront/webcomponents/template-placeholder/anzahl-der-ergebnisse)