Brand Carousel: documentación del carrusel de marcas PrestaShop

Instalación

En el back office, abra Módulos > Gestor de módulos, haga clic en «Subir un módulo» y envíe el archivo dfbrandcarousel-2.0.0.zip. El módulo es compatible con PrestaShop 8.0 a 9.x.

Al instalarse, el módulo crea sus dos tablas, el hook displayDfBrandCarousel, la carpeta /img/dfbrandcarousel/ para los logos alternativos y un primer bloque: un carrusel de marcas en la página de inicio (displayHome) con el título «Nuestras marcas» traducido a cada idioma instalado. Abra su tienda para ver el resultado y después modifique o elimine ese bloque.

El módulo se gestiona desde su botón «Configurar» en el Gestor de módulos.

Actualización desde la versión 1.0.x

Suba el ZIP 2.0.0 sobre la versión instalada. El script de actualización crea las nuevas tablas y traslada su configuración a un bloque llamado «Brand carousel», en el mismo hook: título, número de marcas, columnas, desplazamiento automático, velocidad, espaciado, flechas, puntos, marcas seleccionadas y orden aleatorio. Las marcas sin productos siguen visibles como antes. Los antiguos ajustes DFBC_* se eliminan a continuación. Swiper ya no se usa, lo que resuelve los conflictos con temas y maquetadores que cargan su propia versión.

La lista de bloques

La pestaña Bloques muestra sus bloques con su modo, su hook y su origen. Para cada bloque puede:

• Activar o desactivar el bloque con el interruptor.
• Editar el bloque en el editor.
• Duplicar el bloque. La copia se crea desactivada.
• Eliminar el bloque.
• Arrastrar los bloques para fijar su orden cuando varios comparten el mismo hook.

El botón «Vaciar la caché» borra la caché de marcas, contadores y ventas (vea Caché y rendimiento).

El editor de bloques

El editor muestra los ajustes a la izquierda, repartidos en 5 pestañas, y una vista previa a la derecha. La vista previa se actualiza con cada cambio y puede mostrarse en ancho de ordenador, tableta o móvil. Usa una fuente neutra: en la tienda, el bloque utiliza las fuentes de su tema.

La barra superior contiene el nombre interno del bloque, el interruptor de activación, el selector de idioma de los campos traducibles y el botón Guardar. Un indicador señala los cambios sin guardar y Ctrl+S (Cmd+S en Mac) guarda sin salir del editor.

Pestaña Contenido

Encabezado

• Título y subtítulo: por idioma. Deje el título vacío para ocultarlo.
• Etiqueta del título: H2 en la página de inicio, H3 en una página que ya tiene títulos H2, o p y div para un título sin función de encabezado.
• Disposición del encabezado: título a la izquierda y enlace a la derecha, todo a la izquierda o centrado. En los dos últimos casos, el enlace pasa debajo de los logos.
• Enlace a todas las marcas: texto por idioma y URL. Sin URL, el enlace lleva a la página de marcas de PrestaShop.

Marcas que mostrar

• Todas las marcas activas de la tienda.
• Selección manual: añada marcas desde la lista de la izquierda con el botón + y reordénelas arrastrándolas en la lista de la derecha. «Añadir toda la lista» añade las marcas de la búsqueda actual.
• Marcas de una categoría: marcas con al menos un producto visible en la categoría elegida o en sus subcategorías.
• Marcas de la categoría actual: en una página de categoría, las marcas de esa categoría. En una ficha de producto, las de su categoría principal. En el resto, todas las marcas.

Estos ajustes completan el origen:

• Marcas excluidas: se retiran de la lista, salvo en selección manual.
• Orden: su orden (selección manual), alfabético, primero las que tienen más productos, primero las más vendidas en un periodo de 7 a 730 días, primero las marcas más recientes o aleatorio en cada visita. El orden alfabético ignora acentos y puntuación: L’Oréal se ordena como «loreal».
• Número máximo de marcas: 0 muestra todas las marcas que coinciden.
• Productos mínimos: 1 por defecto, para no enviar al visitante a una página de marca vacía.
• Solo marcas con logo: el filtro se aplica antes del número máximo, así obtiene el número pedido.

