# Documentation du module Regrouper des produits en variantes PrestaShop (dfproductlinker)

> Le module DF ProductLinker (dfproductlinker) relie des fiches produits distinctes pour les afficher comme un seul article avec un sélecteur de couleur, de taille ou de tout autre attribut. Chaque…

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

Le module **DF ProductLinker** (dfproductlinker) relie des fiches produits distinctes pour les afficher comme un seul article avec un sélecteur de couleur, de taille ou de tout autre attribut. Chaque variante reste un produit complet, avec sa propre URL. C'est le mouvement inverse de [DF ProductSplitter](https://www.datafirefly.com/product/separer-declinaisons-en-produits-prestashop/), qui éclate un produit à déclinaisons en produits séparés.

## Installation

1. Téléchargez le ZIP depuis votre compte client DataFirefly.
2. Dans le back-office, allez dans _Modules > Gestionnaire de modules > Installer un module_ et envoyez le ZIP.
3. À l'installation, le module crée ses tables et l'onglet _Catalogue > Variantes liées_.
4. Ouvrez la configuration du module pour vérifier la position du sélecteur.

Le module fonctionne sur PrestaShop 8.0 à 9.x avec le même ZIP, en multiboutique et en multilingue. Ses chaînes sont livrées en français, anglais, espagnol, allemand, italien, néerlandais, polonais et portugais.

Lors d'une mise à jour, le module vide le cache Smarty. Si votre boutique est réglée sur _Ne jamais recompiler les templates_ et que l'affichage ne change pas, videz le cache depuis _Paramètres avancés > Performances_.

## Principe : groupes et axes

Un **groupe** réunit plusieurs produits. Un **axe** est un groupe d'attributs natif de PrestaShop, par exemple Couleur ou Taille : les valeurs, les couleurs hexadécimales, les textures et les traductions saisies dans _Catalogue > Attributs & caractéristiques_ sont reprises telles quelles. Chaque produit du groupe reçoit une valeur sur chaque axe.

Un produit ne peut appartenir qu'à un seul groupe. Les produits eux-mêmes ne sont pas modifiés : le groupe est stocké dans les tables du module.

## Créer un groupe

Allez dans _Catalogue > Variantes liées_ puis _Ajouter un groupe_.

1. Saisissez le **nom du groupe**. Il sert en interne et de nom de repli dans les données structurées.
2. Dans **Axes**, cliquez sur _Ajouter un axe_. Le module propose d'abord un groupe d'attributs de type couleur. Pour chaque axe, choisissez l'**affichage** (automatique, pastille couleur, vignette photo du produit, bouton texte, liste déroulante) et la **propriété des données structurées** (couleur, taille, matière, motif, ou non déclarée).
3. Dans **Produits du groupe**, recherchez les produits par nom, référence ou ID. Les flèches du clavier et la touche Entrée permettent de sélectionner un résultat. Les produits déjà présents dans un autre groupe sont grisés.
4. Pour chaque produit, vérifiez la valeur de chaque axe. Elle est préremplie quand elle figure dans le nom du produit. Une valeur manquante est surlignée en orange et la ligne d'état sous le tableau indique combien de produits sont concernés, ou si deux produits ont les mêmes valeurs.
5. Enregistrez. Le module vous avertit si vous quittez la page avec des modifications non enregistrées.

L'ordre des lignes du groupe est l'ordre des pastilles sur la boutique. Le bouton _Trier selon l'ordre des attributs_ range les lignes dans l'ordre défini dans le catalogue, pratique pour des tailles S, M, L, XL.

## Ce que voit le client

Sur chaque fiche du groupe, le sélecteur affiche le nom de l'axe et la valeur en cours, par exemple _Couleur : Rouge_, puis les valeurs disponibles. Au survol, le libellé montre la valeur pointée. La valeur en cours est encadrée ; les autres sont des liens vers la fiche correspondante.

- Avec plusieurs axes, un clic sur une couleur ouvre le produit qui garde la taille en cours. Si cette combinaison n'existe pas, le module ouvre la variante la plus proche en privilégiant un produit en stock, et la pastille est dessinée en pointillés.
- Une variante en rupture est grisée et barrée, ou masquée selon le réglage.
- Une valeur de couleur sans code hexadécimal ni texture s'affiche en texte dans une pastille allongée.
- Le sélecteur s'affiche aussi dans la quick view des pages catégorie, au-dessus du bouton d'ajout au panier.

## Réglages du module

- **Position du sélecteur** : avant le bloc natif des déclinaisons (recommandé), après ce bloc, dans le hook `displayProductAdditionalInfo`, ou uniquement dans le hook de thème `displayDfProductLinker`.
- **Sélecteur CSS du bloc natif des déclinaisons** : par défaut `.product-variants, .product__variants`. Si rien ne correspond dans votre thème, le sélecteur reste dans le hook.
- **Libellé de l'axe**, **prix de chaque variante** (modes image et bouton), **format d'image** des vignettes.
- **Variantes en rupture** : grisées ou masquées.
- **Couleur d'accent**, **forme** (ronde ou carrée à coins arrondis) et **taille** des pastilles. La taille moyenne donne une zone tactile de 44 px, recommandée sur mobile.
- **Pastilles dans les listes produits**, nombre maximum de pastilles, et **changement d'image au survol**.
- **Un seul produit par groupe**, visibilité des autres produits et produit affiché : voir la section suivante.
- **URL canonique des variantes** et **données structurées ProductGroup** : voir la section SEO.

Pour un placement sur mesure, choisissez la position _hook de thème_ et ajoutez cette ligne dans le template produit de votre thème : `{hook h='displayDfProductLinker' product=$product}`.

## Un seul produit par groupe dans les catégories

