Omnisearch

Alimentato dall’ultima tecnologia Search di Clerk, Omnisearch ti offre la flessibilità necessaria per offrire la migliore esperienza di ricerca moderna:

• Risultati live vengono mostrati ai tuoi visitatori mentre digitano, includendo prodotti, categorie e pagine.
• Ordinamento e filtraggio: permette ai visitatori di affinare la ricerca in modo intuitivo e semplice.
• Facile da integrare nel tuo sito utilizzando uno dei nostri fantastici template di partenza.
• Si adatta al tuo brand tramite la modifica di alcune impostazioni standard come logo, font, colori e altro ancora.
• È completamente personalizzabile con HTML, CSS e Liquid per developers.

Per iniziare #

Omnisearch è costituito da un Design personalizzabile per la parte visiva e un blocco Element che consente l’installazione sul tuo sito.

Creazione di un design #

Questo viene fatto in Search > Designs > New Design

Seleziona il tipo Omnisearch, scegli un design iniziale e dagli un nome.

Clicca su Save per salvare il design standard. Torna all’elenco dei design o al design principale come passaggio di navigazione separato.

I nostri design standard funzionano immediatamente e possono sempre essere modificati in seguito. La modifica richiede la conoscenza di HTML, CSS e Liquid. Consulta Styling in questa guida per maggiori informazioni.

Creazione di un Element #

Questo viene fatto in Search > Element > New Element

I blocchi Element sono contenitori per gli elementi che crei nel tuo account my.clerk.io. Contengono la logica per mostrare i risultati e le impostazioni su quanti risultati mostrare. La logica Empty State può essere modificata tramite Rules.

• Name ti aiuta a identificare l’elemento nel caso tu voglia crearne più di uno. Può essere modificato in seguito.

• Element type è Omnisearch per default e non dovrebbe essere cambiato. Qui puoi anche aggiungere filters se necessario, ma nella maggior parte delle configurazioni non serve.

• Empty State Logic ti permette di selezionare il tipo di prodotti da mostrare quando Omnisearch viene aperto inizialmente, prima che vengano digitate parole. Di default è Bestsellers ma può essere personalizzato ad esempio con Visitor Recommendations.

Finalizzare il design #

Il design attraverso cui renderizzare il blocco Element. Seleziona il design che hai creato.

Se il tuo design include variabili, possono essere impostate anche qui.

Puoi controllare il numero di risultati da mostrare per ciascun tipo, ogni volta che viene effettuata una ricerca. In generale raccomandiamo queste quantità:

• Prodotti: 20-60
• Suggerimenti: 5
• Categorie & pagine: 10

Infine, scegli gli attributi da includere come Facets e imposta i nomi con cui devono essere visualizzati nei risultati di ricerca. Se non riesci a trovare un attributo specifico nell’elenco, aggiungilo nella lista “filterable attributes”, in Search Configuration.

Inserimento nel sito #

Il metodo raccomandato è injection ma puoi anche inserire l’elemento nel tuo sito con un embedcode.

La Visibilità viene usata per controllare chi può vedere Omnisearch.

• In anteprima ti permette di testare l’elemento senza influenzare il sito live. Puoi aprire il tuo sito in anteprima cliccando “Open site in preview” o aggiungendo ?clerk_content_mode=preview all’URL del tuo sito.

• Nel mio sito live viene usato quando hai finito i test e sei pronto a renderlo pubblico.

Utilizzo dell’injection #

Questo è il metodo più semplice per l’installazione. Clerk aggiungerà automaticamente il codice Omnisearch al tuo sito, indirizzando un campo di ricerca a tua scelta e attivandolo in base a un evento.

• Event controlla cosa deve fare l’utente per attivare Omnisearch. Probabilmente vorrai che si attivi quando i tuoi visitatori cliccano sull’icona di ricerca o sul campo input.