El orden aleatorio se calcula en el navegador. Una caché de página completa puede servir la misma página a todos los visitantes y el orden cambia igualmente en cada visita. En los modos de desplazamiento continuo, el número máximo se aplica primero en orden alfabético y después se mezclan las marcas seleccionadas.

Pestaña Diseño

Los 8 modos de visualización

• Carrusel: logos que avanzan por página o por logo, en 1 a 3 filas, con flechas, puntos y desplazamiento automático.
• Desplazamiento continuo: logos que avanzan sin parar en 1 a 4 filas.
• Desplazamiento vertical: de 1 a 4 columnas que se mueven hacia arriba o hacia abajo.
• Cuadrícula: tarjetas en columnas, con búsqueda, filtro por letra y botón «Ver más» opcionales.
• Muro de logos: cuadrícula sin tarjetas, logos separados por líneas finas.
• Muro rotativo: cuadrícula fija cuyos logos cambian uno a uno.
• Etiquetas: nombres de marcas en etiquetas compactas, con logo pequeño opcional. Adecuado para una columna lateral.
• Directorio A-Z: todas las marcas agrupadas por letra, con una barra de letras clicables y una búsqueda.

Columnas

El número de columnas se ajusta por separado en ordenador (1 a 12), tableta (1 a 8) y móvil (1 a 4). Estos umbrales dependen del ancho disponible para el bloque y no del ancho de la pantalla: un bloque colocado en una columna lateral usa el ajuste móvil incluso en una pantalla grande.

• Filas (carrusel y muro rotativo): 1 a 3. En el carrusel, los logos llenan cada columna de arriba abajo y después las filas se desplazan juntas.
• Mostrar parte del logo siguiente (carrusel): en tableta y móvil asoma el logo siguiente para indicar que la lista se puede deslizar. Las flechas laterales se ocultan entonces en móvil.
• Filas antes de Ver más (cuadrícula y muro de logos): 0 muestra todo de una vez.

Desplazamiento continuo y vertical

• Filas (o columnas en vertical): 1 a 4, nunca más que el número de marcas.
• Marcas distintas en cada fila: las marcas se reparten entre las filas. Desactivado, cada fila muestra todas las marcas desfasadas. El reparto requiere al menos 3 marcas por fila; si no, el módulo desfasa las filas.
• Ancho de los logos (horizontal) o Altura del bloque (vertical).

Búsqueda y filtros

El campo de búsqueda (cuadrícula, muro de logos, directorio) filtra las marcas mientras se escribe, sin tener en cuenta acentos ni puntuación. El filtro por letra (cuadrícula y muro de logos) muestra una barra 0-9, A a Z y # para los nombres que no empiezan por letra ni por cifra. Las letras sin marca aparecen en gris. El directorio admite de 1 a 6 columnas y logos pequeños junto a los nombres.

Espaciado y ancho

• Espacio entre logos y margen vertical de la sección.
• Ancho: ancho de la ubicación, fondo a ancho completo (el fondo cubre la pantalla y el contenido se queda en la columna del tema) o ancho completo de borde a borde (útil para un desplazamiento continuo que cruza toda la pantalla).

Pestaña Estilo

Tarjetas de marca

• Estilo de las tarjetas: relleno, contorno, sombra o sin estilo.
• Altura máxima del logo, altura mínima de las tarjetas, margen interior y redondeo de las esquinas.
• Nombre de la marca: solo si no hay logo, siempre bajo el logo o al pasar el ratón.
• Descripción corta: los primeros 160 caracteres de la descripción corta de la marca.

Logos

• Número de productos bajo el logo o en la etiqueta.
• Efecto del logo: ninguno, gris y color al pasar el ratón, siempre gris, atenuado y nítido al pasar el ratón.
• Efecto al pasar sobre las tarjetas: elevación, zoom del logo, contorno en color de acento o ninguno.
• Quitar los fondos blancos: funde el blanco de los logos JPG en las tarjetas claras. Déjelo desactivado sobre fondos oscuros y use logos transparentes.
• Tamaño de imagen: se recomienda la imagen original. Los tamaños de PrestaShop suelen añadir márgenes blancos alrededor de los logos.

Colores

Se ajustan seis colores: acento (flechas, enlaces, letra activa), fondo de las tarjetas, bordes, fondo de la sección, título y texto. «Restablecer» devuelve el control al tema. El texto sobre el color de acento pasa automáticamente a blanco o negro según el contraste.

