Filtri a Faccette AJAX per PrestaShop — Documentazione

Questa guida copre l’installazione, la configurazione e l’esercizio del modulo Filtri a Faccette AJAX per PrestaShop 8 e 9. Il modulo sostituisce la ricerca a faccette nativa con una navigazione AJAX più rapida, uno slider prezzo con istogramma e un controllo fine dell’indicizzazione SEO delle pagine filtrate.

Installazione

Nel tuo back-office, apri Moduli > Gestore moduli, clicca su Carica un modulo e trascina il file dffacetedfilter.zip. All’installazione il modulo esegue automaticamente:

• la creazione delle sue tabelle e della sua scheda di amministrazione;
• una prima sincronizzazione delle faccette dal tuo catalogo;
• il preriscaldamento dell’indice prezzi (entro pochi secondi).

Prima configurazione

Vai su Catalogo > Filtri a faccette. Vi troverai l’elenco delle faccette, una dashboard di sintesi e le impostazioni generali e SEO.

Sincronizzare le faccette

Il pulsante Sincronizza dal catalogo crea automaticamente le faccette mancanti a partire dai tuoi gruppi di attributi, dalle tue caratteristiche e dalle faccette integrate (prezzo, marca, saldi, disponibilità, condizione). Le faccette esistenti non vengono mai modificate: puoi rilanciare la sincronizzazione in tutta sicurezza dopo aver aggiunto un attributo o una caratteristica.

Ricostruire l’indice prezzi

Il pulsante Ricostruisci l’indice prezzi ricalcola i limiti di prezzo di tutti i prodotti, a lotti, con una barra di avanzamento. Avvialo dopo l’installazione e dopo ogni importazione massiva di prodotti.

Gestire le faccette

Ogni riga può essere riordinata tramite trascinamento (l’ordine definisce sia l’ordine di visualizzazione nel front sia l’ordine normalizzato degli URL), attivata o disattivata e modificata.

Opzioni di una faccetta

• Etichetta: il nome visualizzato, traducibile per lingua.
• Visualizzazione: caselle, campioni di colore / texture, o link semplici. I gruppi di colore ereditano automaticamente la visualizzazione a campioni.
• Selezione multipla: consente di selezionare più valori di una stessa faccetta contemporaneamente, combinati con OR.
• Mostra i contatori: mostra il numero di prodotti accanto a ogni valore.
• Nascondi i valori vuoti: nasconde i valori a zero prodotti invece di mostrarli in grigio.
• Ripiegata per impostazione predefinita: la faccetta si mostra chiusa e il visitatore la espande al clic.
• Valori prima di «Mostra altro»: numero di valori visibili prima del pulsante di espansione (0 = mostra tutti).

Lo slider prezzo e il suo indice

La faccetta Prezzo si mostra come un doppio cursore. Sopra, un istogramma di distribuzione dei prodotti su dodici fasce aiuta il visitatore a collocare i prezzi. Questi dati provengono da un indice prezzi dedicato, separato dalle tabelle di PrestaShop, per restare rapido anche su un catalogo di grandi dimensioni.

Manutenzione dell’indice

L’indice è aggiornato in tempo reale dagli hook quando cambia un prodotto, un prezzo specifico o una combinazione. Per una ricostruzione completa pianificata, usa l’endpoint cron mostrato nel back-office:

/module/dffacetedfilter/cron?token=IL_TUO_TOKEN

La chiamata elabora l’indice a blocchi con un limite di tempo di circa 20 secondi; se restano prodotti, la risposta fornisce l’URL di continuazione da richiamare. Una chiamata notturna giornaliera è sufficiente nella maggior parte dei casi.

La faccetta Saldi

La faccetta In saldo filtra i prodotti attualmente scontati: prodotti contrassegnati come «in offerta» o coperti da un prezzo specifico attivo (una riduzione in corso, entro il suo intervallo di date, per la valuta, il paese e il gruppo correnti). Viene creata attivata per impostazione predefinita durante la sincronizzazione.

Disponibilità e condizione

Vengono create due faccette integrate complementari, disattivate, da attivare secondo le esigenze:

• Disponibilità: un valore «Disponibile» che rispetta la tua impostazione di ordine in esaurimento scorte.
• Condizione: nuovo, usato, ricondizionato.

Limitare una faccetta a categorie

