Omnisearch

Omnisearch è un’esperienza di ricerca completa in un unico overlay. Combina i risultati mentre i visitatori digitano con la navigazione completa dei risultati e le faccette, sostituendo i componenti separati Instant Search e Search Page.
Scegli Omnisearch da solo o Instant Search e Search Page insieme. Se Omnisearch è già installato, non è necessario aggiungere nessuno dei due componenti. Personalizza il design e le impostazioni esistenti di Omnisearch per migliorare l’esperienza.
Omnisearch include:
- Risultati in tempo reale mostrati ai visitatori mentre digitano, inclusi prodotti, categorie e pagine.
- Ordinamento e filtri: per consentire ai visitatori di raffinare la ricerca in modo intuitivo e semplice.
- Facile da integrare nel tuo sito usando uno dei nostri ottimi template di partenza.
- Si adatta al tuo brand modificando alcune impostazioni standard come logo, font, colori e altro ancora.
- È completamente personalizzabile con HTML, CSS e Liquid per developers.
Per iniziare #
Omnisearch consiste in un Design personalizzabile per la grafica e un blocco Element che ne 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 di partenza e assegnagli 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 subito e possono sempre essere modificati in seguito. La modifica richiede 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 elementi creati nel tuo account my.clerk.io. Contengono la logica per mostrare i risultati e le impostazioni su quanti risultati mostrare. La logica dello stato vuoto può anche 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 Element è Omnisearch di default, e non dovrebbe essere cambiato. Qui puoi anche aggiungere filters se necessario, ma per la maggior parte delle configurazioni non serve.
Empty State Logic ti consente di selezionare il tipo di prodotti da mostrare quando Omnisearch viene aperto inizialmente, prima che venga digitata qualsiasi parola. Di default è Bestsellers ma può anche essere personalizzato es. con Visitor Recommendations.
Finalizzare il Design #
Il design attraverso cui verrà renderizzato il blocco Element. Seleziona il design che hai creato.
Se il tuo design include variabili, possono essere impostate qui.
Puoi controllare il numero di risultati da mostrare per ciascun tipo, ogni volta che viene eseguita una ricerca. Raccomandiamo generalmente le seguenti quantità:
- Prodotti: 20-60
- Suggerimenti: 5
- Categorie & pagine: 10
Infine, scegli gli attributi che vuoi includere come Facet e imposta i nomi con cui verranno visualizzati nei risultati di ricerca. Se non trovi un attributo specifico nell’elenco, aggiungilo nell’elenco “attributi filtrabili”, in Search Configuration.
Inserimento nel sito #
Il metodo consigliato è tramite inject ma puoi anche inserire l’elemento nel sito con un embed code.
Visibilità è utilizzata per controllare chi può vedere Omnisearch.
In anteprima ti permette di testare il tuo elemento senza influenzare il sito pubblico. Puoi aprire il tuo sito in anteprima cliccando su “Open site in preview” o aggiungendo
?clerk_content_mode=previewall’URL del tuo sito.Nel mio sito live viene utilizzato quando hai finito di testare e sei pronto a rendere pubblico l’elemento.
Utilizzo di Injection #
Questo è il modo più semplice per installare. Clerk aggiungerà automaticamente il codice Omnisearch al tuo sito, indirizzandolo a un campo di ricerca a tua scelta e attivandolo in base a un evento.
Evento controlla ciò che l’utente deve fare per attivare Omnisearch. Probabilmente vuoi che venga mostrato quando i visitatori cliccano sull’icona di ricerca o sul campo di input.
Elemento decide la parte del sito 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 su di essa), devi solo trovare l’unico CSS selector applicato. Se hai identificatori diversi su mobile e desktop, aggiungili entrambi.
Trova il tuo CSS selector unico così:
- Ispeziona il codice del tuo sito. Nella maggior parte dei browser puoi cliccare col tasto destro ovunque sulla pagina e scegliere Ispeziona o simile.
- Trova l’elemento da indirizzare
- Clicca col tasto destro e trova l’opzione copia > copia selettore
Utilizzo del codice incorporato #
Questo permette di aggiungere Omnisearch con uno snippet. Serve la possibilità di modificare i file HTML del tuo negozio o aggiungere codice con un editor.
Se hai modifiche non salvate, salvale per generare il codice di embedding.
Copia e incolla questo codice nel file che genera tutte le pagine del negozio, idealmente vicino al tag </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 di 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 appare l’interfaccia di ricerca sul tuo sito. Configura questa opzione nella scheda Insert durante la modifica del tuo Omnisearch Element.
Overlay completo #
Questa è la modalità predefinita. Quando attivato, Omnisearch copre l’intera area visibile con un overlay a schermo intero. L’interfaccia di ricerca prende il controllo della pagina, fornendo un’esperienza di ricerca focalizzata.
Usa questa modalità quando desideri:
- Un ambiente di ricerca senza distrazioni
- Controllo completo 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 l’intero schermo, l’overlay di ricerca appare sotto l’header, mantenendo visibile e funzionale l’header.
Usa questa modalità quando vuoi:
- Mantenere header e navigazione accessibili durante la ricerca
- Un’integrazione più armoniosa con il layout del sito
- Un’esperienza di ricerca che sembri una parte naturale del sito
Opzioni di configurazione #
Quando si seleziona Overlay Parziale, sono disponibili impostazioni aggiuntive:
Header selector
Il selettore CSS dell’elemento header del sito. Omnisearch lo usa per posizionare l’overlay direttamente sotto l’header, assicurando un corretto allineamento.
Esempi di selettori:
header.site-header#main-header
Search input selector
Il selettore CSS del campo di input della ricerca esistente. Se specificato, Omnisearch si sincronizza col campo di ricerca dell’header, creando un’esperienza unificata in cui digitare nella barra di ricerca aggiorna i risultati Omnisearch.
Esempi di selettori:
#search-input.header-search input[name="search"]
Larghezza
Controlla la dimensione orizzontale dell’overlay:
- Full width: Occupa tutta la larghezza del viewport
- Content width: Coincide con la larghezza di un elemento contenitore specificato con un selettore CSS
- Larghezza fissa: Una larghezza in pixel specifica
Altezza
Controlla la dimensione verticale dell’overlay:
- Dall’header al fondo: Occupa lo spazio dal fondo dell’header al fondo del viewport
- Percentuale del viewport: Una percentuale dell’altezza del viewport (es., 80%)
- Altezza fissa: Una altezza in pixel specifica
- Altezza massima: Imposta un limite superiore permettendo all’overlay di essere più piccolo se il contenuto richiede meno spazio
Allineamento orizzontale
Determina dove appare l’overlay orizzontalmente:
- Sinistra: Allinea a sinistra del viewport
- Centro: Centra orizzontalmente
- Destra: Allinea a destra del viewport
Posizione verticale
Controlla la posizione verticale rispetto all’header:
- Sotto l’header: Posiziona l’overlay direttamente sotto l’elemento header
- Fisso dall’alto: Un offset in pixel specificato dall’inizio del viewport
Configurazione del design #
La maggior parte delle impostazioni di Omni-search può essere configurata modificando le variabili presenti nei file di design.
Nel linguaggio template liquid, una variabile ha la seguente struttura:
{% assign variable_name = "variable value" %}
Come regola generale, solo il valore della variabile dovrebbe essere modificato per configurare Omni-search.
Gli utenti più tecnici possono naturalmente modificare direttamente anche le linee HTML e CSS. Vedi questa sezione.
Logo #
Per aggiungere un logo al design Omnisearch, imposta os_brand_logo sull’URL immagine del tuo logo.
Caricamento infinito/automatico #
Se desideri controllare se Omni-search debba caricare automaticamente altri risultati prodotto quando l’utente scorre fino all’ultima riga, la variabile deve essere impostata a true o false.
La variabile si chiama tipicamente os_autoload. Impostala su false per impedire il caricamento automatico di altri risultati.
Traduzioni #
Per impostazione predefinita, il template è in inglese. Se il negozio ha una lingua diversa, puoi tradurre gli elementi testuali modificando i valori delle variabili.
Traduci anche le variabili dei pulsanti di ordinamento insieme alle altre variabili di testo.
Suggerimento: Usa un’AI generativa (es. chatGPT) per tradurre in blocco scrivendo “Traduci questi valori delle variabili dall’inglese al danese. Restituisci l’intero codice così può essere copiato/incollato per sostituire il codice esistente: PASTE_VARIABLES_HERE”
Stili #
Per modificare qualunque stile, la configurazione può avvenire nelle variabili CSS.
I template usano variabili CSS strutturate così:
--variable_name: variable_value;
Gli utenti più tecnici possono modificare singole regole CSS per personalizzazioni di design più avanzate.
Colori #
I colori configurabili sono identificabili e configurabili nella sezione sotto il commento CSS “Colors”
/* Colors */
Font #
Come per i colori, la variabile del font si trova sotto il commento /* Font */.
In genere una variabile come:
--font-family: 'Kumbh Sans', sans serif;
Design standard #
Il design standard di Omnisearch include:
Supporto dropdown per varianti: Permette ai clienti di scegliere attributi di variante (es. taglia, colore) prima di aggiungere al carrello.
Selettore quantità.
Pulsante nativo Add-to-Cart che notifica Clerk.js, garantendo che analytics e merchandising siano allineati.
Markup pulito e ben strutturato con commenti chiari.
Variabili centralizzate per stile e comportamento, facilitando la regolazione di colori, spaziature, etichette e opzioni comuni senza modificare codice centrale.
Facet slider per il prezzo per filtrare rapidamente le fasce di prezzo.
Suggerimenti cliccabili che attivano immediatamente una ricerca.
Per gli sviluppatori #
Stili #
I design sono composti da un main layout, stile CSS e un set di sub-design che possono essere richiamati nel main layout.
Puoi modificare tutto ciò per Desktop e Mobile separatamente. Per default, Omni-search usa lo stesso HTML per tutte le dimensioni di schermo e usa il CSS per essere completamente responsive. Ecco perché la scheda Mobile non contiene codice di base.
Se necessario, puoi creare un markup HTML completamente diverso per Mobile che sarà usato sugli schermi più piccoli.
All’inizio potresti voler modificare solo alcune cose per far combaciare il design con lo stile del tuo brand - Puoi sempre modificare il design anche dopo.
HTML #
Questo è il layout principale che controlla la posizione di tutti gli elementi. Usa Liquid come linguaggio di templating.
Nei nostri design di partenza, la prima sezione è dedicata agli elementi più cambiati, come le etichette di ordinamento, la valuta e vari testi che puoi tradurre nella tua lingua.
CSS #
Stile che verrà iniettato con l’HTML, dando pieno controllo sulla grafica in modo contenuto.
Sub-design disponibili #
Nell’editor di codice Search, Available Designs and Components si trova sotto l’area principale di codice. Scorri in 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 Save, poi torna al design principale separatamente.
Tutti i design qui aggiunti possono essere richiamati nel layout generale. Funzionano come moduli modificabili separatamente e aggiungibili tramite il loro ID e nome: {{@247373 - TopBarSearchForm}}
Puoi eliminare, duplicare e copiare il riferimento di ogni sub-design cliccando il pulsante con i tre puntini.
Per modificare un sub-design, clicca sull’icona Modifica. Una volta terminato, clicca su Salva & chiudi per tornare all’editor del layout principale.
Alcuni elementi necessitano identificativi specifici, ad esempio:
- Il campo input
id="clerk-omnisearch-input" - Il content wrapper
id="clerk-omnisearch-content"
Ogni volta che vuoi controllare i tuoi progressi, puoi farlo cliccando il pulsante “Anteprima design”.
Le modifiche più comuni ai design sono queste:
Logo: Accedi a TopBarSearchForm e sostituisci il logo predefinito con il tuo.
Font: Se serve, modifica i font per adattarli allo stile del sito.
Colori: Puoi aggiungere i colori del tuo brand agli elementi che vuoi enfatizzare o armonizzare come bottoni e tag.
Bottoni e bordi tag: Puoi modificarne colore, raggio, larghezza…
Link: Se hai uno stile particolare per i link, puoi personalizzarlo.
Parti reattive vs statiche #
Capire quali parti di Omnisearch vengono re-renderizzate per ogni query — e quali no — è importante nella personalizzazione del design.
Parti statiche vengono renderizzate una sola volta all’apertura dell’overlay e non vengono più toccate dopo:
- Il contenitore overlay stesso (
clerk-omnisearch-overlay) - Il campo input di ricerca (
#clerk-omnisearch-input) - Qualunque HTML del design fuori da
#clerk-omnisearch-content— come logo, bottone chiudi, top bar
Il campo input è intenzionalmente statico. Renderizzarlo a ogni battuta interromperebbe la digitazione del visitatore e rovinerebbe l’esperienza di ricerca.
Parti reattive: tutto ciò che è dentro #clerk-omnisearch-content. Questo wrapper viene re-renderizzato a ogni query:
- Risultati prodotto
- Facet e filtri
- Categorie, pagine e suggerimenti
- Contatore risultati e controlli di ordinamento
- Messaggi “nessun risultato”
Se vuoi che un elemento si aggiorni quando la query cambia — ad esempio un contatore live dei risultati in header — deve stare dentro #clerk-omnisearch-content. Se vuoi che resti visibile e stabile durante la digitazione, posizionalo fuori da quel wrapper.
Stato Nessun Risultato #
Quando una ricerca non restituisce prodotti, Omnisearch non mostra automaticamente un fallback — è gestito nel design tramite Liquid.
L’approccio consigliato è verificare se products è vuoto e condizionare il rendering di uno slider fallback e di un messaggio personalizzato:
{% if products.length > 0 %}
<!-- Risultati normali -->
{% for product in products %}
<!-- product card -->
{% endfor %}
{% else %}
<!-- Nessun risultato 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 simili 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 }}" — visualizzazione delle corrispondenze più vicine:
</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 nel design, dunque può essere tradotto o stilizzato liberamente senza cambiare altre configurazioni fuori dal design editor.
Struttura dell’overlay #
Quando omnisearch viene avviato, crea un elemento con la classe clerk-omnisearch-overlay ed è iniettato alla fine del body.
Qui verrà iniettato il design; avendo il campo input come parte del design, abbiamo necessità strutturali per non re-renderizzare l’input a ogni caricamento. La struttura dovrebbe presentarsi come segue 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 attivato l’elemento trigger, il cursor focus si sposta su questo elemento, aggiungendo l’eventuale query già presente per mantenere l’esperienza utente fluida.
Content Wrapper #
Il content wrapper è dove avvengono la maggior parte delle operazioni; il contenitore attorno deve avere l’identificatore clerk-omnisearch-content. Qui vanno faccette, slider e tutto ciò che non è il campo input.
Classi #
La funzionalità può essere aggiunta al design fornendo classi specifiche agli elementi.
Bottone Chiudi #
clerk-omnisearch-close
Assegnando la classe a un elemento all’interno del design, quell’elemento chiuderà l’overlay.
Ordinamento #
clerk-omnisearch-sort
Trova i menu a tendina di ordinamento e vi aggiunge listener.
Per ottenere un controllo di ordinamento nel design, aggiungi questa classe all’elemento selezionato, ad esempio un dropdown. Per funzionare, l’elemento deve essere del tipo value:[desc|asc], cioè valore da ordinare, due punti e poi desc o asc.
Facoltativamente puoi aggiungere un attributo data-sort-type se vuoi ordinare categorie o pagine.
Search Facet #
clerk-facet-search
Se presente una ricerca facet, crea listener e nasconde le faccette non corrispondenti alla query.
Tale classe, se presente in una pagina, verifica la presenza di elementi facet search. Le ricerche facet consentono di cercare nelle faccette. Per funzionare, l’elemento deve avere un valore stringa.
Pulizia Completa #
clerk-omnisearch-full-reset
Cliccando, gli elementi con questa classe azzerano tutte le faccette selezionate e la query.
Pulizia Facets #
clerk-omnisearch-facet-full-reset
Cliccando, gli elementi con questa classe deselezionano tutte le faccette attive. Tipicamente utilizzato in un bottone “Svuota tutto” in un gruppo di faccette, permette di resettare rapidamente tutti i filtri selezionati.
Pulizia Gruppo #
clerk-omnisearch-facet-group-reset
Cliccando, gli elementi con questa classe deselezionano tutti gli elementi figli nel gruppo.
Per offrire la funzione di deselezionare un intero gruppo di faccette, un elemento può ricevere questa classe. Una volta attivato (es. clic), tutti gli elementi del gruppo vengono deselezionati, resettando quel gruppo. Serve che l’elemento abbia l’attributo data-facet-group con il nome del gruppo da azzerare.
Pulizia Facet #
clerk-omnisearch-facet-reset
Gli elementi con questa classe devono deselezionare un singolo elemento tramite coppia di attributi group/value.
Questa classe serve negli scenari in cui va deselezionata una sola faccetta. Un elemento con questa classe può essere associato a una specifica faccetta in un gruppo tramite data-facet-group e un data-facet-value. Attivandolo, deseleziona solo la faccetta associata, lasciando inalterate le altre.
Facet Click #
clerk-facet
Gli elementi con questa classe sono trattati come faccette selezionabili.
Tutte le faccette devono avere una classe e gli attributi data-facet-group e data-facet-value affinché si sappia cosa sta selezionando il cliente.
Questa pagina è stata tradotta da un'utile intelligenza artificiale, quindi potrebbero esserci errori linguistici. Grazie per la comprensione.