Brand Carousel: documentazione del carosello marchi PrestaShop

Installazione

Nel back office apri Moduli > Gestione moduli, clicca su «Carica un modulo» e invia il file dfbrandcarousel-2.0.0.zip. Il modulo è compatibile con PrestaShop da 8.0 a 9.x.

All’installazione il modulo crea le sue due tabelle, l’hook displayDfBrandCarousel, la cartella /img/dfbrandcarousel/ per i loghi alternativi e un primo blocco: un carosello di marchi in homepage (displayHome) con il titolo «I nostri marchi» tradotto in ogni lingua installata. Apri il negozio per vedere il risultato, poi modifica o elimina quel blocco.

Il modulo si gestisce dal pulsante «Configura» in Gestione moduli.

Aggiornamento dalla versione 1.0.x

Carica lo ZIP 2.0.0 sopra la versione installata. Lo script di aggiornamento crea le nuove tabelle e trasferisce la tua configurazione in un blocco chiamato «Brand carousel», sullo stesso hook: titolo, numero di marchi, colonne, scorrimento automatico, velocità, spaziatura, frecce, punti, marchi selezionati e ordine casuale. I marchi senza prodotti restano visibili come prima. Le vecchie impostazioni DFBC_* vengono poi eliminate. Swiper non è più usato, il che risolve i conflitti con temi e page builder che caricano la propria versione.

L’elenco dei blocchi

La scheda Blocchi elenca i tuoi blocchi con modalità, hook e origine. Per ogni blocco puoi:

• attivarlo o disattivarlo con l’interruttore;
• modificarlo nell’editor;
• duplicarlo (la copia viene creata disattivata);
• eliminarlo;
• trascinare i blocchi per stabilirne l’ordine quando più blocchi condividono lo stesso hook.

Il pulsante «Svuota la cache» cancella la cache di marchi, contatori e vendite (vedi Cache e prestazioni).

L’editor del blocco

L’editor mostra le impostazioni a sinistra, divise in 5 schede, e un’anteprima a destra. L’anteprima si aggiorna a ogni modifica e può essere mostrata in larghezza desktop, tablet o mobile. Usa un font neutro: nel negozio il blocco usa i font del tuo tema.

La barra in alto contiene il nome interno del blocco, l’interruttore di attivazione, il selettore di lingua dei campi traducibili e il pulsante Salva. Un indicatore segnala le modifiche non salvate e Ctrl+S (Cmd+S su Mac) salva senza uscire dall’editor.

Scheda Contenuto

Intestazione

• Titolo e sottotitolo: per lingua. Lascia vuoto il titolo per nasconderlo.
• Tag del titolo: H2 in homepage, H3 in una pagina che ha già titoli H2, oppure p e div per un titolo senza ruolo di intestazione.
• Disposizione dell’intestazione: titolo a sinistra e link a destra, tutto a sinistra o centrato. Negli ultimi due casi il link passa sotto i loghi.
• Link a tutti i marchi: testo per lingua e URL. Senza URL, il link porta alla pagina marchi di PrestaShop.

Marchi da mostrare

• Tutti i marchi attivi del negozio.
• Selezione manuale: aggiungi i marchi dall’elenco di sinistra con il pulsante + e riordinali per trascinamento nell’elenco di destra. «Aggiungi tutto l’elenco» aggiunge i marchi della ricerca in corso.
• Marchi di una categoria: marchi con almeno un prodotto visibile nella categoria scelta o nelle sue sottocategorie.
• Marchi della categoria corrente: in una pagina categoria, i marchi di quella categoria. In una scheda prodotto, quelli della sua categoria principale. Altrove, tutti i marchi.

Queste impostazioni completano l’origine:

• Marchi esclusi: tolti dall’elenco, tranne con la selezione manuale.
• Ordinamento: il tuo ordine (selezione manuale), alfabetico, prima i più forniti, prima i più venduti su un periodo da 7 a 730 giorni, prima i marchi più recenti o casuale a ogni visita. L’ordine alfabetico ignora accenti e punteggiatura: L’Oréal viene ordinato come «loreal».
• Numero massimo di marchi: 0 mostra tutti i marchi corrispondenti.
• Prodotti minimi: 1 per impostazione predefinita, per non mandare il visitatore su una pagina marchio vuota.
• Solo marchi con logo: il filtro si applica prima del numero massimo, quindi ottieni il numero richiesto.

