Brand Carousel: documentação do carrossel de marcas PrestaShop

Instalação

No back-office, abra Módulos > Gestor de módulos, clique em «Carregar um módulo» e envie o ficheiro dfbrandcarousel-2.0.0.zip. O módulo é compatível com PrestaShop 8.0 a 9.x.

Na instalação, o módulo cria as suas duas tabelas, o hook displayDfBrandCarousel, a pasta /img/dfbrandcarousel/ para os logótipos alternativos e um primeiro bloco: um carrossel de marcas na página inicial (displayHome) com o título «As nossas marcas» traduzido em cada idioma instalado. Abra a sua loja para ver o resultado e depois altere ou elimine esse bloco.

O módulo gere-se a partir do botão «Configurar» no Gestor de módulos.

Atualização a partir da versão 1.0.x

Carregue o ZIP 2.0.0 por cima da versão instalada. O script de atualização cria as novas tabelas e transfere a sua configuração para um bloco chamado «Brand carousel», no mesmo hook: título, número de marcas, colunas, deslocamento automático, velocidade, espaçamento, setas, pontos, marcas selecionadas e ordem aleatória. As marcas sem produtos continuam visíveis como antes. As antigas definições DFBC_* são depois eliminadas. O Swiper deixa de ser usado, o que resolve os conflitos com temas e page builders que carregam a sua própria versão.

A lista de blocos

O separador Blocos lista os seus blocos com o modo, o hook e a origem. Para cada bloco pode:

• ativar ou desativar o bloco com o interruptor;
• editar o bloco no editor;
• duplicar o bloco (a cópia é criada desativada);
• eliminar o bloco;
• arrastar os blocos para definir a sua ordem quando vários partilham o mesmo hook.

O botão «Limpar a cache» apaga a cache de marcas, contadores e vendas (ver Cache e desempenho).

O editor de blocos

O editor mostra as definições à esquerda, repartidas por 5 separadores, e uma pré-visualização à direita. A pré-visualização atualiza-se a cada alteração e pode ser vista em largura de computador, tablet ou telemóvel. Usa um tipo de letra neutro: na loja, o bloco usa os tipos de letra do seu tema.

A barra superior contém o nome interno do bloco, o interruptor de ativação, o seletor de idioma dos campos traduzíveis e o botão Guardar. Um indicador assinala as alterações não guardadas e Ctrl+S (Cmd+S no Mac) guarda sem sair do editor.

Separador Conteúdo

Cabeçalho

• Título e subtítulo: por idioma. Deixe o título vazio para o ocultar.
• Etiqueta do título: H2 na página inicial, H3 numa página que já tem títulos H2, ou p e div para um título sem função de cabeçalho.
• Disposição do cabeçalho: título à esquerda e ligação à direita, tudo à esquerda ou centrado. Nos dois últimos casos, a ligação passa para baixo dos logótipos.
• Ligação para todas as marcas: texto por idioma e URL. Sem URL, a ligação leva à página de marcas do PrestaShop.

Marcas a mostrar

• Todas as marcas ativas da loja.
• Seleção manual: adicione marcas a partir da lista da esquerda com o botão + e reordene-as arrastando-as na lista da direita. «Adicionar toda a lista» adiciona as marcas da pesquisa em curso.
• Marcas de uma categoria: marcas com pelo menos um produto visível na categoria escolhida ou nas suas subcategorias.
• Marcas da categoria atual: numa página de categoria, as marcas dessa categoria. Numa página de produto, as da sua categoria principal. Nas restantes, todas as marcas.

Estas definições completam a origem:

• Marcas excluídas: retiradas da lista, exceto na seleção manual.
• Ordenação: a sua ordem (seleção manual), alfabética, mais produtos primeiro, mais vendidas primeiro num período de 7 a 730 dias, marcas mais recentes primeiro ou aleatória a cada visita. A ordem alfabética ignora acentos e pontuação: L’Oréal é ordenada como «loreal».
• Número máximo de marcas: 0 mostra todas as marcas correspondentes.
• Mínimo de produtos: 1 por defeito, para nunca enviar o visitante para uma página de marca vazia.
• Apenas marcas com logótipo: o filtro é aplicado antes do número máximo, por isso obtém o número pedido.

