# Changer la Déclinaison dans le Panier PrestaShop : installation et configuration

> Présentation Le module permet au client de changer la déclinaison d'un produit (taille, couleur ou tout autre attribut) directement depuis la page panier, sans supprimer la ligne. La nouvelle déclinaison…

- Page: <https://www.datafirefly.com/documentation/dfcartcombination/>
- Langue: fr
- Mis à jour le: 2026-10-13
- Autres langues: [en](https://www.datafirefly.com/en/documentation/dfcartcombination/index.md), [es](https://www.datafirefly.com/es/documentation/dfcartcombination/index.md), [de](https://www.datafirefly.com/de/documentation/dfcartcombination/index.md), [it](https://www.datafirefly.com/it/documentation/dfcartcombination/index.md), [pl](https://www.datafirefly.com/pl/documentation/dfcartcombination/index.md), [nl](https://www.datafirefly.com/nl/documentation/dfcartcombination/index.md), [pt](https://www.datafirefly.com/pt/documentation/dfcartcombination/index.md)
- Index: <https://www.datafirefly.com/documentation/llms.txt>

## Présentation

Le module permet au client de changer la déclinaison d'un produit (taille, couleur ou tout autre attribut) directement depuis la page panier, sans supprimer la ligne. La nouvelle déclinaison reprend la quantité, l'adresse de livraison et la position de la ligne. Le stock et la quantité minimale sont vérifiés par le serveur avant l'échange.

## Installation

1. Dans **Modules > Gestionnaire de modules**, cliquez sur **Installer un module** et envoyez le fichier `dfcartcombination-1.0.0.zip`.
2. Le module s'accroche aux hooks `displayCartExtraProductActions` et `actionFrontControllerSetMedia`, et crée la table `ps_dfcartcombination_log` pour l'historique.
3. Ouvrez la configuration du module. Tout est actif par défaut, en mode bouton avec fenêtre.
4. Ajoutez au panier un produit qui a au moins deux déclinaisons et ouvrez la page panier pour vérifier l'affichage. Si rien n'apparaît, videz le cache dans **Paramètres avancés > Performances**.

## Réglages

- **Activer le module** : désactivé, rien n'est chargé sur la page panier.
- **Mode d'affichage** : _Bouton avec fenêtre de sélection_ (un lien « Modifier » par ligne) ou _Listes déroulantes dans la ligne du panier_ (une liste par groupe d'attributs, changement appliqué dès la sélection).
- **Placer sous les attributs du produit** : déplace le sélecteur sous les attributs de la ligne. Désactivez-le pour le laisser là où votre thème appelle le hook, en général dans la colonne d'actions à côté de la corbeille.
- **Afficher le prix par déclinaison** : prix de la déclinaison choisie, prix barré en cas de réduction et écart par rapport à la ligne actuelle. Le prix suit l'affichage TTC ou HT du groupe du client.
- **Afficher l'état du stock** : En stock, Plus que X en stock, Disponible sur commande ou Rupture de stock. Le message « Plus que X » utilise le seuil de quantité restante réglé dans PrestaShop. Rien n'est affiché si la gestion des stocks est désactivée.
- **Afficher l'image de la déclinaison** : première image associée à la déclinaison, sinon l'image de couverture du produit.
- **Déclinaisons indisponibles** : _Afficher en grisé_ ou _Masquer_. La valeur de la ligne actuelle reste toujours visible.
- **Produits exclus** : ID produits séparés par des virgules. Le sélecteur n'apparaît pas pour ces produits et le serveur refuse tout changement les concernant.
- **Couleur d'accent** : couleur du bouton principal et des valeurs sélectionnées.
- **Enregistrer l'historique des changements** : alimente les statistiques affichées sous le formulaire.

## Côté client

### Mode fenêtre

Le bouton **Modifier** ouvre une fenêtre avec l'image de la déclinaison, le nom du produit et la quantité de la ligne. Les groupes d'attributs suivent l'ordre du catalogue :

- groupes de type couleur : pastilles, avec la texture de l'attribut si elle existe ;
- groupes de type radio ou liste : boutons, ou une liste déroulante au-delà de 8 valeurs.