L’ordine casuale viene calcolato nel browser. Una cache di pagina completa può servire la stessa pagina a tutti i visitatori e l’ordine cambia comunque a ogni visita. Nelle modalità a scorrimento continuo, il numero massimo si applica prima in ordine alfabetico, poi i marchi selezionati vengono mescolati.

Scheda Layout

Le 8 modalità di visualizzazione

• Carosello: loghi che avanzano per pagina o per logo, su 1-3 righe, con frecce, punti e scorrimento automatico.
• Scorrimento continuo: loghi che scorrono senza sosta su 1-4 righe.
• Scorrimento verticale: da 1 a 4 colonne che si muovono verso l’alto o verso il basso.
• Griglia: schede in colonne, con ricerca, filtro per lettera e pulsante «Mostra altri» opzionali.
• Muro di loghi: griglia senza schede, loghi separati da linee sottili.
• Muro rotante: griglia fissa i cui loghi cambiano uno alla volta.
• Pillole: nomi dei marchi in pillole compatte, con piccolo logo opzionale. Adatte a una colonna laterale.
• Elenco A-Z: tutti i marchi raggruppati per lettera, con una barra di lettere cliccabili e una ricerca.

Colonne

Il numero di colonne si imposta separatamente per desktop (da 1 a 12), tablet (da 1 a 8) e mobile (da 1 a 4). Queste soglie dipendono dalla larghezza disponibile per il blocco e non da quella dello schermo: un blocco in una colonna laterale usa l’impostazione mobile anche su uno schermo grande.

• Righe (carosello e muro rotante): da 1 a 3. Nel carosello i loghi riempiono ogni colonna dall’alto in basso, poi le righe scorrono insieme.
• Mostra parte del logo successivo (carosello): su tablet e mobile il logo successivo sporge per indicare che l’elenco si può scorrere. Le frecce laterali vengono allora nascoste su mobile.
• Righe prima di Mostra altri (griglia e muro di loghi): 0 mostra tutto subito.

Scorrimento continuo e verticale

• Righe (o colonne in verticale): da 1 a 4, mai più del numero di marchi.
• Marchi diversi su ogni riga: i marchi vengono distribuiti tra le righe. Se disattivato, ogni riga mostra tutti i marchi sfalsati. La distribuzione richiede almeno 3 marchi per riga, altrimenti il modulo sfalsa le righe.
• Larghezza dei loghi (orizzontale) o Altezza del blocco (verticale).

Ricerca e filtri

Il campo di ricerca (griglia, muro di loghi, elenco) filtra i marchi durante la digitazione, senza tenere conto di accenti e punteggiatura. Il filtro per lettera (griglia e muro di loghi) mostra una barra 0-9, A-Z e # per i nomi che non iniziano né con una lettera né con una cifra. Le lettere senza marchi sono in grigio. L’elenco accetta da 1 a 6 colonne e piccoli loghi accanto ai nomi.

Spaziatura e larghezza

• Spazio tra i loghi e margine verticale della sezione.
• Larghezza: larghezza della posizione, sfondo a larghezza piena (lo sfondo copre lo schermo, il contenuto resta nella colonna del tema) o larghezza piena da bordo a bordo (utile per uno scorrimento continuo che attraversa tutto lo schermo).

Scheda Stile

Schede dei marchi

• Stile delle schede: pieno, contorno, ombra o essenziale.
• Altezza massima del logo, altezza minima delle schede, margine interno e arrotondamento degli angoli.
• Nome del marchio: solo senza logo, sempre sotto il logo o al passaggio del mouse.
• Descrizione breve: i primi 160 caratteri della descrizione breve del marchio.

Loghi

• Numero di prodotti sotto il logo o nella pillola.
• Effetto sul logo: nessuno, grigio e colore al passaggio del mouse, sempre grigio, sbiadito e pieno al passaggio.
• Effetto al passaggio sulle schede: sollevamento, zoom del logo, contorno colore d’accento o nessuno.
• Rimuovi gli sfondi bianchi: fonde il bianco dei loghi JPG nelle schede chiare. Lasciala disattivata su sfondi scuri e usa loghi trasparenti.
• Dimensione immagine: si consiglia l’immagine originale. Le dimensioni di PrestaShop aggiungono spesso margini bianchi attorno ai loghi.

Colori

Sono regolabili sei colori: accento (frecce, link, lettera attiva), sfondo delle schede, bordi, sfondo della sezione, titolo e testo. «Reimposta» restituisce il controllo al tema. Il testo sul colore d’accento diventa automaticamente bianco o nero in base al contrasto.