Per impostazione predefinita, una faccetta appare su tutte le pagine di listing. Il modulo di modifica offre due campi per cambiarlo: una regola delle categorie e l’albero delle categorie a cui si applica.

• Mostra solo sulle categorie qui sotto: la faccetta appare unicamente sulle categorie spuntate e sulle loro sottocategorie. È l’impostazione giusta per mostrare «Taglia» solo sotto Scarpe, o «Dimensione schermo» solo sotto Tech.
• Mostra ovunque tranne che sulle categorie qui sotto: la faccetta appare su tutto il negozio, tranne che sulle categorie spuntate e sulle loro sottocategorie. È l’impostazione giusta per nascondere «Tipo di vino» su Vini Rossi e Vini Bianchi, dove la faccetta non aggiunge nulla, mantenendola altrove.

La SEO delle faccette

È uno dei punti di forza del modulo: decidi con precisione quali pagine filtrate possono essere indicizzate. Gli URL dei filtri sono leggibili e seguono questo formato:

/categoria?dff=colore:rosso,blu-scuro/prezzo:10,50/marca:nike

Il parametro si chiama q invece di dff in modalità Creative Elements completa; il formato in sé resta identico. Le faccette sono separate da una barra, lo slug della faccetta e i suoi valori dai due punti, e i valori tra loro da una virgola. L’ordine delle faccette e l’ordinamento dei valori sono normalizzati affinché una stessa combinazione produca sempre un unico URL canonico.

Impostazioni SEO

• Indicizzabile (per faccetta): una faccetta non indicizzabile forza la pagina filtrata a noindex, follow e aggiunge rel="nofollow" sui suoi link.
• N. max di valori indicizzabili: oltre questo numero di valori selezionati, la pagina passa a noindex, follow. Il valore 1 è il più sicuro contro l’esplosione del budget di scansione.
• Canonical proprio sulle pagine indicizzabili: le pagine indicizzabili ricevono un tag canonical che punta al proprio URL di filtro normalizzato. Il canonical del tema viene rimosso lato front per evitare duplicati.
• Tutto a noindex: forza noindex, follow su tutte le pagine filtrate, quali che siano le impostazioni per faccetta.

Modalità AJAX

L’impostazione Modalità AJAX determina come la pagina si aggiorna al clic su un filtro:

• Tema (eventi nativi) — consigliata: il modulo emette l’evento nativo di PrestaShop e lascia che il core e il tema aggiornino la lista, le faccette e la cronologia del browser. È la modalità più compatibile con i temi basati su classic.
• Autogestita: per i temi non standard, il modulo recupera la pagina via AJAX da solo e sostituisce i blocchi interessati. Usala solo se la modalità Tema non aggiorna correttamente la pagina.

Tenere i bot lontani dai filtri

Un tag noindex impedisce l’indicizzazione, non il caricamento: il bot deve prima scaricare la pagina per leggere il tag. Perché smetta di caricare le combinazioni di filtri, non deve scoprirle. Due impostazioni se ne occupano, in Catalogo > Filtri a faccette.

• Link dei filtri scansionabili: Solo faccette indicizzabili mantiene un link reale sulle faccette che hai dichiarato indicizzabili e trasforma le altre in link gestiti da JavaScript. I tuoi clienti cliccano esattamente come prima, ma i bot non trovano più quelle combinazioni nella pagina.
• Vecchi URL dei filtri nativi (?q=): gli URL lasciati dalla ricerca a faccette nativa di PrestaShop, del tipo ?q=Marca-..., possono ricevere una risposta 410 Gone prima ancora che parta una query sul catalogo, oppure un redirect 301 verso il listing non filtrato. La 410 è la risposta meno costosa per il server e quella che fa abbandonare l’URL ai motori. Questa impostazione non si applica né in modalità Creative Elements completa, dove q è il parametro del modulo, né alla pagina di ricerca.

Pannello dei filtri mobile e filtri attivi

Sotto una certa larghezza di schermo, la barra dei filtri viene nascosta e si apre come pannello da un pulsante «Filtri». L’impostazione Pannello dei filtri sotto (px) fissa questa soglia: 767 corrisponde agli smartphone, 1024 va bene quando il tuo layout sposta la colonna dei filtri anche su tablet. Il pannello si chiude con il suo pulsante «Mostra i risultati», con un clic all’esterno o con il tasto Esc.

