Compatibilité de thème
Indique au module l'emplacement exact des éléments de la galerie d'images de votre thème, afin que les vidéos s'affichent au bon endroit et se lisent correctement aux côtés du slider de votre thème.
Disponible depuis la v3.0.0
Présentation
Product Video fonctionne sans configuration supplémentaire avec le thème Classic par défaut de PrestaShop. Lorsque vous utilisez un thème personnalisé ou tiers, le module peut ne pas trouver la galerie d'images, la bande de miniatures ou le conteneur de l'image principale, car ces thèmes utilisent des noms de classes CSS et des structures HTML différents. La section Compatibilité de thème permet de décrire la structure de votre thème au module.
Consultez cette section si les vidéos n'apparaissent pas dans la galerie d'images, si les miniatures sont mal positionnées, si les vidéos ne se chargent pas au clic sur une miniature, ou si la vidéo entre en conflit avec le slider d'images de votre thème. La plupart des problèmes se résolvent en sélectionnant le bon Preset de thème et, si nécessaire, en ajustant quelques sélecteurs individuels.
La section est divisée en sous-sections : Sélecteurs principaux (les trois sélecteurs essentiels), Configuration du slider (pour les thèmes utilisant une bibliothèque de slider de galerie), Balisage des miniatures et images (ajustements de la structure HTML), Débogage, et Plus d'options (réglages de délai, d'interaction et de cas particuliers).
Configuration
Allez dans Modules > Gestionnaire de modules > Product Video > Configurer, puis cliquez sur l'onglet Compatibilité de thème.
Preset de thème
Sélectionnez votre version de PrestaShop pour remplir automatiquement tous les champs de sélecteurs principaux avec les valeurs correctes connues pour le thème par défaut de cette version. Après avoir sélectionné un preset, vérifiez les valeurs renseignées et cliquez sur Enregistrer.
| Option | Description |
|---|---|
| Personnalisé (manuel) | Tous les champs de sélecteurs restent tels quels ; vous les renseignez vous-même |
| PrestaShop 1.6 | Remplit les sélecteurs pour le thème PS 1.6 par défaut |
| PrestaShop 1.7 Classic | Remplit les sélecteurs pour le thème Classic de PS 1.7 |
| PrestaShop 8 | Remplit les sélecteurs pour le thème par défaut de PS 8 |
| PrestaShop 9 | Remplit les sélecteurs pour le thème par défaut de PS 9 |
Commencez par ici. Sélectionnez le preset correspondant à votre version de PS, enregistrez, puis testez sur une page produit avant de modifier quoi que ce soit d'autre. Cela résout la grande majorité des problèmes d'intégration de thème sans configuration supplémentaire.
Sélecteurs principaux
Ces trois sélecteurs sont les plus critiques. Si les vidéos n'apparaissent pas du tout dans la galerie d'images, ce sont les premiers champs à vérifier.
| Champ | Défaut PS 1.6 | Défaut PS 1.7 / 8 / 9 | Description |
|---|---|---|---|
| Image principale du produit | #bigpic | .product-cover:eq(0) img:eq(0) | Sélecteur pour l'élément <img> de la photo principale du produit. L'iframe vidéo remplace cette image. |
| Conteneur de l'image principale / Emplacement vidéo | #view_full_size | .product-cover:eq(0) | Sélecteur pour le conteneur autour de l'image principale. L'intégration vidéo est dimensionnée et positionnée dans cet élément. |
| Sélecteur du conteneur de miniatures | #thumbs_list_frame | .product-images:eq(0) | Sélecteur pour l'élément <ul> ou le wrapper qui contient toutes les miniatures d'images du produit. Les miniatures vidéo sont injectées dans ce conteneur. |
Tous les sélecteurs utilisent la syntaxe jQuery standard : .nomclasse pour les classes, #id pour les identifiants, :eq(0) pour cibler la première correspondance sur la page. Ouvrez les outils développeur de votre navigateur (F12, onglet Inspecteur) sur n'importe quelle page produit pour trouver les bons sélecteurs pour votre thème.
Paramètres de liste et d'interaction
| Champ | Options | Défaut | Description |
|---|---|---|---|
| Type de liste | li, div, a | li | L'élément HTML utilisé pour chaque miniature dans la liste de miniatures de votre thème. |
| Type d'événement au clic | mousedown, mouseup, click, tap | mousedown | L'événement jQuery utilisé pour détecter les clics sur les miniatures. Modifiez ce paramètre si les miniatures ne réagissent pas, ou seulement au deuxième clic. |
Configuration du slider
Si votre thème utilise une bibliothèque de slider d'images pour la galerie produit, vous devez indiquer au module laquelle, afin qu'il puisse insérer les miniatures vidéo dans le slider correctement.
| Champ | Options / Remarques | Défaut | Description |
|---|---|---|---|
| Slider d'images personnalisé | Slick Slider, BX Slider, Owl Carousel (pré-2.0), Owl Carrousel, Swiper Slider, Flickity Carousel, Light Slider, Bootstrap 5 Carousel | Aucun | Sélectionnez la bibliothèque de slider de votre thème. |
| Sélecteur du conteneur de miniatures du slider | Sélecteur jQuery | — | L'élément englobant la piste de miniatures dans le slider. Exemple : pour Swiper, pointez vers l'élément avec la classe .swiper-container. |
| Sélecteur du slider de l'image principale | Sélecteur jQuery | — | L'élément slider englobant l'image principale du produit. À renseigner si votre thème crée un slider pour la zone de l'image principale. |
| HTML du slider de l'image principale (avant) | HTML brut | — | HTML inséré avant chaque slide d'image. À utiliser si votre bibliothèque de slider nécessite une balise wrapper spécifique par slide. |
| HTML du slider de l'image principale (après) | HTML brut | — | HTML inséré après chaque slide d'image. |
| Synchroniser les sliders miniatures et image | Activé / Désactivé | Désactivé | À activer uniquement si le slider de miniatures et le slider d'image principale de votre thème sont synchronisés. |
| Rafraîchir le slider après ajout des éléments | Activé / Désactivé | Désactivé | Force la réinitialisation du slider après l'injection des miniatures vidéo. À activer si vous utilisez Slick Slider ou Owl Carousel v2 et que les miniatures vidéo ne sont pas visibles. |
Balisage des miniatures et images
Utilisez ces champs lorsque votre thème encadre les miniatures dans du HTML spécifique que le module doit reproduire autour des miniatures vidéo qu'il injecte.
| Champ | Défaut | Description |
|---|---|---|
| Classe(s) supplémentaire(s) pour les miniatures | — | Classes CSS ajoutées à chaque miniature vidéo injectée. Séparez plusieurs classes par des espaces. |
| Avant la miniature | — | HTML brut inséré avant chaque élément miniature. |
| Après la miniature | — | HTML brut inséré après chaque élément miniature. |
Lien miniature <a> | Désactivé | À activer si votre thème encadre chaque miniature dans une balise <a>. Le module génèrera un wrapper de lien correspondant autour de la miniature vidéo. |
Classes supplémentaires pour la balise <a> | — | Classes CSS pour l'élément de lien généré. Séparées par des espaces. |
| Classe supplémentaire pour la balise IMG | — | Classe CSS ajoutée à l'élément <img> de la miniature vidéo. |
Débogage
| Champ | Défaut | Description |
|---|---|---|
| Déboguer la génération vidéo dans la console navigateur | Désactivé | Affiche des journaux détaillés d'initialisation et d'injection dans la console navigateur. À utiliser lors du diagnostic de problèmes d'intégration. À désactiver en production. |
Plus d'options
Ces paramètres traitent des cas particuliers dans certains thèmes. Laissez-les à leurs valeurs par défaut sauf si vous avez un problème spécifique qu'ils sont destinés à résoudre.
| Champ | Défaut | Description |
|---|---|---|
| Délai de chargement | 0 ms | Millisecondes d'attente avant l'initialisation du module. À augmenter pour les thèmes JavaScript lourds qui finissent leur rendu après l'événement DOM-ready standard. |
| Délai de rafraîchissement AJAX / changement de déclinaison | 0 ms | Millisecondes d'attente avant la réinsertion des vidéos après un changement de déclinaison ou une mise à jour produit en AJAX. |
| Délai initial au changement de déclinaison | 0 ms | Délai supplémentaire avant la réinsertion de la vidéo après un changement de déclinaison. Laissez à 0 — la vérification de disponibilité du slider gère automatiquement le timing. |
| Direction des miniatures | Horizontal | Indique si votre thème affiche les miniatures en bande horizontale ou verticale. |
| Z-index de l'intégration vidéo | 1 | Z-index CSS pour l'élément vidéo intégré. À augmenter si la vidéo apparaît derrière d'autres éléments de la page, comme un en-tête fixe. |
| Fancy Box | Activé | Ouvre les vidéos dans une lightbox FancyBox au clic sur une miniature. À désactiver si votre thème possède sa propre lightbox et qu'il y a un conflit. |
| Éléments à masquer / afficher | — | Sélecteurs jQuery séparés par des virgules pour les éléments de la page à masquer pendant la lecture d'une vidéo. Ils réapparaissent lorsque le client revient à une image produit normale. |
| Utiliser l'élément sélectionné le plus profond | Désactivé | Force le module à cibler l'élément le plus profond dans le sélecteur (généralement <img>). À activer si les vidéos se déclenchent de façon incohérente ou ne disparaissent pas lors du retour à une image. |
| Désactiver le calcul de taille des miniatures | Désactivé | Empêche le module de redimensionner le conteneur de miniatures après l'injection des miniatures vidéo. À activer si les miniatures décalent le contenu de la page. |
| Désactiver le masquage de l'image principale | Désactivé | Empêche le module de masquer l'image principale du produit lors du chargement d'une vidéo. À utiliser pour les thèmes basés sur un slider affichant plusieurs images simultanément. |
| Désactiver le remplacement de l'image principale | Désactivé | Empêche le module de remplacer le contenu de l'élément image principale. À utiliser pour les thèmes basés sur un slider. |
| Masquer le conteneur de l'image principale | Désactivé | Masque l'intégralité du conteneur de l'image principale lors du chargement d'une vidéo, plutôt que de masquer uniquement l'image à l'intérieur. À utiliser pour les thèmes basés sur un slider. |
| Largeur supplémentaire de la liste de miniatures | 0 | Pixels supplémentaires ajoutés à la largeur du conteneur de miniatures. À utiliser si la miniature vidéo injectée déborde de la bande. Mettre à 0 pour désactiver. |
| Désactiver l'utilisation des miniatures | Désactivé | Contourne entièrement l'injection de miniatures. À utiliser pour les thèmes avec un affichage en grille large qui n'utilise pas de bande de miniatures. |
| Désactiver le padding dans l'intégration | Désactivé | Supprime le wrapper de padding responsive de l'intégration vidéo. À activer si la vidéo apparaît surdimensionnée. |
| Délai entre les changements de miniatures | 0 ms | Millisecondes d'attente entre les événements de changement de miniature. À utiliser si le module se déclenche plus vite que le système de gestion des miniatures du thème, provoquant la réapparition de l'image précédente. |
Blocage de l'interaction vidéo (YouTube uniquement)
Ces paramètres permettent de placer un calque invisible sur le lecteur YouTube pour empêcher l'interaction directe de l'utilisateur tout en gardant la vidéo visible. Cela est utile pour afficher une vidéo en lecture automatique en arrière-plan et masquer les éléments d'interface de YouTube.
| Champ | Défaut | Description |
|---|---|---|
| Bloquer l'interaction vidéo | Désactivé | Ajoute une <div> invisible sur l'intégration YouTube, empêchant les clics, la lecture/pause et l'affichage des contrôles YouTube. |
| Afficher l'icône lecture en pause | Activé | Affiche une icône de lecture circulaire sur la vidéo bloquée lorsqu'elle est en pause. |
| Afficher l'icône pause en lecture | Activé | Affiche une icône de pause circulaire pendant la lecture de la vidéo bloquée. |
| Garder l'icône d'action affichée | Activé | Maintient l'icône pause/lecture en permanence plutôt que de la laisser disparaître. |
Fonctionnement
Lorsqu'un client visite une page produit, le module exécute du JavaScript qui parcourt le DOM de la page en utilisant vos sélecteurs CSS configurés. Il localise l'élément image principale, le conteneur d'image et la liste de miniatures, puis injecte la miniature vidéo dans la liste et positionne l'intégration vidéo dans le conteneur d'image.
Correspondance des sélecteurs
Le module cible les éléments en utilisant des sélecteurs jQuery standard. Si un sélecteur ne retourne aucun élément — parce que votre thème utilise des noms de classes ou des identifiants différents — rien n'est injecté et la galerie apparaît inchangée. Des erreurs apparaissent dans la console navigateur lorsque Déboguer la génération vidéo est activé.
Intégration du slider
Pour les thèmes qui encadrent la galerie dans une bibliothèque de slider JavaScript, le module effectue des étapes supplémentaires après l'injection : il appelle l'API du slider pour ajouter la nouvelle slide de miniature, et rafraîchit optionnellement le slider pour que la nouvelle slide soit visible. L'appel d'API exact dépend de la bibliothèque de slider sélectionnée dans Slider d'images personnalisé. Si votre bibliothèque de slider ne figure pas dans la liste, utilisez les champs de sélecteurs manuels (PV_SLIDER_THUMB_SEL, PV_SLIDER_IMG_SEL) pour définir les éléments que le module doit cibler.
Timing
Les thèmes lourds initialisent parfois leurs sliders ou mettent à jour la galerie produit en AJAX après le déclenchement de l'événement DOM-ready du module. Les champs Délai de chargement et Délai de rafraîchissement AJAX / changement de déclinaison ajoutent une période d'attente avant que le module tente l'injection, garantissant que les éléments de la galerie existent au moment où le module les recherche.
Exemples d'utilisation
Exemple : thème personnalisé avec une classe de conteneur de miniatures différente
Votre thème utilise .product-gallery__thumbs à la place de .product-images. Ouvrez la page produit dans votre navigateur, inspectez le conteneur de miniatures (F12 > cliquez sur l'élément), copiez sa classe. Dans l'onglet Compatibilité de thème, définissez le Sélecteur du conteneur de miniatures sur .product-gallery__thumbs et enregistrez. Les vidéos apparaissent désormais dans la bande de miniatures.
Exemple : thème utilisant Swiper Slider
Votre thème marketplace utilise Swiper pour la galerie d'images produit. Sélectionnez Swiper Slider dans Slider d'images personnalisé. Définissez le Sélecteur du conteneur de miniatures du slider sur le sélecteur CSS de l'élément avec la classe .swiper-container sur votre page produit. Activez Rafraîchir le slider après ajout des éléments et enregistrez. La miniature vidéo apparaît désormais comme une slide dans la galerie Swiper.
Exemple : la vidéo apparaît derrière une barre de navigation fixe
Après le chargement d'une vidéo, elle est masquée sous l'en-tête fixe du site (z-index 1000). Définissez le Z-index de l'intégration vidéo sur 1001 et enregistrez. L'intégration vidéo apparaît désormais au-dessus de l'en-tête.
Exemple : les vidéos disparaissent lors du changement de déclinaison produit
Après le changement d'un attribut produit (taille, couleur), la vidéo disparaît et ne réapparaît pas. Définissez le Délai de rafraîchissement AJAX / changement de déclinaison sur 300 et enregistrez. Le module attend désormais 300 ms que le thème finisse de mettre à jour la galerie avant de réinsérer la vidéo.
Points importants
- Le preset de thème remplit automatiquement mais n'enregistre pas automatiquement. Après avoir sélectionné un preset, vérifiez toujours les sélecteurs renseignés et cliquez sur Enregistrer avant de tester.
- Bibliothèques de slider absentes de la liste. Si le slider de votre thème ne figure pas dans la liste déroulante Slider d'images personnalisé, renseignez manuellement les champs de sélecteurs
PV_SLIDER_THUMB_SELetPV_SLIDER_IMG_SELet activez Rafraîchir le slider pour couvrir la plupart des cas. - Multi-boutique. Ces paramètres sont configurés par boutique. Si vous gérez des boutiques avec des thèmes différents, configurez l'onglet Compatibilité de thème pour chaque boutique séparément.
- Désactivez le padding avec précaution. Activer Désactiver le padding dans l'intégration supprime le wrapper de ratio d'aspect. Sur certains thèmes, cela crée une intégration correctement dimensionnée ; sur d'autres, la vidéo se réduit à une hauteur nulle. Activez-le et enregistrez pour voir quel comportement s'applique à votre thème.
- Le blocage de l'interaction vidéo est réservé à YouTube. Le calque invisible ne fonctionne pas avec les intégrations Vimeo ou HTML5.
- Mode débogage en production. Laisser Déboguer la génération vidéo activé sur une boutique en ligne ne casse rien, mais ajoute des sorties console visibles par tout client qui ouvre les outils développeur. Désactivez-le une fois votre intégration fonctionnelle.
Dépannage
| Problème | Solution |
|---|---|
| Les vidéos n'apparaissent pas dans la galerie | Commencez par le Preset de thème correspondant à votre version de PS. Si cela ne résout pas le problème, utilisez les outils développeur du navigateur (F12 > Inspecteur) pour trouver les noms de classes réels sur l'image principale, le conteneur d'image et la liste de miniatures, puis mettez à jour les trois champs de sélecteurs principaux. |
| La vidéo apparaît au mauvais endroit | Le sélecteur Conteneur de l'image principale / Emplacement vidéo pointe vers le mauvais élément. Inspectez la page et identifiez le wrapper direct autour de l'image principale. |
| La vidéo apparaît derrière d'autres éléments de la page | Augmentez le Z-index de l'intégration vidéo au-dessus du z-index de l'élément qui la recouvre (les en-têtes fixes ont souvent un z-index de 1000 à 9999). |
| Le clic sur la miniature nécessite deux clics | Changez le Type d'événement au clic de mousedown à click. |
| La miniature vidéo n'est pas visible dans le slider | Si vous utilisez Slick Slider ou Owl Carousel v2, activez Rafraîchir le slider après ajout des éléments. |
| Les vidéos disparaissent après le changement de déclinaison | Définissez une valeur de 200 à 500 pour le Délai de rafraîchissement AJAX / changement de déclinaison. |
| La vidéo apparaît surdimensionnée ou déformée | Activez Désactiver le padding dans l'intégration et testez. Si le problème persiste, vérifiez que le sélecteur Conteneur de l'image principale pointe vers le bon élément conteneur. |
| La galerie fonctionne au chargement de la page mais se bloque après la navigation AJAX | Activez Rafraîchir le slider après ajout des éléments et, si nécessaire, augmentez le Délai de rafraîchissement AJAX / changement de déclinaison. |
| La miniature vidéo repousse les autres miniatures hors de l'écran | Activez Désactiver le calcul de taille des miniatures pour empêcher le module de redimensionner le conteneur de miniatures. |
Questions fréquentes
Comment trouver le bon sélecteur CSS pour le conteneur de miniatures de mon thème ?
Ouvrez une page produit dans votre navigateur et appuyez sur F12 pour ouvrir les outils développeur. Cliquez sur l'onglet Inspecteur ou Éléments, puis cliquez directement sur la bande de miniatures de la page produit. Le panneau HTML met en surbrillance l'élément. Regardez son attribut id ou class — il devient votre sélecteur, précédé de # pour les identifiants ou . pour les classes.
Mon thème utilise Slick Slider et les miniatures vidéo sont injectées mais invisibles. Que faire ?
Activez Rafraîchir le slider après ajout des éléments dans la section Configuration du slider. Cela indique au module d'appeler l'API slickAdd de Slick après l'injection de la miniature, pour que le slider enregistre la nouvelle slide et la rende visible.
Puis-je utiliser plusieurs sélecteurs CSS dans un seul champ ?
Oui. jQuery accepte les sélecteurs séparés par des virgules (par exemple .product-cover, .product-image). Cependant, utiliser le sélecteur unique le plus spécifique correspondant à votre thème évite les correspondances involontaires avec d'autres éléments.
La sélection d'un preset de thème écrase-t-elle mes sélecteurs existants ?
Oui. La sélection d'un preset remplit automatiquement les champs de sélecteurs principaux avec les valeurs par défaut du preset. Si vous avez personnalisé ces champs, l'application d'un preset remplacera vos valeurs. Vérifiez les trois champs de sélecteurs principaux après avoir appliqué un preset avant d'enregistrer.
J'ai activé le mode débogage mais je ne vois aucune sortie dans la console. Que se passe-t-il ?
Assurez-vous d'ouvrir la console navigateur (F12 > onglet Console) avant de recharger la page produit — les sorties de débogage sont écrites lors de l'initialisation de la page et n'apparaîtront pas si la console est ouverte après le chargement de la page.
Le blocage de l'interaction vidéo fonctionne-t-il avec les vidéos Vimeo ou HTML5 ?
Non. Le calque invisible est réservé à YouTube. Activer Bloquer l'interaction vidéo sur un produit avec une vidéo Vimeo ou HTML5 n'aura aucun effet visible.
Ces paramètres affectent-ils toutes les boutiques dans une configuration multi-boutique ?
Les paramètres de compatibilité de thème sont spécifiques à chaque boutique. Basculez sur la boutique que vous souhaitez configurer dans le sélecteur de boutique du Back Office avant d'enregistrer les modifications.