Banner de Categoría: guía completa

Presentación y requisitos

Banner de Categoría inserta visuales en la cuadrícula de productos de tus páginas de categoría, en la posición que elijas. Indicas la categoría, el número de producto tras el cual debe aparecer el banner y la imagen que se usará en cada idioma. El módulo se encarga del resto, incluso después de un filtro por facetas o un cambio de página.

• Compatible con PrestaShop 8.0 a 9.x, tema Classic y temas derivados.
• PHP 7.4 a 8.3.
• Multitienda y multiidioma (fr, en, es, de, it, nl, pl, pt).
• Sin overrides, sin cambios de plantilla, sin tareas CRON.
• El marcado del banner se genera en el servidor con una plantilla Smarty; el JavaScript solo lo inserta en el lugar correcto, sin jQuery ni bibliotecas de terceros.

Instalación

1. Descarga el archivo datafireflycategorybanner.zip desde tu cuenta de cliente.
2. En el back office, abre Módulos > Gestor de módulos.
3. Haz clic en Subir un módulo y suelta el archivo.
4. Haz clic en Configurar para acceder a la lista de banners.

Al instalarse, el módulo crea sus tres tablas (banners, traducciones, asociación de tiendas), crea la carpeta /img/datafireflycategorybanner/ y registra sus hooks.

Crear un banner

Desde la página de configuración, haz clic en Añadir un nuevo banner. El formulario agrupa los siguientes ajustes.

Segmentación

• Categoría: la categoría en la que aparece el banner. La lista refleja el árbol de la tienda, con las categorías desactivadas señaladas.
• Aplicar a las subcategorías: extiende el banner a todas las subcategorías de la categoría elegida, sea cual sea su profundidad.
• Después del producto número: el banner se inserta tras ese producto del listado. El valor 4 coloca el banner después del cuarto producto mostrado.

Apariencia y enlace

