Offres quantitatives & badges promo : documentation

Installation

Le module s’installe comme n’importe quel module PrestaShop, par le back-office ou par FTP.

1. Depuis Modules puis Gestionnaire de modules, cliquez sur Installer un module et déposez le fichier dfquantitydeal.zip.
2. Par FTP, décompressez l’archive dans le dossier /modules/ de votre boutique, puis installez DataFirefly – Offres quantitatives & badges promo depuis le gestionnaire de modules.
3. Videz le cache dans Paramètres avancés puis Performances.

L’installation crée huit tables préfixées ps_df_quantity_deal, enregistre sept hooks et ajoute l’onglet Offres quantitatives dans le menu Catalogue.

Réglages généraux

Le bouton Configurer de la fiche module ouvre les réglages qui s’appliquent à toutes les offres.

• Activer le module : coupe l’affichage des badges et le calcul des remises sans désinstaller.
• Badges sur les listings : affiche le badge sur les vignettes des pages catégorie, des résultats de recherche et des blocs de produits.
• Badge sur la fiche produit : interrupteur séparé, pour afficher le badge uniquement en listing si vous le souhaitez.
• Tableau des offres sur la fiche produit : liste les offres applicables au produit sous le bouton d’ajout au panier.
• Détail des offres dans le panier : ajoute sous le récapitulatif panier le montant apporté par chaque offre.
• Calculer les remises TTC : activé, la règle de panier porte un montant toutes taxes comprises. Désactivé, le montant est hors taxes et PrestaShop applique la TVA selon vos règles.
• Libellé de la remise panier : texte affiché sur la ligne de remise du panier et de la commande. Par défaut « Offres quantitatives ».
• Taille de police du badge : en pixels, 13 par défaut.

Créer une offre

Ouvrez Catalogue puis Offres quantitatives, et cliquez sur Nouvelle offre. Le formulaire est réparti en trois onglets.

Onglet Offre

• Nom de l’offre : champ traduit, utilisé dans la liste du back-office et dans le tableau des offres de la fiche produit.
• Type d’offre : les cinq mécaniques décrites plus bas. Le formulaire masque les champs inutiles selon le type choisi.
• Quantité achetée (X) et Quantité offerte (Y) : pour le type X achetés + Y offerts, et X seul pour le prix de lot.
• Rang de l’article remisé (N) : 2 pour « le 2e à -25 % », 3 pour « le 3e à -50 % ».
• Valeur de la remise : pourcentage, montant de remise ou prix imposé selon le type. Le libellé du champ change automatiquement.
• Offre répétable : activée, l’offre s’applique autant de fois que la quantité le permet. Désactivée, elle ne s’applique qu’une fois par panier.
• Regroupement des quantités : par produit, par déclinaison, ou mix and match.
• Priorité : les valeurs les plus basses passent en premier.
• Activer l’offre : équivalent du bouton d’activation dans la liste.

Onglet Conditions

• Périmètre : tout le catalogue, produits sélectionnés, catégories sélectionnées ou marques sélectionnées. Le champ de sélection correspondant apparaît selon le choix.
• Produits concernés : tapez au moins deux caractères pour lancer la recherche. Elle porte sur le nom, la référence et l’ID. Cliquez sur un résultat pour l’ajouter à la liste.
• Catégories concernées : arbre de catégories avec cases à cocher. Un produit rattaché à l’une des catégories cochées déclenche l’offre.
• Marques concernées : liste des fabricants de la boutique.
• Groupes de clients : laissez tout décoché pour appliquer l’offre à tous les groupes, visiteurs compris.
• Exclure les produits déjà en promotion : les produits qui bénéficient d’un prix spécifique sortent du calcul.
• Date de début et Date de fin : laissez vide pour une offre permanente. Une date seule est complétée à 00:00:00 pour le début et 23:59:59 pour la fin.
• Boutiques : visible uniquement si le mode multi-boutique est actif.

Onglet Badge & affichage

