# DfDarkMode: donkere modus voor Shopware 6.7

> Overzicht DfDarkMode voegt een volledige donkere modus toe aan de storefront van Shopware 6.7. De plugin plaatst het attribuut data-bs-theme op het html-hoofdelement van de pagina: uw CSS-variabelen die onder…

- Pagina: <https://www.datafirefly.com/nl/documentation/dfdarkmode/>
- Taal: nl
- Bijgewerkt op: 2026-08-19
- Andere talen: [fr](https://www.datafirefly.com/documentation/dfdarkmode/index.md), [en](https://www.datafirefly.com/en/documentation/dfdarkmode/index.md), [es](https://www.datafirefly.com/es/documentation/dfdarkmode/index.md), [de](https://www.datafirefly.com/de/documentation/dfdarkmode/index.md), [it](https://www.datafirefly.com/it/documentation/dfdarkmode/index.md), [pl](https://www.datafirefly.com/pl/documentation/dfdarkmode/index.md), [pt](https://www.datafirefly.com/pt/documentation/dfdarkmode/index.md)
- Index: <https://www.datafirefly.com/nl/documentation/llms.txt>

## Overzicht

DfDarkMode voegt een volledige donkere modus toe aan de storefront van Shopware 6.7. De plugin plaatst het attribuut `data-bs-theme` op het html-hoofdelement van de pagina: uw CSS-variabelen die onder `[data-bs-theme="dark"]` zijn gedeclareerd, worden automatisch actief, zonder enige wijziging aan uw thema.

- **Automatische detectie** van de instelling `prefers-color-scheme` van de browser (modus Auto)
- **Schakelaar in de header**: een knop die wisselt tussen Auto → Licht → Donker
- **Klantvoorkeur**: visuele keuze op de profielpagina van het klantaccount
- **Dubbele opslag**: cookie voor bezoekers, klantcustomfield voor ingelogde accounts
- **Anti-FOUC**: het thema wordt vóór het renderen van de pagina toegepast, geen witte flits
- **Synchronisatie bij het inloggen**: de voorkeur van het account wordt bij het inloggen automatisch hersteld

## Vereisten

- Shopware 6.7.0 of hoger
- Een thema waarvan de kleuren zijn gedefinieerd via CSS-variabelen onder `[data-bs-theme="dark"]` (conventie van Bootstrap 5.3)

De plugin levert geen donker kleurenpalet: hij stuurt uitsluitend het attribuut `data-bs-theme` aan. Uw CSS voor de donkere modus moet dus al in het thema aanwezig zijn.

## Installatie

1. Kopieer de map `DfDarkMode` naar `custom/plugins/` van uw Shopware-installatie.
2. Voer de volgende commando's uit:

```
bin/console plugin:refresh
bin/console plugin:install --activate DfDarkMode
bin/console theme:compile
```

Na het compileren van het thema verschijnt de schakelknop in de header van de storefront en wordt de kaart "Weergave" getoond op de profielpagina van het klantaccount.

Gebruik in een ontwikkelomgeving `bin/console theme:compile --active-only` of de storefront-watcher om direct opnieuw te compileren.

## Werking

### De drie modi

- **Auto** (standaard): volgt de instelling van de browser of het besturingssysteem. Zet de gebruiker zijn systeem op donker, dan volgt de storefront in realtime.
- **Licht**: forceert de lichte modus, ongeacht de browser.
- **Donker**: forceert de donkere modus, ongeacht de browser.

### Prioriteitsvolgorde van de voorkeur

1. **Ingelogde klant**: het customfield `df_dark_mode_preference` van het klantaccount gaat boven alles.
2. **Bezoeker**: de cookie `df-dark-mode` (levensduur 1 jaar).
3. **Geen voorkeur**: modus Auto.

### Anti-FOUC

Een inline script in de head-tag leest de cookie en past `data-bs-theme` toe voordat de browser de pagina tekent. Resultaat: geen flits van een lichte achtergrond bij het laden in donkere modus, zelfs op een trage verbinding.

### Synchronisatie bij het inloggen

Wanneer een klant inlogt, wordt zijn opgeslagen voorkeur naar de cookie gekopieerd. Het anti-FOUC-script beschikt dus vanaf de volgende pagina over de juiste waarde, op al zijn apparaten.

## Gebruik aan klantzijde

### Knop in de header

De knop toont een pictogram dat past bij de actieve modus: monitor (Auto), zon (Licht) of maan (Donker). Elke klik gaat naar de volgende modus. De wijziging wordt direct toegepast met een zachte overgang en op de achtergrond opgeslagen.

### Profielpagina van het account

Onder **Mijn account → Profiel** biedt een kaart "Weergave" drie aanklikbare tegels (Auto, Licht, Donker). De keuze wordt in het klantaccount opgeslagen en er verschijnt een bevestigingsbericht. Toetsenbordnavigatie (Enter / spatiebalk) wordt ondersteund.

## Aanpassing

### De knop in de header verplaatsen

Standaard wordt de schakelaar in het block `base_header_actions_wishlist` geplaatst. Om hem elders te zetten, overschrijft u het basistemplate in uw thema en voegt u het component in het block van uw keuze in:

```
{% sw_extends '@Storefront/storefront/base.html.twig' %}

{% block base_header_actions_search %}
    {{ parent() }}
    {% sw_include '@Storefront/storefront/component/dark-mode-toggle.html.twig' %}
{% endblock %}
```

### Reageren op themawijzigingen in JavaScript

De plugin zendt bij elke wijziging het event `df-dark-mode-changed` uit op `document`:

```
document.addEventListener('df-dark-mode-changed', (e) => {
    console.log(e.detail.preference);    // 'auto', 'light' of 'dark'
    console.log(e.detail.resolvedTheme); // 'light' of 'dark'
});
```

Nuttig om een kaart, een grafiek of een ander extern component dat de CSS-variabelen niet leest, opnieuw te laden.

### Teksten en vertalingen

Alle labels zijn Shopware-snippets (voorvoegsel `df-dark-mode.`) die u in de administration kunt aanpassen onder **Instellingen → Snippets**. De plugin bevat Frans, Engels en Duits.

## Technische referentie

### Customfield

De plugin maakt bij de installatie een set customfields `df_dark_mode` aan met het veld `df_dark_mode_preference` (select: auto / light / dark), gekoppeld aan de entiteit customer. Het is zichtbaar en aanpasbaar in de administration op de klantkaart.

### AJAX-route

`POST /df-dark-mode/save` met de parameter `mode` (auto / light / dark). Plaatst de cookie en werkt, als er een klant is ingelogd, zijn customfield bij. Antwoord in JSON.

### Cookie

Naam: `df-dark-mode` · Waarden: auto / light / dark · Duur: 365 dagen · SameSite=Lax. Strikt functionele cookie: hij bevat geen persoonsgegevens en geen trackingidentificatie.

## Verwijderen

```
bin/console plugin:deactivate DfDarkMode
bin/console plugin:uninstall DfDarkMode
```

Bij het verwijderen worden de set customfields en de klantvoorkeuren gewist, tenzij de optie "gegevens behouden" is aangevinkt.

## Probleemoplossing

### De knop verschijnt niet in de header

Controleer of het thema daadwerkelijk opnieuw is gecompileerd (`bin/console theme:compile`) en leeg de cache (`bin/console cache:clear`). Als uw thema het block `base_header_actions_wishlist` sterk overschrijft, verplaats dan de include van het component naar een ander block (zie Aanpassing).

### De donkere modus schakelt in maar de kleuren veranderen niet

De plugin plaatst wel degelijk `data-bs-theme="dark"` (controleerbaar in de inspector van de browser), maar uw CSS definieert geen variabelen onder die selector. Voeg uw donkere variabelen toe in het blok `[data-bs-theme="dark"]` van uw thema.

### Witte flits bij het laden

Controleer of geen andere plugin het block `base_head` overschrijft zonder `{{ parent() }}` aan te roepen, want dat verwijdert het anti-FOUC-script.

### De voorkeur blijft niet behouden tussen apparaten

Alleen ingelogde klanten profiteren via hun account van synchronisatie over meerdere apparaten. Voor bezoekers is de voorkeur lokaal aan de browser (cookie).

## Changelog

### 1.0.0

- Eerste versie: browserdetectie, schakelaar in de header, voorkeur in het klantaccount, anti-FOUC, synchronisatie bij het inloggen, snippets FR/EN/DE.