Omnisearch

• Risultati in tempo reale vengono mostrati ai tuoi visitatori mentre digitano, e includono prodotti, categorie e pagine.
• Ordinamento e filtraggio: per permettere ai tuoi visitatori di affinare la ricerca in modo intuitivo e facile.
• Facile da integrare nel tuo sito utilizzando uno dei nostri ottimi template di partenza.
• Si adatta al tuo brand semplicemente modificando alcune impostazioni standard come logo, font, colori e altro.
• Completamente personalizzabile con HTML, CSS e Liquid per sviluppatori.

Per iniziare #

Omnisearch consiste in un Design personalizzabile per la parte visiva e in un blocco Element che consente di installarlo sul tuo sito.

Creazione di un design #

Questo passaggio si effettua da 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 (“out-of-the-box”) e possono essere modificati in ogni momento. La modifica richiede conoscenze di HTML, CSS e Liquid. Consulta Styling in questa guida per ulteriori informazioni.

Creazione di un Element #

Questo passaggio si effettua da 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 “Empty State Logic” può essere gestita tramite Rules.

• Nome ti aiuta a identificare il tuo elemento nel caso tu voglia crearne più di uno. Può essere modificato in seguito.

• Tipo di Element è impostato di default su Omnisearch, e non dovrebbe essere cambiato. Qui puoi anche aggiungere filtri se necessario, ma nella maggior parte delle configurazioni non è necessario.

• Empty State Logic ti permette di selezionare il tipo di prodotti da visualizzare quando Omnisearch viene aperto inizialmente, prima che vengano digitati termini di ricerca. Di default vengono mostrati i Bestseller ma la visualizzazione può essere personalizzata, ad esempio con le Visitor Recommendations.

Finalizza Design #

Il design tramite cui visualizzare il blocco Element. Seleziona il design che hai creato.

Se il tuo design include delle variabili, puoi impostarle anche qui.

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

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

Infine, scegli gli attributi che vuoi includere come Facet e imposta i nomi con cui dovranno essere visualizzati nei risultati. Se un attributo specifico non è presente nell’elenco, aggiungilo nella lista delle “filterable attributes” in Search Configuration.

Inserimento nel sito #

Visibilità serve per controllare chi può vedere Omnisearch.

• In preview ti permette di testare il tuo elemento senza incidere sul sito online. Puoi aprire il sito in modalità preview cliccando “Open site in preview” oppure aggiungendo ?clerk_content_mode=preview all’URL del tuo sito.

• In my live site 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, mirando a un campo di ricerca a tua scelta e attivandolo in base a un evento.

• Evento controlla cosa deve fare l’utente per attivare Omnisearch. Il comportamento più frequente è farlo comparire quando i visitatori cliccano sull’icona di ricerca o sul campo di input.

• Elemento determina la parte del sito web con cui l’utente deve interagire. Ad esempio, se vuoi che Omnisearch venga visualizzato solo quando gli utenti interagiscono con la barra di ricerca (clic o focus), basta trovare il selettore CSS unico applicato a quell’elemento. Se hai identificatori diversi su mobile e su desktop, aggiungili entrambi.

Per trovare il tuo selettore CSS unico:

1. Ispeziona il codice del tuo sito. Nella maggior parte dei browser puoi cliccare col tasto destro ovunque sulla pagina e scegliere Ispeziona o simile.
2. Trova l’elemento che vuoi targettizzare.
3. Fai clic destro su di esso, e trova l’opzione copia > copia selettore.

Uso dell’embedded code #

Se ci sono modifiche non salvate, salvale per generare il codice embedded.

Copia questo codice e incollalo nel file che genera tutte le pagine dello shop, idealmente vicino al tag di fine </body>.

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

Qui sotto trovi 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 appare nel tuo sito. Configurale nella tab Insert quando modifichi il tuo Omnisearch Element.

Full overlay #

