DF Dark Mode pour PrestaShop 8 et 9 — Documentation

DF Dark Mode ajoute un mode sombre complet à votre boutique PrestaShop 8 ou 9, sans aucune modification de votre thème. Le module détecte la préférence système du visiteur, mémorise son choix, et génère le thème sombre côté serveur.

Installation

1. Dans le back-office, ouvrez Modules > Gestionnaire de modules.
2. Cliquez sur Installer un module et déposez le fichier dfdarkmode-1.1.0.zip.
3. Une fois l’installation terminée, cliquez sur Configurer.

Le module est actif immédiatement avec ses réglages par défaut : moteur « filtre intelligent », mode « automatique » et bouton flottant en bas à droite. Aucune configuration n’est nécessaire pour un fonctionnement correct.

Choisir le moteur de rendu

Le module propose deux moteurs. Le choix se fait dans le champ Moteur de rendu de la configuration.

Filtre intelligent (recommandé)

Ce moteur inverse la page entière puis contre-inverse chaque média (images, vidéos, iframes, canvas, arrière-plans) afin que vos photos produit conservent leurs couleurs naturelles. Il fonctionne sur n’importe quel thème, sans configuration ni CSS supplémentaire.

Deux réglages permettent d’affiner le rendu :

• Luminosité (50 à 150 %, défaut 100) — abaissez-la légèrement, à 92 par exemple, si le rendu sombre vous paraît trop lumineux.
• Contraste (50 à 150 %, défaut 100).

Palette générée

Ce moteur calcule une gamme sombre complète à partir de deux couleurs que vous choisissez : une couleur de fond et une couleur d’accent. Neuf variables CSS en sont dérivées automatiquement :

• --df-bg — le fond de page
• --df-surface, --df-surface-2, --df-surface-3 — trois niveaux de surface (cartes, en-têtes, survols)
• --df-border — les bordures
• --df-text, --df-text-muted — le texte principal et le texte atténué
• --df-accent, --df-accent-hover — l’accent et son état de survol

La couleur du texte des boutons est choisie automatiquement (clair ou sombre) selon la luminance relative de votre accent, afin de garantir un contraste lisible. Ce moteur produit un rendu plus net que le filtre, mais peut demander quelques ajustements CSS selon votre thème.

Mode par défaut

Le champ Mode par défaut détermine ce que voit un visiteur qui n’a encore jamais utilisé le bouton :

• Automatique — le module suit la préférence du système d’exploitation du visiteur (réglage prefers-color-scheme). Si le visiteur bascule son appareil en mode sombre pendant sa navigation, la boutique suit en direct, sans rechargement.
• Clair — la boutique reste claire tant que le visiteur ne demande pas le mode sombre.
• Sombre — la boutique s’affiche en sombre pour tout le monde par défaut.

Dès que le visiteur clique sur le bouton, son choix est mémorisé dans son navigateur et prime sur le mode par défaut, pour toutes ses visites suivantes.

Placer le bouton

Le champ Emplacement du bouton propose deux modes.

Bouton flottant

Un bouton rond superposé à la page, dans l’un des quatre coins (haut/bas, gauche/droite). Vous pouvez le masquer sur mobile via le réglage dédié.

Hook de thème

Le bouton est rendu en ligne, dans la mise en page de votre thème. Sélectionnez le hook cible dans la liste :

• displayNav1, displayNav2 — barres supérieures du header (displayNav2 correspond à la zone en haut à droite sur la plupart des thèmes)
• displayTop, displayNavFullWidth, displayBanner
• displayFooter, displayFooterAfter

La variante en ligne du bouton est plus compacte et transparente : elle hérite des couleurs de son conteneur et se fond dans votre header ou votre footer.

Hook personnalisé

Si votre thème exécute un hook qui lui est propre, saisissez simplement son nom dans le champ Nom du hook personnalisé. Le module l’enregistre automatiquement à l’enregistrement du formulaire — aucune ligne de code à écrire. Ce champ est prioritaire sur la liste ci-dessus.

