Omnisearch

• Live-Ergebnisse werden Ihren Besuchern beim Tippen angezeigt und beinhalten Produkte, Kategorien und Seiten.
• Sortieren und Filtern: Damit Ihre Besucher ihre Suche auf intuitive und einfache Weise verfeinern können.
• Leicht zu integrieren in Ihre Seite mit einem unserer großartigen Start-Templates.
• Passt sich Ihrer Marke an, indem Sie einige Standardeinstellungen wie Logo, Schriftarten, Farben und mehr ändern.
• Vollständig anpassbar mit HTML, CSS und Liquid für Entwickler.

Einstieg #

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

Ein Design erstellen #

Dies erfolgt unter Search > Designs > New Design

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

Klicken Sie auf Save & Close, um das Standarddesign fertigzustellen.

Unsere Standarddesigns funktionieren sofort und können jederzeit 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 wird durchgeführt unter 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 der Ergebnisse sowie Einstellungen, wie viele Ergebnisse angezeigt werden sollen. Die Empty State Logic kann durch Rules angepasst werden.

• Name hilft Ihnen, Ihr Element zu identifizieren, falls Sie mehr als eines erstellen möchten. Er 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, falls notwendig, aber für die meisten Setups ist das nicht erforderlich.

• Empty State Logic ermöglicht die Auswahl des Produkttyps, der angezeigt werden soll, wenn Omnisearch zu Beginn geöffnet wird, bevor etwas eingegeben wurde. Standardmäßig ist dies Bestseller, aber es kann z. B. personalisiert werden, etwa mit Visitor Recommendations.

Design abschließen #

Das Design zur Darstellung des Element-Blocks. Wählen Sie das von Ihnen erstellte Design aus.

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

Sie können steuern, wie viele Ergebnisse für jeden Typ bei jeder Suche angezeigt werden. 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 Facets aufnehmen möchten und legen Sie deren Anzeigenamen in den Suchergebnissen fest. Falls Sie ein bestimmtes Attribut in der Liste nicht finden, fügen Sie es zur „filterbare Attribute“-Liste in der Search Configuration hinzu.

In die Website einfügen #

Sichtbarkeit dient zur Steuerung, wer Omnisearch sehen kann.

• In der Vorschau können Sie Ihr Element testen, ohne Ihre Live-Site zu beeinflussen. 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-Site wird verwendet, wenn Sie mit dem Testen fertig sind und Omnisearch öffentlich machen möchten.

Verwendung von Injection #

Dies ist die einfachste Installationsmethode. Clerk fügt den Omnisearch-Code automatisch Ihrer Seite hinzu, indem ein Suchfeld Ihrer Wahl getargeted wird und das Auslösen auf einem Event basiert.

• Event steuert, was der Benutzer tun muss, um Omnisearch auszulösen. Höchstwahrscheinlich möchten Sie es anzeigen, wenn Ihre Besucher auf Ihr Suchicon oder das Eingabefeld klicken.

• Element bestimmt den Teil der Website, mit dem der Nutzer interagieren soll. Wenn Sie z. B. möchten, dass Ihr Omnisearch-Element nur erscheint, wenn Ihre Besucher mit Ihrer Suchleiste interagieren (Klick oder Fokus), müssen Sie lediglich den eindeutigen CSS-Selektor finden, der darauf angewandt wird. Falls Sie auf Mobil und Desktop verschiedene Kennungen verwenden, geben Sie beide an.

So finden Sie Ihren eindeutigen CSS-Selektor:

1. Inspizieren Sie den Seiten-Code. In den meisten Browsern können Sie mit der rechten Maustaste irgendwo auf der Seite klicken und Inspect oder ähnlich wählen.
2. Finden Sie das zu targetierende Element.
3. Rechtsklick darauf und die Option copy > copy selector wählen

Verwendung von eingebettetem Code #

Speichern Sie nicht gespeicherte Änderungen, um den Einbettungscode zu generieren.

Kopieren Sie diesen Code und fügen Sie ihn in die Datei ein, die alle Seiten Ihres Webshops generiert – idealerweise nahe dem </body>-Tag.

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

Nachfolgend ein vollständiges Beispiel eines Omnisearch-Einbettungscodes 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>

Anzeige-Modi #

Omnisearch unterstützt zwei Anzeigemodi, die kontrollieren, wie die Suchoberfläche auf Ihrer Website dargestellt wird. Konfigurieren Sie dies im Insert-Tab beim Bearbeiten Ihres Omnisearch-Elements.

Vollständige Überlagerung #

Dies ist der Standardmodus. Wenn Omnisearch ausgelöst wird, überdeckt es den kompletten Viewport mit einer Fullscreen-Überlagerung. Die Suchoberfläche übernimmt die Seite und bietet ein fokussiertes Sucherlebnis.

Verwenden Sie diesen Modus, wenn Sie möchten:

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

Teilweise Überlagerung #

In diesem Modus wird Omnisearch in Ihren bestehenden Seiten-Header integriert. Anstatt den gesamten Bildschirm zu überdecken, erscheint die Suchüberlagerung unterhalb des Headers, wobei dieser sichtbar und funktionsfähig bleibt.

Verwenden Sie diesen Modus, wenn Sie möchten:

• Dass Header und Navigation während der Suche zugänglich bleiben
• Eine nahtlose Integration in das bestehende Seiten-Layout
• Dass die Suche als natürlicher Teil Ihrer Seite wirkt

Konfigurationsoptionen #

Bei Auswahl der Teilüberlagerung werden zusätzliche Einstellungen verfügbar:

Header-Selektor

Der CSS-Selektor für das Header-Element Ihrer Website. Omnisearch positioniert so die Überlagerung direkt unterhalb des Headers und sorgt für korrekte Ausrichtung.

Beispiel-Selektoren:

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

Sucheingabe-Selektor

Der CSS-Selektor für Ihr bestehendes Suchfeld. Wenn definiert, synchronisiert Omnisearch mit dem Suchfeld Ihres Headers und erstellt so ein einheitliches Sucherlebnis, bei dem die Eingabe im Header-Suchfeld Omnisearch-Ergebnisse aktualisiert.

Beispiel-Selektoren:

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

Breite

Steuert die horizontale Größe der Überlagerung:

• Volle Breite: Deckt die gesamte Viewport-Breite ab
• Containerbreite: Nutzt die Breite eines von Ihnen via CSS-Selektor spezifizierten Containerelements
• Feste Breite: Eine von Ihnen festgelegte Pixelbreite

Höhe

Steuert die vertikale Größe der Überlagerung:

• Vom Header bis zum unteren Rand: Füllt den Bereich vom unteren Rand des Headers bis zum unteren Viewportrand aus
• Viewportrprozentsatz: Ein Prozentwert der Viewport-Höhe (z.B. 80%)
• Feste Höhe: Eine feste Pixelhöhe
• Maximale Höhe: Setzt ein Maximum, lässt aber kleinere Überlagerungen zu, falls weniger Platz benötigt wird

Horizontale Ausrichtung

Kontrolliert die horizontale Positionierung der Überlagerung:

• Links: Am linken Rand des Viewports
• Zentriert: Zentriert im Viewport
• Rechts: Am rechten Rand des Viewports

Vertikale Position

Kontrolliert die vertikale Platzierung relativ zum Header:

• Unter dem Header: Direkt unterhalb des Header-Elements positioniert
• Fixiert vom oberen Rand: Fester Pixelabstand vom oberen Viewportrand

Design-Konfiguration #

Das meiste von Omnisearch kann durch Änderung der Variablen in den Design-Dateien angepasst werden.

In der Liquid Template Language haben Variablen die folgende Struktur:

{% assign variable_name = "variable value" %}

Grundsätzlich sollte nur der Variablenwert geändert werden, um Omnisearch zu konfigurieren.

Technisch versiertere Nutzer können natürlich einzelne HTML- und CSS-Zeilen anpassen, siehe diesen Abschnitt.

Logo #

Um ein Logo zum Omni-search-Design hinzuzufügen, suchen Sie die Bild-URL und tragen Sie diese als Wert der Variable os_brand_logo ein.

Die Variable heißt normalerweise os_brand_logo und sieht dann so aus:

Unendliches/Automatisches Laden #

Wenn Sie steuern möchten, ob Omnisearch automatisch weitere Produktergebnisse lädt, sobald der Nutzer zur letzten Produktreihe scrollt, muss die Variable auf true oder false gesetzt werden. Die Variable heißt üblicherweise os_autoload. In diesem Beispiel lädt Omnisearch keine weiteren Produktergebnisse automatisch nach.

Übersetzungen #

Das Template ist standardmäßig auf Englisch. Falls Ihr Shop eine andere Sprache hat, können Sie die Textbausteine über die Variablenwerte übersetzen.

Dieses Beispiel zeigt die Variablen für den Sortier-Button:

Protip: Nutzen Sie generative KI (z. B. chatGPT), um Variablenwerte auf einmal zu übersetzen, indem Sie z. B. schreiben „Translate these variable values from English to Danish. Return the full code back so it can be copy/pasted to replace the existing code: PASTE_VARIABLES_HERE“

Styling #

Um das Styling zu ändern, kann die Konfiguration über CSS-Variablen erfolgen.

Die Templates nutzen CSS-Variablen, die wie folgt strukturiert sind:

--variable_name: variable_value;

Für technisch Versierte können individuelle CSS-Regeln geändert werden, um komplexere Designanpassungen umzusetzen.

Farben #

Konfigurierbare Farben befinden sich im Abschnitt unter dem Kommentar “Colors” /* Colors */

Schriftarten #

Analog zu den Farben findet sich die Schriftart-Variable unter dem Kommentar /* Font */.

Typischerweise etwa so: --font-family: 'Kumbh Sans', sans serif;

Standarddesign #

Das Standarddesign für Omnisearch umfasst:

• Variants-Dropdown-Unterstützung: Käufer können Variantenattribute (z.B. Größe, Farbe) vor dem Hinzufügen zum Warenkorb wählen.
• Mengen-Auswahl.
• Native Add-to-Cart-Schaltfläche, die Clerk.js benachrichtigt, damit Analytics und Merchandising synchron bleiben.
• Sauberes, klar strukturiertes Markup mit deutlichen Kommentaren.
• Zentrale Variablen für Styling und Verhalten, sodass Sie Farben, Abstände, Labels und gängige Optionen einfach anpassen können, ohne den Kerncode zu ändern.
• Price-Slider-Facet für schnelle Bereichsfilter.
• Anklickbare Vorschläge, die sofort eine Suche auslösen.

Für Entwickler #

Styling #

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

Sie können alles entsprechend für Desktop und Mobile separat bearbeiten. Standardmäßig verwendet Omnisearch das gleiche HTML für alle Bildschirmgrößen und ist durch CSS vollständig responsiv. Deshalb ist der Mobile-Tab anfangs leer.

Wenn nötig, können Sie eigenes HTML für Mobilgeräte erstellen, das auf kleineren Bildschirmen genutzt wird.

Anfangs möchten Sie vielleicht nur einige Dinge anpassen, damit das Design zum Look & Feel Ihrer Marke passt – Sie können Ihr 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 Sortier-Labels, Währung und verschiedenen Texten, die Sie in Ihre Sprache übersetzen können.

CSS #

Styling, das zusammen mit dem HTML injiziert wird und Ihnen vollständige Kontrolle über das Erscheinungsbild in einem abgeschlossenen Rahmen gibt.

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 Namen hinzugefügt werden: {{@247373 - TopBarSearchForm}}

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

Um ein Sub-Design zu bearbeiten, klicken Sie auf das Edit-Icon. Nach dem Bearbeiten klicken Sie auf Save & close, um zum Hauptlayout-Editor zurückzukehren.

Einige Elemente benötigen bestimmte Kennungen wie:

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

Immer wenn Sie Ihren Fortschritt überprüfen möchten, können Sie dafür die Schaltfläche „Preview design“ verwenden.

Die häufigsten Änderungen an Designs sind:

• Logo: Öffnen Sie das TopBarSearchForm und ersetzen Sie das Standardlogo durch Ihres.

• Schriftarten: Bei Bedarf passen Sie die Schriftarten an, damit sie zum Look Ihrer Website passen.

• Farben: Sie können Ihre Markenfarben in den Elementen einfügen, die Sie hervorheben oder mit Ihrer Webseite angleichen möchten, wie Buttons und Tags.

• Button- und Tag-Rahmen: Einstellungen zu Farbe, Radius, Breite…)

• Links: Wenn Sie ein spezifisches Link-Styling nutzen, können Sie dieses ebenfalls anpassen.

Reaktive vs. Statische Teile #

Zu verstehen, welche Teile von Omnisearch pro Abfrage neu gerendert werden – und welche nicht – ist wichtig beim Anpassen des Designs.

Statische Teile werden beim Öffnen der Überlagerung einmalig gerendert und bleiben bei späteren Abfragen unverändert:

