Compatibilidad con el Tema
Indica al módulo exactamente dónde se encuentran los elementos de la galería de imágenes de tu tema para que los vídeos aparezcan en el lugar correcto y se reproduzcan correctamente junto al carrusel del tema.
Disponible desde v3.0.0
Descripción general
Product Video funciona de forma inmediata con el tema Classic predeterminado de PrestaShop. Cuando se utiliza un tema personalizado o de terceros, es posible que el módulo no encuentre la galería de imágenes, la tira de miniaturas o el contenedor principal de imágenes, ya que esos temas usan nombres de clase CSS y estructuras HTML diferentes. La sección Compatibilidad con el Tema es donde se describe la estructura del tema al módulo.
Deberías visitar esta sección si los vídeos no aparecen en la galería de imágenes, las miniaturas están mal posicionadas, los vídeos no se cargan al hacer clic en una miniatura, o el vídeo entra en conflicto con el carrusel de imágenes del tema. La mayoría de los problemas se resuelven seleccionando el Preset de Tema correcto y, si es necesario, ajustando algunos selectores individuales.
La sección está dividida en subsecciones: Selectores Principales (los tres selectores esenciales), Configuración del Carrusel (para temas que usan una biblioteca de carrusel de galería), Marcado de Miniaturas e Imágenes (ajustes de estructura HTML), Depuración y Más Opciones (ajustes de temporización, interacción y casos límite).
Configuración
Ve a Módulos > Gestor de módulos > Product Video > Configurar y haz clic en la pestaña Compatibilidad con el Tema.
Preset de Tema
Selecciona tu versión de PrestaShop para rellenar automáticamente todos los campos de selectores principales con los valores correctos conocidos para el tema predeterminado de esa versión. Tras seleccionar un preset, revisa los valores rellenados y haz clic en Guardar.
| Opción | Descripción |
|---|---|
| Personalizado (manual) | Todos los campos de selectores permanecen como están; los rellenas tú mismo |
| PrestaShop 1.6 | Rellena los selectores para el tema predeterminado de PS 1.6 |
| PrestaShop 1.7 Classic | Rellena los selectores para el tema Classic de PS 1.7 |
| PrestaShop 8 | Rellena los selectores para el tema predeterminado de PS 8 |
| PrestaShop 9 | Rellena los selectores para el tema predeterminado de PS 9 |
Empieza aquí. Selecciona el preset de tu versión de PS, guarda y prueba en una página de producto antes de modificar cualquier otra cosa. Esto resuelve la mayoría de los problemas de integración con el tema sin necesidad de configuración adicional.
Selectores Principales
Estos tres selectores son los más críticos. Si los vídeos no aparecen en la galería de imágenes en absoluto, estos son los primeros campos que debes revisar.
| Campo | Por defecto PS 1.6 | Por defecto PS 1.7 / 8 / 9 | Descripción |
|---|---|---|---|
| Imagen principal del producto | #bigpic | .product-cover:eq(0) img:eq(0) | Selector para el elemento <img> de la foto principal del producto. El iframe de vídeo reemplaza esta imagen. |
| Contenedor de imagen principal / Marcador de posición de vídeo | #view_full_size | .product-cover:eq(0) | Selector para el contenedor alrededor de la imagen principal. El vídeo incrustado se dimensiona y posiciona dentro de este elemento. |
| Selector para el contenedor de miniaturas | #thumbs_list_frame | .product-images:eq(0) | Selector para el elemento <ul> o el contenedor que alberga todas las miniaturas de imágenes del producto. Las miniaturas de vídeo se inyectan en este contenedor. |
Todos los selectores usan sintaxis jQuery estándar: .classname para clases, #id para IDs, :eq(0) para apuntar al primer resultado en la página. Abre las herramientas de desarrollo del navegador (F12, pestaña Inspector) en cualquier página de producto para encontrar los selectores correctos para tu tema.
Configuración de Lista e Interacción
| Campo | Opciones | Por defecto | Descripción |
|---|---|---|---|
| Tipo de lista | li, div, a | li | El elemento HTML usado para cada miniatura en la lista de miniaturas del tema. |
| Tipo de comportamiento al hacer clic | mousedown, mouseup, click, tap | mousedown | El evento jQuery usado para detectar clics en miniaturas. Cámbialo si las miniaturas no responden o solo responden al segundo clic. |
Configuración del Carrusel
Si tu tema usa una biblioteca de carrusel de imágenes para la galería de productos, debes indicar al módulo cuál es para que pueda insertar las miniaturas de vídeo en el carrusel correctamente.
| Campo | Opciones / Notas | Por defecto | Descripción |
|---|---|---|---|
| Carrusel de imágenes personalizado | Slick Slider, BX Slider, Owl Carousel (pre-2.0), Owl Carrousel, Swiper Slider, Flickity Carousel, Light Slider, Bootstrap 5 Carousel | Ninguno | Selecciona la biblioteca de carrusel de tu tema. |
| Selector para el contenedor de miniaturas del carrusel | Selector jQuery | — | El elemento que envuelve la pista de miniaturas dentro del carrusel. Ejemplo: para Swiper, apunta al elemento con la clase .swiper-container. |
| Selector para el carrusel de la imagen principal | Selector jQuery | — | El elemento del carrusel que envuelve la imagen principal del producto. Rellénalo si tu tema construye un carrusel para el área de imagen principal. |
| HTML del carrusel de imagen principal (antes) | HTML sin procesar | — | HTML insertado antes de cada diapositiva de imagen. Úsalo si tu biblioteca de carrusel requiere una etiqueta contenedora específica por diapositiva. |
| HTML del carrusel de imagen principal (después) | HTML sin procesar | — | HTML insertado después de cada diapositiva de imagen. |
| Sincronizar los carruseles de miniaturas e imágenes | Activado / Desactivado | Desactivado | Actívalo solo si el carrusel de miniaturas y el carrusel de imagen principal de tu tema están sincronizados. |
| Actualizar el carrusel tras añadir los elementos | Activado / Desactivado | Desactivado | Fuerza la reinicialización del carrusel tras inyectar las miniaturas de vídeo. Actívalo si usas Slick Slider u Owl Carousel v2 y las miniaturas de vídeo no son visibles. |
Marcado de Miniaturas e Imágenes
Usa estos campos cuando tu tema envuelva las miniaturas en HTML específico que el módulo debe replicar alrededor de las miniaturas de vídeo que inyecta.
| Campo | Por defecto | Descripción |
|---|---|---|
| Clase(s) adicional(es) para los elementos de miniatura | — | Clases CSS añadidas a cada elemento de miniatura de vídeo inyectado. Separa varias clases con espacios. |
| Antes de la miniatura | — | HTML sin procesar insertado antes de cada elemento de miniatura. |
| Después de la miniatura | — | HTML sin procesar insertado después de cada elemento de miniatura. |
Enlace de miniatura <a> | Desactivado | Actívalo si tu tema envuelve cada miniatura en una etiqueta <a>. El módulo generará un contenedor de enlace equivalente alrededor de la miniatura de vídeo. |
Clases adicionales para la etiqueta de enlace <a> | — | Clases CSS para el elemento de enlace generado. Separadas por espacios. |
| Clase adicional para la etiqueta IMG | — | Clase CSS añadida al elemento <img> de la miniatura de vídeo. |
Depuración
| Campo | Por defecto | Descripción |
|---|---|---|
| Depurar la generación de vídeo en la consola del navegador | Desactivado | Muestra registros detallados de inicialización e inyección en la consola del navegador. Úsalo al diagnosticar problemas de integración. Desactívalo en producción. |
Más Opciones
Estos ajustes abordan casos límite específicos en ciertos temas. Déjalos en sus valores predeterminados a menos que tengas un problema concreto que estén diseñados para resolver.
| Campo | Por defecto | Descripción |
|---|---|---|
| Retraso de carga | 0 ms | Milisegundos de espera antes de que el módulo se inicialice. Auméntalo en temas con JavaScript pesado que terminan de renderizarse después del evento DOM-ready estándar. |
| Retraso de actualización tras cambio AJAX / de combinación | 0 ms | Milisegundos de espera antes de reinsertar vídeos tras un cambio de combinación o una actualización AJAX del producto. |
| Retraso inicial al cambiar de combinación | 0 ms | Retraso adicional antes de reinsertar el vídeo tras un cambio de combinación. Déjalo en 0; el control de preparación del carrusel gestiona la temporización automáticamente. |
| Dirección de las miniaturas | Horizontal | Si tu tema muestra las miniaturas en una tira horizontal o vertical. |
| Z-index del vídeo incrustado | 1 | Z-index CSS para el elemento de vídeo incrustado. Auméntalo si el vídeo aparece detrás de otros elementos de la página, como una cabecera fija. |
| Fancy Box | Activado | Abre los vídeos en un lightbox FancyBox al hacer clic en una miniatura. Desactívalo si tu tema tiene su propio lightbox y hay un conflicto. |
| Elementos para ocultar / mostrar | — | Selectores jQuery separados por comas para los elementos de la página que se ocultan mientras se reproduce un vídeo. Vuelven a aparecer cuando el cliente cambia a una imagen normal del producto. |
| Usar el elemento seleccionado más profundo | Desactivado | Obliga al módulo a apuntar al elemento más profundo dentro del selector (normalmente <img>). Actívalo si los vídeos se activan de forma inconsistente o no desaparecen al volver a una imagen. |
| Desactivar el cálculo del tamaño de las miniaturas | Desactivado | Evita que el módulo redimensione el contenedor de miniaturas tras inyectar las miniaturas de vídeo. Actívalo si las miniaturas desplazan el contenido de la página. |
| Desactivar ocultar imagen principal | Desactivado | Impide que el módulo oculte la imagen principal del producto cuando se carga un vídeo. Úsalo con temas basados en carrusel que muestran varias imágenes simultáneamente. |
| Desactivar el reemplazo de la imagen principal | Desactivado | Impide que el módulo reemplace el contenido del elemento de imagen principal. Úsalo con temas basados en carrusel. |
| Ocultar el contenedor de imágenes | Desactivado | Oculta todo el contenedor de imagen principal cuando se carga un vídeo, en lugar de ocultar solo la imagen dentro de él. Úsalo con temas basados en carrusel. |
| Anchura adicional para la lista de miniaturas | 0 | Píxeles adicionales añadidos al ancho del contenedor de miniaturas. Úsalo si la miniatura de vídeo inyectada desborda la tira. Establece 0 para desactivarlo. |
| Desactivar el uso de miniaturas | Desactivado | Omite por completo la inyección de miniaturas. Úsalo en temas con una visualización de imágenes en cuadrícula grande que no utiliza una tira de miniaturas. |
| Desactivar el relleno en el vídeo incrustado | Desactivado | Elimina el contenedor de relleno responsive del vídeo incrustado. Actívalo si el vídeo aparece demasiado grande. |
| Retraso entre cambios de miniatura | 0 ms | Milisegundos de espera entre eventos de cambio de miniatura. Úsalo si el módulo se ejecuta más rápido que el sistema de gestión de miniaturas del tema, causando que la imagen anterior reaparezca. |
Bloqueo de Interacción con el Vídeo (solo YouTube)
Estos ajustes te permiten colocar una capa invisible sobre el reproductor de YouTube para evitar la interacción directa del usuario manteniendo el vídeo visible. Resulta útil al mostrar un vídeo de reproducción automática en segundo plano y quieres ocultar los elementos de la interfaz de YouTube.
| Campo | Por defecto | Descripción |
|---|---|---|
| Bloquear la interacción con el vídeo | Desactivado | Añade un <div> invisible sobre el vídeo de YouTube, impidiendo los clics, la reproducción/pausa y que aparezcan los controles de YouTube. |
| Mostrar icono de reproducción cuando está en pausa | Activado | Muestra un icono circular de reproducción sobre el vídeo bloqueado cuando está en pausa. |
| Mostrar icono de pausa mientras se reproduce | Activado | Muestra un icono circular de pausa mientras el vídeo bloqueado se está reproduciendo. |
| Mantener el icono de acción siempre visible | Activado | Mantiene el icono de pausa/reproducción permanentemente visible en lugar de dejarlo desaparecer. |
Cómo Funciona
Cuando un cliente visita una página de producto, el módulo ejecuta JavaScript que recorre el DOM de la página usando los selectores CSS configurados. Localiza el elemento de imagen principal, el contenedor de imágenes y la lista de miniaturas, luego inyecta la miniatura de vídeo en la lista y posiciona el vídeo incrustado dentro del contenedor de imágenes.
Coincidencia de selectores
El módulo apunta a los elementos usando selectores jQuery estándar. Si un selector no devuelve ningún elemento —porque tu tema usa nombres de clase o IDs diferentes— no se inyecta nada y la galería aparece sin cambios. Los errores aparecen en la consola del navegador cuando está activada la opción Depurar generación de vídeo.
Integración con el carrusel
Para los temas que envuelven la galería en una biblioteca de carrusel JavaScript, el módulo realiza pasos adicionales tras la inyección: llama a la API del carrusel para añadir la nueva diapositiva de miniatura y, opcionalmente, actualiza el carrusel para que la nueva diapositiva sea visible. La llamada exacta a la API depende de la biblioteca de carrusel seleccionada en Carrusel de imágenes personalizado. Si tu biblioteca de carrusel no está en la lista, usa los campos de selector manuales (PV_SLIDER_THUMB_SEL, PV_SLIDER_IMG_SEL) para definir los elementos que el módulo debe apuntar.
Temporización
Los temas pesados a veces inicializan sus carruseles o actualizan la galería de productos mediante AJAX después de que se dispare el evento DOM-ready del módulo. Los campos Retraso de carga y Retraso de actualización tras cambio AJAX / de combinación añaden un período de espera antes de que el módulo intente la inyección, garantizando que los elementos de la galería existan cuando el módulo los busque.
Ejemplos de Uso
Ejemplo: Tema personalizado con una clase de contenedor de miniaturas diferente
Tu tema usa .product-gallery__thumbs en lugar de .product-images. Abre la página de producto en el navegador, inspecciona el contenedor de miniaturas (F12 > haz clic en el elemento), copia su clase. En la pestaña Compatibilidad con el Tema, establece Selector para el contenedor de miniaturas como .product-gallery__thumbs y guarda. Los vídeos aparecen ahora en la tira de miniaturas.
Ejemplo: Tema que usa Swiper Slider
Tu tema de marketplace usa Swiper para la galería de imágenes del producto. Selecciona Swiper Slider en Carrusel de imágenes personalizado. Establece Selector para el contenedor de miniaturas del carrusel con el selector CSS del elemento con la clase .swiper-container en tu página de producto. Activa Actualizar el carrusel tras añadir los elementos y guarda. La miniatura de vídeo aparece ahora como una diapositiva dentro de la galería Swiper.
Ejemplo: El vídeo aparece detrás de una barra de navegación fija
Tras cargar un vídeo, queda oculto debajo de la cabecera fija del sitio (z-index 1000). Establece Z-index del vídeo incrustado en 1001 y guarda. El vídeo incrustado aparece ahora por encima de la cabecera.
Ejemplo: Los vídeos se rompen al cambiar combinaciones del producto
Después de cambiar un atributo del producto (talla, color), el vídeo desaparece y no vuelve a aparecer. Establece Retraso de actualización tras cambio AJAX / de combinación en 300 y guarda. El módulo esperará ahora 300 ms para que el tema termine de actualizar la galería antes de reinsertar el vídeo.
Notas Importantes
- El preset de tema rellena automáticamente pero no guarda automáticamente. Tras seleccionar un preset, revisa siempre los selectores rellenados y haz clic en Guardar antes de probar.
- Bibliotecas de carrusel no incluidas en la lista. Si el carrusel de tu tema no está en el desplegable Carrusel de imágenes personalizado, rellena los campos de selector
PV_SLIDER_THUMB_SELyPV_SLIDER_IMG_SELmanualmente y activa Actualizar el carrusel para cubrir la mayoría de los casos. - Multi-tienda. Estos ajustes se configuran por tienda. Si tienes tiendas con temas diferentes, configura la pestaña Compatibilidad con el Tema para cada tienda por separado.
- Desactiva el relleno con precaución. Activar Desactivar el relleno en el vídeo incrustado elimina el contenedor de relación de aspecto. En algunos temas esto crea un vídeo incrustado con el tamaño correcto; en otros el vídeo se colapsa a cero de altura. Actívalo y guarda para ver qué comportamiento se aplica a tu tema.
- El bloqueo de interacción con el vídeo es solo para YouTube. La capa invisible no funciona con vídeos de Vimeo ni con vídeos HTML5.
- Modo de depuración en producción. Dejar activada la opción Depurar generación de vídeo en una tienda en producción no rompe nada, pero añade salida en la consola visible para cualquier cliente que abra las herramientas de desarrollo. Desactívala una vez que tu integración esté funcionando.
Solución de Problemas
| Problema | Solución |
|---|---|
| Los vídeos no aparecen en la galería | Empieza con el Preset de Tema para tu versión de PS. Si no ayuda, usa las herramientas de desarrollo del navegador (F12 > Inspector) para encontrar los nombres de clase reales en la imagen principal, el contenedor de imágenes y la lista de miniaturas, luego actualiza los tres campos de Selectores Principales. |
| El vídeo aparece en la posición incorrecta | El selector Contenedor de imagen principal / Marcador de posición de vídeo está apuntando al elemento incorrecto. Inspecciona la página e identifica el contenedor directo alrededor de la imagen principal. |
| El vídeo aparece detrás de otros elementos de la página | Aumenta el Z-index del vídeo incrustado por encima del z-index del elemento que se superpone (las cabeceras fijas suelen tener valores entre 1000 y 9999). |
| El clic en la miniatura requiere dos clics para activarse | Cambia el Tipo de comportamiento al hacer clic de mousedown a click. |
| La miniatura de vídeo no es visible en el carrusel | Si usas Slick Slider u Owl Carousel v2, activa Actualizar el carrusel tras añadir los elementos. |
| Los vídeos desaparecen al cambiar una variante del producto | Añade un valor de 200–500 al Retraso de actualización tras cambio AJAX / de combinación. |
| El vídeo aparece demasiado grande o distorsionado | Activa Desactivar el relleno en el vídeo incrustado y prueba. Si sigue mal, verifica que el selector Contenedor de imagen principal apunte al elemento contenedor correcto. |
| La galería funciona al cargar la página pero falla tras la navegación AJAX | Activa Actualizar el carrusel tras añadir los elementos y, si es necesario, aumenta el Retraso de actualización tras cambio AJAX / de combinación. |
| La miniatura de vídeo empuja a otras miniaturas fuera de la pantalla | Activa Desactivar el cálculo del tamaño de las miniaturas para impedir que el módulo redimensione el contenedor de miniaturas. |
Preguntas Frecuentes
¿Cómo encuentro el selector CSS correcto para el contenedor de miniaturas de mi tema?
Abre una página de producto en el navegador y pulsa F12 para abrir las herramientas de desarrollo. Haz clic en la pestaña Inspector o Elementos, luego haz clic directamente sobre la tira de miniaturas en la página de producto. El panel HTML resalta el elemento. Fíjate en su atributo id o class — eso se convierte en tu selector, con # como prefijo para los IDs o . para las clases.
Mi tema usa Slick Slider y las miniaturas de vídeo se inyectan pero no son visibles. ¿Qué debo hacer?
Activa Actualizar el carrusel tras añadir los elementos en la sección Configuración del Carrusel. Esto indica al módulo que llame a la API slickAdd de Slick después de inyectar la miniatura para que el carrusel registre la nueva diapositiva y la haga visible.
¿Puedo usar varios selectores CSS en un mismo campo?
Sí. jQuery acepta selectores separados por comas (por ejemplo .product-cover, .product-image). Sin embargo, usar el selector individual más específico que coincida con tu tema evita coincidencias no deseadas en otros elementos.
¿Cambiar el Preset de Tema sobreescribe mis selectores existentes?
Sí. Seleccionar un preset rellena automáticamente los campos de Selectores Principales con los valores predeterminados del preset. Si has personalizado esos campos, aplicar un preset reemplazará tus valores. Revisa los tres campos de Selectores Principales después de aplicar un preset antes de guardar.
Activé el modo de depuración pero no veo ninguna salida en la consola. ¿Qué está fallando?
Asegúrate de abrir la consola del navegador (F12 > pestaña Consola) antes de recargar la página de producto — la salida de depuración se escribe durante la inicialización de la página y no aparecerá si la consola se abre después de que se cargue la página.
¿Funciona el bloqueo de interacción con el vídeo con Vimeo o vídeos HTML5?
No. La capa invisible es solo para YouTube. Activar Bloquear la interacción con el vídeo en un producto que tiene un vídeo de Vimeo o HTML5 no tendrá ningún efecto visible.
¿Estos ajustes afectan a todas las tiendas en una configuración multi-tienda?
Los ajustes de Compatibilidad con el Tema son específicos de cada tienda. Cambia a la tienda que quieras configurar en el selector de tiendas del Back Office antes de guardar los cambios.