Le nom doit commencer par une lettre et ne contenir que des lettres, des chiffres et des tirets bas. Exemple : displayMonSwitcher.

Depuis un template

Les intégrateurs peuvent afficher le bouton n’importe où dans un fichier .tpl du thème avec la syntaxe widget de PrestaShop :

{widget name='dfdarkmode'}

Cet appel rend toujours le bouton, quel que soit le mode d’emplacement configuré.

Bouton cycle à trois états

Activez l’option Bouton à 3 états pour que le bouton alterne entre clair, sombre et automatique au lieu du simple basculement clair/sombre. Un petit badge « A » apparaît sur le bouton lorsque le mode automatique est actif.

Exclure des éléments

Le champ Sélecteurs CSS exclus accepte une liste de sélecteurs, un par ligne ou séparés par des virgules. Les éléments correspondants conservent leur rendu clair d’origine — pratique pour un logo, une bannière partenaire ou un widget tiers.

.mon-logo
#banniere-partenaire
.widget-avis

Les sélecteurs contenant des accolades, des chevrons ou des points-virgules sont ignorés à l’enregistrement.

Vous pouvez aussi ajouter directement la classe df-no-invert à un élément de votre thème : il sera automatiquement préservé.

CSS personnalisé

Le champ CSS personnalisé est injecté uniquement lorsque le mode sombre est actif. Préfixez vos règles par html.df-dark :

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

Les variables CSS (--df-surface, --df-text, etc.) ne sont disponibles qu’avec le moteur « palette générée ».

API JavaScript

Le module expose une API publique pour vos propres intégrations :

// Mode configuré : "light", "dark" ou "auto"
DFDarkMode.get();

// Mode réellement affiché : "light" ou "dark"
DFDarkMode.effective();

// Forcer un mode (mémorisé dans le navigateur)
DFDarkMode.set('dark');

// Basculer
DFDarkMode.toggle();

Un évènement est émis sur le document à chaque changement de mode :

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

Enfin, tout élément portant l’attribut data-df-darkmode-toggle devient automatiquement un déclencheur, sans code supplémentaire.

Fonctionnement technique

Absence de flash au chargement

Un script synchrone, injecté dans l’en-tête de la page, lit la préférence mémorisée puis applique la classe df-dark à l’élément racine avant le premier rendu du navigateur. Le visiteur en mode sombre ne voit donc jamais la version claire, même brièvement.

Contre-inversion des médias

Avec le moteur filtre, les filtres CSS se composent lorsqu’ils sont imbriqués : ils ne s’annulent pas. Une image placée dans un élément picture déjà contre-inversé serait donc inversée deux fois. Le module neutralise ce cas avec une règle de garde qui remet à zéro le filtre de tout média imbriqué dans un ancêtre déjà contre-inversé.

Mémorisation

Le choix du visiteur est stocké dans le localStorage de son navigateur, sous la clé dfdm. Aucune donnée personnelle n’est collectée ni transmise à un serveur : le module n’utilise ni cookie ni appel réseau, et n’a donc aucune implication RGPD.

Dépannage

Les photos produit apparaissent en négatif

Vérifiez que vous utilisez bien la version 1.1.0 ou supérieure, puis videz le cache PrestaShop (Paramètres avancés > Performances > Vider le cache). Si un élément spécifique reste inversé, ajoutez son sélecteur dans le champ des sélecteurs exclus.

Le bouton n’apparaît pas sur le hook choisi

Certains thèmes n’exécutent pas tous les hooks standards. Vérifiez dans Design > Positions que le module est bien greffé au hook visé, et que ce hook est effectivement appelé par votre thème. En dernier recours, utilisez la syntaxe widget dans le fichier .tpl de votre choix.

Un élément reste illisible en mode sombre

Ajoutez une règle dans le champ CSS personnalisé, préfixée par html.df-dark. Si le problème concerne un bloc entier, l’exclure via les sélecteurs CSS est souvent plus simple.

Désinstallation

La désinstallation supprime toute la configuration du module. Les préférences enregistrées dans le navigateur de vos visiteurs ne sont pas affectées, mais elles deviennent sans effet une fois le module retiré.