Barre de livraison gratuite (dffreeshipbar) : guide complet

Guide complet du module dffreeshipbar 2.3.0 pour PrestaShop 8 et 9 : installation, seuils par pays et par état, emplacements d’affichage (dont la fiche produit et le tiroir panier Creative Elements), messages, apparence, transporteurs, multi-devise et dépannage.

Aperçu

dffreeshipbar affiche une barre de progression indiquant au client combien il lui reste à dépenser pour bénéficier de la livraison gratuite. Lorsque le seuil est atteint, le message bascule sur une confirmation.

Le module fonctionne avec ses propres seuils, stockés dans ses tables. Il n’interroge jamais la variable native PS_SHIPPING_FREE_PRICE : vous pouvez la laisser à 0 et piloter votre franco par des tranches transporteur sans conflit.

Sa particularité est la résolution territoriale à deux niveaux : un seuil peut être défini au niveau du pays et au niveau de l’état PrestaShop. Des territoires rattachés au même pays, comme les départements d’outre-mer rattachés à la France, peuvent ainsi être traités différemment.

Prérequis

• PrestaShop 8.0 à 9.x
• PHP 7.4 minimum (8.0 à 8.3 supportées)
• Thème Classic, Hummingbird ou thème personnalisé appelant les hooks standards
• Creative Elements (facultatif) pour l’emplacement tiroir panier

Installation

1. Dans le back office, aller dans Modules → Gestionnaire de modules → Envoyer un module.
2. Uploader le fichier dffreeshipbar-2.3.0.zip.
3. Cliquer sur Installer puis Configurer.

Le module crée deux tables (PREFIX_dffreeshipbar_country et PREFIX_dffreeshipbar_state, chacune avec une colonne id_shop) et enregistre les hooks displayHeader, displayBanner, displayNav2, displayNavFullWidth, displayShoppingCartFooter, displayCheckoutSummaryTop, displayProductAdditionalInfo, displayCEShoppingCartFooter et actionCarrierUpdate.

L’écran de configuration

L’écran se trouve dans Modules → DataFirefly – Barre de livraison gratuite → Configurer. En tête, un bandeau de synthèse indique l’état du module, le nombre de territoires avec seuil et de territoires exclus, le seuil de repli, le filtrage transporteur et les emplacements actifs. Chaque tuile ouvre l’onglet concerné.

La configuration est répartie en cinq onglets : Général, Territoires, Transporteurs, Messages et Apparence. L’onglet actif est conservé après un enregistrement.

Onglet Général

Seuil global de repli

• Utiliser un seuil global par défaut : sur Non, la barre n’apparaît que dans les territoires configurés. Sur Oui, tout territoire non configuré reçoit le montant saisi.
• Seuil global par défaut : le montant appliqué en dernier recours.

Multi-devise

Tous les montants du module se saisissent dans la devise par défaut de la boutique. Pour un visiteur qui paie dans une autre devise, le seuil est converti au taux de change de PrestaShop avant la comparaison avec son panier, et les montants affichés sont formatés dans sa devise.

Exiger une adresse de livraison

Avant la saisie d’une adresse, la destination n’est qu’une estimation et l’état reste inconnu. Trois modes :

• Jamais : la barre s’affiche dès la navigation, sur la base du pays estimé.
• Pour les pays comportant des états (recommandé) : la barre reste visible partout, sauf dans les pays dont les états peuvent porter des conditions différentes, où elle attend l’adresse.
• Toujours : rien tant qu’aucune adresse n’existe sur le panier.

Base de calcul

• Comparer les totaux TTC : doit correspondre à la base de vos tranches transporteur, sinon la barre et le tunnel de commande divergent.
• Inclure les bons de réduction dans le total : un panier de 70 € avec un bon de 10 € est alors évalué à 60 €.

Les frais de port ne comptent jamais dans la progression.

Groupes clients

Sans case cochée, tous les clients voient la barre. Cochez des groupes pour la réserver à ceux-ci, par exemple aux particuliers quand les professionnels ont d’autres conditions de livraison. Un visiteur non connecté appartient au groupe « Visiteur ».

Masquer tant que le panier est vide

La barre apparaît au premier produit ajouté. La fiche produit la conserve dans tous les cas, puisque c’est l’endroit où le client décide d’ajouter.

Emplacements d’affichage

