dfvariantswatch: swatches de variantes com fotografia e stock

Apresentação

O dfvariantswatch substitui as listas pendentes de declinações das fichas de produto PrestaShop por miniaturas visuais clicáveis (fotografias, cores ou texto), mostra uma pré-visualização da variante na galeria principal ao passar o rato e indica o stock de cada variante diretamente na miniatura.

O módulo funciona melhorando os widgets nativos do PrestaShop via JavaScript: não substitui nenhum template do tema, o que o torna compatível com Classic, Hummingbird e a maioria dos temas premium.

Instalação

1. Back-office → Módulos → Gestor de módulos → Carregar um módulo
2. Arraste e largue o arquivo dfvariantswatch.zip e clique em Instalar
3. Clique em Configurar para aceder às definições

A instalação cria a tabela df_variant_swatch, a pasta de imagens img/dfvariantswatch/ e os valores de configuração por defeito. Não é necessária nenhuma alteração do tema.

Funcionamento das miniaturas

Para cada atributo, o módulo escolhe a fonte da miniatura por esta ordem de prioridade:

1. Imagem carregada no back-office para esse atributo (separador Miniaturas por atributo)
2. Código de cor hexadecimal definido no back-office
3. Imagem derivada automaticamente da primeira combinação que usa esse atributo
4. Cor nativa do PrestaShop do atributo (campo de cor do grupo)
5. Pastilha de texto com o nome do atributo

A salvaguarda dos grupos não diferenciados

A derivação automática só é conservada se as imagens diferirem realmente entre os atributos do grupo, ou se o grupo estiver marcado como grupo de cores no PrestaShop. Concretamente: num produto com um grupo Tamanho (S, M, L, XL) cujas combinações partilham todas as mesmas fotografias, os tamanhos ficam em pastilhas de texto em vez de mostrar quatro vezes a mesma fotografia.

Configuração

Parâmetros gerais

• Ativar o módulo: corta a renderização no front-office sem desinstalar
• Passar o rato = mudança de galeria: a pré-visualização da variante ao passar o rato numa miniatura
• Mostrar o badge de stock: estado de disponibilidade sob cada miniatura
• Ocultar as variantes esgotadas: esconde completamente as miniaturas esgotadas em vez de as riscar
• Forma: redonda, quadrada ou pílula; Tamanho em píxeis
• Limiar de stock baixo: abaixo dele, o badge passa ao estado de stock baixo
• Etiquetas de stock: os três textos são personalizáveis e traduzíveis para português via Internacional → Traduções
• Modo de carregamento dos dados: Inline (recomendado) ou AJAX, ver abaixo
• Grupos não renderizados em swatches: os grupos selecionados conservam o seu widget nativo

Miniaturas por atributo

Este separador lista todos os grupos de atributos da loja. Para cada valor, pode carregar uma imagem (jpg, png, webp ou gif, 2 MB no máximo, 200 por 200 píxeis recomendado) ou introduzir um código de cor no formato #RRGGBB, pré-visualizar a miniatura atual e eliminar um swatch existente.

Modos de carregamento

Inline (por defeito, recomendado): os dados das variantes são incorporados na página no momento da renderização. Nenhuma chamada AJAX no carregamento, apresentação imediata das miniaturas, robustez máxima.

AJAX: os dados são recuperados através de uma chamada depois do carregamento da página. Reserve este modo às lojas atrás de uma cache full-page agressiva em que a frescura do stock apresentado prevalece sobre a velocidade de apresentação.

Acessibilidade por teclado

O seletor implementa o padrão WAI-ARIA radiogroup: a tecla Tab coloca o foco na variante selecionada do grupo (um único ponto de tabulação por grupo), as setas navegam e selecionam dentro do grupo em ciclo e saltando as variantes indisponíveis, Espaço ou Enter valida a miniatura focada. Os estados são anunciados aos leitores de ecrã via aria-checked e os balões respeitam prefers-reduced-motion.

Personalização CSS

As variáveis CSS expostas permitem ajustar a aparência a partir do CSS do seu tema filho sem tocar no módulo:

.dfvs-swatch {
    --dfvs-size: 56px;   /* tamanho das miniaturas */
}
.dfvs-swatch.dfvs-active {
    box-shadow: 0 0 0 2px #b8860b; /* anel da variante ativa */
}

Para desativar a pré-visualização ao passar o rato num produto preciso, adicione um elemento com o atributo data-dfvs-disable-hover no template de produto.

Resolução de problemas

As miniaturas não aparecem

• Verifique que o módulo está ativado na sua configuração
• Abra a consola do navegador: o módulo regista as suas etapas com o prefixo [dfvariantswatch]; verá o número de grupos renderizados ou o motivo da não renderização
• O produto deve ter declinações; um produto simples não mostra nada, é normal

Os tamanhos aparecem em texto e não em fotografia

É o comportamento esperado da salvaguarda: os valores do grupo partilham as mesmas fotografias de combinações. Carregue imagens dedicadas por tamanho no separador Miniaturas por atributo se quiser visuais (por exemplo pictogramas de silhueta).

O bloco nativo reaparece depois de um clique

O módulo reaplica a ocultação depois de cada atualização AJAX do PrestaShop. Se um tema muito personalizado contornar os eventos padrão, contacte o suporte com o URL da ficha de produto em causa.

Desinstalação

A desinstalação elimina a tabela do módulo, as imagens carregadas em img/dfvariantswatch/ e todas as chaves de configuração. As fotografias das suas combinações não são, evidentemente, afetadas.