Banner di Categoria: guida completa
Installare, configurare e gestire i banner di categoria: posizione e dimensione nella griglia, immagine mobile, link per lingua, pianificazione per date all'ora del negozio, sottocategorie, visual per lingua, Creative Elements, multinegozio e risoluzione dei problemi per PrestaShop 1.7, 8 e 9.
Panoramica e requisiti
Banner di Categoria inserisce visual nella griglia prodotti delle tue pagine di categoria, nella posizione che scegli. Indichi la categoria, il numero di prodotto dopo il quale deve comparire il banner e l’immagine da usare per ogni lingua. Al resto pensa il modulo, anche dopo un filtro a faccette o un cambio pagina.
- Compatibile con PrestaShop da 1.7.6 a 9.x, verificato su 1.7.8, 8.2.1 e 9.1.5: temi Classic e Hummingbird, temi derivati, elenchi Creative Elements, temi a griglia CSS.
- PHP da 7.4 a 8.5.
- Multinegozio e multilingua (fr, en, es, de, it, nl, pl, pt).
- Nessun override, nessuna modifica ai template, nessun cron.
- Il markup del banner è generato lato server da un template Smarty; il JavaScript si limita a inserirlo nel punto giusto, senza jQuery né librerie di terze parti.
Le immagini caricate sono archiviate in /img/datafireflycategorybanner/, fuori dalla cartella del modulo. Sopravvivono quindi agli aggiornamenti del modulo.

Installazione
- Scarica l’archivio
datafireflycategorybanner.zipdal tuo account cliente. - Nel back office apri Moduli > Gestore moduli.
- Clicca su Carica un modulo e trascina l’archivio.
- Clicca su Configura per raggiungere l’elenco dei banner.
All’installazione il modulo crea le sue tre tabelle (banner, traduzioni, associazione negozi), crea la cartella /img/datafireflycategorybanner/ e registra i suoi hook.

Creare un banner
Dalla pagina di configurazione clicca su Aggiungi un nuovo banner. Il modulo di modifica raccoglie le impostazioni seguenti.
Targeting
- Categoria: la categoria in cui compare il banner. L’elenco riprende l’albero del negozio, con le categorie disattivate segnalate.
- Applica alle sottocategorie: estende il banner a tutte le sottocategorie della categoria scelta, a qualsiasi profondità.
- Dopo il prodotto numero: il banner viene inserito dopo questo prodotto dell’elenco. Il valore 4 colloca il banner dopo il quarto prodotto mostrato.
- Solo nella prima pagina: mostra il banner solo nella prima pagina dell’elenco, senza ripeterlo a pagina 2, 3 e così via.

