DF Dark Mode para PrestaShop 8 e 9: documentação

O DF Dark Mode acrescenta um modo escuro completo à sua loja PrestaShop 8 ou 9, sem nenhuma alteração do seu tema. O módulo deteta a preferência de sistema do visitante, memoriza a sua escolha e gera o tema escuro do lado do servidor.

Instalação

1. No back-office, abra Módulos > Gestor de módulos.
2. Clique em Instalar um módulo e envie o ficheiro dfdarkmode-1.1.0.zip.
3. Terminada a instalação, clique em Configurar.

O módulo fica ativo imediatamente com as suas definições por defeito: motor «filtro inteligente», modo «automático» e botão flutuante no canto inferior direito. Não é necessária nenhuma configuração para um funcionamento correto.

Escolher o motor de renderização

O módulo propõe dois motores. A escolha é feita no campo Motor de renderização da configuração.

Filtro inteligente (recomendado)

Este motor inverte a página inteira e depois contra-inverte cada elemento multimédia (imagens, vídeos, iframes, canvas, fundos) para que as suas fotografias de produto conservem as suas cores naturais. Funciona em qualquer tema, sem configuração nem CSS adicional.

Duas definições permitem afinar a renderização:

• Luminosidade (50 a 150%, por defeito 100): baixe-a ligeiramente, para 92 por exemplo, se a renderização escura lhe parecer demasiado luminosa.
• Contraste (50 a 150%, por defeito 100).

Paleta gerada

Este motor calcula uma gama escura completa a partir de duas cores que escolhe: uma cor de fundo e uma cor de destaque. Daí derivam automaticamente nove variáveis CSS:

• --df-bg: o fundo da página
• --df-surface, --df-surface-2, --df-surface-3: três níveis de superfície (cartões, cabeçalhos, hovers)
• --df-border: os contornos
• --df-text, --df-text-muted: o texto principal e o texto atenuado
• --df-accent, --df-accent-hover: o destaque e o seu estado de hover

A cor do texto dos botões é escolhida automaticamente (clara ou escura) consoante a luminância relativa do seu destaque, para garantir um contraste legível. Este motor produz uma renderização mais nítida do que o filtro, mas pode exigir alguns ajustes CSS consoante o seu tema.

Modo por defeito

O campo Modo por defeito determina o que vê um visitante que nunca usou o botão:

• Automático: o módulo segue a preferência do sistema operativo do visitante (definição prefers-color-scheme). Se o visitante mudar o seu dispositivo para modo escuro durante a navegação, a loja acompanha em direto, sem recarregamento.
• Claro: a loja fica clara enquanto o visitante não pedir o modo escuro.
• Escuro: a loja é apresentada em escuro para toda a gente por defeito.

Assim que o visitante clica no botão, a sua escolha é memorizada no seu navegador e prevalece sobre o modo por defeito, em todas as suas visitas seguintes.

Posicionar o botão

O campo Posição do botão propõe dois modos.

Botão flutuante

Um botão redondo sobreposto à página, num dos quatro cantos (cima/baixo, esquerda/direita). Pode ocultá-lo em mobile através da definição dedicada.

Hook de tema

O botão é renderizado inline, na disposição do seu tema. Selecione o hook alvo na lista:

• displayNav1, displayNav2: barras superiores do cabeçalho (o displayNav2 corresponde à zona superior direita na maioria dos temas)
• displayTop, displayNavFullWidth, displayBanner
• displayFooter, displayFooterAfter

A variante inline do botão é mais compacta e transparente: herda as cores do seu contentor e funde-se com o seu cabeçalho ou rodapé.

Hook personalizado

Se o seu tema executar um hook próprio, introduza simplesmente o seu nome no campo Nome do hook personalizado. O módulo regista-o automaticamente ao guardar o formulário: nenhuma linha de código a escrever. Este campo tem prioridade sobre a lista acima.

O nome deve começar por uma letra e conter apenas letras, algarismos e underscores. Exemplo: displayMeuSwitcher.