• Element decide la parte del sito web con cui l’utente deve interagire. Ad esempio, se vuoi che il tuo elemento Omnisearch venga mostrato solo quando i visitatori interagiscono con la barra di ricerca (clic o focus), basta trovare l’unico CSS selector applicato. Se hai identificatori diversi in mobile e desktop, aggiungili entrambi.

Trova il tuo CSS selector unico così:

1. Ispeziona il codice del sito. Nella maggior parte dei browser puoi cliccare col tasto destro in qualsiasi punto della pagina e scegliere Inspect o simile.
2. Trova l’elemento che vuoi indirizzare
3. Clicca con il tasto destro su di esso e scegli l’opzione copia > copia selector

Utilizzo del codice embed #

Questo ti consente di aggiungere Omnisearch con uno snippet. Utilizzandolo, devi essere in grado di modificare i file HTML del tuo webshop o aggiungere codice da un editor.

Se hai modifiche non salvate, salvale per generare il codice embed.

Copia questo codice e incollalo nel file che genera tutte le pagine del tuo webshop, idealmente vicino al tag finale </body>.

Sostituisci INSERT_CSS_SELECTOR_FOR_ELEMENT_THAT_SHOULD_TRIGGER_OMNISEARCH con il selettore CSS dell’elemento HTML che deve attivare Omnisearch.

Di seguito un esempio completo di codice embed Omnisearch con tutte le opzioni di configurazione:

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

Modalità di visualizzazione #

Omnisearch supporta due modalità di visualizzazione che controllano come l’interfaccia di ricerca appare sul tuo sito. Configura questa impostazione nella scheda Insert quando modifichi il tuo Omnisearch Element.

Overlay totale #

Questa è la modalità predefinita. Quando viene attivato, Omnisearch copre l’intero viewport con un overlay a schermo intero. L’interfaccia di ricerca prende il controllo della pagina, offrendo un’esperienza di ricerca focalizzata.

Usa questa modalità se desideri:

• Un ambiente di ricerca senza distrazioni
• Il pieno controllo sul layout della ricerca
• L’interfaccia di ricerca completamente indipendente dall’header del sito

Overlay parziale #

Questa modalità integra Omnisearch con l’header esistente del sito. Invece di coprire tutto lo schermo, l’overlay appare al di sotto dell’header, mantenendolo visibile e funzionante.

Usa questa modalità se desideri:

• Header e navigazione sempre accessibili durante la ricerca
• Un’integrazione più fluida con il layout esistente
• Un’esperienza di ricerca che sembri parte naturale del sito

Opzioni di configurazione #

Quando si seleziona Overlay Parziale, sono disponibili impostazioni aggiuntive:

Header selector

Il selettore CSS per l’elemento header del tuo sito. Omnisearch lo usa per posizionare l’overlay direttamente sotto l’header, garantendo un allineamento corretto.

Esempi di selettore:

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

Search input selector

Il selettore CSS per il campo input di ricerca esistente. Quando è fornito, Omnisearch si sincronizza con il campo ricerca dell’header, creando una ricerca unificata in cui digitando nella barra aggiorni i risultati di Omnisearch.

Esempi di selettore:

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

Larghezza

Controlla la dimensione orizzontale dell’overlay:

• Full width: Estende a tutta la larghezza del viewport
• Content width: Corrisponde alla larghezza di un elemento container specificato con un selettore CSS
• Fixed width: Una larghezza in pixel definita

Altezza

Controlla la dimensione verticale dell’overlay:

• From header to bottom: Occupa lo spazio dal fondo dell’header al fondo del viewport
• Viewport percentage: Una percentuale dell’altezza del viewport (es. 80%)
• Fixed height: Una altezza in pixel definita
• Max height: Imposta un limite massimo pur consentendo all’overlay di essere più piccolo se il contenuto lo richiede

Allineamento orizzontale

Controlla dove appare l’overlay orizzontalmente:

• Left: Allineato a sinistra del viewport
• Center: Al centro orizzontale
• Right: Allineato a destra del viewport