Aspetto e link
- Link del banner: URL di destinazione, assoluto (
https://…) o che inizia con una barra (/novita). Lascia vuoto per un banner non cliccabile. - Larghezza nella griglia: numero di colonne prodotto occupate dal banner, da 1 a 4, oppure Riga intera. Sugli schermi che mostrano meno colonne la larghezza viene ridotta automaticamente.
- Altezza nella griglia: numero di righe prodotto occupate dal banner, da 1 a 3. Disponibile sugli elenchi a griglia CSS (Creative Elements, la maggior parte dei temi recenti).
- Visualizzazione dell’immagine: Riempire l’area del banner ritaglia l’immagine alla dimensione della cella, Mantenere le proporzioni dell’immagine la mostra per intero.
- Classe CSS: classi aggiuntive applicate alla cella del banner. Lascia vuoto per riprendere le classi delle celle prodotto del tuo tema. Con larghezza e altezza pari a 1, una classe di dimensione del tuo tema (ad esempio una che imposta
grid-area) resta applicata. - CSS personalizzato: dichiarazioni applicate solo a questo banner, ad esempio
border-radius: 12px; padding: 10px;.
Pianificazione e stato
- Data di inizio e Data di fine: finestra di visualizzazione, nel formato
AAAA-MM-GG HH:MM:SS. Un campo vuoto significa nessun limite da quel lato. - Attivo: mostra o sospende il banner senza eliminarlo.
- Associazione ai negozi: in multinegozio, spunta i negozi interessati.
Immagini per lingua
I campi Immagine del banner, Immagine mobile, Testo alternativo e Link per questa lingua esistono per ogni lingua attiva. Il selettore di lingua posto subito sopra questi campi mostra quelli della lingua scelta. Quando un’immagine è già presente compare un’anteprima, accompagnata da un interruttore Elimina l’immagine che riguarda solo quella lingua.
Formati accettati: JPG, PNG, GIF, WebP e SVG, fino a 4 MB. Una larghezza di 1200 px va bene per la maggior parte delle griglie.

Come viene calcolata la posizione
La posizione si esprime in numero di prodotti e vale per ogni pagina dell’elenco. Un banner impostato su 4 compare dopo il quarto prodotto della pagina corrente, sia che il visitatore si trovi a pagina 1 sia a pagina 3.
Più banner possono puntare alla stessa categoria, ciascuno alla sua posizione. Quando due banner condividono la stessa posizione vengono inseriti uno dopo l’altro, nell’ordine di salvataggio. Se la posizione supera il numero di prodotti mostrati nella pagina, il banner viene semplicemente saltato per quella pagina, senza spostare gli altri.
Per impostazione predefinita il banner occupa il posto di una cella prodotto. I campi Larghezza nella griglia e Altezza nella griglia lo ingrandiscono, come spiegato qui sotto.

Dimensione del banner nella griglia
Ogni banner occupa un blocco di celle prodotto: 1 × 1 per impostazione predefinita, fino a 4 colonne per 3 righe, oppure la riga intera. I prodotti che seguono il banner riempiono le celle rimaste libere, quindi la griglia non lascia buchi.
- Elenchi a griglia CSS (Creative Elements, la maggior parte dei temi recenti): si applicano sia la larghezza sia l’altezza. Un banner 2 × 2 posto dopo il 4° prodotto di una griglia a quattro colonne occupa le prime due colonne delle righe 2 e 3, e i prodotti da 5 a 8 si dispongono accanto.
- Righe Bootstrap (tema Classic): si applica la larghezza, come quota della riga. L’altezza segue quella dell’immagine.
- Schermi piccoli: la larghezza è limitata al numero di colonne visualizzate. Un banner a quattro colonne su una griglia mobile a due colonne passa a riga intera.
In modalità riempimento l’immagine copre tutta l’area, prende l’altezza dei prodotti vicini e viene ritagliata a partire dal centro. Un banner a riga intera mantiene sempre le sue proporzioni, perché nessun prodotto accanto gli dà un’altezza: usa un’immagine orizzontale.
Per un banner 2 × 2 in modalità riempimento, prepara un’immagine leggermente più alta che larga e tieni il messaggio principale al centro, perché i bordi possono essere ritagliati.


Pianificare un’operazione
Imposta una data di inizio e una data di fine perché un banner compaia e sparisca da solo. È lo strumento giusto per preparare saldi, Black Friday o un’operazione di fine anno con settimane di anticipo.
- Solo data di inizio: il banner compare in quella data e resta poi visibile.
- Solo data di fine: il banner viene mostrato subito e si ferma a quella data.
- Entrambe le date: il banner è visibile solo in quella finestra.
- Nessuna data: il banner è permanente.
Le date vengono inserite e confrontate con l’ora del negozio, cioè quella del fuso orario impostato in Internazionale > Localizzazione, e non con l’ora del visitatore. Una data di fine inserita senza ora termina alle 23:59:59.

Coprire un intero albero
L’opzione Applica alle sottocategorie evita di ricreare lo stesso banner in ogni reparto. Impostato su una categoria padre, il banner compare in quella categoria e in tutte le sue discendenti.
La risoluzione si appoggia sull’albero annidato nativo di PrestaShop (colonne nleft e nright), quindi senza query aggiuntive per pagina. Se sposti categorie nell’albero, PrestaShop ricalcola quei valori e l’ambito si adegua da solo.
Immagini e lingue
Ogni banner accetta un visual e un testo alternativo per lingua, il che permette di adattare un messaggio o un prezzo al mercato. Se una lingua non ha ricevuto il proprio visual, il modulo mostra quello della lingua predefinita del negozio invece di nascondere il banner. Il testo alternativo specifico della lingua viene mantenuto, se compilato.
Un’immagine mobile facoltativa può completare ogni visual: viene servita agli schermi larghi al massimo 767 px, con le sue dimensioni. Preparala in formato verticale per un banner a riga intera.
Le dimensioni dell’immagine vengono rilevate al caricamento e scritte negli attributi width e height dell’HTML, evitando lo spostamento del layout durante il caricamento. Il banner visibile all’apertura della pagina viene caricato con priorità (fetchpriority="high"), gli altri in differita (loading="lazy"). I file vengono rinominati con un suffisso casuale e archiviati in /img/datafireflycategorybanner/.
Il testo alternativo viene letto dai motori di ricerca e dagli screen reader. Descrivi il contenuto del visual invece di ripetere il nome della categoria.

Multinegozio
Quando la funzione multinegozio è attiva, il modulo di modifica mostra un blocco Associazione ai negozi. Un banner compare solo nei negozi spuntati, e l’elenco del back office mostra soltanto i banner visibili nel contesto negozio corrente.
Se non viene spuntato alcun negozio, il modulo associa il banner al contesto corrente, così da non creare mai un banner orfano.
Filtri a faccette, ordinamento e paginazione
Su PrestaShop 8 e 9 i filtri a faccette, l’ordinamento e la paginazione ricaricano l’elenco prodotti via AJAX senza ricaricare la pagina. Il modulo sorveglia l’elenco: non appena compaiono nuove celle prodotto, dopo un filtro, un cambio pagina, un pulsante «carica altri» o lo scroll infinito, rimette i banner nelle posizioni giuste. Ascolta anche l’evento updateProductList di PrestaShop.
La griglia prodotti viene individuata a partire dai prodotti stessi (marcatori data-id-product e product-miniature), non dalle classi di un tema preciso. Questo copre il tema Classic, gli elenchi Creative Elements e la maggior parte dei temi su misura.
CSS e JavaScript vengono caricati solo sulle pagine di categoria, e soltanto quando la categoria corrente ha almeno un banner attivo e mostrabile.
Impostazioni: selettore della griglia prodotti
Sotto l’elenco dei banner, il pannello Impostazioni contiene un solo campo, Selettore della griglia prodotti. Lascialo vuoto: la griglia viene rilevata automaticamente.
Solo se i banner non compaiono mai su un tema dalla struttura insolita, inserisci il selettore CSS dell’elemento che contiene direttamente le celle prodotto, ad esempio #js-product-list .products o .ce-products. Quando non trova la griglia, il modulo scrive un avviso [DataFirefly Category Banner] nella console del browser.
Novità della versione 1.3.0
La versione 1.3.0 corregge diversi difetti emersi durante una verifica completa su PrestaShop 1.7.8, 8.2.1 e 9.1.5, e aggiunge alcune impostazioni.
- Immagine mobile: ogni lingua accetta una seconda immagine, mostrata sugli schermi larghi al massimo 767 px. È utile per un banner a riga intera, poco leggibile in formato orizzontale su uno smartphone.
- Link per lingua: un link facoltativo per ogni lingua sostituisce il link comune, per puntare a una pagina con indirizzo tradotto, ad esempio
/en/content/1-delivery. - Solo nella prima pagina: il banner non viene più ripetuto a pagina 2, 3 e così via dell’elenco. Ricompare non appena il visitatore torna a pagina 1 o applica un filtro.
- Calendario delle date: il calendario del modulo di modifica ora compila il formato corretto. Una data di fine inserita senza ora termina alle 23:59:59.
- Ora del negozio: le date sono confrontate con l’ora del negozio. Prima l’orologio del server MySQL, spesso impostato su UTC, spostava l’inizio e la fine di una o due ore.
- Core Web Vitals: i banner vengono inseriti subito dopo la griglia prodotti (hook
displayFooterCategory), prima della prima visualizzazione, il che elimina lo spostamento del layout (CLS). Il banner visibile all’apertura della pagina viene caricato con priorità, i successivi in differita. - Sicurezza delle immagini: gli SVG che contengono uno script, un gestore di eventi o un contenuto esterno vengono rifiutati, e la cartella
/img/datafireflycategorybanner/riceve un proprio.htaccess(solo immagini, SVG isolati). Un’immagine rifiutata non crea più un banner vuoto. - WebP su PrestaShop 1.7: le immagini WebP vengono accettate e servite correttamente.
- Elenco del back office: colonna Immagini con le lingue che hanno un visual, e indicazione dei banner terminati o programmati.
Per aggiornare, installa l’archivio 1.3.0 sopra la versione presente dal gestore dei moduli. I tuoi banner e le tue immagini vengono conservati. Svuota poi la cache di PrestaShop e quella di qualsiasi modulo di prestazioni.
Aggiornamento alla versione 1.2.0
Installa l’archivio 1.2.0 sopra la versione precedente dal gestore dei moduli. Lo script di aggiornamento aggiunge le colonne di dimensione e di visualizzazione dell’immagine, oltre all’impostazione del selettore della griglia. I banner esistenti mantengono l’aspetto attuale: 1 × 1, proporzioni dell’immagine mantenute. Modifica un banner per dargli un’altra dimensione o passarlo in modalità riempimento.
Lo script del front office cambia in questa versione. Dopo l’aggiornamento svuota la cache di PrestaShop e quella di qualsiasi modulo di prestazioni (CCC, cache delle pagine, minificazione), altrimenti continua a essere servito il vecchio script.
Aggiornare dalla versione 1.0.0
Installa semplicemente il nuovo archivio sopra il vecchio dal gestore moduli. Lo script di aggiornamento si occupa di:
- aggiungere le colonne di ambito, pianificazione e dimensioni dell’immagine;
- creare la tabella di associazione ai negozi e riportarvi il negozio d’origine di ogni banner;
- spostare le immagini esistenti da
views/img/banners/a/img/datafireflycategorybanner/e rilevarne le dimensioni; - rimuovere un hook diventato inutile.
I tuoi banner, le loro posizioni e i loro visual vengono conservati.
FAQ e risoluzione dei problemi
Il banner non compare nella pagina di categoria
Verifica nell’ordine: il banner è attivo; la data odierna rientra nella finestra di pianificazione; la categoria puntata è quella consultata, oppure l’ambito alle sottocategorie è attivo; la lingua mostrata ha un’immagine, o ce l’ha la lingua predefinita; in multinegozio, il negozio corrente è spuntato. Svuota infine la cache di PrestaShop.
Su un elenco costruito con Creative Elements o un altro page builder, verifica che il modulo sia alla versione 1.2.0 o successiva: le versioni precedenti riconoscevano solo la griglia del tema Classic. Apri poi la console del browser: un avviso [DataFirefly Category Banner] indica che la griglia non è stata trovata, vedi la sezione Impostazioni.
Il banner compare nel posto sbagliato
La posizione conta i prodotti della pagina corrente. Se il tuo elenco mostra 12 prodotti per pagina, un banner in posizione 20 non comparirà in nessuna pagina. Riduci il valore o aumenta il numero di prodotti per pagina.
Il banner rompe il layout della griglia
Imposta la dimensione con i campi Larghezza nella griglia e Altezza nella griglia anziché con classi di griglia, e svuota il campo Classe CSS a meno che il tuo tema non fornisca una classe di dimensione. Evita di mescolare classi di sistemi di griglia diversi.
Il banner sparisce dopo un filtro
Dalla versione 1.2.0 il modulo reinserisce i banner non appena compaiono nuove celle prodotto nell’elenco, qualunque sia il modulo di filtri. Se il banner scompare ancora, apri la console del browser: un avviso [DataFirefly Category Banner] indica che la griglia non è stata trovata dopo l’aggiornamento. Inserisci allora il selettore della griglia nel pannello Impostazioni e contatta il supporto se il problema persiste.
L’immagine non viene caricata
Il modulo accetta file JPG, PNG, GIF, WebP e SVG fino a 4 MB. Verifica inoltre che /img/datafireflycategorybanner/ sia scrivibile e che le direttive PHP upload_max_filesize e post_max_size siano superiori al peso del file.
Il link del banner viene rifiutato
Sono accettati solo URL che iniziano con http://, https:// o con una barra. È una protezione contro l’iniezione di indirizzi javascript: o data:.
Cosa succede alla disinstallazione?
Il modulo elimina le sue tabelle e la cartella /img/datafireflycategorybanner/ con i visual che contiene. Salva le tue immagini se prevedi di reinstallarlo in seguito.