Scheda Animazione

Carosello

• Scorrimento automatico e pausa tra le pagine (da 1 a 15 secondi).
• Durata della transizione e passo: una pagina intera o un logo.
• Torna all’inizio alla fine: dopo l’ultimo logo il carosello riparte dal primo. Per uno scorrimento senza fine usa la modalità Scorrimento continuo.
• Frecce: 4 stili (pieno, contorno, quadrato, minimale) e 4 posizioni (sui bordi sporgenti, all’interno dei bordi, nell’intestazione, sotto i loghi).
• Punti di paginazione.

Il carosello si usa anche da tastiera (frecce sinistra e destra), con il dito e trascinando con il mouse.

Scorrimento continuo e verticale

• Direzione: verso sinistra o destra, verso l’alto o il basso.
• Alterna le righe: una riga su due scorre nel verso opposto.
• Velocità: da 5 a 400 pixel al secondo, uguale qualunque sia la lunghezza della riga.
• Al passaggio del mouse: rallenta, ferma o continua. Il rallentamento è graduale.
• Sfuma i bordi: i loghi compaiono e scompaiono in dissolvenza.

Muro rotante

Imposta il numero di righe e l’intervallo tra i cambi (da 0,8 a 20 secondi). A ogni cambio un logo della griglia viene sostituito da un marchio non ancora visibile.

Accessibilità

Il pulsante pausa, raccomandato dal criterio WCAG 2.2.2 per i contenuti che si muovono per più di 5 secondi, compare nell’intestazione o sotto i loghi. Le animazioni si fermano anche al passaggio del mouse, al focus da tastiera, quando la scheda del browser è nascosta e quando il blocco esce dallo schermo. Per i visitatori che hanno ridotto le animazioni nel sistema, lo scorrimento continuo diventa una riga ferma da scorrere a mano e il carosello non si muove più da solo.

Scheda Visualizzazione

Posizione

Il campo Hook propone 14 posizioni raggruppate:

• Homepage: displayHome.
• Tutte le pagine: displayWrapperTop, displayWrapperBottom, displayContentWrapperTop, displayContentWrapperBottom, displayNavFullWidth, displayFooterBefore, displayFooterAfter.
• Colonne: displayLeftColumn, displayRightColumn.
• Pagine specifiche: displayFooterProduct, displayFooterCategory, displayShoppingCartFooter.
• Integrazione: displayDfBrandCarousel, oppure «Nessuno» per un blocco mostrato solo tramite widget o shortcode.

«Altro hook» accetta qualsiasi nome che inizi con display (lettere, cifre e trattini bassi). Il modulo vi si aggancia al salvataggio. Il tuo tema deve poi richiamare quell’hook.

Pagine e dispositivi

Pagine limita il blocco ad alcuni tipi di pagina: homepage, categorie, prodotti, marchi, pagine CMS, ricerca, carrello e checkout, altre pagine. Nessuna selezionata: tutte le pagine in cui l’hook esiste. Dispositivi nasconde il blocco su desktop (da 992 px), tablet (da 576 a 991 px) o mobile (sotto i 576 px).

Statistiche

Con «Invia i clic a Google Analytics», ogni clic su un marchio invia l’evento dfbc_brand_click con i parametri dfbc_block, brand_id e brand_name. L’evento va a dataLayer se è presente Google Tag Manager, altrimenti a gtag. In GTM crea un attivatore «Evento personalizzato» su dfbc_brand_click.

Inserire un blocco altrove

La scheda Integrazione del modulo e la sezione «Inserisci questo blocco altrove» di ogni blocco salvato forniscono i codici da copiare. Sostituisci 3 con il numero del blocco.

• In un template del tema: {widget name='dfbrandcarousel' id_block=3} mostra quel blocco, qualunque sia il suo hook.
• Con l’hook del modulo: {hook h='displayDfBrandCarousel'} mostra tutti i blocchi assegnati a quell’hook, {hook h='displayDfBrandCarousel' id_block=3} un blocco specifico.
• In una pagina CMS: incolla [dfbrandcarousel id="3"] nel contenuto. Lo shortcode viene sostituito dal blocco, anche quando è da solo in un paragrafo.
• Contenuti AJAX o page builder: se il blocco viene inserito dopo il caricamento della pagina, chiama window.DFBC.init(contenitore). window.DFBC.destroy(contenitore) ferma i blocchi in modo pulito prima di rimuoverne l’HTML.

