DF Dark Mode für PrestaShop 8 und 9 — Dokumentation

DF Dark Mode ergänzt Ihren PrestaShop-8- oder -9-Shop um einen vollständigen Dark Mode, ganz ohne Änderung an Ihrem Theme. Das Modul erkennt die Systemeinstellung des Besuchers, speichert seine Auswahl und erzeugt das dunkle Theme serverseitig.

Installation

1. Öffnen Sie im Back Office Module > Modul-Manager.
2. Klicken Sie auf Modul hochladen und legen Sie die Datei dfdarkmode-1.1.0.zip ab.
3. Klicken Sie nach der Installation auf Konfigurieren.

Das Modul ist mit seinen Standardeinstellungen sofort aktiv: Smart-Filter-Engine, Modus „automatisch“ und schwebender Button unten rechts. Für einen korrekten Betrieb ist keine Konfiguration nötig.

Die Rendering-Engine wählen

Das Modul bietet zwei Engines. Die Auswahl erfolgt im Feld Rendering-Engine der Konfiguration.

Smart-Filter (empfohlen)

Diese Engine invertiert die gesamte Seite und invertiert anschließend jedes Medium gegen (Bilder, Videos, iFrames, Canvas, Hintergründe), damit Ihre Produktfotos ihre natürlichen Farben behalten. Sie funktioniert auf jedem Theme, ohne Konfiguration und ohne zusätzliches CSS.

Zwei Einstellungen erlauben die Feinabstimmung:

• Helligkeit (50 bis 150 %, Standard 100) — senken Sie sie leicht ab, etwa auf 92, wenn Ihnen die dunkle Darstellung zu hell erscheint.
• Kontrast (50 bis 150 %, Standard 100).

Generierte Palette

Diese Engine berechnet eine vollständige dunkle Skala aus zwei Farben Ihrer Wahl: einer Hintergrundfarbe und einer Akzentfarbe. Daraus werden automatisch neun CSS-Variablen abgeleitet:

• --df-bg — der Seitenhintergrund
• --df-surface, --df-surface-2, --df-surface-3 — drei Oberflächenstufen (Karten, Kopfzeilen, Hover)
• --df-border — die Rahmen
• --df-text, --df-text-muted — Haupttext und gedämpfter Text
• --df-accent, --df-accent-hover — der Akzent und sein Hover-Zustand

Die Textfarbe der Buttons wird anhand der relativen Leuchtdichte Ihres Akzents automatisch gewählt (hell oder dunkel), um lesbaren Kontrast zu gewährleisten. Diese Engine liefert ein saubereres Ergebnis als der Filter, kann aber je nach Theme ein paar CSS-Anpassungen erfordern.

Standardmodus

Das Feld Standardmodus bestimmt, was ein Besucher sieht, der den Button noch nie benutzt hat:

• Automatisch — das Modul folgt der Einstellung des Betriebssystems des Besuchers (Einstellung prefers-color-scheme). Stellt der Besucher sein Gerät während des Besuchs auf Dunkel um, folgt der Shop live, ohne Neuladen.
• Hell — der Shop bleibt hell, bis der Besucher den Dark Mode anfordert.
• Dunkel — der Shop wird standardmäßig für alle dunkel angezeigt.

Sobald der Besucher auf den Button klickt, wird seine Auswahl im Browser gespeichert und hat bei allen folgenden Besuchen Vorrang vor dem Standardmodus.

Den Button platzieren

Das Feld Platzierung des Umschalters bietet zwei Modi.

Schwebender Button

Ein runder Button, der über der Seite liegt, in einer der vier Ecken (oben/unten, links/rechts). Über die entsprechende Einstellung können Sie ihn auf Mobilgeräten ausblenden.

Theme-Hook

Der Button wird inline im Layout Ihres Themes ausgegeben. Wählen Sie den Ziel-Hook aus der Liste:

• displayNav1, displayNav2 — obere Leisten des Headers (displayNav2 entspricht bei den meisten Themes dem Bereich oben rechts)
• displayTop, displayNavFullWidth, displayBanner
• displayFooter, displayFooterAfter

Die Inline-Variante des Buttons ist kompakter und transparent: Sie erbt die Farben ihres Containers und fügt sich in Ihren Header oder Footer ein.

Benutzerdefinierter Hook

Führt Ihr Theme einen eigenen Hook aus, geben Sie dessen Namen einfach im Feld Name des benutzerdefinierten Hooks ein. Das Modul registriert ihn beim Speichern des Formulars automatisch — ohne eine Zeile Code. Dieses Feld hat Vorrang vor der obigen Liste.

Der Name muss mit einem Buchstaben beginnen und darf nur Buchstaben, Ziffern und Unterstriche enthalten. Beispiel: displayMeinSwitcher.

Aus einem Template heraus