• Der Overlay-Container selbst (clerk-omnisearch-overlay)
• Das Suchfeld (#clerk-omnisearch-input)
• Jegliches HTML im Design außerhalb von #clerk-omnisearch-content – z.B. Logo, Schließen-Button oder Top-Bar

Das Eingabefeld ist bewusst statisch. Würde es bei jedem Tastendruck neu gerendert, würde dies das Tippen des Besuchers unterbrechen.

Reaktive Teile sind alles innerhalb von #clerk-omnisearch-content. Dieser gesamte Wrapper wird bei jeder Abfrage neu gerendert:

• Produktergebnisse
• Facets und Filter
• Kategorien, Seiten und Vorschläge
• Ergebnismenge und Sortiersteuerung
• Keine-Ergebnisse-Nachrichten

Soll ein Element bei Erneuerung der Anfrage aktualisiert werden – z. B. eine Live-Ergebnisanzahl im Header – muss es innerhalb von #clerk-omnisearch-content platziert werden. Soll es beim Tippen stabil sichtbar bleiben, gehört es außerhalb dieses Wrappers.

Kein-Ergebnis-Zustand #

Wenn eine Suche keine Produkte findet, wird von Omnisearch kein Fallback automatisch angezeigt – dies erfolgt via Liquid im Design.

Die empfohlene Methode ist, zu prüfen, ob Produkte leer sind, und dann einen Fallback-Slider und eine eigene Nachricht einzublenden:

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

{% else %}
  <!-- Kein Ergebnis Fallback -->
  <div class="clerk-no-results-message">
    Keine Ergebnisse für "{{ query }}" — hier einige 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, wann Omnisearch unscharfe oder verwandte Treffer anzeigt statt exakter Ergebnisse, und dementsprechend eine Mitteilung anzeigen:

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

Beide Muster können kombiniert werden. Typischerweise erscheint die no_exact_match-Meldung inline über den Ergebnissen; der Fallback-Slider nur, wenn products.length == 0.

Der Text der Kein-Ergebnis-Meldung ist reines HTML im Design, kann also beliebig übersetzt oder gestaltet werden, ohne Konfiguration außerhalb des Design-Editors zu ändern.

Overlay-Struktur #

Wird Omnisearch ausgelöst, erzeugt es ein Element mit der Klasse clerk-omnisearch-overlay und fügt dieses ans Ende des body ein.

Hier wird das Design eingefügt, da das Eingabefeld Teil des Designs ist, ist eine strukturelle Vorgabe notwendig, um zu verhindern, dass das Eingabefeld bei jeder Anfrage neu gerendert wird. Der Aufbau sollte wie folgt unter dem Overlay aussehen:

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

Eingabefeld #

Das Eingabefeld muss den Identifier clerk-omnisearch-input besitzen. Bei Auslösen des Trigger-Elements wird der Cursor auf dieses Feld gesetzt und die aktuelle Anfrage hineingefügt, um das Nutzererlebnis nahtlos zu gestalten.

Content Wrapper #

Der Content Wrapper ist der Bereich, in dem die wichtigsten Prozesse ablaufen. Der Wrapper benötigt den Identifier clerk-omnisearch-content. Hier befinden sich Facets, Slider und alles andere außer dem Eingabefeld.

Klassen #

Funktionalität kann hinzugefügt werden, indem bestimmten Elementen spezielle Klassen zugewiesen werden.

Schließen-Button #

clerk-omnisearch-close

Wenn diese Klasse an ein Element im Design angehängt wird, blendet es das Overlay aus.

Sortierung #

clerk-omnisearch-sort

Damit werden Sortier-Dropdowns gefunden und Listener hinzugefügt.

Um ein Sortier-Element ins Design einzufügen, einfach diese Klasse dem Selektor (z.B. einem Dropdown) zuweisen. Damit es funktioniert, muss das Element folgendes Format haben: value:[desc|asc], also das Feld, nach dem sortiert werden soll, und anschließend desc oder asc. Optional kann ein Attribut data-sort-type angegeben werden, wenn nach Kategorien oder Seiten sortiert werden soll.

Search Facet #

clerk-facet-search

Wenn eine Facet-Suche vorhanden ist, wird ein Listener erstellt und Facets, die nicht zur Suche passen, ausgeblendet.

Die Klasse prüft bei Anwesenheit auf der Seite, ob Facet-Suchen vorhanden sind. Diese bieten Nutzern die Möglichkeit, innerhalb von Facets zu suchen. Damit es funktioniert, benötigt das Element einen String-Wert.

Komplett zurücksetzen #

clerk-omnisearch-full-reset

Werden Elemente mit dieser Klasse aktiviert, werden alle ausgewählten Facets gelöscht und die Anfrage zurückgesetzt.

Facets zurücksetzen #

clerk-omnisearch-facet-full-reset

Beim Klick werden mit dieser Klasse alle aktiven Facets des Bereichs abgewählt. Dies sieht man typischerweise bei einem „Alles löschen“-Button innerhalb einer Facet-Gruppe.

Gruppe zurücksetzen #

clerk-omnisearch-facet-group-reset

Beim Klick werden alle untergeordneten Elemente innerhalb der Gruppe abgewählt.

Um das Feature zu bieten, eine komplette Facet-Gruppe zu deselektieren, kann ein Element diese Klasse erhalten. Nach Aktivierung (z.B. Klick) werden alle Elemente der Gruppe abgewählt. Hierfür muss das zu löschende Gruppenelement als Attribut mit Namen data-facet-group versehen sein.

Einzelnes Facet zurücksetzen #

clerk-omnisearch-facet-reset

Elemente mit dieser Klasse können ein einzelnes Facet per Gruppen-/Wert-Attribut abwählen.

Die Klasse eignet sich für Fälle, in denen ein einzelnes Facet abgewählt werden muss. Ein Element mit dieser Klasse kann einer Facet in einer Gruppe durch data-facet-group und data-facet-value zugeordnet werden. Nach Aktivierung wird nur dieses zugehörige Facet deaktiviert, andere Auswahl bleibt erhalten.

Facet-Klick #

clerk-facet

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

Alle Facets benötigen diese Klasse und die Attribute data-facet-group und data-facet-value, damit gemessen werden kann, was der Nutzer auswählt.