Omnisearch

Basato sull’ultima tecnologia Search di Clerk, Omnisearch ti offre la flessibilità di cui hai bisogno per offrire la migliore esperienza di ricerca moderna:

• Risultati live vengono mostrati ai tuoi visitatori mentre digitano e includono prodotti, categorie e pagine.
• Ordinamento e filtri: per permettere ai tuoi visitatori di raffinare la loro 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 modificando alcune impostazioni standard come logo, font, colori e altro.
• Completamente personalizzabile con HTML, CSS e Liquid per developers.

Come iniziare #

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

Creazione di un design #

Si fa in Search > Designs > New Design

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

Clicca su Save & Close per finalizzare il design standard.

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

Creazione di un Element #

Si fa in Search > Element > New Element

I blocchi Element sono contenitori per gli elementi creati nel tuo account my.clerk.io. Contengono la logica per mostrare i risultati e le impostazioni su quanti risultati visualizzare. Anche la logica dello stato vuoto può essere modificata tramite Rules.

• Nome ti aiuta a identificare il tuo elemento nel caso volessi crearne più di uno. Può essere modificato successivamente.

• Tipo di elemento, di default è Omnisearch e non dovrebbe essere cambiato. Da qui puoi anche aggiungere filters se necessario, ma per la maggior parte delle configurazioni non è richiesto.

• Empty State Logic ti consente di selezionare il tipo di prodotti da mostrare all’apertura iniziale di Omnisearch, prima che vengano digitati termini di ricerca. Di default è Bestsellers ma può essere personalizzata, ad esempio con Visitor Recommendations.

Finalizzare il Design #

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

Se il tuo design include delle variabili, è qui che possono essere impostate.

Puoi controllare il numero di risultati da visualizzare per ogni tipo, ogni volta che viene effettuata una ricerca. Raccomandiamo generalmente queste quantità:

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

Infine, scegli gli attributi che vuoi includere come Facets e imposta i nomi con cui devono essere mostrati nei risultati di ricerca. Se non trovi un attributo specifico nell’elenco, aggiungilo nella lista “filterable attributes”, nelle Impostazioni di Search.

Inserimento nel sito #

Il metodo consigliato è tramite injection, ma puoi anche inserire l’elemento nel sito tramite embedcode.

Visibilità serve a controllare chi può vedere Omnisearch.

• In preview ti consente di testare il tuo elemento senza impattare sul sito live. Puoi aprire il sito in modalità preview cliccando su “Open site in preview” o aggiungendo ?clerk_content_mode=preview all’URL del tuo sito.

• In my live site viene usato quando hai finito i test ed è pronto per essere pubblico.

Utilizzo di injection #

Questo è il modo più facile per installare. Clerk aggiungerà automaticamente il codice Omnisearch al tuo sito, agendo su un campo ricerca a tua scelta e attivandosi in seguito a un evento.

• Evento controlla cosa dovrà fare l’utente per attivare Omnisearch. Probabilmente vorrai mostrarlo quando i visitatori cliccano sull’icona o il campo di ricerca.

• Elemento decide quale parte del sito deve essere interattiva per l’utente. Ad esempio, se vuoi che l’elemento Omnisearch venga visualizzato solo quando l’utente interagisce con la barra di ricerca (clic o focus), devi individuare il CSS selector univoco applicato a quell’elemento. Se hai identificativi diversi per mobile e desktop, aggiungili entrambi.

Trova il tuo selettore CSS unico così:

1. Ispeziona il codice del sito. Nei browser puoi cliccare col destro e scegliere Ispeziona o simile.
2. Trova l’elemento che vuoi identificare
3. Clic destro sopra l’elemento e trova l’opzione copia > copia selettore

Utilizzo dal codice embed #

Questo ti consente di aggiungere Omnisearch tramite uno snippet. Per farlo devi poter modificare i file HTML del tuo shop o aggiungere codice tramite 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 sito, idealmente vicino al tag di chiusura </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 compare l’interfaccia di ricerca nel tuo sito. Configura questa opzione nella scheda Insert durante la modifica del tuo Element Omnisearch.

Full overlay #

Questa è la modalità predefinita. Quando attivata, Omnisearch copre l’intera area visibile della pagina 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
• Controllo completo del layout della ricerca
• Un’interfaccia di ricerca completamente indipendente dall’header del sito

Partial overlay #

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

Usa questa modalità se desideri:

• Mantenere header e navigazione 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 #

Con Partial Overlay vengono rese disponibili impostazioni aggiuntive:

Header selector

Il selettore CSS dell’elemento header del sito. Omnisearch lo utilizza per posizionare l’overlay direttamente sotto l’header, garantendo il corretto allineamento.

Esempi di selettori:

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

Search input selector

Il selettore CSS per il campo di ricerca esistente. Se specificato, Omnisearch si sincronizza con il campo ricerca dell’header, creando un’esperienza unificata nella quale la digitazione aggiorna i risultati di Omnisearch.

Esempi di selettori:

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

Larghezza

Controlla la dimensione orizzontale dell’overlay:

• Full width: L’overlay copre tutta la larghezza della viewport
• Content width: Corrisponde alla larghezza di un elemento container specificato tramite selettore CSS
• Fixed width: Una larghezza in pixel definita manualmente

Altezza

Controlla l’altezza verticale dell’overlay:

• From header to bottom: Riempie lo spazio dall’header al fondo della viewport
• Viewport percentage: Una percentuale dell’altezza della finestra (ad esempio, 80%)
• Fixed height: Un’altezza pixel definita
• Max height: Imposta un limite superiore permettendo alla finestra di essere più bassa se necessario

Allineamento orizzontale

Controlla dove appare l’overlay orizzontalmente:

• Sinistra: Allinea a sinistra
• Centro: Centra orizzontalmente
• Destra: Allinea a destra

Posizione verticale

Controlla dove appare verticalmente rispetto all’header:

• Below header: Posiziona l’overlay subito sotto il tuo header
• Fixed from top: Un offset in pixel dalla parte superiore del viewport

Configurazione del design #

La maggior parte delle personalizzazioni di Omni-search si fanno cambiando le variabili nei file di design.

Nel liquid template language, una variabile ha struttura:

{% assign variable_name = "variable value" %}

Come regola, dovrebbe essere modificato solo il valore della variabile per configurare Omni-search.

Utenti più tecnici possono modificare anche linee specifiche di HTML e CSS, vedi questa sezione.

Logo #

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

Infinite/auto load #

Se vuoi controllare se Omni-search deve caricare più prodotti automaticamente, quando l’utente scorre fino all’ultima riga dei prodotti, la variabile va impostata su true o false. Solitamente la variabile si chiama os_autoload. Impostala a false per bloccare il caricamento automatico di altri risultati da parte di Omnisearch.

Traduzioni #

Di default, il template è in inglese. Se il tuo negozio usa un’altra lingua, puoi tradurre gli elementi testuali modificando i valori delle variabili.

Traduci le variabili relative ai bottoni di ordinamento nel template insieme agli altri testi.

Protip: Usa AI generativa (es. chatGPT) per tradurre massivamente, scrivendo “Traduci questi valori delle variabili da English a Danish. Restituisci il codice completo così posso copiarlo/incollarlo per sostituire quello esistente: PASTE_VARIABLES_HERE”

Stile #

Per cambiare qualsiasi stile, la configurazione si fa nelle variabili CSS.

I template utilizzano variabili CSS che hanno una struttura simile a questa:

--variable_name: variable_value;

Gli utenti più tecnici possono modificare anche singole regole CSS per modifiche piú avanzate.

Colori #

I colori configurabili possono essere trovati e modificati nella sezione sotto il commento CSS “Colors”
/* Colors */

Font #

Similmente ai colori, la variabile dei font si trova sotto il commento /* Font */.

Solitamente la variabile è: --font-family: 'Kumbh Sans', sans serif;

Design standard #

Il design standard per Omnisearch include:

• Supporto al menù a tendina delle Varianti: Permette ai clienti di scegliere gli attributi variante (es. taglia, colore) prima di aggiungere al carrello.

• Selettore quantità.

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

• Markup pulito e ben strutturato con commenti chiari.

• Variabili centralizzate per stile e comportamento, rendendo facile modificare colori, spazi, etichette e opzioni comuni senza toccare il codice di base.

• Slider prezzo come facet per un filtro rapido per fascia di prezzo.

• Suggerimenti cliccabili che avviano subito una ricerca.

Per developer #

Stile #

I design consistono di main layout, stile CSS e una serie di sub-design che possono essere referenziati nel layout principale.

Puoi modificare tutto questo separatamente per Desktop e Mobile. Di default, Omni-search usa lo stesso HTML per tutte le dimensioni di schermo e usa CSS per la responsività. Per questo nella tab Mobile all’inizio non c’è codice.

Se necessario, puoi creare un markup HTML completamente diverso per Mobile, usato solo su schermi piccoli.

All’inizio, puoi modificare solo alcuni aspetti per far corrispondere il design al look and feel del tuo brand - Potrai sempre modificarlo in seguito.

HTML #

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

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

CSS #

Stile che viene iniettato insieme all’HTML, dandoti il controllo totale del look, ma in modo isolato.

Sub-design disponibili #

Tutti i design aggiunti qui possono essere referenziati nel layout generale. Funzionano come moduli che si modificano separatamente e sono aggiunti indicando ID e nome: {{@247373 - TopBarSearchForm}}

Puoi eliminare, duplicare e copiare il riferimento di ogni sub-design cliccando sul bottone con i tre puntini.

Per modificare un sub-design, clicca sull’icona Modifica. Una volta terminato, clicca Save & close per tornare all’editor principale.

Alcuni elementi necessitano di identificatori specifici, ad esempio:

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

Ogni volta che vuoi vedere i progressi, puoi farlo cliccando sul bottone “Preview design”.

Le modifiche più frequenti ai design sono:

• Logo: Vai su TopBarSearchForm e sostituisci il logo di default col tuo.

• Font: Se serve, aggiusta i font per rispettare il look del sito.

• Colori: Aggiungi i colori del tuo brand in quegli elementi che vuoi enfatizzare o armonizzare (bottoni, tag, ecc).

