> ## 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.

# ws-search

> ws-search ist die Wurzel-WebComponent der Suche: sie initialisiert API-Verbindung, Konfiguration und bindet ws-search-box, ws-filters und ws-search-result ein.

Die Komponente `<ws-search>` stellt die Verbindung zwischen dem Frontend (Sucheingabefeld, Filter) und dem Such-Backend her. Sie ist erforderlich, um die Suchanfragen auszuführen und die Daten für Filter und Suchergebnisse abzurufen.

## Voraussetzung

* Die Komponente muss auf jeder Seite vorhanden sein, auf der `<ws-search-box>` genutzt wird, jedoch nur einmal pro Seite.

## Komponente

Die Komponente kann wie folgt auf der Kategorie- und Suchergebnisseite eingebunden 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~"
  {ST-CatPage}category="~CAT-Index~"{/ST-CatPage}                          <!-- Schreibweise WEBSALE V8 -->
  category="{{= $wsViews.current.info.category.id | ifNull('') }}"    <!-- Schreibweise WEBSALE VX -->
  page-size="24"
  default-sort="_score_desc">
</ws-search>
```

> [!NOTE]
>
> Bitte beachten: In diesem Code-Beispiel sind sowohl die `category`-Schreibweisen von WEBSALE V8 und VX beschrieben (als Kommentar direkt hinter der jeweiligen Zeile). Bitte darauf achten, den nicht gebrauchten Teil bei Verwendung zu entfernen.

* **Attribute**
  * `url`:
    * Gibt die URL für die API-Endpunkte an, über die die Suchanfragen ausgeführt werden.
    * Schema: `<ihre-shopid>.search.websale.net/api`
  * `category`: Category-ID (für Filter auf Kategorie) - leer lassen, falls man sich nicht auf einer Kategorieseite befindet.
  * Verwendung auf Kategorieseiten mit Hilfe von [ST-CatPage](https://doku.websale.net/index.html?tag_st-catpage.html) (nur für WEBSALE V8)
  * `redirect-url`: Ziel-URL, zu der bei einer Sucheingabe weitergeleitet wird (beispielsweise die Suchergebnisseite). Details siehe [Weiterleitung zur Suchergebnisseite](#weiterleitung-zur-suchergebnisseite-redirect-url).
  * `health-check`: Aktiviert einen einmaligen Status-Check des Such-Backends beim Initialisieren. Details siehe [Health-Check beim Initialisieren](#health-check-beim-initialisieren-health-check).

## Weiterleitung zur Suchergebnisseite (`redirect-url`)

Mit dem Attribut `redirect-url` leitet `<ws-search>` bei einer Sucheingabe automatisch zur angegebenen Ziel-URL weiter. Das ist auf Seiten sinnvoll, die selbst keine Suchergebnisse anzeigen (beispielsweise Landingpages oder die Startseite). Der Nutzer gibt dort einen Suchbegriff ein und landet direkt auf der Suchergebnisseite.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
<!-- Source code -->
<ws-search
  url="https://test.shop.websale.net/api"
  redirect-url="{{= $wsViews.url('Search', {}) }}">
</ws-search>

<!-- DOM Output -->
<ws-search
  url="https://test.shop.websale.net/api"
  redirect-url="/?wsvc=Search">
</ws-search>
```

**Verhalten**

* Die Weiterleitung erfolgt nur, wenn die aktuelle Seite nicht bereits die Ziel-Seite ist - das verhindert eine Redirect-Schleife auf der Suchergebnisseite selbst.
* Der Suchbegriff wird als URL-Parameter `query` an die Ziel-URL angehängt.

**Beispiel**

* Auf einer Landingpage: Suche nach „laptop" → Weiterleitung zu `/?wsvc=Search&query=laptop`
* Auf der Suchergebnisseite: Suche nach „laptop" → keine Weiterleitung, die Suche wird direkt ausgeführt

> [!NOTE]
>
> `redirect-url` ist ab `ws-search-component-1.9.1.js` verfügbar und ersetzt das bisherige Weiterleitungs-Skript im Template (Event-Listener auf `wsPerformSearch`).

## Health-Check beim Initialisieren (`health-check`)

Mit dem Attribut `health-check` prüft `<ws-search>` beim Initialisieren einmalig den Status des Such-Backends und der konfigurierten Indices. Der Check ist standardmäßig deaktiviert. Das Ergebnis wird ausschließlich in der Browser-Konsole ausgegeben.

```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~"
  health-check="true">
</ws-search>
```

**Verhalten**

* Bei aktiviertem Check wird beim Initialisieren ein Request an `<url>/health?subshop=<subshop>` ausgeführt.
* Das Konsolen-Level wird aus dem Ergebnis abgeleitet:

| **Ergebnis** | **Konsolen-Ausgabe** |
| - | - |
| Alle Indices OK | `console.info` |
| Einzelne Indices mit Fehlern | `console.warn` |
| Kein funktionierender Index | `console.error` |

* **Attribute**
  * `health-check`: `true` / `yes` aktiviert den Check. Default: deaktiviert.

> [!NOTE]
>
> `health-check` ist ab `ws-search-component-1.9.1.js` verfügbar. Der zugehörige API-Endpunkt setzt websale\_search ab Version 1.20.1 voraus.

## CSS & Styling

Die Komponente erzeugt keinen weiteren HTML- oder CSS-Code, da es sich nicht um eine visuelle Komponente handelt.

Es können weder innerhalb der Komponente noch durch die Ausgabe CSS-Anpassungen oder HTML-Elemente ergänzt werden.


## Related topics

- [ws-search-button](https://dokumentation.websale.de/ws-search/integration-in-die-templates-storefront/webcomponents/ui-komponenten/ws-search-button.md)
- [ws-search-box](https://dokumentation.websale.de/ws-search/integration-in-die-templates-storefront/webcomponents/ui-komponenten/ws-search-box.md)
- [ws-search-info](https://dokumentation.websale.de/ws-search/integration-in-die-templates-storefront/webcomponents/ui-komponenten/ws-search-info.md)
- [ws-search-result](https://dokumentation.websale.de/ws-search/integration-in-die-templates-storefront/webcomponents/ui-komponenten/ws-search-result.md)
- [ws-search-result-tabs](https://dokumentation.websale.de/ws-search/integration-in-die-templates-storefront/webcomponents/ui-komponenten/ws-search-result-tabs.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.