L’impostazione Etichetta dei filtri attivi sceglie cosa mostra ogni filtro attivo: faccetta e valore («Colore: Rosso») oppure solo il valore («Rosso»). Gli screen reader ricevono sempre entrambi.

Compatibilità con Creative Elements

Creative Elements (WebshopWorks) non legge il blocco di faccette renderizzato da un modulo. I suoi widget Filtri e Filtri attivi, e il suo pulsante Filtri mobile, ricostruiscono il proprio markup a partire dalla collezione di faccette nativa portata dal risultato di ricerca. Dalla versione 1.3 il modulo pubblica questa collezione: tutti e tre i widget funzionano e conservano tutti i loro controlli di design, campioni di colore e slider prezzo compresi.

Le due impostazioni

In Catalogo > Filtri a faccette > Compatibilità con Creative Elements:

• Modalità di compatibilità: Completa, quando Creative Elements è installato, Completa, sempre, Parziale o Disattivata. La modalità completa usa i widget dei filtri di Creative Elements e URL in ?q=; la modalità parziale mantiene gli URL in ?dff= e usa i blocchi del modulo (vedi sotto).
• Blocco filtri renderizzato da: Automatico affida la barra laterale a Creative Elements sui listing di cui controlla il template, e mantiene il blocco del modulo altrove. Scegli Questo modulo se il tuo template di listing Creative Elements non contiene un widget Filtri e preferisci la barra laterale di DataFirefly.

In modalità completa, il parametro URL diventa q

Creative Elements codifica il parametro q in modo fisso, sia nei suoi widget sia nello script del suo slider prezzo. In modalità completa il modulo si allinea quindi su q invece di dff:

/categoria?q=colore:rosso,blu-scuro/prezzo:10,50/marca:nike

Il formato in sé non cambia, solo il nome del parametro. Gli URL già generati con dff vengono reindirizzati con un 301 al loro equivalente in q: nulla di indicizzato o salvato nei preferiti va perso.

Modalità parziale: mantenere gli URL in dff

In modalità parziale il modulo non pubblica le sue faccette per i widget dei filtri di Creative Elements, che restano vuoti, e gli URL mantengono il parametro ?dff=. Al loro posto collochi i blocchi del modulo nel tuo template di listing con il widget Modulo di Creative Elements: seleziona il modulo e inserisci uno di questi nomi di hook.

• displayDffFacets: la barra dei filtri (è anche ciò che appare se il campo hook resta vuoto);
• displayDffActiveFilters: i filtri attivi e il link «Cancella tutto»;
• displayDffFiltersButton: un pulsante «Filtri» che apre il pannello mobile.

Per mantenere il controllo sul design del pulsante puoi anche usare un widget Pulsante di Creative Elements e aggiungergli la classe CSS dff-open-filters nella sua scheda Avanzate: aprirà allora lo stesso pannello. I widget di Creative Elements per elenco prodotti, paginazione, ordinamento e contatore continuano a funzionare normalmente. In cambio, l’aspetto dei filtri si regola con il colore accento del modulo e il tuo CSS, non con la scheda Stile di Creative Elements.

Da sapere

• Mantieni la modalità AJAX «Tema». Creative Elements si appoggia all’evento nativo di PrestaShop e restituisce i propri blocchi renderizzati; la modalità autogestita non saprebbe sostituirli.
• A partire da Creative Elements 3.x, i link delle faccette non sono più veri link ma elementi governati da JavaScript. È una buona notizia per il tuo budget di scansione: le combinazioni di filtri non sono più individuabili da un bot. In cambio, il filtraggio diventa strettamente dipendente da JavaScript nella sua interfaccia.
• Evita il carattere / nell’etichetta della tua faccetta Prezzo: lo slider di Creative Elements costruisce il proprio URL nel browser a partire da quell’etichetta.

Cache dei contatori

Il calcolo dei contatori disgiuntivi può essere costoso su un catalogo di grandi dimensioni. Il modulo memorizza il loro risultato in cache per un breve tempo configurabile (300 secondi per impostazione predefinita). Questa cache viene invalidata automaticamente a ogni modifica del catalogo e a ogni modifica di una faccetta. Nel back-office è disponibile un pulsante Svuota la cache dei contatori.

Statistiche d’uso