A partir de um template

Os integradores podem mostrar o botão em qualquer sítio de um ficheiro .tpl do tema com a sintaxe widget do PrestaShop:

{widget name='dfdarkmode'}

Esta chamada renderiza sempre o botão, qualquer que seja o modo de posicionamento configurado.

Botão de ciclo com três estados

Ative a opção Botão de 3 estados para que o botão alterne entre claro, escuro e automático em vez da simples alternância claro/escuro. Aparece um pequeno emblema «A» no botão quando o modo automático está ativo.

Excluir elementos

O campo Seletores CSS excluídos aceita uma lista de seletores, um por linha ou separados por vírgulas. Os elementos correspondentes conservam a sua renderização clara de origem: prático para um logótipo, um banner de parceiro ou um widget de terceiros.

.meu-logotipo
#banner-parceiro
.widget-avaliacoes

Os seletores que contêm chavetas, sinais de maior/menor ou pontos e vírgulas são ignorados ao guardar.

Pode também adicionar diretamente a classe df-no-invert a um elemento do seu tema: será automaticamente preservado.

CSS personalizado

O campo CSS personalizado só é injetado quando o modo escuro está ativo. Prefixe as suas regras com html.df-dark:

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

As variáveis CSS (--df-surface, --df-text, etc.) só estão disponíveis com o motor «paleta gerada».

API JavaScript

O módulo expõe uma API pública para as suas próprias integrações:

// Modo configurado: "light", "dark" ou "auto"
DFDarkMode.get();

// Modo realmente apresentado: "light" ou "dark"
DFDarkMode.effective();

// Forçar um modo (memorizado no navegador)
DFDarkMode.set('dark');

// Alternar
DFDarkMode.toggle();

É emitido um evento no document a cada mudança de modo:

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

Por fim, qualquer elemento com o atributo data-df-darkmode-toggle torna-se automaticamente um acionador, sem código adicional.

Funcionamento técnico

Ausência de flash no carregamento

Um script síncrono, injetado no cabeçalho da página, lê a preferência memorizada e aplica depois a classe df-dark ao elemento raiz antes da primeira renderização do navegador. O visitante em modo escuro nunca vê portanto a versão clara, nem por breves instantes.

Contra-inversão dos elementos multimédia

Com o motor de filtro, os filtros CSS compõem-se quando estão aninhados: não se anulam. Uma imagem colocada num elemento picture já contra-invertido seria portanto invertida duas vezes. O módulo neutraliza este caso com uma regra de salvaguarda que repõe a zero o filtro de qualquer elemento multimédia aninhado num ancestral já contra-invertido.

Memorização

A escolha do visitante é guardada no localStorage do seu navegador, sob a chave dfdm. Nenhum dado pessoal é recolhido nem transmitido a um servidor: o módulo não usa nem cookie nem chamada de rede, e não tem portanto nenhuma implicação em matéria de RGPD.

Resolução de problemas

As fotografias de produto aparecem em negativo

Verifique que está a usar a versão 1.1.0 ou superior, e esvazie depois a cache do PrestaShop (Parâmetros avançados > Desempenho > Limpar a cache). Se um elemento específico continuar invertido, adicione o seu seletor no campo dos seletores excluídos.

O botão não aparece no hook escolhido

Alguns temas não executam todos os hooks padrão. Verifique em Design > Posições que o módulo está ligado ao hook visado, e que esse hook é efetivamente chamado pelo seu tema. Em último recurso, use a sintaxe widget no ficheiro .tpl à sua escolha.

Um elemento continua ilegível em modo escuro

Adicione uma regra no campo CSS personalizado, com o prefixo html.df-dark. Se o problema disser respeito a um bloco inteiro, excluí-lo através dos seletores CSS é frequentemente mais simples.

Desinstalação

A desinstalação elimina toda a configuração do módulo. As preferências registadas no navegador dos seus visitantes não são afetadas, mas deixam de ter efeito uma vez o módulo removido.