Questa è la modalità predefinita. Alla sua attivazione, Omnisearch copre l’intera finestra con un overlay a schermo intero. L’interfaccia di ricerca prende il controllo totale della pagina, offrendo un’esperienza di ricerca focalizzata.

Usa questa modalità se desideri:

• Un ambiente di ricerca privo di distrazioni
• Pieno controllo sul layout della ricerca
• L’interfaccia di ricerca completamente indipendente dall’header del sito

Partial overlay #

Questa modalità integra Omnisearch con l’header esistente del tuo sito. Invece di coprire tutto lo schermo, l’overlay appare sotto all’header che rimane visibile e funzionante.

Usa questa modalità se desideri:

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

Opzioni di configurazione #

Quando viene selezionata la Partial Overlay, sono disponibili ulteriori impostazioni:

Header selector

Il selettore CSS per l’elemento header del tuo sito. Omnisearch lo usa per posizionare correttamente l’overlay sotto l’header.

Esempi di selettore:

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

Search input selector

Il selettore CSS del tuo campo di input di ricerca esistente. Se fornito, Omnisearch sarà sincronizzato al campo di ricerca dell’header, creando così un’esperienza unificata in cui digitando nella barra di ricerca dell’header si aggiornano i risultati di Omnisearch.

Esempi di selettore:

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

Larghezza

Controlla la dimensione orizzontale dell’overlay:

• Full width: occuperà tutta la larghezza della finestra
• Content width: coincide con la larghezza di un contenitore che specifichi tramite selettore CSS
• Fixed width: una larghezza in pixel specifica definita da te

Altezza

Controlla la dimensione verticale dell’overlay:

• From header to bottom: riempie lo spazio dall’header al fondo della finestra
• Viewport percentage: una percentuale dell’altezza della finestra (es. 80%)
• Fixed height: una specifica altezza in pixel
• Max height: imposta un limite massimo lasciando l’overlay più basso se i contenuti richiedono meno spazio

Allineamento orizzontale

Controlla dove appare orizzontalmente l’overlay:

• Left: allinea a sinistra
• Center: allinea al centro
• Right: allinea a destra

Posizione verticale

Controlla la posizione verticale rispetto all’header:

• Below header: posiziona immediatamente sotto l’header
• Fixed from top: scostamento in pixel dal bordo superiore della finestra

Configurazione del design #

Gran parte di Omni-search può essere configurata modificando le variabili presenti nei file di design.

Nel linguaggio di template liquid, una variabile ha una struttura simile a questa:

{% assign variable_name = "variable value" %}

Come regola generale, si dovrebbe modificare solo il valore della variabile per configurare Omni-search.

Gli utenti più esperti possono modificare anche linee specifiche di HTML e CSS, consulta questa sezione.

Logo #

Per aggiungere il logo al design di Omni-search, trova semplicemente l’URL dell’immagine e inseriscilo nel valore della variabile: os_brand_logo.

La variabile tipicamente si chiama os_brand_logo e sarà simile a questa dopo aver incollato il logo:

Infinite/auto load #

Se vuoi controllare se Omni-search deve caricare automaticamente altri prodotti quando l’utente scorre fino all’ultima riga di prodotti, la variabile va impostata a true o false. Di solito la variabile si chiama os_autoload. In questo esempio, Omni-search non carica automaticamente altri risultati.

Traduzioni #

Di default il template è in inglese. Se il tuo negozio usa un’altra lingua, puoi tradurre i testi cambiando il valore delle variabili.

Questo esempio mostra le variabili per il bottone di ordinamento:

Protip: Usa la generativa AI (es. chatGPT) per tradurre in massa: scrivi “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 #

Per cambiare lo stile, la configurazione avviene tramite le variabili CSS.

I template usano le variabili CSS che hanno una struttura come questa:

--variable_name: variable_value;

Gli utenti più esperti possono modificare singole regole CSS per cambiare in modo avanzato il design.

Colori #

