DF Dark Mode voor PrestaShop 8 en 9: volledige gids

DF Dark Mode voegt een volwaardige donkere modus toe aan uw PrestaShop 8- of 9-winkel, zonder enige wijziging aan uw thema. De module detecteert de systeemvoorkeur van de bezoeker, onthoudt zijn keuze en bouwt het donkere thema aan serverzijde op.

Installatie

1. Open in de backoffice Modules > Modulebeheer.
2. Klik op Een module installeren en plaats het bestand dfdarkmode-1.1.0.zip.
3. Klik na de installatie op Configureren.

De module is meteen actief met zijn standaardinstellingen: motor « slim filter », modus « automatisch » en een zwevende knop rechtsonder. Voor een correcte werking is geen configuratie nodig.

De rendermotor kiezen

De module biedt twee motoren. U kiest die in het veld Rendermotor van de configuratie.

Slim filter (aanbevolen)

Deze motor keert de hele pagina om en keert daarna elk medium (afbeeldingen, video’s, iframes, canvas, achtergronden) opnieuw om, zodat uw productfoto’s hun natuurlijke kleuren behouden. Hij werkt op elk thema, zonder configuratie of extra CSS.

Twee instellingen verfijnen het resultaat:

• Helderheid (50 tot 150 %, standaard 100): verlaag die lichtjes, bijvoorbeeld naar 92, als de donkere weergave u te licht lijkt.
• Contrast (50 tot 150 %, standaard 100).

Gegenereerd palet

Deze motor berekent een volledig donker kleurgamma uit twee kleuren die u kiest: een achtergrondkleur en een accentkleur. Daaruit worden automatisch negen CSS-variabelen afgeleid:

• --df-bg: de paginaachtergrond
• --df-surface, --df-surface-2, --df-surface-3: drie oppervlakniveaus (kaarten, headers, hovertoestanden)
• --df-border: de randen
• --df-text, --df-text-muted: de hoofdtekst en de gedempte tekst
• --df-accent, --df-accent-hover: het accent en de hovertoestand ervan

De tekstkleur van de knoppen wordt automatisch gekozen (licht of donker) op basis van de relatieve luminantie van uw accent, om een leesbaar contrast te waarborgen. Deze motor levert een scherper resultaat dan het filter, maar kan afhankelijk van uw thema enkele CSS-aanpassingen vragen.

Standaardmodus

Het veld Standaardmodus bepaalt wat een bezoeker ziet die de knop nog nooit heeft gebruikt:

• Automatisch: de module volgt de voorkeur van het besturingssysteem van de bezoeker (instelling prefers-color-scheme). Zet de bezoeker zijn toestel tijdens het browsen in donkere modus, dan volgt de winkel meteen, zonder herladen.
• Licht: de winkel blijft licht zolang de bezoeker de donkere modus niet vraagt.
• Donker: de winkel verschijnt standaard voor iedereen in het donker.

Zodra de bezoeker op de knop klikt, wordt zijn keuze in zijn browser onthouden en gaat die voor op de standaardmodus, bij al zijn volgende bezoeken.

De knop plaatsen

Het veld Plaatsing van de knop biedt twee modi.

Zwevende knop

Een ronde knop over de pagina heen, in een van de vier hoeken (boven of onder, links of rechts). U kunt die op mobiel verbergen via de daarvoor bestemde instelling.

Themahook

De knop wordt inline in de opmaak van uw thema weergegeven. Kies de doelhook uit de lijst:

• displayNav1, displayNav2: bovenbalken van de header (displayNav2 komt bij de meeste thema’s overeen met de zone rechtsboven)
• displayTop, displayNavFullWidth, displayBanner
• displayFooter, displayFooterAfter

De inlinevariant van de knop is compacter en transparant: die neemt de kleuren van zijn container over en gaat op in uw header of footer.

Eigen hook

Voert uw thema een eigen hook uit, vul dan gewoon de naam ervan in in het veld Naam van de eigen hook. De module registreert die automatisch bij het opslaan van het formulier: u hoeft geen regel code te schrijven. Dit veld gaat voor op de lijst hierboven.

De naam moet met een letter beginnen en mag alleen letters, cijfers en liggende streepjes bevatten. Bijvoorbeeld: displayMijnSwitcher.