La dashboard, in cima alla pagina di amministrazione, riassume gli ultimi 30 giorni: prodotti indicizzati, numero di visualizzazioni di pagine filtrate, quota di budget di scansione tenuta fuori dall’indice (pagine filtrate servite come noindex) e una classifica delle faccette più usate. Il traffico dei bot è escluso da queste cifre, che descrivono quindi il comportamento dei tuoi clienti. Puoi disattivare la registrazione delle statistiche nelle impostazioni di prestazioni.

Pagine supportate

Le faccette si applicano alle pagine di categoria, marca, fornitore, novità, più venduti, offerte e risultati di ricerca (rispettando il ranking nativo di PrestaShop). La faccetta Marca viene nascosta automaticamente su una pagina di marca, e le faccette limitate per categoria su una pagina di ricerca.

Disattivare la ricerca a faccette nativa

Il modulo ha la priorità su ps_facetedsearch, ma consigliamo di disattivare quest’ultimo per evitare un doppio lavoro di indicizzazione. Un avviso nel back-office te lo ricorda se resta attivo.

Risoluzione dei problemi

• Le faccette non appaiono: avvia una sincronizzazione, verifica che almeno una faccetta sia attiva e che tu sia su una pagina di listing supportata.
• Manca lo slider prezzo: ricostruisci l’indice prezzi; la faccetta Prezzo si nasconde finché l’indice è vuoto per la categoria visualizzata.
• La pagina non si aggiorna via AJAX: imposta la modalità AJAX su «Autogestita» se il tuo tema non segue lo standard di PrestaShop.
• Dopo un clic le caselle non si spuntano e un secondo filtro sostituisce il primo: corretto nella 1.4.3. Il blocco delle faccette non veniva aggiornato dopo il filtraggio AJAX. Nella console del browser, dffFaceted.listening() deve restituire true.
• Su mobile i filtri compaiono sotto l’elenco dei prodotti: corretto nella 1.4.1 per i temi Bootstrap 5 come Hummingbird. Controlla anche l’impostazione della soglia del pannello.
• L’ordine delle faccette non viene salvato: corretto nella 1.3.1. Prima di quella versione, PrestaShop inviava i dati del trascinamento sotto una chiave che il modulo non leggeva; la notifica annunciava un successo ma non veniva scritto nulla.
• Una faccetta appare su una categoria che ho deselezionato: deselezionare non nasconde. Spunta quella categoria e scegli la regola «Mostra ovunque tranne che sulle categorie qui sotto».
• I widget di Creative Elements restano vuoti: in modalità completa, verifica che la modalità di compatibilità sia su una delle opzioni «Completa» e che il modulo sia in modalità AJAX «Tema». In modalità parziale è normale: quei widget sono sostituiti dai blocchi del modulo posizionati con il widget Modulo.
• La barra dei filtri appare due volte: il tuo template di Creative Elements contiene un widget Filtri e il modulo renderizza anche il proprio. Imposta Blocco filtri renderizzato da su Automatico o Widget di Creative Elements.
• Troppe pagine indicizzate: abbassa il n. max di valori indicizzabili, rendi non indicizzabili le faccette ad alta cardinalità (colore, taglia), oppure attiva «Tutto a noindex» mentre riprendi il controllo.

Il codice sorgente è fornito non cifrato. Hai 12 mesi di aggiornamenti di compatibilità e supporto entro 24 ore.

Novità della versione 1.4

Modalità Creative Elements parziale

Gli URL mantengono ?dff=, e filtri, filtri attivi e pulsante mobile del modulo si posizionano nel layout con il widget Modulo di Creative Elements. Vedi la sezione Compatibilità con Creative Elements.

Controllo della scansione

I link delle faccette possono essere riservati alle faccette indicizzabili, e i vecchi URL ?q= della ricerca nativa possono ricevere una 410 prima di qualsiasi query sul catalogo. Vedi la sezione Tenere i bot lontani dai filtri.

Pannello mobile e filtri attivi

Il pannello dei filtri mobile non dipende più dalle classi di utilità del tema, assenti nei temi Bootstrap 5 come Hummingbird, e segue una soglia di larghezza configurabile. I filtri attivi possono mostrare solo il valore.

Aggiornamento AJAX

Il modulo aggiorna da sé faccette e filtri attivi dopo ogni filtraggio, senza dipendere dai selettori del tema. Sono corretti due difetti che impedivano questo aggiornamento: l’iscrizione agli eventi di PrestaShop avveniva troppo presto per andare a buon fine (1.4.3), e il passaggio automatico alla modalità autogestita dopo 900 ms lasciava i widget del page builder sullo stato precedente (1.4.1).