• Texte du badge : champ traduit. Laissez vide pour une génération automatique à partir des valeurs de l’offre.
• Couleur de fond et Couleur du texte : sélecteurs de couleur, valeurs par défaut rouge et blanc.
• Forme : carré, coins arrondis, pilule, ruban incliné, pastille ronde.
• Position sur la vignette : haut gauche, haut droite, bas gauche, bas droite, ou affichage en ligne sous le prix.
• Afficher sur les listings, sur la fiche produit, dans le tableau des offres : trois interrupteurs par offre, en complément des réglages globaux.
• Description de l’offre : texte riche traduit, affiché sous la phrase explicative dans le tableau des offres.

Les cinq types d’offres

X achetés + Y offerts

Le format classique du 2+1, 3+1 ou 4+2. Le moteur découpe les unités éligibles du panier en lots de X plus Y. Pour chaque lot complet, les Y unités les moins chères sont offertes.

Exemple : offre 4+2, six articles à 4,49 € dans le panier. Un lot complet, deux unités offertes, remise de 8,98 €. Avec cinq articles seulement, aucun lot n’est complet et la remise est nulle.

Le Nième à -X %

Le moteur découpe les unités en lots de N. Dans chaque lot, l’unité de rang N reçoit le pourcentage de remise. Comme les unités sont triées par prix décroissant, l’article remisé est le moins cher du lot.

Exemple : offre « le 2e à -25 % », quatre articles à 20 €. Deux lots de deux, deux articles remisés de 5 €, remise totale de 10 €.

Le Nième à -X €

Même découpage, mais la remise est un montant fixe. Elle est plafonnée au prix de l’article : une remise de 30 € sur un article à 8 € donne 8 € de remise, pas 30 €.

Le Nième à prix imposé

L’article de rang N est ramené au prix que vous fixez. La remise correspond à la différence. Pour « le 2e à 1 € » sur deux articles à 12 €, la remise est de 11 €.

Prix de lot

Pour chaque lot de X unités, le total est ramené au prix que vous annoncez. Sur une offre 3 pour 10 € avec six articles à 5 €, le moteur forme deux lots et applique 10 € de remise au total.

Quel article est offert

Le moteur trie les unités éligibles par prix décroissant, puis applique l’avantage aux moins chères de chaque lot. C’est la règle utilisée par la grande distribution et celle qu’attend le client.

Sur un lot 3+1 composé d’articles à 20 €, 15 €, 10 € et 5 €, l’article offert est celui à 5 €. Le client paye 45 € au lieu de 50 €.

Regroupement des quantités

• Par produit : toutes les déclinaisons d’une même référence comptent ensemble. Six flacons du même gel douche déclenchent une offre 4+2 même s’il s’agit de trois parfums différents.
• Par déclinaison : chaque variante compte pour elle-même. Il faut six unités du même parfum pour déclencher la même offre.
• Mix and match : toutes les unités des produits rattachés à l’offre alimentent le même compte. Utile pour faire du 4+2 sur une gamme complète.

Priorité et cumul entre offres

Les offres sont évaluées dans l’ordre de leur priorité, de la plus basse à la plus haute. Chaque offre consomme les unités qu’elle utilise, et l’offre suivante travaille sur le reste. Une même unité n’est jamais remisée deux fois.

Exemple : sept articles dans le panier, une offre 4+2 en priorité 10. Six unités sont consommées par le lot, la septième reste disponible pour une offre de priorité 20 qui viserait le même produit.

Le badge

Variables du texte

Le champ Texte du badge accepte cinq variables, remplacées à l’affichage par les valeurs de l’offre.

• {x} : quantité achetée
• {y} : quantité offerte
• {n} : rang de l’article remisé
• {value} : valeur de la remise, sans zéros inutiles
• {price} : valeur de la remise formatée en prix, dans la devise du client

Vous pouvez aussi écrire le texte en dur : « 4+2 gratuits », « 3+1 offert », « le 2e à -25 % ». Le champ est traduit, donc chaque langue a sa formulation.

