DF Dark Mode para PrestaShop 8 y 9 — Documentación

DF Dark Mode añade un modo oscuro completo a su tienda PrestaShop 8 o 9, sin ninguna modificación de su tema. El módulo detecta la preferencia del sistema del visitante, memoriza su elección y genera el tema oscuro en el servidor.

Instalación

1. En el back-office, abra Módulos > Gestor de módulos.
2. Haga clic en Subir un módulo y suelte el archivo dfdarkmode-1.1.0.zip.
3. Una vez completada la instalación, haga clic en Configurar.

El módulo está activo de inmediato con sus ajustes predeterminados: motor de filtro inteligente, modo automático y botón flotante abajo a la derecha. No es necesaria ninguna configuración para que funcione correctamente.

Elegir el motor de renderizado

El módulo ofrece dos motores. La elección se realiza en el campo Motor de renderizado de la configuración.

Filtro inteligente (recomendado)

Este motor invierte toda la página y luego contrainvierte cada medio (imágenes, vídeos, iframes, canvas, fondos) para que sus fotos de producto conserven sus colores naturales. Funciona en cualquier tema, sin configuración ni CSS adicional.

Dos ajustes permiten afinar el resultado:

• Brillo (50 a 150 %, predeterminado 100) — redúzcalo ligeramente, a 92 por ejemplo, si el renderizado oscuro le parece demasiado luminoso.
• Contraste (50 a 150 %, predeterminado 100).

Paleta generada

Este motor calcula una gama oscura completa a partir de dos colores que usted elige: un color de fondo y un color de acento. De ellos se derivan automáticamente nueve variables CSS:

• --df-bg — el fondo de página
• --df-surface, --df-surface-2, --df-surface-3 — tres niveles de superficie (tarjetas, cabeceras, estados hover)
• --df-border — los bordes
• --df-text, --df-text-muted — el texto principal y el texto atenuado
• --df-accent, --df-accent-hover — el acento y su estado hover

El color del texto de los botones se elige automáticamente (claro u oscuro) según la luminancia relativa de su acento, para garantizar un contraste legible. Este motor produce un resultado más limpio que el filtro, pero puede requerir algunos ajustes CSS según su tema.

Modo predeterminado

El campo Modo predeterminado determina lo que ve un visitante que todavía no ha usado el botón:

• Automático — el módulo sigue la preferencia del sistema operativo del visitante (ajuste prefers-color-scheme). Si el visitante cambia su dispositivo a modo oscuro mientras navega, la tienda le sigue en directo, sin recargar.
• Claro — la tienda permanece clara hasta que el visitante pida el modo oscuro.
• Oscuro — la tienda se muestra oscura para todo el mundo por defecto.

En cuanto el visitante hace clic en el botón, su elección se memoriza en su navegador y prevalece sobre el modo predeterminado en todas sus visitas siguientes.

Colocar el botón

El campo Ubicación del botón ofrece dos modos.

Botón flotante

Un botón redondo superpuesto a la página, en una de las cuatro esquinas (arriba/abajo, izquierda/derecha). Puede ocultarlo en móvil mediante el ajuste dedicado.

Hook de tema

El botón se muestra en línea, dentro del diseño de su tema. Seleccione el hook de destino en la lista:

• displayNav1, displayNav2 — barras superiores de la cabecera (displayNav2 corresponde a la zona superior derecha en la mayoría de los temas)
• displayTop, displayNavFullWidth, displayBanner
• displayFooter, displayFooterAfter

La variante en línea del botón es más compacta y transparente: hereda los colores de su contenedor y se funde con su cabecera o su pie.

Hook personalizado

Si su tema ejecuta un hook propio, basta con escribir su nombre en el campo Nombre del hook personalizado. El módulo lo registra automáticamente al guardar el formulario, sin escribir ni una línea de código. Este campo tiene prioridad sobre la lista anterior.

El nombre debe empezar por una letra y contener solo letras, cifras y guiones bajos. Ejemplo: displayMiSwitcher.

Desde una plantilla