Quando un blocco compare in una pagina in cui il modulo non ha caricato i suoi file (widget in un template, hook personalizzato), il blocco li aggiunge da sé, una sola volta per pagina.

Loghi dei marchi

La scheda Loghi dei marchi elenca tutti i marchi attivi con il logo PrestaShop e il numero di prodotti.

• Logo alternativo: carica un file PNG, JPG, WebP, GIF o SVG di massimo 2 MB. Sostituisce il logo PrestaShop in tutti i blocchi. «Rimuovi» torna al logo originale.
• Link personalizzato: URL completo (https://…) o percorso che inizia con /. Un link verso un altro sito si apre in una nuova scheda. Se vuoto, il link porta alla pagina del marchio.

Gli SVG che contengono script, attributi di evento, oggetti incorporati o link esterni vengono rifiutati: esportali di nuovo come SVG semplice. I file sono salvati in /img/dfbrandcarousel/, il cui file .htaccess blocca l’esecuzione di script e applica una policy di sicurezza agli SVG.

Se un modulo di ottimizzazione immagini ha creato versioni .webp o .avif accanto ai loghi PrestaShop in /img/m/, vengono servite automaticamente ai browser compatibili.

Personalizzare l’HTML

Copia modules/dfbrandcarousel/views/templates/hook/dfbrandcarousel.tpl in themes/tuo-tema/modules/dfbrandcarousel/views/templates/hook/dfbrandcarousel.tpl e modifica la copia. Gli aggiornamenti del modulo non la sovrascrivono. Tutti i valori del template sono già escapati dal modulo, per questo si usa nofilter.

Ogni blocco viene generato in un elemento <section class="dfbc dfbc--MODALITÀ"> con l’id dfbc-NUMERO-N. Per un CSS mirato usa preferibilmente le classi, ad esempio:

.dfbc--marquee .dfbc-card { border-radius: 999px; }

Multinegozio e lingue

I blocchi si gestiscono negozio per negozio: scegli un negozio nel selettore del back office prima di modificarli. Loghi alternativi e link personalizzati sono comuni a tutti i negozi. Titolo, sottotitolo e testo del link si inseriscono per lingua. Il modulo è tradotto in inglese, francese, spagnolo, tedesco, italiano, olandese, polacco e portoghese, e supporta le lingue da destra a sinistra.

Cache e prestazioni

Il modulo non carica jQuery, né Swiper, né alcuna libreria esterna. CSS e JavaScript pesano circa 5 KB e 7 KB compressi e vengono caricati solo nelle pagine in cui può comparire un blocco: un blocco su displayHome non carica nulla nelle schede prodotto.

L’elenco dei marchi resta in cache 6 ore, il numero di prodotti per marchio 1 ora e le vendite 12 ore, in var/cache/. Questa cache viene svuotata a ogni salvataggio nel modulo e quando un marchio o un prodotto viene aggiunto, modificato o eliminato. PrestaShop esegue questi trigger solo per i dipendenti autorizzati a visualizzare il modulo: se un collega senza questo permesso modifica il catalogo, usa il pulsante «Svuota la cache».

Domande frequenti

Il blocco non compare

Verifica che il blocco sia attivo, che il tema richiami il suo hook e che i filtri Pagine e Dispositivi consentano la pagina visitata. Verifica poi che restino marchi da mostrare: l’anteprima dell’editor indica quanti marchi sono selezionati e mostra un messaggio quando nessuno corrisponde (origine, prodotti minimi, filtro sui loghi).

I loghi mostrano rettangoli bianchi

I loghi di PrestaShop sono JPG su sfondo bianco. Attiva «Rimuovi gli sfondi bianchi» su schede chiare, oppure carica loghi trasparenti nella scheda Loghi dei marchi.

I loghi sono sfocati

Scegli «Immagine originale» in Dimensione immagine, oppure carica un logo alternativo in SVG o in PNG ad alta risoluzione.

Lo scorrimento non si muove

Forse è stato premuto il pulsante pausa, oppure il sistema del visitatore chiede di ridurre le animazioni. In questo secondo caso il modulo mostra volutamente loghi fermi.

Manca un marchio

Il marchio deve essere attivo, associato al negozio e avere almeno il numero minimo di prodotti visibili. Controlla anche i marchi esclusi e l’opzione «Solo marchi con logo».

Disinstallazione

La disinstallazione elimina le tabelle del modulo, la cartella /img/dfbrandcarousel/ con i loghi alternativi e la cache del modulo.