Si le champ reste vide, le module génère un libellé court à partir du type et des valeurs : 4+2 pour une offre X achetés Y offerts, -25% x2 pour un Nième à pourcentage.

Position et intégration à la vignette

Le badge est rendu dans le bloc prix, via le hook displayProductPriceBlock. Un script front le déplace ensuite dans le conteneur de la vignette pour l’afficher par-dessus l’image. Le placement est rejoué après les rafraîchissements Ajax de la recherche à facettes, de la pagination et du quick view.

Le mode En ligne (sous le prix) désactive ce déplacement et laisse le badge dans le flux, sous le prix. Choisissez ce mode si votre thème utilise une structure de vignette non standard.

Calcul de la remise dans le panier

À chaque modification du panier, le moteur recalcule le total des remises et synchronise une règle de panier privée. Son code interne commence par DFQD suivi de l’identifiant du panier. Le client ne voit qu’une ligne de remise et n’a aucun code à saisir.

La règle est mise à jour uniquement si le montant a changé, ce qui évite de la recréer à chaque chargement de page. Si le total retombe à zéro, la règle est détachée du panier puis supprimée.

À la validation de la commande, la règle est désactivée et sa date de fin est ramenée dans le passé pour qu’elle ne puisse pas être réutilisée. Elle reste rattachée à la commande, donc visible dans vos exports comptables et utilisable pour un avoir.

Adapter l’affichage à votre thème

Trois templates sont surchargeables. Copiez-les depuis /modules/dfquantitydeal/views/templates/hook/ vers /themes/votre-theme/modules/dfquantitydeal/views/templates/hook/.

• badge.tpl : le badge lui-même
• offers.tpl : le tableau des offres de la fiche produit
• cart.tpl : le récapitulatif sous le panier

Le CSS est isolé sous le préfixe dfqd. Pour un ajustement ponctuel, ciblez les classes depuis votre feuille de style de thème plutôt que de modifier views/css/front.css, qui serait écrasé à la mise à jour.

Multi-boutique et multilingue

Chaque offre est rattachée aux boutiques que vous cochez dans l’onglet Conditions. Une offre créée sur une boutique n’apparaît pas sur les autres tant qu’elle n’y est pas rattachée.

Les champs Nom, Texte du badge et Description sont traduits dans les langues installées. Le badge affiché reprend la langue du client.

Dépannage

Le badge ne s’affiche pas

1. Vérifiez que le module et l’offre sont actifs, et que la date du jour est dans la période de validité.
2. Vérifiez le périmètre : un produit doit être explicitement rattaché à l’offre, ou appartenir à une catégorie ou une marque cochée.
3. Contrôlez les interrupteurs d’affichage, dans les réglages globaux et dans l’onglet Badge de l’offre.
4. Si le groupe de clients est restreint, testez avec un compte du bon groupe.
5. Videz le cache Smarty et le cache de votre serveur.

La remise ne s’applique pas au panier

La quantité doit atteindre le seuil de l’offre selon le mode de regroupement choisi. En mode Par déclinaison, six unités réparties sur trois variantes ne déclenchent pas une offre 4+2. Vérifiez aussi que le produit n’est pas exclu par l’option sur les produits déjà en promotion.

Deux offres se marchent dessus

Ce comportement est attendu : une unité consommée par la première offre sort du calcul de la seconde. Si vous voulez qu’une offre passe avant l’autre, baissez sa priorité.

Le badge apparaît au mauvais endroit

Certains thèmes personnalisés n’utilisent pas la structure de vignette standard. Passez la position sur En ligne (sous le prix), ou surchargez badge.tpl pour placer le badge où vous le souhaitez.

Désinstallation

La désinstallation supprime les huit tables du module, ses clés de configuration et l’onglet du menu Catalogue. Les règles de panier déjà rattachées à des commandes passées sont conservées, pour ne pas altérer votre historique comptable.