Omnisearch

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

• Live-Ergebnisse werden Ihren Besuchern beim Tippen angezeigt und umfassen Produkte, Kategorien und Seiten.
• Sortieren und Filtern: damit Ihre Besucher ihre Suche intuitiv und einfach verfeinern können.
• Einfach zu integrieren in Ihre Seite durch eine unserer großartigen Startvorlagen.
• Passt zu Ihrer Marke durch das Ändern einiger Standardeinstellungen wie Logo, Schriftarten, Farben und mehr.
• Vollständig anpassbar mit HTML, CSS und Liquid für Entwickler.

Einstieg #

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

Design erstellen #

Dies erfolgt in 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, um das Standarddesign zu speichern. Kehren Sie zur Designliste oder dem Hauptdesign als separaten Navigationsschritt zurück.

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

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 zum Anzeigen der Ergebnisse und die Einstellungen, wie viele Ergebnisse angezeigt werden sollen. Die Logik für den leeren Zustand kann auch über Rules angepasst werden.

• Name hilft Ihnen, Ihr Element zu identifizieren, 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, falls erforderlich, aber für die meisten Setups ist dies nicht nötig.

• Empty State Logic ermöglicht Ihnen die Auswahl des Produkttyps, der angezeigt wird, wenn Omnisearch initial geöffnet wird, bevor Begriffe eingegeben werden. Standardmäßig ist dies Bestsellers, kann jedoch auch z.B. mit Visitor Recommendations personalisiert werden.

Design finalisieren #

Das Design, um den Element-Block anzuzeigen. Wählen Sie das von Ihnen erstellte Design aus.

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

Sie können steuern, wie viele Ergebnisse je Typ angezeigt werden sollen, bei jeder Suche. Wir empfehlen in der Regel folgende Mengen:

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

Wählen Sie zuletzt die Attribute, die Sie als Facetten anzeigen lassen möchten, und legen Sie die Namen fest, unter denen sie in den Suchergebnissen erscheinen sollen. Falls Sie ein bestimmtes Attribut nicht in der Liste finden, fügen Sie es in der Liste „filterable attributes“ unter Search Configuration hinzu.

In die Website einfügen #

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

Sichtbarkeit wird verwendet, um zu steuern, wer die Omnisearch sehen kann.

• Im Vorschau-Modus können Sie Ihr Element testen, ohne Ihre Live-Seite 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 Website anhängen.

• Auf meiner Live-Seite wird verwendet, wenn Sie mit dem Testen fertig sind und es öffentlich machen wollen.

Verwendung von Injection #

Dies ist der einfachste Weg zur Installation. Clerk fügt den Omnisearch-Code automatisch Ihrer Seite hinzu, indem ein Suchfeld Ihrer Wahl angesprochen wird und das Event als Auslöser nutzt.

• Event steuert, was der Nutzer tun muss, um Omnisearch auszulösen. In der Regel soll es angezeigt werden, wenn Ihre Besucher auf Ihr Such-Icon oder Eingabefeld klicken.

• Element entscheidet, welcher Bereich der Website von Nutzern angesprochen werden soll. Wenn Ihr Omnisearch-Element z.B. nur angezeigt werden soll, wenn Ihre Besucher mit Ihrer Suchleiste interagieren (Klick oder Fokus), brauchen Sie nur den eindeutigen CSS-Selektor herauszufinden, der darauf angewandt wird. Falls Sie unterschiedliche Kennungen für Mobile und Desktop haben, fügen Sie beide hinzu.

So finden Sie Ihren einzigartigen CSS-Selektor:

1. Inspizieren Sie den Code Ihrer Seite. In den meisten Browsern können Sie mit Rechtsklick irgendwo auf Ihrer Seite Untersuchen oder ähnlich wählen.
2. Finden Sie das Ziel-Element
3. Rechtsklick darauf, dann die Option copy > copy selector wählen

Verwendung von eingebettetem Code #

Damit können Sie Omnisearch mit einem Snippet hinzufügen. Dafür müssen Sie die HTML-Dateien Ihres Webshops bearbeiten oder Code mit einem Editor einfügen können.

Wenn Sie nicht gespeicherte Änderungen haben, speichern Sie sie, um den Einbettungscode zu generieren.

Kopieren Sie diesen Code und fügen Sie ihn in die Datei ein, die alle Seiten des Webshops erzeugt, idealerweise am Ende des </body>-Tags.

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

Unten finden Sie ein vollständiges Beispiel für einen Omnisearch-Einbettungscode mit allen Konfigurationsmöglichkeiten:

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

Ansichtsmodi #

Omnisearch unterstützt zwei Ansichtsmodi, die steuern, wie die Suchoberfläche auf Ihrer Seite erscheint. Konfigurieren Sie dies im Tab Insert, wenn Sie Ihr Omnisearch-Element bearbeiten.

Vollbild-Overlay #

Dies ist der Standardmodus. Wenn ausgelöst, überdeckt Omnisearch den gesamten Viewport mit einem Fullscreen-Overlay. Die Suchoberfläche übernimmt die Seite und bietet ein fokussiertes Sucherlebnis.

Verwenden Sie diesen Modus, wenn Sie:

• Eine ablenkungsfreie Suchumgebung wünschen
• Volle Kontrolle über das Such-Layout benötigen
• Die Suchoberfläche vollständig unabhängig vom Seitenkopf Ihres Shops sein soll

Teil-Overlay #

In diesem Modus wird Omnisearch mit Ihrem vorhandenen Seitenkopf integriert. Statt den kompletten Screen zu überdecken, erscheint das Such-Overlay unterhalb Ihres Headers, während der Header sichtbar und benutzbar bleibt.

Verwenden Sie diesen Modus, wenn Sie:

• Ihren Header und die Navigation während der Suche zugänglich halten möchten
• Eine nahtlosere Integration mit dem aktuellen Seitenlayout wünschen
• Das Sucherlebnis sich wie ein natürlicher Teil Ihrer Seite anfühlen soll

Konfigurationsoptionen #

Wenn Teil-Overlay ausgewählt ist, sind zusätzliche Einstellungen verfügbar:

Header-Selektor

Der CSS-Selektor für das Header-Element Ihrer Website. Omnisearch nutzt diesen, um das Overlay direkt unterhalb Ihres Headers zu positionieren und für korrekte Ausrichtung zu sorgen.

Beispielselektoren:

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

Suchfeld-Input-Selektor

Der CSS-Selektor für das bestehende Suchfeld Ihrer Seite. Wenn angegeben, synchronisiert Omnisearch sich mit dem Suchfeld Ihres Headers. So werden beim Tippen in das Suchfeld des Headers die Omnisearch-Ergebnisse live aktualisiert.

Beispielselektoren:

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

Breite

Kontrolliert die horizontale Größe des Overlays:

• Volle Breite: Erstreckt sich über die gesamte Viewport-Breite
• Content-Breite: Entspricht der Breite eines Container-Elements, dass Sie mit einem CSS-Selektor angeben
• Feste Breite: Eine von Ihnen definierte Pixelbreite

Höhe

Kontrolliert die vertikale Größe des Overlays:

• Vom Header bis zum unteren Rand: Füllt den Bereich vom Headerende bis zum unteren Rand des Viewports
• Viewport-Prozentsatz: Ein Prozentsatz der Viewport-Höhe (z.B. 80%)
• Feste Höhe: Eine spezifische Pixelhöhe
• Maximale Höhe: Legt ein Oberlimit fest, das Overlay kann aber kleiner sein, wenn weniger Platz benötigt wird

Horizontale Ausrichtung

Bestimmt, wo das Overlay horizontal erscheint:

• Links: Am linken Rand des Viewports ausgerichtet
• Zentriert: Über die Breite zentriert
• Rechts: Am rechten Rand des Viewports ausgerichtet

Vertikale Position

Kontrolliert die Platzierung relativ zum Header:

• Unter Header: Overlay direkt unter dem Header-Element platzieren
• Fester Abstand von oben: Fester Pixelabstand vom oberen Rand des Viewports

Designkonfiguration #

Der Großteil der Omni-search kann durch Ändern der Variablen in den Design-Dateien konfiguriert werden.

In der liquid template language sieht eine Variable so aus:

{% assign variable_name = "variable value" %}

Als Faustregel gilt: Nur der Variablenwert sollte geändert werden, um Omnisearch zu konfigurieren.

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

Logo #

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

Infinite/Auto Load #

Möchten Sie steuern, ob Omni-search automatisch weitere Produktergebnisse lädt, sobald der Nutzer bis zur letzten Produktreihe scrollt, setzen Sie die Variable auf true oder false. Die Variable heißt meist os_autoload. Setzen Sie sie auf false, um das automatische Nachladen zu verhindern.

Übersetzungen #

Standardmäßig ist das Template auf Englisch. Wenn Ihr Shop eine andere Sprache verwendet, können Sie die Textelemente durch Ändern der Variablen übersetzen.

Übersetzen Sie die Variablen der Sortier-Buttons im Template zusammen mit den anderen Text-Variablen.

Protip: Verwenden Sie generative AI (z.B. chatGPT) für die Massenübersetzung, indem Sie 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 #

Jede Stiländerung kann bei den CSS-Variablen erledigt werden.

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

--variable_name: variable_value;

Technisch versierte Nutzer können individuelle CSS-Regeln ergänzen, um komplexere Designänderungen vorzunehmen.

Farben #

Konfigurierbare Farben finden Sie im Bereich unter dem CSS-Kommentar “Colors” /* Colors */

Schriften #

Wie bei den Farben finden Sie die Schriftvariable unter dem Kommentar /* Font */.

Typischerweise gibt es eine Variable wie: --font-family: 'Kumbh Sans', sans serif;

Standard-Design #

Das Standard-Design für Omnisearch umfasst:

• Varianten-Dropdown-Unterstützung: Lassen Sie Käufer Variantattribute (z.B. Größe, Farbe) wählen, bevor sie in den Warenkorb legen.

• Mengenwähler.

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

• Sauberes, gut strukturiertes Markup mit klaren Kommentaren.

• Zentralisierte Variablen für Styling und Verhalten, die es einfach machen, Farben, Abstände, Bezeichnungen und häufige Optionen zu ändern, ohne den Kerncode anzufassen.

• Preisschieberegler-Facette für schnelles Filtern von Preisbereichen.

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

Für Entwickler #

Styling #

Designs bestehen aus einem Haupt-Layout, CSS-Styling und einer Sammlung von Sub-Designs, auf die im Haupt-Layout verwiesen werden kann.

Sie können alle Bereiche für Desktop und Mobile separat bearbeiten. Standardmäßig verwendet Omni-search das gleiche HTML für alle Bildschirmgrößen und wird durch CSS vollständig responsiv gestaltet. Deshalb enthält der Mobile-Tab anfangs keinen Code.

Falls nötig, können Sie ein komplett anderes HTML-Markup für Mobile erstellen, das bei kleinen Bildschirmen verwendet wird.

Zunächst möchten Sie vielleicht nur wenige Dinge anpassen, um das Design an Ihre Markenästhetik anzupassen – Sie können Ihr Design jederzeit später weiterbearbeiten.

HTML #

Das Hauptlayout steuert die Platzierung aller Elemente. Es verwendet Liquid als Template-Sprache.

In unseren Startdesigns ist der erste Block den am häufigsten angepassten Elementen gewidmet, wie Sortier-Labels, Währung und allen Texten, die Sie in Ihre Sprache übersetzen können.

CSS #

Das Styling wird zusammen mit dem HTML eingeblendet und gibt Ihnen komplette Kontrolle über die Optik im Container.

Verfügbare Sub-Designs #

Im Search Code Editor finden Sie Available Designs and Components unterhalb des Haupt-Code-Bereichs. Scrollen Sie nach unten, um ein Component zu finden und zu bearbeiten. Über die Tabs über dem Editor wechseln Sie zwischen Desktop- und Mobile-HTML/CSS.

Nachdem Sie ein Component bearbeitet haben, klicken Sie Save und kehren dann separat zum Hauptdesign zurück. Alle Designs, die hier hinzugefügt werden, können im allgemeinen Layout referenziert werden. Sie funktionieren als Module, die separat bearbeitet werden, und werden per ID und Namen hinzugefügt: {{@247373 - TopBarSearchForm}}

Sie können jedes Sub-Design löschen, duplizieren und die Referenz per Drei-Punkte-Schaltfläche kopieren.

Zum Bearbeiten eines Sub-Designs klicken Sie auf das Edit-Icon. Nach Abschluss klicken Sie auf Save & close, um zum Hauptlayout-Editor zurückzukehren.

Bestimmte Elemente benötigen spezifische Kennungen, zum Beispiel:

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

Möchten Sie Ihre Fortschritte prüfen, können Sie dies jederzeit mit dem Button „Preview design“ tun.

Die häufigsten Designänderungen sind diese:

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

• Schriften: Passen Sie ggf. die Schriftarten an Ihre Corporate Identity an.

• Farben: Sie können Ihre Markenfarben für besonders wichtige Elemente wie Buttons und Tags verwenden.

• Buttons und Tag-Grenzen: Passen Sie Farbe, Radius und Breite nach Bedarf an.

• Links: Falls Sie einen speziellen Stil für Links haben, bearbeiten Sie ihn hier.

Reaktive vs. Statische Bereiche #

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

Statische Bereiche werden einmal gerendert, wenn das Overlay geöffnet wird, und nicht bei späteren Abfragen aktualisiert:

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

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

Reaktive Bereiche sind alles innerhalb von #clerk-omnisearch-content. Dieser Wrapper wird bei jeder Suchanfrage neu aufgebaut:

• Produktergebnisse
• Facets und Filter
• Kategorien, Seiten und Vorschläge
• Ergebnismengen und Sortier-Steuerelemente
• Keine-Ergebnisse-Nachrichten

Soll ein Element mit jedem Query-Update aktualisiert werden – z.B. eine Live-Trefferzahl im Header – muss es innerhalb von #clerk-omnisearch-content leben. Soll es ständig sichtbar und stabil bleiben, platzieren Sie es außerhalb dieses Wrappers.

Kein-Ergebnis-Status #

Wenn eine Suchanfrage keine Produkte liefert, zeigt Omnisearch nicht automatisch einen Fallback an – dies steuern Sie im Design über Liquid.

Die empfohlene Methode ist, zu prüfen, ob die Produkte leer sind, und bedingt einen Fallback-Slider und eine individuelle Nachricht zu rendern:

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

{% else %}
  <!-- Fallback bei keinen Ergebnissen -->
  <div class="clerk-no-results-message">
    Keine Ergebnisse für „{{ query }}“ — hier sind stattdessen 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 nutzen, um zu erkennen, wann Omnisearch unscharfe oder verwandte Ergebnisse statt exakter Treffer zeigt, und eine entsprechende Nachricht anzeigen:

{% if results.products.no_exact_match %}
  <div class="clerk-no-exact-match">
    Keine exakten Ergebnisse für „{{ query }}“ — zeige beste Übereinstimmungen:
  </div>
{% endif %}

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

Der Text der No-Results-Meldung ist in einfachem HTML im Design, kann also beliebig übersetzt oder gestaltet werden, ohne Einstellungen außerhalb des Design-Editors zu ändern.