A ordem aleatória é calculada no navegador. Uma cache de página completa pode servir a mesma página a todos os visitantes e a ordem muda na mesma a cada visita. Nos modos de deslocamento contínuo, o número máximo aplica-se primeiro por ordem alfabética e depois as marcas escolhidas são baralhadas.

Separador Esquema

Os 8 modos de apresentação

• Carrossel: logótipos que avançam por página ou por logótipo, em 1 a 3 linhas, com setas, pontos e deslocamento automático.
• Deslocamento contínuo: logótipos que deslizam sem pausa em 1 a 4 linhas.
• Deslocamento vertical: 1 a 4 colunas que se movem para cima ou para baixo.
• Grelha: cartões em colunas, com pesquisa, filtro por letra e botão «Ver mais marcas» opcionais.
• Mural de logótipos: grelha sem cartões, logótipos separados por linhas finas.
• Mural rotativo: grelha fixa cujos logótipos mudam um a um.
• Etiquetas: nomes de marcas em etiquetas compactas, com logótipo pequeno opcional. Adequado a uma coluna lateral.
• Diretório A-Z: todas as marcas agrupadas por letra, com uma barra de letras clicáveis e uma pesquisa.

Colunas

O número de colunas define-se separadamente para computador (1 a 12), tablet (1 a 8) e telemóvel (1 a 4). Estes patamares dependem da largura disponível para o bloco e não da largura do ecrã: um bloco numa coluna lateral usa a definição de telemóvel mesmo num ecrã grande.

• Linhas (carrossel e mural rotativo): 1 a 3. No carrossel, os logótipos preenchem cada coluna de cima para baixo e depois as linhas deslocam-se em conjunto.
• Mostrar parte do logótipo seguinte (carrossel): em tablet e telemóvel, o logótipo seguinte espreita para indicar que a lista se pode deslizar. As setas laterais ficam então ocultas no telemóvel.
• Linhas antes de Ver mais marcas (grelha e mural de logótipos): 0 mostra tudo de uma vez.

Deslocamento contínuo e vertical

• Linhas (ou colunas na vertical): 1 a 4, nunca mais do que o número de marcas.
• Marcas diferentes em cada linha: as marcas são repartidas entre as linhas. Desativado, cada linha mostra todas as marcas desfasadas. A repartição exige pelo menos 3 marcas por linha; caso contrário, o módulo desfasa as linhas.
• Largura dos logótipos (horizontal) ou Altura do bloco (vertical).

Pesquisa e filtros

O campo de pesquisa (grelha, mural de logótipos, diretório) filtra as marcas durante a escrita, sem ter em conta acentos nem pontuação. O filtro por letra (grelha e mural de logótipos) mostra uma barra 0-9, A a Z e # para os nomes que não começam por letra nem por algarismo. As letras sem marcas aparecem a cinzento. O diretório aceita 1 a 6 colunas e logótipos pequenos ao lado dos nomes.

Espaçamento e largura

• Espaço entre logótipos e margem vertical da secção.
• Largura: largura da posição, fundo em largura total (o fundo cobre o ecrã e o conteúdo fica na coluna do tema) ou largura total de margem a margem (útil para um deslocamento contínuo que atravessa todo o ecrã).

Separador Estilo

Cartões das marcas

• Estilo dos cartões: preenchido, contorno, sombra ou simples.
• Altura máxima do logótipo, altura mínima dos cartões, margem interior e arredondamento dos cantos.
• Nome da marca: só sem logótipo, sempre por baixo do logótipo ou ao passar o rato.
• Descrição curta: os primeiros 160 caracteres da descrição curta da marca.

Logótipos

• Número de produtos por baixo do logótipo ou na etiqueta.
• Efeito no logótipo: nenhum, cinzento e cor ao passar o rato, sempre cinzento, esbatido e nítido ao passar o rato.
• Efeito ao passar sobre os cartões: elevação, zoom do logótipo, contorno na cor de destaque ou nenhum.
• Remover os fundos brancos: funde o branco dos logótipos JPG nos cartões claros. Deixe-a desativada em fundos escuros e use logótipos transparentes.
• Tamanho da imagem: recomenda-se a imagem original. Os tamanhos do PrestaShop acrescentam muitas vezes margens brancas à volta dos logótipos.

Cores

Podem ajustar-se seis cores: destaque (setas, ligações, letra ativa), fundo dos cartões, contornos, fundo da secção, título e texto. «Repor» devolve o controlo ao tema. O texto sobre a cor de destaque passa automaticamente a branco ou preto consoante o contraste.