Posizione verticale

Controlla il posizionamento verticale rispetto all’header:

• Below header: Posiziona l’overlay subito sotto l’elemento header
• Fixed from top: Un offset in pixel dal bordo superiore del viewport

Configurazione del design #

La maggior parte di Omni-search può essere configurata attraverso la modifica delle variabili presenti nei file di design.

Nel linguaggio template liquid, una variabile ha questa struttura:

{% assign variable_name = "variable value" %}

Come regola generale, solo il valore della variabile deve essere cambiato per configurare Omni-search.

Gli utenti più tecnici possono comunque modificare direttamente linee di HTML e CSS, vedi questa sezione.

Logo #

Per aggiungere un logo al design di Omnisearch, imposta os_brand_logo sull’URL dell’immagine del tuo logo.

Infinite/auto load #

Se vuoi controllare se Omni-search deve caricare automaticamente più prodotti quando l’utente raggiunge l’ultima riga, la variabile deve essere impostata su true o false. La variabile si chiama di solito os_autoload. Impostala su false per evitare che Omnisearch carichi altri risultati automaticamente.

Traduzioni #

Per default, il template è in inglese. Se il negozio ha una lingua diversa, puoi tradurre gli elementi di testo cambiando i valori delle variabili.

Traduce anche le variabili dei pulsanti di ordinamento nel template insieme alle altre variabili di testo.

Protip: Usa l’IA generativa (es. ChatGPT) per traduzioni massive scrivendo “Traduci questi valori di variabile da inglese a danese. Restituisci il codice completo per poterlo copiare e incollare: PASTE_VARIABLES_HERE”

Styling #

Per modificare qualsiasi aspetto dello stile, la configurazione può essere fatta nelle variabili CSS.

I template utilizzano variabili CSS che hanno la struttura:

--variable_name: variable_value;

Gli utenti più tecnici possono anche modificare regole CSS individuali per cambiamenti di design più complessi.

Colori #

I colori configurabili si trovano e configurano nella sezione sotto il commento CSS “Colors” /* Colors */

Font #

Come per i colori, la variabile del font si trova sotto il commento /* Font */.

Tipicamente ha una variabile tipo: --font-family: 'Kumbh Sans', sans serif;

Design standard #

Il design standard di Omnisearch include:

• Supporto dropdown per varianti: consente ai clienti di scegliere le varianti (es. taglia, colore) prima dell’aggiunta al carrello.

• Selettore quantità.

• Pulsante Add-to-Cart nativo che notifica Clerk.js, mantenendo analytics e merchandising sincronizzati.

• Markup pulito e ben strutturato con commenti chiari.

• Variabili centralizzate per stile e comportamento, rendendo facile modificare colori, spaziature, etichette e opzioni comuni senza cambiare il codice centrale.

• Facet Price slider per un rapido filtraggio per range di prezzo.

• Suggerimenti cliccabili che avviano immediatamente una ricerca.

Per sviluppatori #

Styling #

I design consistono in un layout principale, stile CSS e un insieme di sub-design che possono essere richiamati nel layout principale.

Puoi modificarli tutti separatamente per Desktop e Mobile. Per default, Omni-search usa lo stesso HTML per tutti gli schermi e usa il CSS per essere completamente responsive. Ecco perché la tab Mobile non ha codice inizialmente.

Se necessario, puoi creare un markup HTML completamente diverso per Mobile, che verrà usato solo su schermi più piccoli.

All’inizio potresti voler solo modificare poche cose per far combaciare il design con il look & feel del tuo brand – Potrai sempre editarlo successivamente.

HTML #

Questo è il layout principale che controlla la posizione di tutti gli elementi. Usa Liquid come linguaggio template.

Nei nostri design di partenza, la prima sezione è dedicata agli elementi più comunemente modificati, come etichette di ordinamento, valuta e i vari testi che puoi tradurre nella tua lingua.