Pestaña Animación

Carrusel

• Desplazamiento automático y pausa entre páginas (1 a 15 segundos).
• Duración de la transición y paso: una página entera o un logo.
• Volver al inicio al llegar al final: tras el último logo, el carrusel vuelve al primero. Para un desplazamiento sin fin, use el modo Desplazamiento continuo.
• Flechas: 4 estilos (relleno, contorno, cuadrado, mínimo) y 4 posiciones (en los bordes sobresaliendo, dentro de los bordes, en el encabezado, debajo de los logos).
• Puntos de paginación.

El carrusel también funciona con el teclado (flechas izquierda y derecha), con el dedo y arrastrando con el ratón.

Desplazamiento continuo y vertical

• Sentido: hacia la izquierda o la derecha, hacia arriba o hacia abajo.
• Alternar las filas: una fila de cada dos se desplaza en sentido contrario.
• Velocidad: 5 a 400 píxeles por segundo, igual sea cual sea la longitud de la fila.
• Al pasar el ratón: ralentizar, detener o seguir. La ralentización es progresiva.
• Difuminar los bordes: los logos aparecen y desaparecen con un fundido.

Muro rotativo

Ajuste el número de filas y el tiempo entre cambios (0,8 a 20 segundos). En cada cambio, un logo de la cuadrícula se sustituye por una marca que todavía no está visible.

Accesibilidad

El botón de pausa, recomendado por el criterio WCAG 2.2.2 para todo contenido que se mueve más de 5 segundos, aparece en el encabezado o debajo de los logos. Las animaciones también se detienen al pasar el ratón, con el foco del teclado, cuando la pestaña está oculta y cuando el bloque sale de la pantalla. Para los visitantes que redujeron las animaciones en su sistema, el desplazamiento continuo se convierte en una fila quieta que desplazan a mano y el carrusel deja de moverse solo.

Pestaña Visualización

Ubicación

El campo Hook propone 14 ubicaciones agrupadas:

• Página de inicio: displayHome.
• Todas las páginas: displayWrapperTop, displayWrapperBottom, displayContentWrapperTop, displayContentWrapperBottom, displayNavFullWidth, displayFooterBefore, displayFooterAfter.
• Columnas: displayLeftColumn, displayRightColumn.
• Páginas específicas: displayFooterProduct, displayFooterCategory, displayShoppingCartFooter.
• Integración: displayDfBrandCarousel, o «Ninguno» para un bloque mostrado solo con el widget o el shortcode.

«Otro hook» acepta cualquier nombre que empiece por display (letras, cifras y guiones bajos). El módulo se registra en él al guardar. Su tema debe llamar después a ese hook.

Páginas y dispositivos

Páginas limita el bloque a ciertos tipos de página: inicio, categorías, productos, marcas, páginas CMS, búsqueda, carrito y pedido, otras páginas. Ninguna marcada: todas las páginas donde existe el hook. Dispositivos oculta el bloque en ordenador (992 px o más), tableta (576 a 991 px) o móvil (menos de 576 px).

Estadísticas

Con «Enviar los clics a Google Analytics», cada clic en una marca envía el evento dfbc_brand_click con los parámetros dfbc_block, brand_id y brand_name. El evento se envía a dataLayer si Google Tag Manager está presente y, si no, a gtag. En GTM, cree un activador «Evento personalizado» sobre dfbc_brand_click.

Colocar un bloque en otro lugar

La pestaña Integración del módulo y la sección «Insertar este bloque en otro lugar» de cada bloque guardado dan los códigos que copiar. Sustituya 3 por el número del bloque.

• En una plantilla del tema: {widget name='dfbrandcarousel' id_block=3} muestra ese bloque, sea cual sea su hook.
• Con el hook del módulo: {hook h='displayDfBrandCarousel'} muestra todos los bloques asignados a ese hook, {hook h='displayDfBrandCarousel' id_block=3} un bloque concreto.
• En una página CMS: pegue [dfbrandcarousel id="3"] en el contenido. El shortcode se sustituye por el bloque, incluso si está solo en un párrafo.
• Contenido cargado por AJAX o maquetador: si el bloque se inserta después de cargar la página, llame a window.DFBC.init(contenedor). window.DFBC.destroy(contenedor) detiene los bloques de forma limpia antes de retirar su HTML.