Vanuit een template

Integratoren kunnen de knop overal in een .tpl-bestand van het thema tonen met de widgetsyntaxis van PrestaShop:

{widget name='dfdarkmode'}

Deze aanroep toont de knop altijd, welke plaatsingsmodus er ook is ingesteld.

Knop met drie standen

Schakel de optie Knop met 3 standen in zodat de knop tussen licht, donker en automatisch wisselt in plaats van eenvoudig tussen licht en donker om te schakelen. Wanneer de automatische modus actief is, verschijnt er een badge « A » op de knop.

Elementen uitsluiten

Het veld Uitgesloten CSS-selectors aanvaardt een lijst met selectors, één per regel of door komma’s gescheiden. De overeenkomstige elementen behouden hun oorspronkelijke lichte weergave, wat handig is voor een logo, een partnerbanner of een externe widget.

.mijn-logo
#partnerbanner
.reviews-widget

Selectors met accolades, punthaken of puntkomma’s worden bij het opslaan genegeerd.

U kunt ook rechtstreeks de klasse df-no-invert aan een element van uw thema toevoegen: dat wordt dan automatisch gespaard.

Eigen CSS

Het veld Eigen CSS wordt alleen geïnjecteerd wanneer de donkere modus actief is. Zet html.df-dark voor uw regels:

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

De CSS-variabelen (--df-surface, --df-text en zo verder) zijn alleen beschikbaar met de motor « gegenereerd palet ».

JavaScript-API

De module stelt een publieke API beschikbaar voor uw eigen integraties:

// Ingestelde modus: "light", "dark" of "auto"
DFDarkMode.get();

// Werkelijk getoonde modus: "light" of "dark"
DFDarkMode.effective();

// Een modus afdwingen (onthouden in de browser)
DFDarkMode.set('dark');

// Omschakelen
DFDarkMode.toggle();

Bij elke moduswissel wordt een gebeurtenis op het document uitgestuurd:

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

Tot slot wordt elk element met het attribuut data-df-darkmode-toggle automatisch een schakelaar, zonder extra code.

Technische werking

Geen flits bij het laden

Een synchroon script, geïnjecteerd in de header van de pagina, leest de onthouden voorkeur en zet de klasse df-dark op het rootelement vóór de eerste weergave door de browser. Een bezoeker in donkere modus ziet dus nooit de lichte versie, ook niet kort.

Terugkeren van de media

Met de filtermotor stapelen CSS-filters zich op wanneer ze genest zijn: ze heffen elkaar niet op. Een afbeelding in een picture-element dat al is teruggekeerd, zou dus twee keer worden omgekeerd. De module ondervangt dat met een beschermende regel die het filter van elk medium binnen een reeds teruggekeerde voorouder op nul zet.

Onthouden

De keuze van de bezoeker wordt in de localStorage van zijn browser bewaard, onder de sleutel dfdm. Er worden geen persoonsgegevens verzameld of naar een server gestuurd: de module gebruikt geen cookie en doet geen enkele netwerkaanroep, en heeft dus geen enkele AVG-implicatie.

Problemen oplossen

De productfoto’s verschijnen in negatief

Controleer of u wel versie 1.1.0 of hoger gebruikt en leeg daarna de PrestaShop-cache (Geavanceerde parameters > Prestaties > Cache legen). Blijft een specifiek element omgekeerd, voeg dan de selector ervan toe aan het veld met uitgesloten selectors.

De knop verschijnt niet op de gekozen hook

Sommige thema’s voeren niet alle standaardhooks uit. Controleer in Design > Posities of de module wel aan de beoogde hook is gekoppeld en of die hook daadwerkelijk door uw thema wordt aangeroepen. Gebruik als laatste redmiddel de widgetsyntaxis in het .tpl-bestand van uw keuze.

Een element blijft onleesbaar in donkere modus

Voeg een regel toe in het veld voor eigen CSS, voorafgegaan door html.df-dark. Gaat het om een heel blok, dan is het uitsluiten via de CSS-selectors vaak eenvoudiger.

Verwijderen

Bij het verwijderen wordt de volledige configuratie van de module gewist. De voorkeuren die in de browser van uw bezoekers zijn opgeslagen, blijven onaangeroerd, maar hebben geen effect meer zodra de module weg is.