• Enlace del banner: URL de destino, absoluta (https://…) o que empiece por una barra (/novedades). Déjalo vacío para un banner no clicable.
• Clase CSS: clases de cuadrícula aplicadas a la celda del banner, por ejemplo col-12 o col-12 col-md-6. Déjalo vacío para reutilizar automáticamente las clases de las celdas de producto de tu tema.
• CSS personalizado: declaraciones aplicadas solo a este banner, por ejemplo border-radius: 12px; padding: 10px;.

Programación y estado

• Fecha de inicio y Fecha de fin: ventana de visualización, con formato AAAA-MM-DD HH:MM:SS. Un campo vacío significa que no hay límite por ese lado.
• Activo: muestra o suspende el banner sin borrarlo.
• Asociación de tiendas: en multitienda, marca las tiendas correspondientes.

Imágenes por idioma

Los campos Imagen del banner y Texto alternativo existen para cada idioma activo. Las pestañas de idioma situadas en la parte superior del formulario muestran los campos del idioma seleccionado. Cuando ya hay una imagen, aparece una vista previa junto a un interruptor Eliminar la imagen que solo afecta a ese idioma.

Cómo se calcula la posición

La posición se expresa en número de productos y se aplica a cada página del listado. Un banner configurado en 4 aparece tras el cuarto producto de la página actual, tanto si el visitante está en la página 1 como en la 3.

Varios banners pueden apuntar a la misma categoría, cada uno en su posición. Cuando dos banners comparten posición, se insertan uno tras otro en el orden de guardado. Si la posición supera el número de productos mostrados en la página, el banner simplemente se omite en esa página, sin desplazar a los demás.

Por defecto el banner adopta el ancho de una celda de producto: el módulo lee las clases de cuadrícula del primer producto de la lista y se las aplica al banner. Rellena el campo Clase CSS para forzar otro ancho, por ejemplo un banner a todo el ancho con col-12.

Programar una campaña

Indica una fecha de inicio y una fecha de fin para que un banner aparezca y desaparezca solo. Es la herramienta adecuada para preparar las rebajas, el Black Friday o una campaña de fin de año con semanas de antelación.

• Solo fecha de inicio: el banner aparece en esa fecha y permanece visible después.
• Solo fecha de fin: el banner se muestra de inmediato y se detiene en esa fecha.
• Ambas fechas: el banner solo es visible dentro de esa ventana.
• Sin fechas: el banner es permanente.

Cubrir un árbol completo

La opción Aplicar a las subcategorías evita recrear el mismo banner en cada sección. Colocado en una categoría padre, el banner se muestra en esa categoría y en todas sus descendientes.

La resolución se apoya en el árbol anidado nativo de PrestaShop (columnas nleft y nright), sin consultas adicionales por página. Si mueves categorías en el árbol, PrestaShop recalcula esos valores y el alcance se ajusta automáticamente.

Imágenes e idiomas

Cada banner acepta un visual y un texto alternativo por idioma, lo que permite adaptar un mensaje o un precio a cada mercado. Si un idioma no ha recibido su propio visual, el módulo muestra el del idioma por defecto de la tienda en lugar de ocultar el banner.

Las dimensiones de la imagen se leen al subirla y se escriben en los atributos width y height del HTML, lo que evita el desplazamiento del diseño durante la carga. Los archivos se renombran con un sufijo aleatorio y se guardan en /img/datafireflycategorybanner/.

Multitienda

Cuando la funcionalidad multitienda está activa, el formulario muestra un bloque Asociación de tiendas. Un banner solo aparece en las tiendas marcadas, y la lista del back office solo muestra los banners visibles en el contexto de tienda actual.

Si no se marca ninguna tienda, el módulo asocia el banner al contexto actual para no crear nunca un banner huérfano.

Filtros por facetas, ordenación y paginación

En PrestaShop 8 y 9, los filtros por facetas, la ordenación y la paginación recargan el listado por AJAX sin recargar la página. El módulo escucha el evento updateProductList de PrestaShop, retira los banners anteriores y los vuelve a insertar en las posiciones correctas tras cada actualización del DOM.

El CSS y el JavaScript se cargan solo en las páginas de categoría, y únicamente cuando la categoría actual tiene al menos un banner activo y mostrable.

Actualizar desde la versión 1.0.0

Instala simplemente el nuevo archivo sobre el anterior desde el gestor de módulos. El script de actualización se encarga de:

• añadir las columnas de alcance, programación y dimensiones de imagen;
• crear la tabla de asociación de tiendas y recuperar en ella la tienda original de cada banner;
• mover las imágenes existentes de views/img/banners/ a /img/datafireflycategorybanner/ y leer sus dimensiones;
• retirar un hook que ha dejado de ser necesario.

Tus banners, sus posiciones y sus visuales se conservan.

FAQ y resolución de problemas

El banner no aparece en la página de categoría

Comprueba en este orden: el banner está activo; la fecha de hoy está dentro de la ventana de programación; la categoría apuntada es la que se está consultando, o el alcance a subcategorías está activado; el idioma mostrado tiene imagen, o la tiene el idioma por defecto; en multitienda, la tienda actual está marcada. Por último, vacía la caché de PrestaShop.

El banner aparece en el sitio equivocado

La posición cuenta los productos de la página actual. Si tu listado muestra 12 productos por página, un banner en la posición 20 no aparecerá en ninguna. Reduce el valor o aumenta el número de productos por página.

El banner rompe el diseño de la cuadrícula

Vacía el campo Clase CSS para que el banner reutilice las clases de las celdas de producto de tu tema. Si quieres un banner a todo el ancho, escribe col-12. Evita mezclar clases de sistemas de cuadrícula distintos.

El banner desaparece tras filtrar

El módulo se engancha de nuevo al evento updateProductList. Si tu tema o un módulo de filtrado de terceros sustituye por completo el contenedor del listado sin disparar ese evento, la reinserción no puede producirse. Contacta con el soporte indicando el tema y el módulo de filtrado utilizados.

La imagen no se sube

El módulo acepta archivos JPG, PNG, GIF, WebP y SVG de hasta 4 MB. Comprueba también que /img/datafireflycategorybanner/ tiene permisos de escritura y que las directivas upload_max_filesize y post_max_size de PHP superan el peso del archivo.

El enlace del banner es rechazado

Solo se aceptan URL que empiecen por http://, https:// o por una barra. Es una protección contra la inyección de direcciones javascript: o data:.

¿Qué ocurre al desinstalar?

El módulo elimina sus tablas y la carpeta /img/datafireflycategorybanner/ con los visuales que contiene. Haz copia de tus imágenes si piensas reinstalarlo más adelante.