Cuando un bloque se muestra en una página donde el módulo no cargó sus archivos (widget en una plantilla, hook personalizado), el bloque los añade por sí mismo, una sola vez por página.

Logos de las marcas

La pestaña Logos de las marcas lista todas las marcas activas con su logo de PrestaShop y su número de productos.

• Logo alternativo: suba un archivo PNG, JPG, WebP, GIF o SVG de 2 MB como máximo. Sustituye al logo de PrestaShop en todos los bloques. «Quitar» vuelve al logo original.
• Enlace personalizado: URL completa (https://…) o ruta que empiece por /. Un enlace a otro sitio se abre en una pestaña nueva. Vacío, el enlace lleva a la página de la marca.

Los SVG que contienen scripts, atributos de evento, objetos incrustados o enlaces externos se rechazan: expórtelos de nuevo como SVG simple. Los archivos se guardan en /img/dfbrandcarousel/, cuyo archivo .htaccess bloquea la ejecución de scripts y aplica una política de seguridad a los SVG.

Si un módulo de optimización de imágenes ha creado versiones .webp o .avif junto a los logos de PrestaShop en /img/m/, se sirven automáticamente a los navegadores compatibles.

Personalizar el HTML

Copie modules/dfbrandcarousel/views/templates/hook/dfbrandcarousel.tpl en themes/su-tema/modules/dfbrandcarousel/views/templates/hook/dfbrandcarousel.tpl y modifique la copia. Las actualizaciones del módulo no la sustituyen. Todos los valores de la plantilla ya vienen escapados por el módulo, de ahí el uso de nofilter.

Cada bloque se genera en un elemento <section class="dfbc dfbc--MODO"> con el identificador dfbc-NÚMERO-N. Para un CSS específico, use preferentemente las clases, por ejemplo:

.dfbc--marquee .dfbc-card { border-radius: 999px; }

Multitienda e idiomas

Los bloques se gestionan tienda por tienda: elija una tienda en el selector del back office antes de modificarlos. Los logos alternativos y los enlaces personalizados son comunes a todas las tiendas. El título, el subtítulo y el texto del enlace se introducen por idioma. El módulo está traducido al inglés, francés, español, alemán, italiano, neerlandés, polaco y portugués, y admite idiomas de derecha a izquierda.

Caché y rendimiento

El módulo no carga jQuery, ni Swiper, ni ninguna librería externa. Su CSS y su JavaScript pesan unos 5 KB y 7 KB comprimidos y solo se cargan en las páginas donde puede aparecer un bloque: un bloque en displayHome no carga nada en las fichas de producto.

La lista de marcas se guarda en caché 6 horas, el número de productos por marca 1 hora y las ventas 12 horas, en var/cache/. Esta caché se vacía con cada guardado en el módulo y cuando se añade, modifica o elimina una marca o un producto. PrestaShop solo ejecuta estos disparadores para los empleados con permiso para ver el módulo: si un colaborador sin ese permiso modifica el catálogo, use el botón «Vaciar la caché».

Preguntas frecuentes

El bloque no aparece

Compruebe que el bloque está activo, que su tema llama a su hook y que los filtros Páginas y Dispositivos permiten la página consultada. Después compruebe que quedan marcas que mostrar: la vista previa del editor indica cuántas marcas se seleccionan y muestra un mensaje cuando ninguna coincide (origen, mínimo de productos, filtro de logos).

Los logos muestran rectángulos blancos

Los logos de PrestaShop son JPG con fondo blanco. Active «Quitar los fondos blancos» en tarjetas claras o suba logos transparentes en la pestaña Logos de las marcas.

Los logos se ven borrosos

Elija «Imagen original» en Tamaño de imagen, o suba un logo alternativo en SVG o en PNG de buena resolución.

El desplazamiento no se mueve

Puede que se haya pulsado el botón de pausa, o que el sistema del visitante pida menos animaciones. En este segundo caso, el módulo muestra los logos quietos a propósito.

Falta una marca

La marca debe estar activa, asociada a la tienda y tener al menos el número mínimo de productos visibles. Revise también las marcas excluidas y la opción «Solo marcas con logo».

Desinstalación

La desinstalación elimina las tablas del módulo, la carpeta /img/dfbrandcarousel/ con los logos alternativos y la caché del módulo.