Omnisearch

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

Per iniziare #

Omnisearch è composto da un Design personalizzabile per la grafica e da un blocco Element che consente la sua installazione sul tuo sito.

Creare un design #

Questa operazione si esegue 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 subito e si possono sempre modificare successivamente. La modifica richiede la conoscenza di HTML, CSS e Liquid. Consulta la sezione Styling in questa guida per maggiori informazioni.

Creare un Element #

Questa operazione si esegue 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 per il numero di risultati da visualizzare. Anche la logica dello Stato Vuoto può essere gestita tramite Rules.

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

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

• Empty State Logic ti consente di selezionare i tipi di prodotti da mostrare quando Omnisearch viene aperto inizialmente, prima che vengano scritte parole. Di default è Bestsellers, ma può essere anche personalizzato, ad esempio con Visitor Recommendations.

Finalizzare il Design #

Il design da usare per mostrare il blocco Element. Seleziona il design che hai creato.

Se il tuo design comprende delle variabili, puoi impostarle qui.

Puoi gestire il numero di risultati da visualizzare per ogni tipo, ogni volta che viene fatta una ricerca. Generalmente raccomandiamo queste quantità:

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

Infine, scegli gli attributi che vuoi includere come Facets e imposta i nomi che dovranno essere mostrati nei risultati di ricerca. Se non trovi un attributo specifico nell’elenco, aggiungilo alla lista “filterable attributes”, in Search Configuration.

Inserimento nel sito #

La visibilità serve per controllare chi può vedere Omnisearch.

• In preview ti consente di testare il tuo elemento senza impattare il sito live. Puoi visualizzare il sito in anteprima cliccando su “Open site in preview” o aggiungendo ?clerk_content_mode=preview all’url del sito.

• In my live site si usa quando hai finito i test e sei pronto a pubblicare.

Uso tramite injection #

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

• Event controlla quale azione deve fare l’utente per attivare Omnisearch. Molto probabilmente vuoi che venga mostrato quando i visitatori cliccano sull’icona di ricerca o nel campo di input.

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

Per trovare il CSS selector unico:

1. Ispeziona il codice del sito. Nella maggior parte dei browser puoi cliccare col tasto destro in qualsiasi punto e scegliere Ispeziona o simili.
2. Trova l’elemento da targettizzare.
3. Clicca con il tasto destro, poi copia > copia selector.

Uso tramite codice incorporato #

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

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

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

Qui sotto trovi un esempio completo di embedcode 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 viene mostrata l’interfaccia di ricerca sul tuo sito. Questa opzione è disponibile nella tab Insert durante la modifica dell’Element Omnisearch.

Full overlay #

Questa è la modalità predefinita. Quando viene attivato, Omnisearch copre l’intera area visibile con un overlay a schermo intero. L’interfaccia di ricerca sostituisce la pagina, offrendo un’esperienza di ricerca incentrata.

Usa questa modalità quando vuoi:

• Un ambiente di ricerca privo di distrazioni
• Controllo completo sul layout della ricerca
• Un’interfaccia di ricerca completamente indipendente dall’header del sito

Partial overlay #

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

Usa questa modalità quando vuoi:

• Mantenere header e navigazione accessibili durante la ricerca
• Un’integrazione perfetta con il layout già esistente
• Un’esperienza di ricerca che sembri naturale nel contesto del sito

Opzioni di configurazione #

Quando si seleziona Partial Overlay, vengono offerte opzioni aggiuntive:

Header selector

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

Esempi di selectors:

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

Search input selector

Il CSS selector del campo input di ricerca esistente. Se fornito, Omnisearch si sincronizza con il campo di ricerca dell’header, creando un’esperienza unica in cui ciò che viene digitato viene subito mostrato nei risultati Omnisearch.

Esempi di selectors:

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

Larghezza

Controlla la dimensione orizzontale dell’overlay:

• Full width: Si estende per l’intera larghezza del viewport
• Content width: Combacia con la larghezza di un elemento container specificato da un CSS selector
• Fixed width: Una larghezza in pixel definita da te

Altezza

Controlla la dimensione verticale dell’overlay:

• From header to bottom: Occupa lo spazio subito sotto l’header fino al fondo schermo
• Viewport percentage: Una percentuale dell’altezza del viewport (es. 80%)
• Fixed height: Una determinata altezza in pixel
• Max height: Imposta un limite massimo lasciando l’overlay più piccolo se il contenuto richiede meno spazio

Allineamento orizzontale

Stabilisce dove l’overlay appare orizzontalmente:

• Left: Allineato a sinistra del viewport
• Center: Centrato orizzontalmente
• Right: Allineato a destra del viewport

Posizione verticale

Gestisce il posizionamento rispetto all’header:

• Below header: Sotto l’elemento header del sito
• Fixed from top: Un offset specifico in pixel dalla parte superiore

Configurazione del design #

La maggior parte della Omni-search può essere configurata cambiando le variabili presenti nei file di design.

Nel linguaggio liquid template, una variabile ha questa struttura:

{% assign variable_name = "variable value" %}

In generale, solo il valore della variabile dovrebbe essere modificato per configurare la Omni-search.

Gli utenti tecnici possono anche modificare direttamente HTML e CSS: vedi questa sezione.

Logo #

Per inserire il logo nella grafica di Omni-search, basta trovare l’URL dell’immagine e inserirlo nel valore della variabile: os_brand_logo.

La variabile si chiama tipicamente os_brand_logo, e dovrebbe apparire così una volta incollato il logo:

Infinite/auto load #

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

Traduzioni #

Per impostazione predefinita, il template è in inglese. Se il tuo negozio è in un’altra lingua, puoi tradurre i testi cambiando il valore delle variabili.