• Haut de page : bannière visible sur tout le site.
• Fiche produit : voir la section dédiée ci-dessous.
• Panier et commande : bloc affiché sur la page panier et dans le tunnel.
• Tiroir panier Creative Elements : voir la section dédiée ci-dessous.

Pour un placement libre, le module implémente WidgetInterface :

{widget name='dffreeshipbar'}
{widget name='dffreeshipbar' position='cart'}

La barre sur la fiche produit

La barre s’affiche sous le bouton d’ajout au panier (hook displayProductAdditionalInfo). En plus de la progression actuelle, une ligne indique l’effet de l’ajout du produit affiché :

• si le produit suffit à atteindre le seuil : « Ajoutez ce produit et la livraison vous est offerte » ;
• sinon : « Avec ce produit, plus que 2,50 € pour la livraison gratuite ».

Le calcul utilise le prix de la déclinaison sélectionnée multiplié par la quantité saisie, sur la même base HT ou TTC que le panier, avec les prix spécifiques du client. Il se relance quand le client change de déclinaison ou de quantité.

Le tiroir panier Creative Elements

Sur une boutique dont le header est construit avec Creative Elements, la barre s’intègre au panier latéral du widget Panier en habillage Sidebar, par le hook displayCEShoppingCartFooter que ce widget exécute. L’habillage Classic n’ouvre pas de tiroir.

Le réglage Position dans le tiroir panier propose trois emplacements : sous le titre du tiroir, au-dessus du récapitulatif ou au-dessus des boutons de commande.

La barre se met à jour en Ajax à chaque ajout au panier et à chaque suppression depuis le tiroir, sans rechargement, avec une jauge qui glisse depuis sa valeur précédente. Creative Elements ne reconstruit que la liste des produits et le récapitulatif : la barre reste en place entre deux mises à jour.

Onglet Territoires

Le tableau liste tous les pays actifs de la boutique et, sous chaque pays comportant des états, ses états en retrait. Un champ de recherche et un filtre « territoires configurés » facilitent la navigation. Les montants sont en devise par défaut.

Ordre de résolution

Pour une adresse de livraison, le module cherche dans cet ordre et s’arrête au premier résultat : l’état de l’adresse, puis le pays, puis le seuil global de repli s’il est activé. Sans résultat, la barre ne s’affiche pas.

Case à cocher et montant : deux effets différents

• Case décochée : la barre est masquée pour ce territoire, sans héritage du pays ni du seuil global.
• Case cochée, montant vide : la règle est supprimée, le territoire hérite du niveau supérieur.
• Case cochée, montant saisi : ce montant s’applique.

Exemple : franco métropole uniquement

• France : case cochée, montant 65.
• Corse : case cochée, montant vide ; elle hérite des 65 €.
• Guadeloupe, Martinique, Guyane, Réunion, Mayotte : cases décochées.
• Seuil global de repli : désactivé.

Onglet Transporteurs

Trois modes : tous les transporteurs, affichage réservé aux transporteurs cochés, ou masquage pour les transporteurs cochés. Les règles sont enregistrées sur l’id_reference du transporteur : PrestaShop recrée un transporteur à chaque modification, mais sa référence reste stable.

Le réglage Avant sélection du transporteur décide si la barre s’affiche sur le catalogue et le panier tant qu’aucun transporteur n’est choisi.

Onglet Messages

Cinq messages se personnalisent pour chaque langue active :

• Panier vide (défaut : « Livraison gratuite dès {threshold}. »)
• Panier en cours (défaut : « Plus que {amount} pour bénéficier de la livraison gratuite ! »)
• Seuil atteint
• Fiche produit : ce produit débloque la livraison gratuite
• Fiche produit : montant restant après ajout du produit

Deux jetons sont disponibles : {amount} pour le montant restant et {threshold} pour le seuil. Ils sont remplacés par le montant formaté dans la devise du visiteur, en gras. Le texte est affiché tel quel : le HTML saisi n’est pas interprété. Un champ laissé vide reprend le texte traduit fourni avec le module.

Onglet Apparence

• Couleurs : fond, barre, texte et message de réussite, avec un sélecteur et un champ hexadécimal synchronisés.
• Icône : camion, colis, cadeau ou aucune. Les icônes sont en SVG et une coche remplace l’icône quand le seuil est atteint.
• Animation : rayures animées pendant la progression, automatiquement coupées pour les visiteurs qui ont activé la réduction des animations dans leur système.
• Bannière refermable : ajoute un bouton de fermeture à la bannière du haut de page. Une fois fermée, elle reste masquée jusqu’à la fermeture du navigateur. Les autres emplacements ne sont pas concernés.