CSS #

Stile che verrà inserito con l’HTML, dandoti pieno controllo sul visual in modo contenuto.

Sub-design disponibili #

Nell’editor del codice Search, Available Designs and Components è sotto l’area principale del codice. Scorri verso il basso per trovare e modificare un componente. Usa le tab sopra l’editor per passare tra HTML/CSS desktop e mobile.

Dopo aver modificato un componente, clicca su Save, quindi torna al design principale separatamente. Tutti i design aggiunti qui possono essere richiamati nel layout generale. Funzionano come moduli modificati a parte e aggiunti tramite ID e nome: {{@247373 - TopBarSearchForm}}

Puoi eliminare, duplicare o copiare il riferimento a qualsiasi sub-design cliccando sui tre puntini.

Per modificare un sub-design, clicca sulla sua icona Edit. Una volta finito, clicca su Save & close per tornare all’editor principale.

Alcuni elementi richiedono identificatori specifici, come:

• Il campo input id="clerk-omnisearch-input"
• Il content wrapper id="clerk-omnisearch-content"

Quando vuoi controllare i progressi, puoi farlo cliccando il bottone “Preview design”.

Le modifiche più comuni ai design sono queste:

• Logo: Accedi al TopBarSearchForm e sostituisci il logo predefinito con il tuo.

• Font: Se necessario, regola i font per abbinarli allo stile del sito.

• Colori: Puoi aggiungere i colori del brand negli elementi che vuoi evidenziare o uniformare agli altri elementi come bottoni e tag.

• Bordi di bottoni e tag: Puoi modificarne colore, raggio, spessore…

• Link: Se hai uno stile specifico per i link, puoi modificarlo anche qui.

Parti reattive vs statiche #

Capire quali parti di Omnisearch vengono ri-renderizzate a ogni query – e quali no – è importante quando si personalizza il design.

Parti statiche vengono renderizzate una sola volta all’apertura dell’overlay e non vengono toccate nelle query successive:

• Il container dell’overlay stesso (clerk-omnisearch-overlay)
• Il campo di input di ricerca (#clerk-omnisearch-input)
• Qualsiasi HTML nel design che si trova fuori da #clerk-omnisearch-content — come logo, bottone di chiusura o top bar

Il campo input è volutamente statico. Ri-renderizzarlo a ogni battitura interromperebbe la digitazione del visitatore e comprometterebbe l’esperienza.

Parti reattive sono tutto ciò che sta dentro #clerk-omnisearch-content. Questo wrapper viene ri-renderizzato per ogni query:

• Risultati prodotto
• Facets e filtri
• Categorie, pagine e suggerimenti
• Conteggio risultati e controlli di ordinamento
• Messaggi nessun risultato

Se vuoi che un elemento si aggiorni a ogni modifica della query – ad esempio un conteggio live dei risultati nell’header – deve essere inserito dentro #clerk-omnisearch-content. Se invece vuoi che resti visibile e stabile durante la digitazione, mettilo fuori da quel wrapper.

Stato nessun risultato #

Quando una ricerca non trova prodotti, Omnisearch non mostra automaticamente un fallback — questo viene gestito nel design usando Liquid.

L’approccio consigliato è verificare se i prodotti sono vuoti e condizionare la visualizzazione di uno slider fallback e di un messaggio personalizzato:

{% if products.length > 0 %}
  <!-- Risultati normali -->
  {% for product in products %}
    <!-- scheda prodotto -->
  {% endfor %}

{% else %}
  <!-- Nessun risultato - fallback -->
  <div class="clerk-no-results-message">
    Nessun risultato per "{{ query }}" — ecco alcune scelte popolari:
  </div>

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

Puoi anche usare results.products.no_exact_match per rilevare quando Omnisearch mostra corrispondenze “fuzzy” o correlate invece di risultati esatti, e mostrare un messaggio appropriato:

{% if results.products.no_exact_match %}
  <div class="clerk-no-exact-match">
    Nessun risultato esatto per "{{ query }}" — mostriamo i risultati più vicini:
  </div>
{% endif %}

Entrambi i pattern possono essere combinati. Una configurazione tipica mostra il messaggio no_exact_match sopra ai risultati e lo slider fallback solo quando products.length == 0.

Il testo del messaggio “nessun risultato” è HTML puro dentro il design, quindi può essere tradotto o stilizzato liberamente senza cambiare nessuna configurazione fuori dal design editor.

Struttura overlay #

Quando omnisearch viene avviato, crea un elemento con la classe clerk-omnisearch-overlay e lo inserisce in fondo al body.

Qui verrà iniettato il design. Poiché l’input fa parte del design, occorre una struttura che non ri-renderizzi il campo input a ogni caricamento. La struttura dovrebbe essere così, sotto l’overlay:

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

Campo input #

Per trovare il campo input deve avere l’identificatore clerk-omnisearch-input. Una volta che il trigger element viene attivato, viene focalizzato il cursore su questo elemento, e inserita la query per offrire una UX fluida.

Content Wrapper #

Il content wrapper è dove si svolge la maggior parte delle azioni: il wrapper deve avere l’identificatore clerk-omnisearch-content. Qui devono esserci facets, slider e tutto tranne il campo input.

Classi #

Si può aggiungere funzionalità al design tramite classi specifiche sugli elementi.

Bottone chiusura #

clerk-omnisearch-close

Applicando la classe a un elemento nel design, questo nasconderà l’overlay.

Ordinamento #

clerk-omnisearch-sort

Trova tutti i dropdown di ordinamento e vi aggiunge listener.

Per avere un sorting nel design, aggiungilo all’elemento selezionabile, ad esempio un dropdown. Per funzionare, l’elemento deve essere tipo value:[desc|asc], cioè il valore da ordinare, seguito da due punti e poi desc o asc. Facoltativamente si può aggiungere un attributo data-sort-type se vuoi ordinare categorie o pagine.

Search Facet #

clerk-facet-search

Se c’è una ricerca facet, crea un listener e nasconde facets che non corrispondono alla query.

La classe, quando presente, controlla l’esistenza di elementi facet search. Le facet search permettono all’utente di cercare nelle facets. Per funzionare, serve un valore stringa.

Full Clear #

clerk-omnisearch-full-reset

Se cliccato, gli elementi con questa classe eliminano tutte le facets selezionate e resettano la query.

Facets Clear #

clerk-omnisearch-facet-full-reset

Se cliccato, gli elementi con questa classe deselezionano tutte le facets attive. Tipicamente usata su un bottone ‘Pulisci tutto’ in un gruppo, per consentire agli utenti di resettare i filtri.

Group Clear #

clerk-omnisearch-facet-group-reset

Se cliccato, gli elementi con questa classe deselezionano tutti i figli del gruppo.

Per offrire la funzione di deselezionare un intero gruppo di facets, un elemento può ricevere la classe. Una volta attivato (ad esempio, cliccato), tutti gli elementi del gruppo vengono deselezionati. Per funzionare, l’elemento deve avere come attributo il nome del gruppo da pulire: data-facet-group.

Facet Clear #

clerk-omnisearch-facet-reset

Gli elementi con questa classe devono deselezionare un solo elemento dato un gruppo/valore specifico.

Questa classe è pensata per i casi in cui è necessario deselezionare un’unica facet. Un elemento con questa classe può essere associato a una facet specifica tramite attributi data-facet-group e data-facet-value. Dopo l’attivazione, deselezionerà solo quella facet, lasciando inalterate le altre selezionate.

Facet Click #

clerk-facet

Gli elementi con questa classe verranno trattati come facet selezionabili.

Tutte le facets devono avere la classe e gli attributi data-facet-group e data-facet-value, per sapere cosa l’utente sta selezionando.