Overlay-Struktur #

Beim Start von Omnisearch wird ein Element mit der Klasse clerk-omnisearch-overlay erzeugt und am unteren Ende des body eingefügt.

Hier wird das Design eingeblendet. Da das Eingabefeld Teil des Designs ist, müssen bestimmte Strukturvorgaben eingehalten werden, damit das Feld nicht bei jeder Anfrage neu gerendert wird. Die Struktur sollte unter dem Overlay wie folgt aussehen:

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

Eingabefeld #

Um das Eingabefeld zu finden, muss es die Kennung clerk-omnisearch-input haben. Sobald das auslösende Element aktiviert wurde, wird der Cursor-Fokus auf dieses Feld gesetzt und die aktuelle Suchanfrage hineingeschrieben, um das Nutzererlebnis nahtlos zu halten.

Content Wrapper #

Im Content Wrapper passiert das meiste: alle Facets, Slider und weitere Elemente außer dem Input Feld gehören hier hinein. Die Umrahmung benötigt die Kennung clerk-omnisearch-content.

Klassen #

Durch bestimmte Klassen an Elementen können Funktionen im Design bereitgestellt werden.

Schließen-Button #

clerk-omnisearch-close

Wenn diese Klasse einem Element im Design hinzugefügt wird, blendet dieses Element das Overlay aus.

Sortierung #

clerk-omnisearch-sort

Findet Sortier-Dropdowns und fügt Listener hinzu.

Um ein Sortierfeld zu erhalten, fügen Sie dieses der auswählbaren Komponente hinzu, z.B. einem Dropdown. Das Element muss das Format value:[desc|asc] tragen – also das gewünschte Sortierkriterium, einen Doppelpunkt und anschließend desc oder asc. Optional können Sie ein data-sort-type-Attribut hinzufügen, wenn Sie Kategorien oder Seiten sortieren wollen.

Such-Facet #

clerk-facet-search

Falls eine Facet-Suche vorhanden ist, wird ein Listener erstellt und Facets ausgeblendet, die nicht zum Query passen.

Diese Klasse prüft auf Facet-Suchfelder und erlaubt Nutzern, gezielt innerhalb von Facets zu filtern. Hierfür muss das Feld einen Stringwert haben.

Alles Löschen #

clerk-omnisearch-full-reset

Beim Klicken auf Elemente mit dieser Klasse werden alle ausgewählten Facets gelöscht und die Suche zurückgesetzt.

Facets Löschen #

clerk-omnisearch-facet-full-reset

Beim Klicken auf Elemente mit dieser Klasse werden alle aktiven Facets deaktiviert. Oft als „Alle löschen“-Button in einer Gruppe von Facets, um alle Filter einfach zurückzusetzen.

Gruppen-Löschen #

clerk-omnisearch-facet-group-reset

Beim Klicken auf Elemente mit dieser Klasse werden sämtliche Elemente innerhalb der Gruppe deaktiviert.

Um z.B. alle Facets einer bestimmten Gruppe zu löschen, geben Sie dem betroffenen Element die Klasse und das Attribut data-facet-group mit.

Einzelnes Facet Löschen #

clerk-omnisearch-facet-reset

Elemente mit dieser Klasse müssen ein einzelnes Facet anhand des Gruppen-/Werteattribut-Paares löschen.

Diese Klasse ist gedacht, wenn ein spezielles Facet abgewählt werden soll. Versehen Sie das Element mit Klasse, dem Gruppennamen (data-facet-group) und Wert (data-facet-value). Nach Aktivierung wird nur das angegebene Facet abgewählt, andere bleiben erhalten.

Facet Click #

clerk-facet

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

Alle Facets sollten diese Klasse sowie data-facet-group und data-facet-value als Attribute haben, damit Aktionen eindeutig zugeordnet werden können.