Cette option n'affiche qu'une vignette par groupe dans les listes de catégories. Les autres produits du groupe passent en visibilité _Recherche uniquement_ (ou _Nulle part_ selon le réglage) : leurs fiches restent en ligne avec leur URL, et les pastilles de la vignette mènent vers elles.

- **Produit affiché** : le premier du groupe, ou le premier en stock. Dans ce second cas, le produit affiché est recalculé à chaque mouvement de stock.
- La visibilité d'origine de chaque produit est sauvegardée. Elle est restaurée quand vous désactivez l'option, désactivez le groupe, retirez un produit de son groupe ou désinstallez le module.
- Si vous modifiez à la main la visibilité d'un produit masqué, votre valeur devient la nouvelle valeur d'origine.
- Le bouton _Resynchroniser la visibilité_ de la configuration réapplique la règle à tous les groupes. Utilisez-le si des produits ont été modifiés par un employé sans droit sur le module, car PrestaShop ne déclenche alors pas les hooks du module.

Avant d'activer l'option, vérifiez que votre générateur de sitemap inclut les produits en visibilité _Recherche uniquement_, sinon les variantes masquées sortiraient du sitemap.

## SEO : données structurées et URL canonique

Le module ajoute sur chaque fiche du groupe un bloc JSON-LD `ProductGroup` avec `hasVariant` et `variesBy`. Chaque variante y figure avec son nom, son URL, sa référence, son EAN13 s'il est valide, son image, sa valeur sur chaque axe, le prix affiché au client et sa disponibilité. Le nom du groupe est tiré du nom du produit sans ses valeurs, dans la langue du visiteur. Désactivez l'option si un autre module génère déjà ce bloc.

Par défaut, chaque variante garde une URL canonique vers elle-même : chaque couleur est indexée séparément. Si vos fiches couleur sont quasi identiques, l'option _Canonique vers le produit principal du groupe_ fait pointer la canonique de toutes les variantes vers le produit principal, c'est-à-dire le produit affiché dans les listes si l'option un seul produit par groupe est active, sinon le premier produit actif du groupe.

## Assistant de regroupement automatique

Depuis la liste des groupes, cliquez sur _Assistant de regroupement automatique_. Il repère les produits qui sont le même article en plusieurs couleurs ou tailles.

1. Choisissez une catégorie, ou tout le catalogue.
2. Cochez les groupes d'attributs à détecter, par exemple Couleur et Taille. Les valeurs doivent exister comme valeurs d'attribut et apparaître dans le nom du produit.
3. Choisissez la règle : noms identiques une fois les valeurs retirées, ou références partageant la même racine (TSH01-RED et TSH01-BLUE).
4. Cliquez sur _Aperçu_, décochez les groupes à ignorer, puis _Créer les groupes sélectionnés_.

Les produits déjà présents dans un groupe sont ignorés, et l'analyse porte sur 5 000 produits par passage.

## Import et export CSV

Le bouton _Import / export CSV_ ouvre la page dédiée. L'export produit une ligne par produit, dans le même format que l'import. Colonnes :

```
group_id;group_name;group_active;axes;product_id;product_reference;product_name;values
;T-shirt Basic;1;Couleur|Taille;;TSH01-NAVY-M;;Couleur:Bleu marine|Taille:M
```

- Un groupe est reconnu par `group_id`, sinon par son nom exact. Chaque groupe présent dans le fichier est remplacé par ses lignes ; les groupes absents ne sont pas modifiés.
- Un produit est retrouvé par `product_id`, sinon par `product_reference`, qui doit être unique dans le catalogue. `product_name` est informatif.
- `values` contient des paires Axe:Valeur séparées par `|`, avec les noms des groupes d'attributs et des valeurs dans n'importe quelle langue de la boutique.
- Le séparateur `;` ou `,` est détecté automatiquement. Fichier UTF-8, 5 Mo maximum.

L'import se fait en deux temps : _Analyser le fichier_ affiche les groupes créés ou remplacés, les valeurs d'attribut qui seront créées et chaque ligne rejetée avec son motif ; _Lancer l'import_ exécute ensuite. Deux options : _Déplacer les produits qui appartiennent déjà à un autre groupe_ et _Créer les valeurs d'attribut manquantes_ (leur couleur reste vide, à compléter dans le catalogue).

## Fiche produit du back-office

Dans l'onglet Modules de la fiche produit, l'encart DF ProductLinker indique le groupe du produit et la valeur de chaque produit du groupe, avec un lien vers l'édition du groupe. Si le produit n'est dans aucun groupe, un lien crée un groupe à partir de ce produit.

## Questions fréquentes

### Le sélecteur n'apparaît pas sur une fiche

Vérifiez que le groupe est actif, que la fiche fait partie du groupe, qu'au moins deux produits du groupe sont actifs et qu'au moins un axe a deux valeurs différentes. Si vous avez choisi la position hook de thème, le hook `displayDfProductLinker` doit être présent dans le template produit.

### Le sélecteur s'affiche sous le bouton panier

Le sélecteur CSS du bloc natif des déclinaisons ne correspond à aucun élément de votre thème. Indiquez la classe du bloc de déclinaisons de votre thème dans la configuration.

### Les pastilles n'apparaissent pas dans les listes

L'option doit être activée, et le premier axe du groupe doit être affiché en pastille couleur ou en vignette photo. Votre thème doit appeler le hook natif `displayProductListReviews` dans la miniature produit, comme le fait le thème Classic.

### Puis-je combiner le module avec des déclinaisons natives ?

Oui. Un cas courant : un produit par couleur, chacun avec des déclinaisons de taille. Le sélecteur du module gère les couleurs, le bloc natif gère les tailles.