Los integradores pueden mostrar el botón en cualquier punto de un archivo .tpl del tema con la sintaxis widget de PrestaShop:

{widget name='dfdarkmode'}

Esta llamada muestra siempre el botón, sea cual sea el modo de ubicación configurado.

Botón de ciclo de tres estados

Active la opción Botón de 3 estados para que el botón alterne entre claro, oscuro y automático en lugar del simple cambio claro/oscuro. Un pequeño distintivo «A» aparece en el botón cuando el modo automático está activo.

Excluir elementos

El campo Selectores CSS excluidos acepta una lista de selectores, uno por línea o separados por comas. Los elementos correspondientes conservan su renderizado claro original, práctico para un logotipo, un banner de socio o un widget de terceros.

.mi-logo
#banner-socio
.widget-resenas

Los selectores que contienen llaves, corchetes angulares o puntos y comas se descartan al guardar.

También puede añadir directamente la clase df-no-invert a un elemento de su tema: se preservará automáticamente.

CSS personalizado

El campo CSS personalizado se inyecta únicamente cuando el modo oscuro está activo. Prefije sus reglas con html.df-dark:

html.df-dark .header-banner {
    background: var(--df-surface);
    color: var(--df-text);
}

Las variables CSS (--df-surface, --df-text, etc.) solo están disponibles con el motor de paleta generada.

API JavaScript

El módulo expone una API pública para sus propias integraciones:

// Modo configurado: "light", "dark" o "auto"
DFDarkMode.get();

// Modo realmente mostrado: "light" o "dark"
DFDarkMode.effective();

// Forzar un modo (memorizado en el navegador)
DFDarkMode.set('dark');

// Alternar
DFDarkMode.toggle();

Se emite un evento en el documento en cada cambio de modo:

document.addEventListener('dfdarkmode:change', function (e) {
    console.log(e.detail.mode);  // "light" | "dark" | "auto"
    console.log(e.detail.dark);  // true | false
});

Por último, cualquier elemento con el atributo data-df-darkmode-toggle se convierte automáticamente en un disparador, sin código adicional.

Funcionamiento técnico

Sin parpadeo al cargar

Un script síncrono, inyectado en la cabecera de la página, lee la preferencia memorizada y aplica la clase df-dark al elemento raíz antes del primer renderizado del navegador. El visitante en modo oscuro no ve por tanto nunca la versión clara, ni siquiera brevemente.

Contrainversión de los medios

Con el motor de filtro, los filtros CSS se componen cuando están anidados: no se anulan entre sí. Una imagen situada dentro de un elemento picture ya contrainvertido se invertiría por tanto dos veces. El módulo neutraliza este caso con una regla de protección que restablece el filtro de cualquier medio anidado dentro de un ancestro ya contrainvertido.

Memorización

La elección del visitante se almacena en el localStorage de su navegador, bajo la clave dfdm. No se recopila ni se transmite ningún dato personal a un servidor: el módulo no usa cookies ni llamadas de red, por lo que no tiene ninguna implicación RGPD.

Solución de problemas

Las fotos de producto aparecen en negativo

Compruebe que utiliza la versión 1.1.0 o superior y luego vacíe la caché de PrestaShop (Parámetros avanzados > Rendimiento > Vaciar la caché). Si un elemento concreto sigue invertido, añada su selector al campo de selectores excluidos.

El botón no aparece en el hook elegido

Algunos temas no ejecutan todos los hooks estándar. Compruebe en Diseño > Posiciones que el módulo está efectivamente vinculado al hook de destino y que ese hook es realmente invocado por su tema. Como último recurso, use la sintaxis widget en el archivo .tpl que prefiera.

Un elemento sigue siendo ilegible en modo oscuro

Añada una regla en el campo de CSS personalizado, prefijada con html.df-dark. Si el problema afecta a un bloque entero, excluirlo mediante los selectores CSS suele ser más sencillo.

Desinstalación

La desinstalación elimina toda la configuración del módulo. Las preferencias guardadas en el navegador de sus visitantes no se ven afectadas, pero dejan de tener efecto una vez retirado el módulo.