Separador Animação

Carrossel

• Deslocamento automático e pausa entre páginas (1 a 15 segundos).
• Duração da transição e passo: uma página inteira ou um logótipo.
• Voltar ao início no fim: depois do último logótipo, o carrossel regressa ao primeiro. Para um deslocamento sem fim, use o modo Deslocamento contínuo.
• Setas: 4 estilos (preenchido, contorno, quadrado, mínimo) e 4 posições (nas margens a sobressair, dentro das margens, no cabeçalho, por baixo dos logótipos).
• Pontos de paginação.

O carrossel também funciona com o teclado (setas esquerda e direita), com o dedo e arrastando com o rato.

Deslocamento contínuo e vertical

• Sentido: para a esquerda ou para a direita, para cima ou para baixo.
• Alternar as linhas: uma linha em cada duas desloca-se no sentido oposto.
• Velocidade: 5 a 400 píxeis por segundo, igual qualquer que seja o comprimento da linha.
• Ao passar o rato: abrandar, parar ou continuar. O abrandamento é progressivo.
• Esbater as margens: os logótipos aparecem e desaparecem em fundido.

Mural rotativo

Defina o número de linhas e o tempo entre trocas (0,8 a 20 segundos). A cada troca, um logótipo da grelha é substituído por uma marca que ainda não está visível.

Acessibilidade

O botão de pausa, recomendado pelo critério WCAG 2.2.2 para qualquer conteúdo que se mova durante mais de 5 segundos, aparece no cabeçalho ou por baixo dos logótipos. As animações param também ao passar o rato, com o foco do teclado, quando o separador está oculto e quando o bloco sai do ecrã. Para os visitantes que reduziram as animações no sistema, o deslocamento contínuo torna-se uma linha parada que deslocam à mão e o carrossel deixa de avançar sozinho.

Separador Apresentação

Posição

O campo Hook propõe 14 posições agrupadas:

• Página inicial: displayHome.
• Todas as páginas: displayWrapperTop, displayWrapperBottom, displayContentWrapperTop, displayContentWrapperBottom, displayNavFullWidth, displayFooterBefore, displayFooterAfter.
• Colunas: displayLeftColumn, displayRightColumn.
• Páginas específicas: displayFooterProduct, displayFooterCategory, displayShoppingCartFooter.
• Integração: displayDfBrandCarousel, ou «Nenhum» para um bloco mostrado apenas através do widget ou do shortcode.

«Outro hook» aceita qualquer nome que comece por display (letras, algarismos e sublinhados). O módulo regista-se nele ao guardar. O seu tema tem depois de chamar esse hook.

Páginas e dispositivos

Páginas limita o bloco a certos tipos de página: página inicial, categorias, produtos, marcas, páginas CMS, pesquisa, carrinho e checkout, outras páginas. Nenhuma assinalada: todas as páginas onde o hook existe. Dispositivos oculta o bloco em computador (992 px ou mais), tablet (576 a 991 px) ou telemóvel (menos de 576 px).

Estatísticas

Com «Enviar os cliques para o Google Analytics», cada clique numa marca envia o evento dfbc_brand_click com os parâmetros dfbc_block, brand_id e brand_name. O evento vai para dataLayer se o Google Tag Manager estiver presente e, caso contrário, para gtag. No GTM, crie um acionador «Evento personalizado» sobre dfbc_brand_click.

Colocar um bloco noutro local

O separador Integração do módulo e a secção «Inserir este bloco noutro local» de cada bloco guardado dão os códigos a copiar. Substitua 3 pelo número do bloco.

• Num template do tema: {widget name='dfbrandcarousel' id_block=3} mostra esse bloco, seja qual for o seu hook.
• Com o hook do módulo: {hook h='displayDfBrandCarousel'} mostra todos os blocos atribuídos a esse hook, {hook h='displayDfBrandCarousel' id_block=3} um bloco específico.
• Numa página CMS: cole [dfbrandcarousel id="3"] no conteúdo. O shortcode é substituído pelo bloco, mesmo quando está sozinho num parágrafo.
• Conteúdo AJAX ou page builder: se o bloco for inserido depois de a página carregar, chame window.DFBC.init(contentor). window.DFBC.destroy(contentor) para os blocos de forma limpa antes de remover o seu HTML.

