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 variante reste un produit complet, avec sa propre URL. C’est le mouvement inverse de DF ProductSplitter, 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.

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.

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.