• Bordi di bottoni e tag: Puoi regolarne colore, raggio, larghezza…

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

Parti reattive vs statiche #

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

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

• Il contenitore overlay stesso (clerk-omnisearch-overlay)
• Il campo input di ricerca (#clerk-omnisearch-input)
• Qualsiasi HTML fuori da #clerk-omnisearch-content — come logo, pulsante chiudi o top bar

Il campo input è statico di proposito. Ri-renderizzarlo a ogni tasto disturberebbe la digitazione e l’esperienza dell’utente.

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

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

Se vuoi che un elemento si aggiorni con la query — ad esempio il conteggio live dei risultati nell’header — deve essere dentro #clerk-omnisearch-content. Se vuoi che rimanga visibile e stabile mentre l’utente digita, mettilo fuori da quel wrapper.

Stato nessun risultato #

Quando una ricerca non restituisce prodotti, Omnisearch non mostra in automatico dei fallback — questo si controlla nel design tramite Liquid.

Il metodo raccomandato è controllare se la lista prodotti è vuota e mostrare condizionalmente uno slider di fallback e un messaggio personalizzato:

{% if products.length > 0 %}
  <!-- Normal results -->
  {% for product in products %}
    <!-- product card -->
  {% endfor %}

{% else %}
  <!-- No results fallback -->
  <div class="clerk-no-results-message">
    Nessun risultato per "{{ query }}" — ecco alcune proposte 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 dei risultati esatti, e mostrare un messaggio adeguato:

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

Entrambi gli schemi possono essere combinati. Un setup tipico mostra il messaggio no_exact_match sopra i risultati, e lo slider di fallback solo se products.length == 0.

Il testo del messaggio di nessun risultato è semplice HTML inserito nel design, quindi può essere tradotto o stilizzato liberamente senza cambiare nulla fuori dal design editor.

Struttura dell’overlay #

Quando omnisearch viene avviato, crea un elemento con classe clerk-omnisearch-overlay che viene inserito in fondo al body.

Qui viene inserito il design; poiché abbiamo l’elemento input parte del design, sono richieste delle strutture specifiche per non ri-renderizzare l’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 individuare il campo input, deve avere identificatore clerk-omnisearch-input. Una volta che l’elemento trigger è attivo, spostiamo il focus su questo campo, aggiungendo la query per mantenere un’esperienza fluida.

Content Wrapper #

Il content wrapper è il luogo dove avvengono la maggior parte delle azioni, deve avere identificatore clerk-omnisearch-content. Qui si inseriscono facets, slider e tutto ciò che non è campo input.

Classi #

Al design può essere aggiunta funzionalità aggiungendo classi specifiche agli elementi.

Bottone Chiudi #

clerk-omnisearch-close

Attribuendo questa classe a un elemento nel design, l’elemento nasconderà l’overlay.

Ordinamento #

clerk-omnisearch-sort

Trova i dropdown per l’ordinamento e aggiunge listener.

Per un elemento di ordinamento nel design, aggiungi questa classe all’elemento di selezione, ad esempio a un dropdown. Deve avere il valore nel formato value:[desc|asc], cioè il valore da ordinare, due punti, e poi desc o asc. Opzionalmente puoi aggiungere l’attributo data-sort-type se vuoi ordinare categorie o pagine.

Search Facet #

clerk-facet-search

Se è presente una ricerca tra le facets, crea listener e nasconde facets non corrispondenti alla query.

La classe, quando presente in una pagina, verifica la presenza di elementi di ricerca facet. Le facet search permettono all’utente di cercare tra le facets. Per funzionare, l’elemento deve avere un valore testuale.

Full Clear #

clerk-omnisearch-full-reset

Quando cliccati, gli elementi con questa classe resettano tutti i facets e la query.

Facets Clear #

clerk-omnisearch-facet-full-reset

Cliccando, gli elementi con questa classe deselezionano tutti i facets attivi. Tipico di un bottone tipo ‘Cancella tutto’ in un gruppo di facets.

Group Clear #

clerk-omnisearch-facet-group-reset

Cliccando, gli elementi con questa classe deselezionano tutti i figli nel gruppo.

Per permettere la deselezione di un intero gruppo di facets, un elemento può avere questa classe. Una volta attivato (ad esempio al click), tutti gli elementi nel gruppo saranno deselezionati, resettando il gruppo. Per funzionare, l’elemento deve avere l’attributo data-facet-group per identificare il gruppo da resettare.

Facet Clear #

clerk-omnisearch-facet-reset

Gli elementi con questa classe deselezionano un singolo elemento dato il gruppo/valore.

Questa classe serve quando si vuole deselezionare un singolo facet. Un elemento con questa classe va associato a uno specifico facet di un gruppo fornendo sia data-facet-group che data-facet-value. Al click, verrà deselezionato solo il facet relativo, lasciando gli altri invariati.

Facet Click #

clerk-facet

Gli elementi con questa classe sono considerati facet selezionabili.

Tutti i facets devono avere la classe, insieme agli attributi data-facet-group e data-facet-value in modo da identificare cosa ha selezionato il cliente.