Barra di spedizione gratuita (dffreeshipbar): guida completa
Installa e configura la barra di spedizione gratuita per PrestaShop 8 e 9: soglie per paese e per stato, scheda prodotto, carrello laterale Creative Elements, messaggi per lingua, aspetto, corrieri, gruppi di clienti, multivaluta e risoluzione dei problemi.
Guida completa al modulo dffreeshipbar 2.3.0 per PrestaShop 8 e 9: installazione, soglie per paese e per stato, posizioni di visualizzazione (comprese la scheda prodotto e il carrello laterale di Creative Elements), messaggi, aspetto, corrieri, multivaluta e risoluzione dei problemi.
Panoramica
dffreeshipbar mostra una barra di avanzamento che indica al cliente quanto gli manca da spendere per ottenere la spedizione gratuita. Al raggiungimento della soglia il messaggio passa a una conferma.
Il modulo lavora con le proprie soglie, salvate in tabelle dedicate. Non consulta mai la variabile nativa PS_SHIPPING_FREE_PRICE: puoi lasciarla a 0 e gestire la spedizione gratuita con le fasce del corriere senza conflitti.
La sua particolarità è la risoluzione territoriale a due livelli: una soglia può essere definita per paese e per stato PrestaShop. Territori collegati allo stesso paese, come i dipartimenti d’oltremare legati alla Francia, possono così essere trattati diversamente.
Requisiti
- PrestaShop dalla 8.0 alla 9.x
- PHP 7.4 minimo (8.0 – 8.3 supportate)
- Tema Classic, Hummingbird o un tema personalizzato che richiami gli hook standard
- Creative Elements (facoltativo) per la posizione nel carrello laterale
Installazione
- Nel back office, andare in Moduli → Gestore moduli → Carica un modulo.
- Caricare il file
dffreeshipbar-2.3.0.zip. - Cliccare su Installa e poi su Configura.
Il modulo crea due tabelle (PREFIX_dffreeshipbar_country e PREFIX_dffreeshipbar_state, ciascuna con una colonna id_shop) e registra gli hook displayHeader, displayBanner, displayNav2, displayNavFullWidth, displayShoppingCartFooter, displayCheckoutSummaryTop, displayProductAdditionalInfo, displayCEShoppingCartFooter e actionCarrierUpdate.
La schermata di configurazione
La schermata si trova in Moduli → DataFirefly – Barra di spedizione gratuita → Configura. In alto, una fascia di riepilogo indica lo stato del modulo, il numero di territori con soglia e di territori esclusi, la soglia di ripiego, il filtro corrieri e le posizioni attive. Ogni riquadro apre la scheda corrispondente.
La configurazione è divisa in cinque schede: Generale, Territori, Corrieri, Messaggi e Aspetto. La scheda attiva resta selezionata dopo il salvataggio.
Scheda Generale
Soglia globale di ripiego
- Usa una soglia globale predefinita: su No, la barra compare solo nei territori configurati. Su Sì, ogni territorio non configurato riceve l’importo inserito.
- Soglia globale predefinita: l’importo applicato come ultima istanza.
Multivaluta
Tutti gli importi del modulo si inseriscono nella valuta predefinita del negozio. Per un visitatore che paga in un’altra valuta, la soglia viene convertita al tasso di cambio di PrestaShop prima del confronto con il suo carrello, e gli importi visualizzati sono formattati nella sua valuta.
Richiedi un indirizzo di consegna
Prima dell’inserimento di un indirizzo, la destinazione è solo una stima e lo stato resta sconosciuto. Tre modalità:
- Mai: la barra compare durante la navigazione, in base al paese stimato.
- Per i paesi con stati (consigliata): la barra resta visibile ovunque tranne nei paesi i cui stati possono avere condizioni diverse, dove attende l’indirizzo.
- Sempre: nulla finché non esiste un indirizzo sul carrello.
Base di calcolo
- Confronta i totali IVA inclusa: deve corrispondere alla base delle fasce del corriere, altrimenti barra e checkout non coincidono.
- Includi le regole del carrello nel totale: un carrello da 70 € con un buono da 10 € viene allora valutato a 60 €.
Le spese di spedizione non contano mai ai fini dell’avanzamento.
Gruppi di clienti
Senza caselle selezionate, tutti i clienti vedono la barra. Seleziona dei gruppi per riservarla a loro, ad esempio ai privati quando i professionisti hanno altre condizioni di spedizione. Un visitatore non connesso appartiene al gruppo «Visitatore».
Nascondi finché il carrello è vuoto
La barra compare con il primo prodotto aggiunto. La scheda prodotto la mantiene in ogni caso, perché è lì che il cliente decide di aggiungere.
Posizioni di visualizzazione
- Cima della pagina: banner visibile su tutto il sito.
- Scheda prodotto: vedi la sezione dedicata più avanti.
- Carrello e checkout: blocco nella pagina carrello e nel checkout.
- Carrello laterale di Creative Elements: vedi la sezione dedicata più avanti.
Per un posizionamento libero, il modulo implementa WidgetInterface:
{widget name='dffreeshipbar'}
{widget name='dffreeshipbar' position='cart'}La barra nella scheda prodotto
La barra compare sotto il pulsante di aggiunta al carrello (hook displayProductAdditionalInfo). Oltre all’avanzamento attuale, una riga indica l’effetto dell’aggiunta del prodotto visualizzato:
- se il prodotto basta a raggiungere la soglia: «Aggiungi questo prodotto e la spedizione è gratuita»;
- altrimenti: «Con questo prodotto, ti mancheranno solo 2,50 € per la spedizione gratuita».
Il calcolo usa il prezzo della combinazione selezionata moltiplicato per la quantità inserita, sulla stessa base IVA del carrello e con i prezzi specifici del cliente. Si ripete quando il cliente cambia combinazione o quantità.
Il carrello laterale di Creative Elements
In un negozio il cui header è costruito con Creative Elements, la barra si integra nel carrello laterale del widget Carrello con skin Sidebar, tramite l’hook displayCEShoppingCartFooter eseguito dal widget. La skin Classic non apre un carrello laterale.
L’impostazione Posizione nel carrello laterale offre tre punti: sotto il titolo, sopra il riepilogo o sopra i pulsanti di checkout.
La barra si aggiorna in Ajax a ogni aggiunta al carrello e a ogni rimozione dal carrello laterale, senza ricaricare, e l’indicatore scorre dal valore precedente. Creative Elements ricostruisce solo l’elenco dei prodotti e il riepilogo: la barra resta al suo posto tra un aggiornamento e l’altro.
Scheda Territori
La tabella elenca tutti i paesi attivi del negozio e, sotto ogni paese dotato di stati, i suoi stati rientrati. Un campo di ricerca e un filtro dei territori configurati facilitano la navigazione. Gli importi sono nella valuta predefinita.
Ordine di risoluzione
Per un indirizzo di consegna, il modulo cerca in quest’ordine e si ferma alla prima corrispondenza: lo stato dell’indirizzo, poi il paese, poi la soglia globale di ripiego se attivata. Senza corrispondenza, la barra non viene mostrata.
Casella e importo: due effetti diversi
- Casella deselezionata: la barra è nascosta per quel territorio, senza eredità dal paese né dalla soglia globale.
- Casella selezionata, importo vuoto: la regola viene eliminata, il territorio eredita dal livello superiore.
- Casella selezionata, importo indicato: si applica quell’importo.
Esempio: solo territorio metropolitano
- Francia: selezionata, importo
65. - Corsica: selezionata, importo vuoto; eredita i 65 €.
- Guadalupa, Martinica, Guyana francese, Riunione, Mayotte: deselezionate.
- Soglia globale di ripiego: disattivata.
Scheda Corrieri
Tre modalità: tutti i corrieri, visualizzazione riservata ai corrieri selezionati, oppure nascondere per i corrieri selezionati. Le regole sono salvate sull’id_reference del corriere: PrestaShop ricrea un corriere a ogni modifica, ma il suo riferimento resta stabile.
L’impostazione Prima della scelta del corriere decide se la barra compare nel catalogo e nel carrello finché nessun corriere è stato scelto.
Scheda Messaggi
Cinque messaggi si personalizzano per ogni lingua attiva:
- Carrello vuoto (predefinito: «Spedizione gratuita a partire da {threshold}.»)
- Carrello in corso (predefinito: «Ti mancano solo {amount} per la spedizione gratuita!»)
- Soglia raggiunta
- Scheda prodotto: questo prodotto sblocca la spedizione gratuita
- Scheda prodotto: importo residuo dopo l’aggiunta del prodotto
Sono disponibili due segnaposto: {amount} per l’importo mancante e {threshold} per la soglia. Vengono sostituiti dall’importo formattato nella valuta del visitatore, in grassetto. Il testo viene mostrato così com’è: l’HTML inserito non viene interpretato. Un campo vuoto mantiene il testo tradotto fornito con il modulo.
Scheda Aspetto
- Colori: sfondo, barra, testo e messaggio di successo, con un selettore di colore e un campo esadecimale sincronizzati.
- Icona: camion, pacco, regalo o nessuna. Le icone sono SVG e un segno di spunta sostituisce l’icona al raggiungimento della soglia.
- Animazione: righe animate durante l’avanzamento, disattivate automaticamente per i visitatori che hanno chiesto al sistema di ridurre il movimento.
- Banner richiudibile: aggiunge un pulsante di chiusura al banner in cima alla pagina. Una volta chiuso, resta nascosto fino alla chiusura del browser. Le altre posizioni non sono interessate.
Un’anteprima dal vivo mostra il banner, la scheda prodotto e la soglia raggiunta, e si aggiorna a ogni modifica prima del salvataggio.
Aggiornamento in tempo reale
Ogni posizione stampa un contenitore, anche quando la barra non ha nulla da mostrare. Dopo un evento di carrello, indirizzo, fase del checkout, combinazione o quantità, una sola richiesta ottiene la barra di tutte le posizioni della pagina, e ogni contenitore viene riempito o svuotato sul posto. Una barra nascosta al caricamento può così comparire senza ricaricare, e viceversa.
Lo script è in ascolto sugli eventi PrestaShop updateCart, updatedCart, updatedAddressForm, changedCheckoutStep, updateDeliveryForm e updatedProduct. Per forzare un aggiornamento dal tuo codice:
document.dispatchEvent(new Event('dffreeshipbar:refresh'));Multinegozio e traduzioni
Le soglie portano un id_shop: ogni negozio ha le proprie regole. Seleziona il contesto del negozio in alto nel back office prima di aprire la configurazione.
Il modulo è fornito tradotto in italiano, francese, inglese, tedesco, spagnolo e polacco. Per i testi rivolti al cliente, la scheda Messaggi copre la maggior parte delle esigenze.
Aggiornamento da una versione precedente
La sostituzione dello ZIP esegue automaticamente gli script di migrazione. Le tue soglie sono conservate. Le nuove opzioni partono disattivate in un negozio esistente: scheda prodotto, carrello vuoto, banner richiudibile e restrizione per gruppo. I colori salvati dalle versioni precedenti sono normalizzati nel formato #rrggbb, e le cache Smarty e opcache vengono svuotate.
Risoluzione dei problemi
La barra non compare da nessuna parte
- La fascia di riepilogo segnala che nessun territorio ha una soglia?
- Il modulo e le posizioni desiderate sono attivi?
- L’obbligo di indirizzo è su Sempre mentre provi senza indirizzo?
- Ci sono gruppi di clienti selezionati di cui il tuo account di prova non fa parte?
- L’opzione per il carrello vuoto è attiva con un carrello vuoto?
La barra compare dove non dovrebbe
Verifica che la casella del territorio sia davvero deselezionata, e non solo che ne sia stato svuotato l’importo.
Niente nel carrello laterale di Creative Elements
- Il widget Carrello deve usare la skin Sidebar.
- L’opzione «Mostra nel carrello laterale di Creative Elements» deve essere attiva.
- Dopo un aggiornamento dalla 2.1.0 o precedente, svuota la cache in Parametri avanzati → Prestazioni.
L’importo non corrisponde al checkout
- L’impostazione IVA deve corrispondere alla base delle fasce del corriere.
- Un buono può riportare il carrello sotto la soglia.
- Il modulo non legge le tue fasce: riporta nel modulo ogni modifica di fascia.
La barra non si aggiorna dopo un’aggiunta
L’aggiornamento si basa sugli eventi JavaScript di PrestaShop. Se un modulo carrello di terze parti non li emette, lancia dffreeshipbar:refresh dal suo codice. Controlla anche la console: un errore JavaScript a monte impedisce l’installazione del listener.
Disinstallazione
La disinstallazione elimina entrambe le tabelle delle soglie e tutte le chiavi di configurazione con prefisso DFFREESHIPBAR_, messaggi compresi. Esporta entrambe le tabelle se prevedi di reinstallare.
FAQ rapida
- Il modulo legge
PS_SHIPPING_FREE_PRICE? Mai. - Il modulo legge le mie fasce corriere? No, le soglie si inseriscono manualmente. Una sincronizzazione automatica è possibile come sviluppo su misura.
- La mia spedizione gratuita dipende anche dal peso. È gestita? No, il modulo misura solo un importo.
- Posso usare il grassetto o un link in un messaggio? No, il testo viene protetto. Gli importi dei segnaposto sono messi in grassetto automaticamente.
- Un banner chiuso ricompare? Alla successiva apertura del browser.
Supporto e aggiornamenti
Il modulo include 12 mesi di aggiornamenti e supporto. Supporto via email in francese o inglese, risposta entro 24 ore lavorative. Contatta il supporto DataFirefly indicando le versioni di PrestaShop, PHP e del modulo, il tema utilizzato, e il territorio e il corriere interessati.