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.

Inhaltsverzeichnis

1 1. Globale Einbindung auf allen Templates
2 2. Integration auf der Suchergebnisseite (ws_search.htm)

1. Globale Einbindung auf allen Templates

In den meisten Fällen wird das Sucheingabefeld (ws-searchbox) 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 eine 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.

1.1 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 zur WEBSALE JavaScript-Bibliothek finden Sie hier.
Eine Übersicht über verfügbare Versionen und Module der WEBSALE JavaScript-Bibliothek finden Sie hier.

Hinweis: 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.

1.2 JavaScript-Bundle (ws-search-component-1.0.1.js)

WEBSALE stellt ein JavaScript-Bundle mit dem Namen ws-search-component-1.0.1.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-1.0.1.js

Durch diese Möglichkeit können Sie spezifische Anpassungen für Ihre Shop-Templates vornehmen, beispielsweise Änderungen am Verhalten der Suche oder Filterlogik.

1.3 Kommunikationskomponente

Die Kommunikationskomponente wird überall benötigt, wo das Sucheingabefeld (ws-searchbox) verwendet wird. Sie stellt sicher, dass Suchanfragen korrekt verarbeitet und an das Backend übermittelt werden.


<ws-communication url="https://<ihre-shopid>.search.websale.net/api" subshop="~WS-SubShopID~" version="1.0"> </ws-communication>

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

1.4 Sucheingabefeld mit optionaler Suggestfunktion

Das Sucheingabefeld wird über die <ws-searchbox> 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-searchbox 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-searchbox>

Weitere Details zur Nutzung Komponenten finden Sie in den detaillierten Dokumentationen zur Komponente ws-searchbox und ws-search-button.

1.5 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 wsElementsFound = false;

		// Produktnummern auslesen und für weitere Verarbeitung vorbereiten
		for (var i = 0; i < wsResultList.length; i++) {
			wsElementsFound = true;
			wsPayload += "&ws_pl_" + (i + 1) + "=";
			wsPayload += wsResultList[i]._id;
		}

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

	// 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('newSearch', function(event) {
    	event.preventDefault();
		location.href = "~URL-Homepage~" + "?act=search&query=" + 
			encodeURIComponent(event.detail.query);
		return false;
	});
	{/!DC-FPTemplate(ws_search.htm)}
    
	// Extrahiert Suchparameter aus der URL beim Laden der Seite
	document.addEventListener('DOMContentLoaded', () => {
		const url = new URL(window.location.href);
		const searchParams = new URLSearchParams(url.search);
	});
</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 (newSearch 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.

2. Integration auf der Suchergebnisseite (ws_search.htm)

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

2.1 Verwendung der Komponente ws-search-results

Die Komponente <ws-search-results> liefert die Produktliste basierend auf dem eingegebenen Suchbegriff, den gewählten Filtern und Sortieroptionen.

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

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

2.2 Template-Platzhalter für die Produktbox

Damit die Darstellung der Suchergebnisse über die WEBSALE Produktbox erfolgen kann, wird für jedes Produkt eine eindeutige ID definiert.

Diese ID wird in einem <template> mit folgender Struktur angelegt:

<template id="resultItemTemplate">
    <div id="wsProductWebComponent-{{result.prodindexbase}}" class="result-item">
        {{result.brand}}
        {{result.name}}
        <div data-sep=",">{{result.price}} €</div>
    </div>
</template>

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

2.3 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 Punkt 1.5) 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.

Hinweis: 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.

2.4 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>

  <!-- Produktdaten-Filter -->   
  <ws-filter type="checkbox" multiple="true" name="color" filter-msg="Kein Filter vorhanden"></ws-filter>
  <ws-filter type="checkbox" multiple="true" name="salesrank"></ws-filter>
  
  <!-- Custom-Filter -->
  <ws-filter type="checkbox" multiple="true" name="salesrank" filter-msg="Kein Filter für Topseller vorhanden"></ws-filter>
  <ws-filter type="checkbox" multiple="true" name="rating" filter-msg="Kein Filter für Bewertung vorhanden"></ws-filter>
  <ws-filter type="checkbox" multiple="true" name="new_field" filter-msg="Kein Filter für Neue Produkte vorhanden"></ws-filter>
  <ws-filter type="checkbox" multiple="true" name="inventory" filter-msg="Kein Filter für Lagerbestand vorhanden"></ws-filter>
  <ws-filter type="checkbox" multiple="true" name="reduced_field" filter-msg="Kein Filter für Sales vorhanden"></ws-filter>
  
</ws-filters>

<ws-filter-chip></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:

2.5 JavaScript zum Rendering der Filter

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

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

Das Skript zeigt die erhaltenen Ergebnisse (resultData) in der Browser-Konsole an, um eine schnelle Kontrolle zu ermöglichen.

Hinweis: Nutzen Sie das Javascript bereits für die Suche & Suchergebnisseite können Sie es auch auf dem Kategorietemplate verwenden.

2.6 Sortierung der Suchergebnisse

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

<ws-sortbox></ws-sortbox>

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

2.7 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:

<!-- Anzeige der aktuellen Ergebnisse im Format "1-16 von 150 Produkten" -->
<div class="total-container">
   <div data-template="{{result.from}} - {{result.to}} von {{result.total}} Produkten"></div>
</div>

<!-- Auswahl der Anzahl der Einträge pro Seite -->
<ws-paging-size-selector type="dropdown" default="16" options='[16, 32, 48, 64, 80]'></ws-paging-size-selector>

<!-- Blätterfunktion für die Navigation zwischen den Seiten -->
<ws-pagination maxVisiblePages="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: