DF Dark Mode per PrestaShop 8 e 9 — Documentazione

DF Dark Mode aggiunge una modalità scura completa al suo negozio PrestaShop 8 o 9, senza alcuna modifica al tema. Il modulo rileva la preferenza di sistema del visitatore, memorizza la sua scelta e genera il tema scuro lato server.

Installazione

1. Nel back office, apra Moduli > Gestore dei moduli.
2. Clicchi su Carica un modulo e trascini il file dfdarkmode-1.1.0.zip.
3. Al termine dell’installazione, clicchi su Configura.

Il modulo è attivo immediatamente con le impostazioni predefinite: motore a filtro intelligente, modalità automatica e pulsante flottante in basso a destra. Non è necessaria alcuna configurazione per un funzionamento corretto.

Scegliere il motore di rendering

Il modulo propone due motori. La scelta si effettua nel campo Motore di rendering della configurazione.

Filtro intelligente (consigliato)

Questo motore inverte l’intera pagina e poi contro-inverte ogni media (immagini, video, iframe, canvas, sfondi) affinché le sue foto prodotto conservino i colori naturali. Funziona su qualsiasi tema, senza configurazione né CSS aggiuntivo.

Due regolazioni permettono di affinare il risultato:

• Luminosità (da 50 a 150 %, predefinito 100) — la abbassi leggermente, a 92 per esempio, se il rendering scuro le sembra troppo luminoso.
• Contrasto (da 50 a 150 %, predefinito 100).

Palette generata

Questo motore calcola una gamma scura completa a partire da due colori a sua scelta: un colore di sfondo e un colore d’accento. Da essi vengono derivate automaticamente nove variabili CSS:

• --df-bg — lo sfondo della pagina
• --df-surface, --df-surface-2, --df-surface-3 — tre livelli di superficie (schede, intestazioni, hover)
• --df-border — i bordi
• --df-text, --df-text-muted — il testo principale e il testo attenuato
• --df-accent, --df-accent-hover — l’accento e il suo stato hover

Il colore del testo dei pulsanti viene scelto automaticamente (chiaro o scuro) in base alla luminanza relativa del suo accento, per garantire un contrasto leggibile. Questo motore produce un risultato più pulito del filtro, ma può richiedere qualche ritocco CSS a seconda del tema.

Modalità predefinita

Il campo Modalità predefinita determina ciò che vede un visitatore che non ha ancora usato il pulsante:

• Automatica — il modulo segue la preferenza del sistema operativo del visitatore (impostazione prefers-color-scheme). Se il visitatore passa il dispositivo alla modalità scura durante la navigazione, il negozio lo segue in tempo reale, senza ricaricare.
• Chiara — il negozio resta chiaro finché il visitatore non richiede la modalità scura.
• Scura — il negozio viene mostrato scuro a tutti per impostazione predefinita.

Non appena il visitatore clicca sul pulsante, la sua scelta viene memorizzata nel browser e prevale sulla modalità predefinita in tutte le visite successive.

Posizionare il pulsante

Il campo Posizione del pulsante propone due modalità.

Pulsante flottante

Un pulsante rotondo sovrapposto alla pagina, in uno dei quattro angoli (alto/basso, sinistra/destra). Può nasconderlo su mobile tramite l’impostazione dedicata.

Hook di tema

Il pulsante viene visualizzato in linea, all’interno del layout del suo tema. Selezioni l’hook di destinazione dall’elenco:

• displayNav1, displayNav2 — barre superiori dell’header (displayNav2 corrisponde all’area in alto a destra nella maggior parte dei temi)
• displayTop, displayNavFullWidth, displayBanner
• displayFooter, displayFooterAfter

La variante in linea del pulsante è più compatta e trasparente: eredita i colori del suo contenitore e si fonde con il suo header o il suo footer.

Hook personalizzato

Se il suo tema esegue un hook proprio, basta digitarne il nome nel campo Nome dell’hook personalizzato. Il modulo lo registra automaticamente al salvataggio del modulo, senza scrivere una riga di codice. Questo campo ha la priorità sull’elenco precedente.