I colori configurabili si trovano e regolano sotto il commento CSS “Colors” /* Colors */

Font #

Come per i colori, la variabile del font si trova nella sezione /* Font */.

In genere ha questa forma: --font-family: 'Kumbh Sans', sans serif;

Design standard #

Il design standard per Omnisearch include:

• Supporto dropdown per Varianti: consenti agli acquirenti di scegliere le varianti (es. taglia, colore) prima di aggiungere al carrello.

• Selettore quantità.

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

• Markup pulito e ben strutturato, con commenti chiari.

• Variabili centralizzate per stile e funzionamento, così è facile adattare colori, spaziature, etichette e opzioni comuni senza toccare il codice principale.

• Facet-slider per il prezzo per filtri rapidi per fascia di prezzo.

• Suggerimenti cliccabili che attivano subito la ricerca.

Per sviluppatori #

Styling #

I design consistono in un layout principale, CSS styling e in una serie di sub-design che possono essere richiamati dal layout principale.

Puoi modificare tutto questo separatamente per Desktop e Mobile. Di default Omni-search usa lo stesso HTML su tutte le dimensioni schermo, e utilizza il CSS per l’adattamento responsive. Per questo la scheda Mobile di default non contiene codice.

Se servisse, puoi creare un HTML completamente differente per Mobile, che sarà usato sugli schermi più piccoli.

Inizialmente, potresti voler solo adattare alcuni elementi per far sì che il design rispecchi l’aspetto del tuo brand - Potrai sempre modificare il design in seguito.

HTML #

Questo è il layout principale che controlla il posizionamento degli elementi. Utilizza Liquid come linguaggio di template.

Nei nostri design di partenza, la prima sezione è dedicata agli elementi che solitamente vengono modificati di più, come etichette per l’ordinamento, valuta e i diversi testi che puoi tradurre nella tua lingua.

CSS #

Lo stile che sarà iniettato insieme all’HTML, per dare controllo completo sul look in maniera isolata.

Sub-design disponibili #

Qualsiasi sub-design aggiunto qui può essere richiamato nel layout generale. Funzionano come moduli modificabili separatamente e vengono aggiunti con il loro ID e nome: {{@247373 - TopBarSearchForm}}

Puoi eliminare, duplicare e copiare il riferimento di qualsiasi sub-design cliccando sul pulsante con i tre punti.

Per modificare un sub-design, clicca sulla sua icona Modifica. Quando hai finito, clicca su Save & close per tornare all’editor layout principale.

Alcuni elementi necessitano identificatori specifici, tra cui:

• Il campo input id="clerk-omnisearch-input"
• Il contenitore dei risultati id="clerk-omnisearch-content"

Puoi verificare i tuoi progressi in qualsiasi momento cliccando su “Anteprima design”.

Le modifiche più frequenti ai design sono queste:

• Logo: Accedi a TopBarSearchForm e sostituisci il logo di default con il tuo.

• Font: Se necessario, adatta i font all’immagine del tuo sito.

• Colori: Inserisci i colori del tuo brand negli elementi che vuoi enfatizzare o uniformare, come bottoni o tag.

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

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

Parti Reattive vs Statiche #

Capire quali parti di Omnisearch si ri-renderizzano ad ogni ricerca — e quali no — è importante per la personalizzazione del design.

Parti statiche sono renderizzate una volta sola quando l’overlay si apre e non vengono toccate nelle query successive:

• Il contenitore dell’overlay (clerk-omnisearch-overlay)
• Il campo di input (#clerk-omnisearch-input)
• Qualsiasi HTML nel design che vive fuori da #clerk-omnisearch-content — esempio, logo, bottone di chiusura, top bar

Il campo di input è volutamente statico. Ri-renderizzarlo ad ogni pressione interromperebbe la scrittura dell’utente e peggiorerebbe l’esperienza.

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

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

Se vuoi che un elemento si aggiorni alla query — per esempio un conteggio risultati in tempo reale nell’header — deve essere dentro #clerk-omnisearch-content. Se 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 tramite Liquid.

L’approccio consigliato è verificare se products è vuoto e, in tal caso, mostrare uno slider alternativo e un messaggio personalizzato:

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

{% else %}
  <!-- Fallback nessun risultato -->
  <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 sta mostrando risultati fuzzy o correlati invece che esatti, e mostrare così un messaggio adeguato:

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

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

Il testo del messaggio nessun risultato è HTML puro all’interno del design, quindi può essere tradotto o stilizzato liberamente senza modificare altre impostazioni fuori dall’editor.

Struttura dell’overlay #

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

Qui viene iniettato il design, dato che l’elemento input fa parte del design stesso, ci sono esigenze strutturali per non ri-renderizzare il campo input ad ogni caricamento. La struttura deve essere la seguente 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’identificativo clerk-omnisearch-input. Quando viene attivato l’elemento trigger, spostiamo il focus del cursore su questo campo e aggiungiamo l’eventuale query presente, per mantenere fluida l’esperienza utente.

Content Wrapper #

Il content wrapper è dove avviene la maggior parte delle operazioni, e deve avere l’identificativo clerk-omnisearch-content. Qui si troveranno facet, slider e tutto ciò che non è il campo input.

Classi #

È possibile aggiungere funzionalità al design aggiungendo classi specifiche agli elementi.

Bottone di chiusura #

clerk-omnisearch-close

Aggiungendo questa classe a un elemento all’interno del design, tale elemento nasconderà l’overlay.

Ordinamento #

clerk-omnisearch-sort

Trova i dropdown di ordinamento e vi aggiunge listener.

Per inserire un elemento di ordinamento nel design, aggiungilo all’elemento di selezione, es. un dropdown. Deve avere un valore del tipo value:[desc|asc], cioè il valore da ordinare seguito da due punti e poi desc o asc. Opzionalmente aggiungi l’attributo data-sort-type se vuoi ordinare categorie o pagine.

Search Facet #

clerk-facet-search

Se è presente una ricerca tra i facet, crea un listener e nasconde i facet che non corrispondono.

La classe, se presente nella pagina, controlla l’esistenza di elementi di ricerca facet. Le ricerche facet permettono agli utenti di cercare tra i facet. Per funzionare, l’elemento deve avere un valore stringa.

Full Clear #

clerk-omnisearch-full-reset

Quando cliccato, un elemento con questa classe azzera tutti i facet selezionati e resetta la ricerca.

Facets Clear #

clerk-omnisearch-facet-full-reset

Quando cliccato, un elemento con questa classe deseleziona tutti i facet attivi. Tipicamente usato su un bottone “Pulisci tutto” in un gruppo di facet, per permettere agli utenti di resettare tutti i filtri in un colpo solo.

Group Clear #

clerk-omnisearch-facet-group-reset

Quando cliccato, un elemento con questa classe deseleziona tutti i child nel gruppo.

Per offrire la funzione di deselezionare interi gruppi di facet, l’elemento può avere questa classe. All’attivazione (es. click), tutte le voci del gruppo saranno deselezionate, resettando il gruppo. Per funzionare, deve avere come attributo il gruppo da resettare con nome data-facet-group.

Facet Clear #

clerk-omnisearch-facet-reset

Elementi con questa classe deselezionano un singolo elemento dato il pair gruppo/valore.

Questa classe è pensata per casi in cui serve deselezionare solo un facet. Un elemento con questa classe deve avere sia il gruppo (data-facet-group) che il valore (data-facet-value). All’attivazione, deseleziona solo il facet indicato senza toccare gli altri.

Facet Click #

clerk-facet

Elementi con questa classe vengono trattati come facet selezionabili.

Tutti i facet devono avere sia la classe che gli attributi data-facet-group e data-facet-value, così da poter individuare cosa seleziona l’utente.