dfvariantswatch — Swatches variantes photo & stock

Présentation

dfvariantswatch remplace les listes déroulantes de déclinaisons des fiches produit PrestaShop par des vignettes visuelles cliquables (photos, couleurs ou texte), affiche un aperçu de la variante dans la galerie principale au survol, et indique le stock de chaque variante directement sur la vignette.

Le module fonctionne en améliorant les widgets natifs de PrestaShop via JavaScript : il ne remplace aucun template du thème, ce qui le rend compatible avec Classic, Hummingbird et la plupart des thèmes premium.

Installation

1. Back-office → Modules → Module Manager → Téléverser un module
2. Glissez-déposez l’archive dfvariantswatch.zip puis cliquez sur Installer
3. Cliquez sur Configurer pour accéder aux réglages

L’installation crée la table df_variant_swatch, le dossier d’images img/dfvariantswatch/ et les valeurs de configuration par défaut. Aucune modification de thème n’est nécessaire.

Fonctionnement des vignettes

Pour chaque attribut, le module choisit la source de la vignette dans cet ordre de priorité :

1. Image uploadée en back-office pour cet attribut (onglet Vignettes par attribut)
2. Code couleur hexadécimal défini en back-office
3. Image dérivée automatiquement de la première combinaison utilisant cet attribut
4. Couleur native PrestaShop de l’attribut (champ couleur du groupe)
5. Pastille texte avec le nom de l’attribut

Le garde-fou des groupes non différenciés

La dérivation automatique n’est conservée que si les images diffèrent réellement entre les attributs du groupe, ou si le groupe est marqué comme groupe de couleurs dans PrestaShop. Concrètement : sur un produit avec un groupe Taille (S, M, L, XL) dont toutes les combinaisons partagent les mêmes photos, les tailles restent en pastilles texte au lieu d’afficher quatre fois la même photo.

Configuration

Paramètres généraux

• Activer le module — coupe le rendu front sans désinstaller
• Survol = changement de galerie — l’aperçu de la variante au survol d’une vignette
• Afficher le badge stock — état de disponibilité sous chaque vignette
• Masquer les variantes en rupture — cache complètement les vignettes épuisées au lieu de les barrer
• Forme — ronde, carrée ou pilule ; Taille en pixels
• Seuil stock faible — en dessous, le badge passe à l’état stock faible
• Libellés stock — les trois textes sont personnalisables et traduisibles via Localisation → Traductions
• Mode de chargement des données — Inline (recommandé) ou AJAX, voir ci-dessous
• Groupes non rendus en swatches — les groupes sélectionnés conservent leur widget natif

Vignettes par attribut

Cet onglet liste tous les groupes d’attributs de la boutique. Pour chaque valeur, vous pouvez uploader une image (jpg, png, webp ou gif, 2 Mo maximum, 200 sur 200 pixels recommandé) ou saisir un code couleur au format #RRGGBB, prévisualiser la vignette actuelle et supprimer un swatch existant.

Modes de chargement

Inline (défaut, recommandé) : les données de variantes sont embarquées dans la page au moment du rendu. Aucun appel AJAX au chargement, affichage immédiat des vignettes, robustesse maximale.

AJAX : les données sont récupérées via un appel après le chargement de la page. Réservez ce mode aux boutiques derrière un cache full-page agressif où la fraîcheur du stock affiché prime sur la vitesse d’affichage.

Accessibilité clavier

Le sélecteur implémente le pattern WAI-ARIA radiogroup : la touche Tab place le focus sur la variante sélectionnée du groupe (un seul point de tabulation par groupe), les flèches naviguent et sélectionnent au sein du groupe en bouclant et en sautant les variantes indisponibles, Espace ou Entrée valide la vignette focalisée. Les états sont annoncés aux lecteurs d’écran via aria-checked et les infobulles respectent prefers-reduced-motion.

Personnalisation CSS

Les variables CSS exposées permettent d’ajuster l’apparence depuis le CSS de votre thème enfant sans toucher au module :

.dfvs-swatch {
    --dfvs-size: 56px;   /* taille des vignettes */
}
.dfvs-swatch.dfvs-active {
    box-shadow: 0 0 0 2px #b8860b; /* anneau de la variante active */
}

Pour désactiver l’aperçu au survol sur un produit précis, ajoutez un élément portant l’attribut data-dfvs-disable-hover dans le template produit.

Dépannage

Les vignettes ne s’affichent pas

• Vérifiez que le module est activé dans sa configuration
• Ouvrez la console du navigateur : le module trace ses étapes avec le préfixe [dfvariantswatch] — vous verrez le nombre de groupes rendus ou la raison du non-rendu
• Le produit doit avoir des déclinaisons ; un produit simple n’affiche rien, c’est normal

Les tailles s’affichent en texte et pas en photo

C’est le comportement attendu du garde-fou : les valeurs du groupe partagent les mêmes photos de combinaisons. Uploadez des images dédiées par taille dans l’onglet Vignettes par attribut si vous souhaitez des visuels (par exemple des pictogrammes de gabarit).

Le bloc natif réapparaît après un clic

Le module ré-applique le masquage après chaque mise à jour AJAX de PrestaShop. Si un thème très personnalisé contourne les événements standards, contactez le support avec l’URL de la fiche produit concernée.

Désinstallation

La désinstallation supprime la table du module, les images uploadées dans img/dfvariantswatch/ et toutes les clés de configuration. Les photos de vos combinaisons ne sont évidemment pas touchées.