Il nome deve iniziare con una lettera e contenere solo lettere, cifre e trattini bassi. Esempio: displayMioSwitcher.

Da un template

Gli integratori possono visualizzare il pulsante ovunque in un file .tpl del tema con la sintassi widget di PrestaShop:

{widget name='dfdarkmode'}

Questa chiamata mostra sempre il pulsante, qualunque sia la modalità di posizionamento configurata.

Pulsante a ciclo di tre stati

Attivi l’opzione Pulsante a 3 stati affinché il pulsante alterni tra chiara, scura e automatica invece del semplice passaggio chiaro/scuro. Un piccolo badge «A» compare sul pulsante quando la modalità automatica è attiva.

Escludere elementi

Il campo Selettori CSS esclusi accetta un elenco di selettori, uno per riga o separati da virgole. Gli elementi corrispondenti conservano il loro rendering chiaro originale, comodo per un logo, un banner partner o un widget di terze parti.

.mio-logo
#banner-partner
.widget-recensioni

I selettori contenenti parentesi graffe, parentesi angolari o punti e virgola vengono scartati al salvataggio.

Può anche aggiungere direttamente la classe df-no-invert a un elemento del suo tema: verrà preservato automaticamente.

CSS personalizzato

Il campo CSS personalizzato viene iniettato solo quando la modalità scura è attiva. Anteponga alle sue regole html.df-dark:

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

Le variabili CSS (--df-surface, --df-text, ecc.) sono disponibili solo con il motore a palette generata.

API JavaScript

Il modulo espone un’API pubblica per le sue integrazioni:

// Modalità configurata: "light", "dark" o "auto"
DFDarkMode.get();

// Modalità realmente visualizzata: "light" o "dark"
DFDarkMode.effective();

// Forzare una modalità (memorizzata nel browser)
DFDarkMode.set('dark');

// Alternare
DFDarkMode.toggle();

Un evento viene emesso sul documento a ogni cambio di modalità:

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

Infine, qualsiasi elemento con l’attributo data-df-darkmode-toggle diventa automaticamente un attivatore, senza codice aggiuntivo.

Funzionamento tecnico

Nessun lampeggio al caricamento

Uno script sincrono, iniettato nell’intestazione della pagina, legge la preferenza memorizzata e applica la classe df-dark all’elemento radice prima del primo rendering del browser. Il visitatore in modalità scura non vede quindi mai la versione chiara, nemmeno per un istante.

Contro-inversione dei media

Con il motore a filtro, i filtri CSS si compongono quando sono annidati: non si annullano a vicenda. Un’immagine collocata in un elemento picture già contro-invertito verrebbe quindi invertita due volte. Il modulo neutralizza questo caso con una regola di protezione che azzera il filtro di ogni media annidato in un antenato già contro-invertito.

Memorizzazione

La scelta del visitatore è archiviata nel localStorage del suo browser, con la chiave dfdm. Nessun dato personale viene raccolto o trasmesso a un server: il modulo non usa cookie né chiamate di rete, e non ha quindi alcuna implicazione GDPR.

Risoluzione dei problemi

Le foto prodotto appaiono in negativo

Verifichi di utilizzare la versione 1.1.0 o superiore, poi svuoti la cache di PrestaShop (Parametri avanzati > Prestazioni > Svuota la cache). Se un elemento specifico resta invertito, aggiunga il suo selettore nel campo dei selettori esclusi.

Il pulsante non compare sull’hook scelto

Alcuni temi non eseguono tutti gli hook standard. Verifichi in Design > Posizioni che il modulo sia effettivamente agganciato all’hook di destinazione e che tale hook venga realmente richiamato dal suo tema. Come ultima risorsa, usi la sintassi widget nel file .tpl che preferisce.

Un elemento resta illeggibile in modalità scura

Aggiunga una regola nel campo CSS personalizzato, con il prefisso html.df-dark. Se il problema riguarda un blocco intero, escluderlo tramite i selettori CSS è spesso più semplice.

Disinstallazione

La disinstallazione elimina l’intera configurazione del modulo. Le preferenze salvate nel browser dei suoi visitatori non vengono modificate, ma diventano prive di effetto una volta rimosso il modulo.