Omnisearch

Angetrieben von Clerks neuester Search-Technologie bietet Omnisearch Ihnen die Flexibilität, die Sie benötigen, um das beste moderne Sucherlebnis zu bieten:

• Live-Ergebnisse werden Ihren Besuchern während der Eingabe angezeigt und beinhalten Produkte, Kategorien und Seiten.
• Sortierung und Filterung: Damit Ihre Besucher ihre Suche auf intuitive und einfache Weise verfeinern können.
• Einfach zu integrieren in Ihre Website mit einer unserer großartigen Startvorlagen.
• Es passt zu Ihrer Marke, indem Sie wenige Standard-Einstellungen wie Logo, Schriftarten, Farben und mehr anpassen.
• Vollständig anpassbar mit HTML, CSS und Liquid für Entwickler.

Erste Schritte #

Omnisearch besteht aus einem anpassbaren Design für das visuelle Erscheinungsbild und einem Element-Block, der die Installation auf Ihrer Website ermöglicht.

Ein Design erstellen #

Dies erfolgt in Search > Designs > New Design

Wählen Sie den Typ Omnisearch, wählen Sie ein Startdesign und geben Sie ihm einen Namen.

Klicken Sie auf Save & Close, um das Standarddesign abzuschließen.

Unsere Standarddesigns funktionieren sofort und können jederzeit später bearbeitet werden. Für die Bearbeitung sind Kenntnisse in HTML, CSS und Liquid erforderlich. Weitere Informationen finden Sie unter Styling in diesem Leitfaden.

Ein Element erstellen #

Dies erfolgt in Search > Element > New Element

Element-Blöcke sind Container für Elemente, die Sie in Ihrem my.clerk.io-Konto erstellen. Sie enthalten die Logik zur Anzeige von Ergebnissen und Einstellungen dafür, wie viele Ergebnisse angezeigt werden sollen. Die Logik für den leeren Zustand kann auch über Rules gesteuert werden.

• Name hilft Ihnen, Ihr Element zu erkennen, falls Sie mehr als eines erstellen möchten. Es kann später geändert werden.

• Elementtyp ist standardmäßig Omnisearch und sollte nicht geändert werden. Hier können Sie auch Filter hinzufügen, wenn nötig – in den meisten Setups ist dies nicht notwendig.

• Logik für den leeren Zustand ermöglicht Ihnen die Auswahl, welche Produkttypen beim erstmaligen Öffnen von Omnisearch angezeigt werden, bevor Suchbegriffe eingegeben wurden. Standardmäßig ist dies Bestsellers, kann aber z. B. mit Visitor Recommendations personalisiert werden.

Design abschließen #

Das Design, das zur Darstellung des Element-Blocks verwendet wird. Wählen Sie das erstellte Design aus.

Wenn Ihr Design Variablen enthält, können diese hier ebenfalls festgelegt werden.

Sie können die Anzahl der Ergebnisse für jeden Typ bei jeder Suche einstellen. Wir empfehlen im Allgemeinen folgende Mengen:

• Produkte: 20–60
• Vorschläge: 5
• Kategorien & Seiten: 10

Wählen Sie abschließend die Attribute, die Sie als Facetten einbinden möchten, und legen Sie fest, wie deren Namen in den Suchergebnissen angezeigt werden sollen. Falls Sie ein bestimmtes Attribut nicht in der Liste finden, fügen Sie es zur Liste „filterable attributes“ in der Search Configuration hinzu.

In die Seite einfügen #

Die empfohlene Methode hierfür ist die Injection, aber Sie können das Element auch mit einem Embedcode auf Ihrer Seite einfügen.

Sichtbarkeit steuert, wer die Omnisearch sehen kann.

• Im Vorschau-Modus können Sie Ihr Element testen, ohne dass Ihre Live-Seite beeinflusst wird. Sie können Ihre Seite in der Vorschau öffnen, indem Sie auf “Open site in preview” klicken oder ?clerk_content_mode=preview an die URL Ihrer Seite anhängen.

• Auf meiner Live-Seite wird genutzt, wenn Sie mit dem Testen fertig sind und das Element veröffentlichen möchten.

Verwendung von Injection #

Dies ist der einfachste Weg zur Installation. Clerk fügt den Omnisearch-Code automatisch zu Ihrer Seite hinzu, indem ein Suchfeld Ihrer Wahl angesprochen und ein Ereignis als Trigger genutzt wird.

• Ereignis (Event) steuert, was der Nutzer tun muss, um Omnisearch auszulösen. In der Regel möchten Sie, dass das Overlay angezeigt wird, wenn Besucher auf das Suchsymbol oder das Suchfeld klicken.

• Element legt fest, mit welchem Teil der Webseite der Nutzer interagieren soll. Möchten Sie z. B., dass Ihr Omnisearch-Element nur angezeigt wird, wenn Besucher mit Ihrer Suchleiste interagieren (anklicken oder den Fokus darauf richten), müssen Sie lediglich den passenden CSS-Selektor dazu angeben. Falls Sie unterschiedliche Identifikatoren für Mobil und Desktop haben, fügen Sie beide hinzu.

So finden Sie Ihren eindeutigen CSS-Selektor:

1. Untersuchen Sie den Code Ihrer Seite. In den meisten Browsern können Sie dazu mit der rechten Maustaste auf die Seite klicken und Untersuchen oder Ähnliches wählen.
2. Suchen Sie das Element, das Sie ansprechen möchten.
3. Rechtsklick darauf und die Option Kopieren > Selektor kopieren wählen.

Verwendung eines Embedcodes #

Damit können Sie Omnisearch mit einem Snippet einbinden. Dafür benötigen Sie Zugang zu den HTML-Dateien Ihres Webshops oder Sie fügen Code mit einem Editor hinzu.

Falls Sie nicht gespeicherte Änderungen haben, speichern Sie diese, um den Embedcode zu generieren.

Kopieren Sie den Code und fügen Sie ihn in die Datei ein, die alle Seiten Ihres Webshops generiert, idealerweise in der Nähe des </body>-Tags.

Ersetzen Sie INSERT_CSS_SELECTOR_FOR_ELEMENT_THAT_SHOULD_TRIGGER_OMNISEARCH mit dem CSS-Selektor des HTML-Elements, das Omnisearch auslösen soll.

Nachfolgend finden Sie ein vollständiges Beispiel für einen Omnisearch-Embedcode mit allen Konfigurationsoptionen:

<span class="clerk"
    data-template="@omnisearch"
    data-api="search/omni"
    data-trigger-element="INSERT_CSS_SELECTOR_FOR_ELEMENT_THAT_SHOULD_TRIGGER_OMNISEARCH"
    data-limit="40"
    data-suggestions="6"
    data-categories="6"
    data-pages="6"
    data-omni-search-suggestions="6"
    data-omni-search-categories="6"
    data-omni-search-pages="6"
    data-omni-search-empty="recommendations/popular">
</span>

Anzeigemodi #

Omnisearch unterstützt zwei Anzeigemodi, die steuern, wie die Suchoberfläche auf Ihrer Website erscheint. Dies konfigurieren Sie im Tab Insert, wenn Sie Ihr Omnisearch-Element bearbeiten.

Vollständiges Overlay (Full overlay) #

Dies ist der Standardmodus. Bei Auslösung bedeckt Omnisearch den gesamten Viewport mit einem Fullscreen-Overlay. Die Suche übernimmt die Seite und ermöglicht ein fokussiertes Sucherlebnis.

Verwenden Sie diesen Modus, wenn Sie Folgendes möchten:

• Eine ablenkungsfreie Suchumgebung
• Volle Kontrolle über das Layout der Suche
• Dass die Suchoberfläche komplett unabhängig von Ihrem Seiten-Header ist

Teilweises Overlay (Partial overlay) #

In diesem Modus wird Omnisearch in Ihren bestehenden Header integriert. Anstatt den gesamten Bildschirm zu überdecken, erscheint das Such-Overlay unterhalb Ihres Headers, während dieser weiterhin sichtbar und benutzbar bleibt.

Verwenden Sie diesen Modus, wenn Sie Folgendes möchten:

• Ihr Header und Ihre Navigation bleiben während der Suche zugänglich
• Eine nahtlosere Integration in das bestehende Layout Ihrer Seite
• Das Sucherlebnis fühlt sich wie ein natürlicher Bestandteil Ihrer Seite an

Konfigurationsoptionen #

Wenn Partial Overlay ausgewählt ist, stehen zusätzliche Einstellungen zur Verfügung:

Header-Selektor

Der CSS-Selektor für das Header-Element Ihrer Seite. Omnisearch nutzt diesen, um das Overlay direkt unter Ihrem Header auszurichten.

Beispielhafte Selektoren:

• header
• .site-header
• #main-header

Search input selector

Der CSS-Selektor für Ihr bestehendes Suchfeld. Ist dieser angegeben, synchronisiert Omnisearch sich mit dem Suchfeld im Header und ermöglicht so eine einheitliche Suche, bei der die Eingabe im Header-Suchfeld die Omnisearch-Ergebnisse aktualisiert.

Beispielhafte Selektoren:

• #search-input
• .header-search input
• [name="search"]

Breite

Steuert die horizontale Größe des Overlays:

• Gesamte Breite: Über die gesamte Viewport-Breite
• Inhaltsbreite: Entspricht der Breite eines von Ihnen mit CSS-Selektor angegebenen Container-Elements
• Feste Breite: Von Ihnen definierte Pixelbreite

Höhe

Steuert die vertikale Größe des Overlays:

• Vom Header bis unten: Füllt den Bereich unterhalb des Headers bis an den unteren Rand des Viewports
• Prozentsatz des Viewports: Ein Prozentsatz der Höhe des Viewports (z. B. 80 %)
• Feste Höhe: Eine festgelegte Pixelhöhe
• Maximale Höhe: Setzt ein oberes Limit, lässt das Overlay aber kleiner werden, wenn weniger Platz benötigt wird

Horizontale Ausrichtung

Steuert die horizontale Position des Overlays:

• Links: Am linken Rand des Viewports ausgerichtet
• Zentriert: Horizontal zentriert
• Rechts: Am rechten Rand des Viewports ausgerichtet

Vertikale Position

Steuert die vertikale Platzierung bezüglich des Headers:

• Unter dem Header: Das Overlay wird direkt unter dem Header-Element positioniert
• Fest vom oberen Rand: Fester Pixelabstand vom oberen Rand des Viewports

Design-Konfiguration #

Das meiste der Omni-Search kann durch Änderung der Variablen in den Design-Dateien konfiguriert werden.

In der Liquid-Template-Sprache hat eine Variable den Aufbau:

{% assign variable_name = "variable value" %}

Als Faustregel gilt, dass nur der Wert der Variable zur Konfiguration der Omni-Search geändert werden sollte.

Technisch versierte Nutzer können auch spezifische HTML- und CSS-Zeilen anpassen, siehe diesen Abschnitt.

Logo #

Um ein Logo zum Omnisearch-Design hinzuzufügen, setzen Sie os_brand_logo auf die Bild-URL Ihres Logos.

Infinite/Auto Load #

Falls Sie steuern möchten, ob Omni-Search automatisch mehr Produkte lädt, sobald der Nutzer zur letzten Produktreihe scrollt, sollte die Variable auf true oder false gesetzt werden. Die Variable heißt in der Regel os_autoload. Setzen Sie sie auf false, um zu verhindern, dass Omnisearch weitere Ergebnisse automatisch lädt.

Übersetzungen #

Standardmäßig ist die Vorlage auf Englisch. Wenn Ihr Shop eine andere Sprache hat, können Sie die Textelemente durch Änderung der Variablen-Werte übersetzen.

Übersetzen Sie die Variablen der Sortier-Schaltfläche sowie die anderen Textvariablen.

Profitipp: Nutzen Sie generative KI (z. B. chatGPT) für Massenübersetzungen, indem Sie schreiben: „Übersetze diese Variablenwerte von Englisch nach Dänisch. Gib den vollständigen Code zurück, damit er kopiert/ersetzt werden kann: PASTE_VARIABLES_HERE“

Styling #

Jede Stil-Änderung kann in den CSS-Variablen vorgenommen werden.

Die Vorlagen verwenden CSS-Variablen, die so aufgebaut sind:

--variable_name: variable_value;

Fortgeschrittene Nutzer können auch einzelne CSS-Regeln anpassen, um komplexere Designanpassungen vorzunehmen.

Farben #

Die konfigurierbaren Farben finden Sie im Abschnitt unter dem CSS-Kommentar „Colors“ /* Colors */

Schriftarten #

Analog zu den Farben finden Sie die Schriftvariablen unter dem Kommentar /* Font */.

Typisch sieht die Variable so aus: --font-family: 'Kumbh Sans', sans serif;

Standarddesign #

Das Standarddesign für Omnisearch umfasst:

• Variantenauswahl (Dropdown-Varianten): Ermöglicht Käufern die Auswahl von Varianten-Attributen (z. B. Größe, Farbe), bevor sie etwas in den Warenkorb legen.

• Mengen-Auswahl.

• Native Add-to-Cart-Schaltfläche, die Clerk.js benachrichtigt, sodass Analytik und Merchandising synchron bleiben.

• Sauberes, gut strukturiertes Markup mit klaren Kommentaren.

• Zentralisierte Variablen für Styling und Verhalten, für leichte Anpassung von Farben, Abständen, Beschriftungen und Optionen ohne Änderung des Kerncodes.

• Preisschieberegler als Facette für schnelle Bereichsfilterung.

• Anklickbare Vorschläge, die sofort eine Suche auslösen.

Für Entwickler #

Styling #

Designs bestehen aus einem Hauptlayout, CSS-Styling und einer Reihe von Sub-Designs, die im Hauptlayout referenziert werden können.

Sie können all dies für Desktop und Mobilgeräte getrennt bearbeiten. Standardmäßig verwendet die Omni-search dasselbe HTML für alle Bildschirmgrößen und sorgt über CSS für volle Responsivität. Daher ist der Mobile-Tab anfangs leer.

Bei Bedarf können Sie ein völlig anderes HTML-Markup für Mobilgeräte erstellen, das auf kleineren Bildschirmen genutzt wird.

Anfangs möchten Sie vielleicht nur Kleinigkeiten anpassen, damit das Design Ihrer Marke entspricht – Sie können das Design jederzeit später bearbeiten.

HTML #

Dies ist das Hauptlayout, das die Platzierung aller Elemente steuert. Es verwendet Liquid als Template-Sprache.

In unseren Startdesigns ist der erste Abschnitt den am häufigsten geänderten Elementen gewidmet, wie Sortierlabels, Währung und allen Texten, die Sie in Ihre Sprache übersetzen können.

CSS #

Das Styling wird zusammen mit dem HTML eingebettet und gibt Ihnen volle Kontrolle über das Aussehen, auf sichere und gekapselte Weise.

Verfügbare Sub-Designs #

Alle hier hinzugefügten Designs können im allgemeinen Layout referenziert werden. Sie funktionieren als Module, die separat bearbeitet werden und mit ihrer ID und ihrem Namen hinzugefügt werden: {{@247373 - TopBarSearchForm}}

Sie können jedes Sub-Design löschen, duplizieren oder die Referenz kopieren, indem Sie auf die Drei-Punkte-Schaltfläche klicken.

Zum Bearbeiten eines Sub-Designs klicken Sie auf das Bearbeiten-Symbol. Nach dem Bearbeiten klicken Sie auf Save & close, um zum Hauptlayout zurückzukehren.

Einige Elemente benötigen bestimmte Identifikatoren, wie:

• Das Eingabefeld id="clerk-omnisearch-input"
• Den Content Wrapper id="clerk-omnisearch-content"

Wenn Sie Ihren Fortschritt prüfen möchten, können Sie dies durch Klick auf die Schaltfläche „Preview design“ tun.

Die häufigsten Änderungen an Designs sind:

• Logo: Greifen Sie auf das TopBarSearchForm zu und ersetzen Sie das Standardlogo durch Ihr eigenes.