Un aperçu en direct montre la bannière, la fiche produit et le seuil atteint, et se met à jour à chaque changement avant enregistrement.

Mise à jour en temps réel

Chaque emplacement imprime un conteneur, même quand la barre n’a rien à afficher. Après un événement panier, adresse, étape du tunnel, déclinaison ou quantité, une seule requête récupère la barre de tous les emplacements de la page, qui sont remplis ou vidés sur place. Une barre masquée au chargement peut donc apparaître sans rechargement, et inversement.

Le script écoute les événements PrestaShop updateCart, updatedCart, updatedAddressForm, changedCheckoutStep, updateDeliveryForm et updatedProduct. Pour un rafraîchissement depuis votre propre code :

document.dispatchEvent(new Event('dffreeshipbar:refresh'));

Multi-boutique et traductions

Les seuils portent un id_shop : chaque boutique a ses propres règles. Sélectionnez le contexte de la boutique en haut du back office avant d’ouvrir la configuration.

Le module est livré traduit en français, anglais, allemand, espagnol, italien et polonais. Pour les textes côté client, l’onglet Messages suffit dans la plupart des cas.

Mise à jour depuis une version antérieure

Le remplacement du ZIP exécute automatiquement les scripts de migration. Vos seuils sont conservés. Les nouvelles options démarrent désactivées sur une boutique existante : fiche produit, masquage du panier vide, bannière refermable, restriction par groupe. Les couleurs enregistrées par les anciennes versions sont normalisées au format #rrggbb, et les caches Smarty et opcache sont vidés.

Dépannage

La barre ne s’affiche nulle part

1. Le bandeau de synthèse signale-t-il qu’aucun territoire n’a de seuil ?
2. Le module est-il activé, et les emplacements voulus sont-ils activés ?
3. Le mode d’exigence d’adresse est-il sur Toujours alors que vous testez sans adresse ?
4. Des groupes clients sont-ils cochés sans que votre compte de test en fasse partie ?
5. L’option « Masquer tant que le panier est vide » est-elle active avec un panier vide ?

La barre s’affiche là où elle ne devrait pas

Vérifiez que la case du territoire est bien décochée, et non simplement que son montant a été vidé.

Rien dans le tiroir Creative Elements

• Le widget Panier doit être en habillage Sidebar.
• L’option « Afficher dans le tiroir panier Creative Elements » doit être active.
• Après une mise à jour depuis la 2.1.0 ou antérieure, videz le cache dans Paramètres avancés → Performances.

Le montant ne correspond pas au tunnel de commande

• Le réglage TTC doit correspondre à la base de vos tranches transporteur.
• Un bon de réduction peut faire repasser le panier sous le seuil.
• Le module ne lit pas vos tranches : reportez toute modification de tranche dans le module.

La barre ne se met pas à jour après un ajout

Le rafraîchissement repose sur les événements JavaScript de PrestaShop. Si un module de panier tiers ne les émet pas, déclenchez dffreeshipbar:refresh depuis son code. Vérifiez aussi la console : une erreur JavaScript en amont empêche l’écoute de s’installer.

Désinstallation

La désinstallation supprime les deux tables de seuils et toutes les clés de configuration préfixées DFFREESHIPBAR_, messages compris. Exportez les deux tables si vous prévoyez de réinstaller.

FAQ rapide

• Le module lit-il PS_SHIPPING_FREE_PRICE ? Non, jamais.
• Le module lit-il mes tranches transporteur ? Non, les seuils sont saisis manuellement. Une synchronisation automatique est possible en développement spécifique.
• Mon franco dépend aussi du poids. Est-ce géré ? Non, le module ne mesure qu’un montant.
• Puis-je mettre du gras ou un lien dans un message ? Non, le texte est échappé. Les montants des jetons sont mis en gras automatiquement.
• La bannière fermée revient-elle ? À la prochaine ouverture du navigateur.

Support et mises à jour

Le module inclut 12 mois de mises à jour et de support. Support par email en français ou en anglais, réponse sous 24 heures ouvrées. Contactez le support DataFirefly en précisant les versions de PrestaShop, de PHP et du module, le thème utilisé, et le territoire et le transporteur concernés.