Integratoren können den Button mit der Widget-Syntax von PrestaShop an beliebiger Stelle in einer .tpl-Datei des Themes ausgeben:

{widget name='dfdarkmode'}

Dieser Aufruf gibt den Button immer aus, unabhängig vom konfigurierten Platzierungsmodus.

Drei-Zustands-Zyklus

Aktivieren Sie die Option Umschalter mit 3 Zuständen, damit der Button zwischen hell, dunkel und automatisch wechselt statt nur zwischen hell und dunkel. Bei aktivem Automatikmodus erscheint ein kleines Abzeichen „A“ auf dem Button.

Elemente ausnehmen

Das Feld Ausgeschlossene CSS-Selektoren nimmt eine Liste von Selektoren entgegen, einen pro Zeile oder durch Kommas getrennt. Passende Elemente behalten ihre ursprüngliche helle Darstellung — praktisch für ein Logo, ein Partner-Banner oder ein Widget von Drittanbietern.

.mein-logo
#partner-banner
.bewertungs-widget

Selektoren mit geschweiften Klammern, spitzen Klammern oder Semikolons werden beim Speichern verworfen.

Sie können einem Element Ihres Themes auch direkt die Klasse df-no-invert geben: Es wird dann automatisch geschützt.

Benutzerdefiniertes CSS

Das Feld Benutzerdefiniertes CSS wird nur eingefügt, wenn der Dark Mode aktiv ist. Stellen Sie Ihren Regeln html.df-dark voran:

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

Die CSS-Variablen (--df-surface, --df-text und so weiter) stehen nur mit der Engine „generierte Palette“ zur Verfügung.

JavaScript-API

Das Modul stellt eine öffentliche API für Ihre eigenen Integrationen bereit:

// Konfigurierter Modus: "light", "dark" oder "auto"
DFDarkMode.get();

// Tatsächlich angezeigter Modus: "light" oder "dark"
DFDarkMode.effective();

// Einen Modus erzwingen (im Browser gespeichert)
DFDarkMode.set('dark');

// Umschalten
DFDarkMode.toggle();

Bei jedem Moduswechsel wird auf dem Dokument ein Ereignis ausgelöst:

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

Schließlich wird jedes Element mit dem Attribut data-df-darkmode-toggle automatisch zu einem Auslöser, ohne zusätzlichen Code.

Technische Funktionsweise

Kein Flackern beim Laden

Ein synchrones Skript im Kopfbereich der Seite liest die gespeicherte Einstellung und setzt die Klasse df-dark auf das Wurzelelement, bevor der Browser zum ersten Mal rendert. Ein Besucher im Dark Mode sieht die helle Version daher nie, auch nicht kurz.

Gegeninvertierung der Medien

Bei der Filter-Engine setzen sich verschachtelte CSS-Filter zusammen: Sie heben einander nicht auf. Ein Bild in einem bereits gegeninvertierten picture-Element würde also zweimal invertiert. Das Modul neutralisiert diesen Fall mit einer Schutzregel, die den Filter jedes Mediums zurücksetzt, das in einem bereits gegeninvertierten Vorfahren verschachtelt ist.

Speicherung

Die Auswahl des Besuchers wird im localStorage seines Browsers unter dem Schlüssel dfdm abgelegt. Es werden keine personenbezogenen Daten erhoben oder an einen Server übertragen: Das Modul verwendet weder Cookies noch Netzwerkaufrufe und hat daher keine DSGVO-Implikationen.

Fehlerbehebung

Produktfotos erscheinen als Negativ

Stellen Sie sicher, dass Sie Version 1.1.0 oder höher verwenden, und leeren Sie dann den PrestaShop-Cache (Erweiterte Einstellungen > Leistung > Cache leeren). Bleibt ein bestimmtes Element invertiert, fügen Sie seinen Selektor im Feld der ausgeschlossenen Selektoren hinzu.

Der Button erscheint nicht am gewählten Hook

Manche Themes führen nicht alle Standard-Hooks aus. Prüfen Sie unter Design > Positionen, ob das Modul tatsächlich am Ziel-Hook eingehängt ist und ob dieser Hook von Ihrem Theme wirklich aufgerufen wird. Als letzte Möglichkeit verwenden Sie die Widget-Syntax in der .tpl-Datei Ihrer Wahl.

Ein Element bleibt im Dark Mode unlesbar

Fügen Sie im Feld für benutzerdefiniertes CSS eine Regel mit dem Präfix html.df-dark hinzu. Betrifft das Problem einen ganzen Block, ist der Ausschluss über die CSS-Selektoren oft einfacher.

Deinstallation

Die Deinstallation entfernt die gesamte Konfiguration des Moduls. Die in den Browsern Ihrer Besucher gespeicherten Einstellungen bleiben erhalten, sind nach dem Entfernen des Moduls aber wirkungslos.