Live Search & Autocomplete — Documentazione

Installazione

Requisiti

Magento 2.4.x (Open Source o Adobe Commerce), PHP 8.1–8.5. Funziona con qualsiasi motore di ricerca supportato da Magento (OpenSearch, Elasticsearch o MySQL). Compatibile con i temi Hyvä e Luma. Richiede il modulo gratuito codingrow/module-core. Nessun provider AI o API key necessari — il modulo è pura ricerca di catalogo.

Configurazione iniziale

Installa tramite Composer, abilita il modulo ed esegui il consueto upgrade/compile:

composer require codingrow/module-live-search-autocomplete
bin/magento module:enable Codingrow_LiveSearchAutocomplete
bin/magento setup:upgrade && bin/magento setup:di:compile
bin/magento cache:flush

Poi vai su Stores → Configuration → Codingrow → Live Search & Autocomplete, incolla la tua chiave di licenza, imposta Enable = Yes e svuota la cache.

Configurazione

Tutte le opzioni si trovano sotto Stores → Configuration → Codingrow → Live Search & Autocomplete.

Disinstallazione

Imposta Enable = No per disattivarlo senza rimuovere nulla, oppure rimuovi del tutto il modulo:

bin/magento module:disable Codingrow_LiveSearchAutocomplete
composer remove codingrow/module-live-search-autocomplete
bin/magento setup:upgrade && bin/magento cache:flush

Ricerca & sinonimi

Come funziona

Uno script leggero e indipendente dal tema si aggancia al tuo campo di ricerca esistente (rileva automaticamente le barre di ricerca Hyvä e Luma). Mentre il cliente digita, applica un debounce all'input e chiede al modulo i prodotti corrispondenti, poi mostra un menu a tendina con miniatura, nome, prezzo ed eventuale sconto per ogni risultato, più un link "vedi tutti i risultati" alla pagina di ricerca completa. Ogni risultato rimanda direttamente alla pagina prodotto. I risultati rispettano visibilità del prodotto, disponibilità e ambito dello store.

Prestazioni

I suggerimenti vengono recuperati dal motore di ricerca indicizzato di Magento — lo stesso motore che alimenta la pagina dei risultati (OpenSearch, Elasticsearch o MySQL) — tramite la richiesta nativa quick_search_container. Poiché la corrispondenza è fatta dall'indice e non dalla scansione del database, il tempo di risposta resta basso e non cresce con le dimensioni del catalogo. Su uno store dal vivo di 67.000 prodotti, i suggerimenti tornano in circa un secondo e restano costanti man mano che il catalogo cresce.

Ricerca su campi estesi

Se l'autocompletamento cerchi solo nome/SKU oppure anche nella descrizione e in altri campi è controllato da Magento stesso, per attributo — non da un interruttore del modulo. Sotto Stores → Attributes → Product, ogni attributo ha un flag "Use in Search" e un peso di ricerca. Di default name, sku, description e short_description sono ricercabili, quindi l'autocompletamento li cerca già. Per includere o escludere un campo, o per far pesare di più uno di essi, modifica le impostazioni di ricerca di quell'attributo e riesegui l'indicizzazione — l'autocompletamento segue la stessa configurazione della pagina dei risultati, e resta veloce indipendentemente dalle dimensioni del catalogo.

Search Synonyms nativi

Il modulo usa sempre i Search Synonyms nativi di Magento. Aggiungili o modificali dall'admin standard in Marketing → SEO & Search → Search Synonyms; l'autocompletamento li recepisce immediatamente. Quando una query non restituisce nulla, il modulo la espande con i sinonimi corrispondenti e riprova.

Sinonimi di AI Personal Shopper

Se è installato anche il modulo Codingrow AI Personal Shopper (opzionale, dipendenza soft), l'autocompletamento attinge inoltre al suo registro di sinonimi auto-apprendenti — i termini regionali, dialettali e con errori di battitura che l'assistente ha appreso da conversazioni reali. Questo fa sì che anche le ricerche "sbagliate" trovino i prodotti giusti. Attivalo con Use AI Personal Shopper synonyms = Yes. Senza quel modulo, l'autocompletamento funziona perfettamente con i soli sinonimi nativi.

Utilizzo

Come appare

Il menu a tendina viene iniettato sotto la tua barra di ricerca esistente e stilizzato per non intralciare il tuo tema. Ogni riga mostra la miniatura del prodotto (se abilitata), il nome e il prezzo con eventuale sconto; il colore d'accento (prezzi e link "vedi tutti i risultati") è configurabile. La navigazione da tastiera (frecce e Invio) e il layout mobile sono gestiti automaticamente.

Barra di ricerca fissa

Trasforma la ricerca del negozio in un header compatto sempre visibile: quando il cliente scorre la pagina, una barra sottile si fissa in alto con il logo del negozio, il menu, i link ad account e carrello e — soprattutto — il campo di ricerca con lo stesso autocomplete in tempo reale. La ricerca resta a portata di sguardo su ogni pagina, come fanno i grandi marketplace. Indipendente dal tema: funziona su Hyva e Luma e riusa l'azione di ricerca nativa, quindi invio e autocomplete si comportano esattamente come la ricerca normale.

Su desktop la barra e' una sola riga. Su mobile non supera mai due righe — menu hamburger, logo, account e carrello sulla prima riga, il campo di ricerca sulla seconda — cosi' entra negli schermi piccoli senza spingere giu' il contenuto. Compare quando il cliente supera una soglia di scorrimento configurabile e si nasconde di nuovo in cima alla pagina.

Si attiva in Stores → Configuration → Codingrow → Live Search & Autocomplete → Appearance con Sticky search bar = Yes (con una soglia di scorrimento opzionale in pixel). La barra espone anche uno slot per il bottone di ricerca AI del modulo AI Personal Shopper, se installato.

La barra sticky e ciò che non deve coprire

Con la barra di ricerca sticky attiva, superata la soglia di scroll compare in cima allo schermo una barra compatta. Essendo fissa, copre quello che le finisce sotto: nella scheda prodotto è di solito il titolo, prima riga del riquadro d'acquisto che il tema tiene in vista. E ci resterebbe per tutta la pagina, non di passaggio.

Keep pinned content clear of the sticky bar (attiva di default) risolve: la barra pubblica la propria altezza misurata nella proprietà CSS --crls-sticky-h sull'elemento <html> — 0px quando è nascosta — e tutto ciò che è ancorato in alto scende esattamente di quel tanto, per poi tornare al suo posto quando la barra sparisce. Anche i link con àncora atterrano sotto la barra. L'altezza è misurata, mai cablata: circa 57px su desktop, circa 107px sotto i 768px, dove il campo di ricerca va a capo su una riga propria.

Gli elementi ancorati dentro un contenitore che scorre davvero non vengono toccati: si ancorano a quel contenitore, non al viewport. Anche i tuoi template possono leggere la stessa proprietà: top: calc(1.5rem + var(--crls-sticky-h, 0px)), il cui fallback mantiene l'offset originale dove il modulo non è installato.

Licenza

Il modulo usa una licenza per dominio (una chiave del singolo modulo, o una chiave di abbonamento Codingrow che sblocca ogni modulo Codingrow). La chiave è verificata localmente: non rallenta mai lo storefront e non espone mai i tuoi dati. L'autocompletamento non viene mostrato senza una licenza valida. La licenza copre la versione attuale più 1 anno di update e supporto; puoi continuare a usare per sempre le versioni coperte e rinnovare il supporto (−35%) per aggiornare a versioni successive.

Risoluzione dei problemi