Novità della versione 1.3.1

Due correzioni segnalate in produzione.

L’ordine delle faccette viene salvato. PrestaShop invia i dati del trascinamento sotto l’identificatore privato del prefisso id_, cioè facet, e non sotto il nome della tabella. Il modulo leggeva la chiave sbagliata e non scriveva nulla, mentre il browser continuava a mostrare una conferma. L’ordine viene ora ricostruito integralmente dalla lista ricevuta, il che rende la scrittura idempotente, e la chiamata restituisce uno stato reale.

Regola delle categorie «tranne». La restrizione per categorie era solo una whitelist: si poteva limitare una faccetta a certe categorie, mai escluderla da esse. Vedi la sezione Limitare una faccetta a categorie più sopra.

Novità della versione 1.3

Compatibilità con Creative Elements

Il modulo pubblica ora le sue faccette come collezione nativa, la struttura che il page builder si aspetta. I suoi widget Filtri, Filtri attivi e Cancella, e il suo pulsante Filtri mobile, funzionano con il modulo e conservano tutti i loro controlli di design. Vedi la sezione Compatibilità con Creative Elements più sopra, in particolare il cambio di nome del parametro URL.

Prestazioni sotto il traffico dei bot

La navigazione a faccette crolla sotto il traffico automatizzato perché ogni combinazione distinta è un mancato accesso alla cache. Questa versione elimina il lavoro per richiesta che non dipende dalla selezione:

• Mappe dei valori raccolte insieme: i valori possibili di ogni faccetta dipendono dal catalogo, non dalla selezione. Vengono caricati da un’unica voce di cache invece che con una query e diversi accessi a disco per faccetta su ogni pagina.
• Cache dei contatori protetta: oltre tre faccette o sei valori, una combinazione viene calcolata ma non più memorizzata. Sono quelle che generano i bot, non vengono mai rilette e memorizzarle gonfiava solo la tabella. Entrambe le soglie sono configurabili.
• Visibilità del catalogo: la sottoquery di controllo dei gruppi clienti, prima ripetuta dentro ogni query di conteggio, viene rimossa sulle pagine di categoria quando nessuna categoria attiva è ristretta per i gruppi del visitatore.
• Landing page senza query: l’insieme delle destinazioni attive è mantenuto come indice compatto, quindi la risposta negativa, di gran lunga la più frequente, non costa nulla.
• Statistiche: nessuna scrittura per i bot.

Novità della versione 1.2

Landing page SEO

In Catalogo > Filtri a faccette > Landing page SEO, trasforma una combinazione di filtri precisa (ad esempio Scarpe × Colore: rosso × Marca: Nike) in una vera pagina di atterraggio: meta title, meta description, H1 e introduzione editoriale, per lingua. Per puntare a una combinazione, copia il valore del parametro dff (o q in modalità Creative Elements completa) da un URL filtrato del tuo negozio e incollalo nel modulo.

Tutte le landing attive sono elencate in una sitemap XML dedicata, con alternates hreflang, pronta da inviare in Search Console:

/module/dffacetedfilter/sitemap

Altre novità

• Faccetta Sottocategorie: propone le sottocategorie dirette della categoria visualizzata; il listing include allora automaticamente l’intero sottoalbero.
• Ordinamento dei valori per faccetta: posizione a catalogo, alfabetico o numero di prodotti decrescente.
• Campioni colore a griglia o in lista: ogni faccetta colore può mostrarsi come griglia orizzontale di campioni o come lista verticale con etichette e contatori.
• Nascondere le faccette con un solo valore: una faccetta il cui unico valore copre l’intero listing non aggiunge potere di filtro; questa impostazione la rimuove automaticamente.
• Colore accento: scegli con il selettore il colore di caselle spuntate, interruttori, slider e badge; il contrasto del testo è calcolato automaticamente.
• AJAX resiliente: se il tema non risponde all’evento nativo, il modulo passa automaticamente alla modalità autogestita; la posizione di scroll è preservata dopo ogni filtro e i filtri mobili si aprono in un modal a schermo intero.
• 8 lingue nel front: IT, EN, FR, ES, DE, PL, PT, NL incluse nel modulo.