• Schriftarten: Falls nötig, passen Sie die Schriften an das Erscheinungsbild Ihrer Website an.

• Farben: Sie können die Markenfarben in Elementen hervorheben, die Sie betonen oder auf Ihr Corporate Design abstimmen möchten, wie z. B. Buttons und Tags.

• Schaltflächen- und Tag-Grenzen: Sie können Farbe, Radius, Breite der Umrandungen anpassen …

• Links: Falls Sie ein spezielles Link-Styling haben, können Sie auch dies anpassen.

Reaktive vs. Statische Teile #

Es ist wichtig zu wissen, welche Teile von Omnisearch bei jeder Anfrage neu gerendert werden – und welche nicht – wenn Sie das Design anpassen.

Statische Teile werden einmalig beim Öffnen des Overlays gerendert und bei späteren Anfragen nicht mehr angepasst:

• Der Overlay-Container selbst (clerk-omnisearch-overlay)
• Das Suchfeld (#clerk-omnisearch-input)
• Jegliches HTML im Design, das außerhalb von #clerk-omnisearch-content liegt – wie das Logo, der Close-Button oder die Top-Bar

Das Eingabefeld ist absichtlich statisch. Würde es bei jedem Tastendruck neu gerendert, wäre das Tipperlebnis für Besucher gestört.

Reaktive Teile sind alles innerhalb von #clerk-omnisearch-content. Diese komplette Wrapper wird bei jeder Anfrage neu gerendert:

• Produktergebnisse
• Facetten und Filter
• Kategorien, Seiten und Vorschläge
• Ergebnisanzahl und Sortiersteuerung
• Keine-Ergebnisse-Nachrichten

Soll ein Element bei jeder Suchanfrage aktualisiert werden – etwa eine Live-Ergebniszählung im Header – muss es innerhalb von #clerk-omnisearch-content platziert werden. Soll es beim Tippen des Besuchers stabil sichtbar bleiben, platzieren Sie es außerhalb.

Zustand: Keine Ergebnisse #

Wenn eine Anfrage keine Produkte findet, zeigt Omnisearch nicht automatisch ein Fallback – dies wird im Design über Liquid gesteuert.

Die empfohlene Methode ist, ob Produkte vorhanden sind zu prüfen und bedingt einen Fallback-Slider und eine benutzerdefinierte Nachricht anzuzeigen:

{% if products.length > 0 %}
  <!-- Normale Ergebnisse -->
  {% for product in products %}
    <!-- Produktkarte -->
  {% endfor %}

{% else %}
  <!-- Fallback für keine Ergebnisse -->
  <div class="clerk-no-results-message">
    Keine Ergebnisse für "{{ query }}" — hier sind stattdessen beliebte Produkte:
  </div>

  <span class="clerk"
    data-api="recommendations/popular"
    data-limit="8"
    data-template="@omnisearch-product-card">
  </span>
{% endif %}

Sie können auch results.products.no_exact_match verwenden, um zu erkennen, wenn Omnisearch unscharfe oder verwandte Ergebnisse statt exakter Resultate anzeigt und dann eine entsprechende Nachricht ausgeben:

{% if results.products.no_exact_match %}
  <div class="clerk-no-exact-match">
    Keine genauen Ergebnisse für "{{ query }}" — zeige die ähnlichsten Treffer:
  </div>
{% endif %}

Beide Muster können kombiniert werden. Ein typisches Setup zeigt die no_exact_match-Nachricht über den Ergebnissen und den Fallback-Slider nur, wenn products.length == 0.

Der Text der Keine-Ergebnisse-Nachricht ist normales HTML innerhalb des Designs und kann beliebig übersetzt oder gestylt werden, ohne Einstellungen außerhalb des Design-Editors zu ändern.

Overlay-Struktur #

Wird Omnisearch initiiert, erzeugt es ein Element mit der Klasse clerk-omnisearch-overlay, das am Ende des Bodys eingefügt wird.

Hier wird das Design eingebettet; da das Eingabefeld Teil des Designs ist, müssen strukturelle Anforderungen erfüllt werden, damit das Eingabefeld nicht bei jeder Anfrage neu gerendert wird. Die Struktur unterhalb des Overlays sollte folgendermaßen aussehen:

<div>
    <input type="text" id="clerk-omnisearch-input"/>
    <div id="clerk-omnisearch-content">
        Element!
    </div>
</div>

Eingabefeld #

Um das Eingabefeld zu identifizieren, muss es den Bezeichner clerk-omnisearch-input haben. Nach dem Triggern setzen wir den Cursor-Fokus auf dieses Element und fügen die jeweilige Suchanfrage hinzu, um das Nutzererlebnis nahtlos zu halten.

Content Wrapper #

Im Content Wrapper findet das meiste statt; der Wrapper muss den Bezeichner clerk-omnisearch-content haben. Hier sollten die Facets, Slider und alles platziert werden, was nicht das Eingabefeld ist.

Klassen #

Designs können durch das Hinzufügen bestimmter Klassen zu Elementen mit Funktionalität angereichert werden.

Schließen-Button #

clerk-omnisearch-close

Wenn Sie die Klasse einem Element im Design geben, blendet dieses das Overlay aus.

Sortierung #

clerk-omnisearch-sort

Findet Dropdowns für die Sortierung und fügt ihnen Listener hinzu.

Um ein Sortier-Element im Design zu erhalten, fügen Sie dies in das Drop-Down-Element ein. Damit es funktioniert, benötigt es den Wert in folgender Form: value:[desc|asc], also den Wert, nach dem sortiert werden soll, Doppelpunkt, dann entweder desc oder asc. Optional kann das Attribut data-sort-type hinzugefügt werden, wenn nach Kategorien oder Seiten sortiert werden soll.

Search Facet #

clerk-facet-search

Ist ein Facet-Search vorhanden, wird ein Listener erzeugt und Facets, die nicht zur Anfrage passen, werden ausgeblendet.

Die Klasse prüft beim Vorhandensein in einer Webseite, ob Facet-Search-Elemente existieren. Facet-Searches bieten eine Möglichkeit zur Suche innerhalb der Facetten. Damit es funktioniert, benötigt das Element einen string-Wert.

Vollständiges Zurücksetzen #

clerk-omnisearch-full-reset

Wird darauf geklickt, werden mit dieser Klasse alle gewählten Facets gelöscht und die Suchanfrage wird zurückgesetzt.

Facet-Löschen Alle #

clerk-omnisearch-facet-full-reset

Beim Klick werden mit dieser Klasse alle aktiven Facets abgewählt. Typischerweise findet man dies auf einem “Alles löschen”-Button innerhalb einer Facettengruppe, was dem Nutzer ermöglicht, alle gewählten Filter einfach zurückzusetzen.

Gruppen-Löschen #

clerk-omnisearch-facet-group-reset

Beim Klick werden mit dieser Klasse alle Kindelemente der Gruppe abgewählt.

Um eine Funktion zum Abwählen einer gesamten Facettengruppe zu bieten, geben Sie einem Element diese Klasse. Nach Aktivierung (z. B. Klick) werden alle Elemente innerhalb dieser Gruppe deaktiviert. Damit es funktioniert, muss das Element das gegebenen Attribut data-facet-group besitzen.

Facet-Löschen Einzeln #

clerk-omnisearch-facet-reset

Elemente mit dieser Klasse müssen ein einzelnes Element mit dem angegebenen Gruppen-/Wert-Attribut-Paar abwählen.

Diese Klasse ist für Szenarien gedacht, in denen nur ein einzelner Facet abgewählt werden muss. Ein Element mit dieser Klasse kann einem bestimmten Facet in einer Gruppe zugewiesen werden, indem es sowohl data-facet-group als auch data-facet-value erhält. Nach Aktivierung wird nur dieser Facet auf Basis des Attribut-Paars abgewählt, andere bleiben gewählt.

Facet-Klick #

clerk-facet

Elemente mit dieser Klasse werden als auswählbare Facet behandelt.

Alle Facets benötigen eine Klasse mit den Attributen data-facet-group und data-facet-value, damit erkannt werden kann, was der Kunde anklickt.