Quando um bloco aparece numa página onde o módulo não carregou os seus ficheiros (widget num template, hook personalizado), o bloco adiciona-os sozinho, uma única vez por página.

Logótipos das marcas

O separador Logótipos das marcas lista todas as marcas ativas com o logótipo do PrestaShop e o número de produtos.

• Logótipo alternativo: carregue um ficheiro PNG, JPG, WebP, GIF ou SVG com 2 MB no máximo. Substitui o logótipo do PrestaShop em todos os blocos. «Remover» volta ao logótipo original.
• Ligação personalizada: URL completo (https://…) ou caminho que comece por /. Uma ligação para outro site abre num novo separador. Vazia, a ligação leva à página da marca.

Os SVG com scripts, atributos de evento, objetos incorporados ou ligações externas são recusados: exporte-os de novo como SVG simples. Os ficheiros ficam em /img/dfbrandcarousel/, cujo ficheiro .htaccess bloqueia a execução de scripts e aplica uma política de segurança aos SVG.

Se um módulo de otimização de imagens criou versões .webp ou .avif ao lado dos logótipos do PrestaShop em /img/m/, estas são servidas automaticamente aos navegadores compatíveis.

Personalizar o HTML

Copie modules/dfbrandcarousel/views/templates/hook/dfbrandcarousel.tpl para themes/o-seu-tema/modules/dfbrandcarousel/views/templates/hook/dfbrandcarousel.tpl e edite a cópia. As atualizações do módulo não a substituem. Todos os valores do template já vêm escapados pelo módulo, daí o uso de nofilter.

Cada bloco é gerado num elemento <section class="dfbc dfbc--MODO"> com o identificador dfbc-NÚMERO-N. Para CSS específico, prefira as classes, por exemplo:

.dfbc--marquee .dfbc-card { border-radius: 999px; }

Multiloja e idiomas

Os blocos gerem-se loja a loja: escolha uma loja no seletor do back-office antes de os editar. Os logótipos alternativos e as ligações personalizadas são comuns a todas as lojas. O título, o subtítulo e o texto da ligação introduzem-se por idioma. O módulo está traduzido em inglês, francês, espanhol, alemão, italiano, neerlandês, polaco e português, e suporta idiomas escritos da direita para a esquerda.

Cache e desempenho

O módulo não carrega jQuery, nem Swiper, nem qualquer biblioteca externa. O CSS e o JavaScript pesam cerca de 5 KB e 7 KB comprimidos e só são carregados nas páginas onde um bloco pode aparecer: um bloco em displayHome não carrega nada nas páginas de produto.

A lista de marcas fica em cache 6 horas, o número de produtos por marca 1 hora e as vendas 12 horas, em var/cache/. Esta cache é limpa a cada gravação no módulo e sempre que uma marca ou um produto é adicionado, alterado ou eliminado. O PrestaShop só executa estes acionadores para os funcionários com permissão para ver o módulo: se um colega sem essa permissão alterar o catálogo, use o botão «Limpar a cache».

Perguntas frequentes

O bloco não aparece

Verifique se o bloco está ativo, se o seu tema chama o hook e se os filtros Páginas e Dispositivos permitem a página consultada. Verifique depois se ainda restam marcas a mostrar: a pré-visualização do editor indica quantas marcas estão selecionadas e mostra uma mensagem quando nenhuma corresponde (origem, mínimo de produtos, filtro de logótipos).

Os logótipos mostram retângulos brancos

Os logótipos do PrestaShop são JPG com fundo branco. Ative «Remover os fundos brancos» em cartões claros, ou carregue logótipos transparentes no separador Logótipos das marcas.

Os logótipos estão desfocados

Escolha «Imagem original» em Tamanho da imagem, ou carregue um logótipo alternativo em SVG ou em PNG de alta resolução.

O deslocamento não se mexe

O botão de pausa pode ter sido premido, ou o sistema do visitante pede menos animações. Neste segundo caso, o módulo mostra propositadamente logótipos parados.

Falta uma marca

A marca tem de estar ativa, associada à loja e ter pelo menos o número mínimo de produtos visíveis. Verifique também as marcas excluídas e a opção «Apenas marcas com logótipo».

Desinstalação

A desinstalação elimina as tabelas do módulo, a pasta /img/dfbrandcarousel/ com os logótipos alternativos e a cache do módulo.