En bas, le prix, l'écart de prix et l'état du stock de la sélection s'actualisent à chaque clic. Le bouton **Mettre à jour le panier** reste inactif tant que la sélection est identique à la ligne ou indisponible. La fenêtre se ferme avec Échap, la croix ou un clic en dehors, et se navigue au clavier (flèches entre les valeurs d'un groupe). Sur mobile, elle s'ouvre depuis le bas de l'écran.

### Mode listes déroulantes

Chaque groupe d'attributs devient une liste dans la ligne. Le changement est envoyé dès qu'une valeur est choisie. Les lignes d'attributs que le thème affiche déjà (par exemple « Taille : S ») sont masquées pour éviter le doublon. Un message sous les listes indique la mise à jour en cours ou l'erreur éventuelle.

### Combinaison inexistante

Si la valeur choisie n'existe pas avec les autres attributs sélectionnés (M Bleu absent du catalogue par exemple), le module bascule sur la déclinaison existante qui contient cette valeur et garde le plus d'attributs actuels, en privilégiant une déclinaison commandable.

## Contrôles avant l'échange

Le navigateur envoie le produit, la déclinaison actuelle et la déclinaison choisie. Le serveur vérifie ensuite :

- le token de la session ;
- que le produit est actif et disponible à la commande, et que le mode catalogue est désactivé ;
- que la déclinaison choisie appartient au produit et à la boutique ;
- que la ligne d'origine existe toujours dans le panier, sans personnalisation ;
- que le produit n'est pas lié à une règle panier cadeau du panier ;
- que la quantité finale atteint la quantité minimale de la déclinaison ;
- que le stock couvre la quantité finale, sauf si la vente hors stock est autorisée pour le produit.

La nouvelle déclinaison est ajoutée avec la méthode native `updateQty`, puis l'ancienne est retirée avec `deleteProduct`. Si le retrait échoue, l'ajout est annulé. Si la déclinaison choisie est déjà dans le panier, les quantités sont additionnées sur une seule ligne. Sinon, la nouvelle ligne reprend la date d'ajout de l'ancienne pour garder sa place dans le panier.

Après l'échange, le module émet l'événement `updateCart` de PrestaShop. Le thème recharge alors la liste, les totaux et le mini-panier. Sans réaction du thème au bout de 3 secondes, la page se recharge.

## Lignes non concernées

- produits sans déclinaison ou avec une seule déclinaison ;
- lignes avec personnalisation (texte, fichier) ;
- produits offerts par une règle panier ;
- produits exclus dans la configuration.

## Historique et statistiques

Sous le formulaire de configuration, le bloc **Historique des changements** affiche :

- le nombre de changements et de paniers concernés sur 30 jours ;
- le nombre de paniers modifiés devenus des commandes, avec le taux ;
- les 10 produits les plus modifiés ;
- les 20 derniers changements, avec la déclinaison de départ et la déclinaison choisie.

Le bouton **Vider l'historique** supprime les données de la boutique courante. Un produit souvent changé d'une taille vers la taille au-dessus signale un guide des tailles ou une fiche à revoir.

## Thèmes et personnalisation

Le thème Classic et la plupart des thèmes qui en dérivent appellent `displayCartExtraProductActions` dans chaque ligne du panier. Si votre thème ne l'appelle pas, le script crée le sélecteur à partir des liens de suppression des lignes (`data-id-product` et `data-id-product-attribute`). Le fichier JavaScript n'est chargé que sur la page panier.

Pour ajuster le style, surchargez dans le CSS de votre thème les variables `--dfcc-accent`, `--dfcc-text`, `--dfcc-border` ou les classes `.dfcc-edit`, `.dfcc-modal__dialog`, `.dfcc-option`.

Avec un thème très personnalisé ou un module de panier latéral, testez le changement de déclinaison sur une copie de la boutique, en client invité et en client connecté.

## Pour les développeurs

Après chaque changement réussi, le module exécute le hook `actionDfCartCombinationChange` avec les paramètres `cart`, `id_product`, `id_product_attribute_from`, `id_product_attribute_to` et `quantity`. Un module tiers peut s'y accrocher pour synchroniser un CRM ou un outil d'analyse.

## Limites connues

- Les lignes personnalisées gardent leur déclinaison dans la version 1.0.0.
- Le changement se fait depuis la page panier, pas depuis le récapitulatif du tunnel de commande ni le mini-panier.
- Un module de panier latéral qui ne passe pas par l'événement `updateCart` ne se met à jour qu'au rechargement de la page.