Questo esempio mostra le variabili per il bottone di ordinamento:

Protip: Usa l’intelligenza artificiale (ad esempio chatGPT) per tradurre in massa inserendo “Traduci questi valori di variabile dall’inglese al danese. Restituisci il codice completo così da poterlo copiare/incollare a sostituzione del codice esistente: PASTE_VARIABLES_HERE”

Styling #

Per modificare lo stile, la configurazione avviene nelle variabili CSS.

I template usano CSS variables con questa struttura:

--variable_name: variable_value;

Per utenti più esperti, possono essere modificate regole CSS individuali per cambiamenti più avanzati.

Colori #

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

Font #

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

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

Design standard #

Il design standard per Omnisearch comprende:

• Supporto per dropdown Varianti: consente agli utenti di scegliere tra varianti (es. taglia, colore) prima dell’acquisto.

• Selettore quantità.

• Pulsante nativo Add-to-Cart che notifica Clerk.js, per garantire sincronizzazione fra analytics e merchandising.

• Markup pulito e ben strutturato con commenti esplicativi.

• Variabili centralizzate per stile e comportamento, così è facile regolare colori, spaziature, etichette e opzioni comuni senza modificare il codice base.

• Price slider per filtraggio rapido su range di prezzo.

• Suggerimenti cliccabili che attivano subito la ricerca.

Per sviluppatori #

Styling #

I design sono composti da un layout principale, stile CSS e un set di sub-design richiamabili dal layout principale.

Puoi modificare ognuno di questi per Desktop e Mobile separatamente. Per impostazione predefinita, la Omni-search usa lo stesso HTML per tutte le dimensioni, affidando alla CSS la piena responsività. Ecco perché il tab Mobile parte senza codice.

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

Inizialmente potresti voler solo personalizzare pochi dettagli per allineare il design al 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 base, la prima sezione è dedicata agli elementi più cambiati, come etichette di ordinamento, valuta e testi vari che puoi tradurre nella tua lingua.

CSS #

Stile visivo abbinato all’HTML, ti permette controllo completo sul look in modo isolato.

Sub-design disponibili #

Qualunque sub-design aggiunto qui può essere richiamato nel layout generale. Funzionano come moduli indipendenti, si aggiungono tramite ID e nome: {{@247373 - TopBarSearchForm}}

Puoi cancellare, duplicare o copiare il riferimento di un sub-design cliccando sul pulsante con i tre puntini.

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

Alcuni elementi richiedono identificativi specifici, ad esempio:

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

Quando vuoi controllare i tuoi progressi, puoi cliccare su “Preview design”.

Le modifiche più frequenti ai design sono queste:

• Logo: Accedi a TopBarSearchForm e sostituisci il logo predefinito col tuo.

• Font: Se c’è bisogno, regola i font per uniformare il sito.

• Colori: Puoi aggiungere i colori del tuo brand sugli elementi che vuoi enfatizzare o uniformare (es. bottoni, tag).

• Bottoni e bordi tag: Puoi regolare colore, raggio, larghezza…

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

Struttura overlay #

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

Qui verrà inserito il design: dato che l’input è parte del design, è importante seguire una struttura affinché non venga renderizzato nuovamente ad ogni caricamento. La struttura sotto l’overlay dovrebbe essere così:

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

Input field #

Per essere trovato, il campo input deve avere l’identificativo clerk-omnisearch-input. Quando viene attivato l’elemento trigger, il focus viene spostato su questo campo e la query inserita, per garantire fluidità all’esperienza utente.

Content Wrapper #

Il content wrapper è dove avviene la maggior parte delle operazioni; la struttura attorno deve avere l’id clerk-omnisearch-content. Qui vanno inseriti i facets, slider e tutto ciò che non è il campo input.

Classi #

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

Close Button #

clerk-omnisearch-close

Se associ la classe a un elemento all’interno del design, quel componente nasconderà l’overlay.

Sorting #

clerk-omnisearch-sort

Rileva i dropdown di ordinamento e vi aggiunge i listener.

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

Search Facet #

clerk-facet-search

Se è presente una ricerca tra i facets, crea un listener e nasconde i facets che non fanno match.

La classe, se presente in una pagina, controlla se esistono facet search. Queste permettono all’utente di cercare tra i facets. Per funzionare, l’elemento deve avere un valore stringa.

Full Clear #

clerk-omnisearch-full-reset

Se cliccati, gli elementi con questa classe azzerano tutte le selezioni di facets e resettano la query.

Facets Clear #

clerk-omnisearch-facet-full-reset

Se cliccati, gli elementi con questa classe deselezionano tutti i facets attivi. Normalmente si trova su un bottone “Cancella tutto” nei gruppi di facets.

Group Clear #

clerk-omnisearch-facet-group-reset

Se cliccati, gli elementi con questa classe deselezionano tutto ciò che è figlio del gruppo.

Per offrire la possibilità di deselezionare un gruppo intero di facets, un elemento può avere questa classe. Quando viene attivato (es. cliccato), tutti gli elementi nel gruppo vengono deselezionati. Per funzionare, serve un attributo col gruppo da resettare denominato data-facet-group.

Facet Clear #

clerk-omnisearch-facet-reset

Elementi con questa classe deselezionano un singolo facet data una coppia gruppo/valore di attributi.

Questa classe serve in scenari dove si deve deselezionare un singolo facet. Un elemento con questa classe e gli attributi data-facet-group e data-facet-value andrà a deselezionare solo quel facet collegato, lasciando invariati gli altri.

Facet Click #

clerk-facet

Elementi con questa classe vengono trattati come facets selezionabili.

Tutti i facets devono avere la classe e gli attributi data-facet-group e data-facet-value, così sappiamo quale filtro seleziona il cliente.