Banner de Categoria: guia completo
Instalar, configurar e gerir os banners de categoria: posição e tamanho na grelha, imagem móvel, ligação por idioma, agendamento por datas na hora da loja, subcategorias, Creative Elements, multiloja e resolução de problemas para PrestaShop 1.7, 8 e 9.
Apresentação e requisitos
O Banner de Categoria insere visuais na grelha de produtos das suas páginas de categoria, na posição que escolher. Indica a categoria, o número do produto a seguir ao qual o banner deve aparecer e a imagem a usar em cada idioma. Do resto trata o módulo, mesmo depois de um filtro por facetas ou de uma mudança de página.
- Compatível com o PrestaShop 1.7.6 a 9.x, verificado nas versões 1.7.8, 8.2.1 e 9.1.5: temas Classic e Hummingbird, temas derivados, listagens Creative Elements, temas com grelha CSS.
- PHP 7.4 a 8.5.
- Multiloja e multilingue (fr, en, es, de, it, nl, pl, pt).
- Sem overrides, sem alterações de templates, sem tarefas CRON.
- O HTML do banner é gerado no servidor por um template Smarty; o JavaScript limita-se a inseri-lo no sítio certo, sem jQuery nem bibliotecas de terceiros.
As imagens carregadas ficam em /img/datafireflycategorybanner/, fora da pasta do módulo. Sobrevivem, portanto, às atualizações do módulo.

Instalação
- Transfira o ficheiro
datafireflycategorybanner.zipa partir da sua conta de cliente. - No back office, abra Módulos > Gestor de módulos.
- Clique em Carregar um módulo e largue o ficheiro.
- Clique em Configurar para aceder à lista de banners.
Na instalação, o módulo cria as suas três tabelas (banners, traduções, associação a lojas), cria a pasta /img/datafireflycategorybanner/ e regista os seus hooks.

Criar um banner
Na página de configuração, clique em Adicionar um novo banner. O formulário reúne as definições seguintes.
Segmentação
- Categoria: a categoria onde o banner aparece. A lista reproduz a árvore da loja, com as categorias desativadas assinaladas.
- Aplicar às subcategorias: estende o banner a todas as subcategorias da categoria escolhida, seja qual for a profundidade.
- Depois do produto número: o banner é inserido a seguir a este produto da listagem. O valor 4 coloca o banner depois do quarto produto apresentado.
- Apenas na primeira página: mostra o banner apenas na primeira página da listagem, sem o repetir na página 2, 3, etc.

Aspeto e ligação
- Ligação do banner: URL de destino, absoluto (
https://…) ou a começar por uma barra (/novidades). Deixe vazio para um banner sem ligação. - Largura na grelha: número de colunas de produto ocupadas pelo banner, de 1 a 4, ou Linha inteira. Nos ecrãs que mostram menos colunas, a largura é reduzida automaticamente.
- Altura na grelha: número de linhas de produto ocupadas pelo banner, de 1 a 3. Disponível nas listagens com grelha CSS (Creative Elements, a maioria dos temas recentes).
- Apresentação da imagem: Preencher a área do banner recorta a imagem ao tamanho da célula, Manter as proporções da imagem mostra-a por inteiro.
- Classe CSS: classes adicionais aplicadas à célula do banner. Deixe vazio para reutilizar as classes das células de produto do seu tema. Com largura e altura 1, uma classe de tamanho do seu tema (por exemplo uma que define
grid-area) continua a aplicar-se. - CSS personalizado: declarações aplicadas apenas a este banner, por exemplo
border-radius: 12px; padding: 10px;.
Agendamento e estado
- Data de início e Data de fim: janela de exibição, no formato
AAAA-MM-DD HH:MM:SS. Um campo vazio significa sem limite desse lado. - Ativo: mostra ou suspende o banner sem o eliminar.
- Associação a lojas: em multiloja, marque as lojas em causa.
Imagens por idioma
Os campos Imagem do banner, Imagem móvel, Texto alternativo e Ligação para este idioma existem para cada idioma ativo. O seletor de idioma situado logo acima destes campos mostra os do idioma selecionado. Quando já existe uma imagem, aparece uma pré-visualização acompanhada de um interruptor Eliminar a imagem que afeta apenas esse idioma.
Formatos aceites: JPG, PNG, GIF, WebP e SVG, até 4 MB. Uma largura de 1200 px serve para a maioria das grelhas.

Como a posição é calculada
A posição exprime-se em número de produtos e aplica-se a cada página da listagem. Um banner definido em 4 aparece a seguir ao quarto produto da página atual, esteja o visitante na página 1 ou na página 3.
Vários banners podem visar a mesma categoria, cada um na sua posição. Quando dois banners partilham a mesma posição, são inseridos um a seguir ao outro, pela ordem de gravação. Se a posição ultrapassar o número de produtos apresentados na página, o banner é simplesmente ignorado nessa página, sem deslocar os restantes.
Por predefinição, o banner ocupa o lugar de uma célula de produto. Os campos Largura na grelha e Altura na grelha aumentam-no, como explicado abaixo.

Tamanho do banner na grelha
Cada banner ocupa um bloco de células de produto: 1 × 1 por predefinição, até 4 colunas por 3 linhas, ou a linha inteira. Os produtos que se seguem ao banner preenchem as células livres, pelo que a grelha não fica com vazios.
- Listagens com grelha CSS (Creative Elements, a maioria dos temas recentes): aplicam-se a largura e a altura. Um banner 2 × 2 colocado a seguir ao 4.º produto de uma grelha de quatro colunas ocupa as duas primeiras colunas das linhas 2 e 3, e os produtos 5 a 8 ficam ao lado.
- Linhas Bootstrap (tema Classic): aplica-se a largura, como fração da linha. A altura segue a da imagem.
- Ecrãs pequenos: a largura fica limitada ao número de colunas apresentadas. Um banner de quatro colunas numa grelha móvel de duas colunas passa a linha inteira.
No modo de preenchimento, a imagem cobre toda a área, assume a altura dos produtos ao lado e é recortada a partir do centro. Um banner em linha inteira mantém sempre as suas proporções, porque não há produto ao lado que lhe dê altura: use uma imagem horizontal.
Para um banner 2 × 2 em modo de preenchimento, prepare uma imagem um pouco mais alta do que larga e mantenha a mensagem principal ao centro, porque as margens podem ser recortadas.


Agendar uma campanha
Indique uma data de início e uma data de fim para que um banner apareça e desapareça sozinho. É a ferramenta certa para preparar saldos, Black Friday ou uma campanha de fim de ano com semanas de antecedência.
- Apenas data de início: o banner aparece nessa data e fica visível a seguir.
- Apenas data de fim: o banner é exibido de imediato e termina nessa data.
- Ambas as datas: o banner só é visível dentro dessa janela.
- Sem datas: o banner é permanente.
As datas são introduzidas e comparadas na hora da loja, a do fuso horário definido em Internacional > Localização, e não na hora do visitante. Uma data de fim introduzida sem hora termina às 23:59:59.

Cobrir uma árvore completa
A opção Aplicar às subcategorias evita recriar o mesmo banner em cada secção. Definido numa categoria pai, o banner aparece nessa categoria e em todas as suas descendentes.
A resolução assenta na árvore aninhada nativa do PrestaShop (colunas nleft e nright), pelo que não custa uma consulta adicional por página. Se mover categorias na árvore, o PrestaShop recalcula esses valores e o âmbito acompanha automaticamente.
Imagens e idiomas
Cada banner aceita um visual e um texto alternativo por idioma, o que permite adaptar uma mensagem ou um preço ao mercado. Se um idioma não recebeu o seu próprio visual, o módulo mostra o do idioma predefinido da loja em vez de esconder o banner. O texto alternativo próprio do idioma é mantido, se estiver preenchido.
Uma imagem móvel opcional pode complementar cada visual: é servida aos ecrãs com 767 px de largura ou menos, com as suas próprias dimensões. Prepare-a em formato vertical para um banner em linha inteira.
As dimensões da imagem são lidas no carregamento e escritas nos atributos width e height do HTML, o que evita o deslocamento do layout durante o carregamento. O banner visível logo à abertura da página é carregado com prioridade (fetchpriority="high"), os restantes em diferido (loading="lazy"). Os ficheiros são renomeados com um sufixo aleatório e guardados em /img/datafireflycategorybanner/.
O texto alternativo é lido pelos motores de busca e pelos leitores de ecrã. Descreva o conteúdo do visual em vez de repetir o nome da categoria.

Multiloja
Quando a funcionalidade multiloja está ativa, o formulário mostra um bloco Associação a lojas. Um banner só aparece nas lojas marcadas, e a lista do back office mostra apenas os banners visíveis no contexto de loja atual.
Se não marcar nenhuma loja, o módulo associa o banner ao contexto atual, para nunca criar um banner órfão.
Filtros por facetas, ordenação e paginação
No PrestaShop 8 e 9, os filtros por facetas, a ordenação e a paginação recarregam a lista de produtos por AJAX sem recarregar a página. O módulo vigia a listagem: assim que surgem novas células de produto, após um filtro, uma mudança de página, um botão «carregar mais» ou o scroll infinito, volta a colocar os banners nas posições certas. Também escuta o evento updateProductList do PrestaShop.
A grelha de produtos é identificada a partir dos próprios produtos (marcadores data-id-product e product-miniature), e não das classes de um tema concreto. Isto cobre o tema Classic, as listagens Creative Elements e a maioria dos temas à medida.
O CSS e o JavaScript são carregados apenas nas páginas de categoria, e só quando a categoria atual tem pelo menos um banner ativo e apresentável.
Definições: seletor da grelha de produtos
Por baixo da lista de banners, o painel Definições contém um único campo, Seletor da grelha de produtos. Deixe-o vazio: a grelha é detetada automaticamente.
Apenas se os banners nunca aparecerem num tema com uma estrutura invulgar, introduza o seletor CSS do elemento que contém diretamente as células de produto, por exemplo #js-product-list .products ou .ce-products. Quando não encontra a grelha, o módulo escreve um aviso [DataFirefly Category Banner] na consola do navegador.
Novidades da versão 1.3.0
A versão 1.3.0 corrige vários defeitos detetados numa verificação completa no PrestaShop 1.7.8, 8.2.1 e 9.1.5, e acrescenta algumas definições.
- Imagem móvel: cada idioma aceita uma segunda imagem, apresentada nos ecrãs com 767 px de largura ou menos. É útil para um banner em linha inteira, pouco legível em formato horizontal num telemóvel.
- Ligação por idioma: uma ligação opcional por idioma substitui a ligação comum, para apontar para uma página cujo endereço está traduzido, por exemplo
/en/content/1-delivery. - Apenas na primeira página: o banner deixa de se repetir nas páginas 2, 3, etc. da listagem. Volta a aparecer assim que o visitante regressa à página 1 ou aplica um filtro.
- Calendário das datas: o calendário do formulário passa a preencher o formato correto. Uma data de fim introduzida sem hora termina às 23:59:59.
- Hora da loja: as datas são comparadas com a hora da loja. Antes, o relógio do servidor MySQL, muitas vezes definido em UTC, desfasava o início e o fim em uma a duas horas.
- Core Web Vitals: os banners são inseridos logo a seguir à grelha de produtos (hook
displayFooterCategory), antes da primeira apresentação da página, o que elimina o deslocamento do layout (CLS). O banner visível à abertura da página é carregado com prioridade, os seguintes em diferido. - Segurança das imagens: os SVG que contêm um script, um gestor de eventos ou conteúdo externo são recusados, e a pasta
/img/datafireflycategorybanner/recebe o seu próprio.htaccess(apenas imagens, SVG isolados). Uma imagem recusada já não cria um banner vazio. - WebP no PrestaShop 1.7: as imagens WebP são aceites e servidas corretamente.
- Lista do back office: coluna Imagens com os idiomas que têm visual, e indicação dos banners terminados ou agendados.
Para atualizar, instale o arquivo 1.3.0 por cima da versão atual a partir do gestor de módulos. Os seus banners e as suas imagens são mantidos. Limpe depois a cache do PrestaShop e a de qualquer módulo de desempenho.
Atualizar para a versão 1.2.0
Instale o arquivo 1.2.0 por cima da versão anterior a partir do gestor de módulos. O script de atualização acrescenta as colunas de tamanho e de apresentação da imagem, bem como a definição do seletor de grelha. Os banners existentes mantêm o aspeto atual: 1 × 1, proporções da imagem mantidas. Edite um banner para lhe dar outro tamanho ou passá-lo para o modo de preenchimento.
O script do front office muda nesta versão. Após a atualização, limpe a cache do PrestaShop e a de qualquer módulo de desempenho (CCC, cache de páginas, minificação); caso contrário, o script anterior continua a ser servido.
Atualizar a partir da versão 1.0.0
Basta instalar o novo ficheiro por cima do antigo a partir do gestor de módulos. O script de atualização trata de:
- adicionar as colunas de âmbito, agendamento e dimensões da imagem;
- criar a tabela de associação a lojas e transpor para ela a loja original de cada banner;
- mover as imagens existentes de
views/img/banners/para/img/datafireflycategorybanner/e ler as suas dimensões; - remover um hook que deixou de ser necessário.
Os seus banners, as suas posições e os seus visuais são preservados.
FAQ e resolução de problemas
O banner não aparece na página de categoria
Verifique por esta ordem: o banner está ativo; a data de hoje está dentro da janela de agendamento; a categoria visada é a que está a ser consultada, ou o âmbito às subcategorias está ligado; o idioma apresentado tem imagem, ou o idioma predefinido tem uma; em multiloja, a loja atual está marcada. Por fim, limpe a cache do PrestaShop.
Numa listagem construída com o Creative Elements ou outro construtor de páginas, confirme que o módulo está na versão 1.2.0 ou superior: as versões anteriores só reconheciam a grelha do tema Classic. Abra depois a consola do navegador: um aviso [DataFirefly Category Banner] indica que a grelha não foi encontrada, consulte a secção Definições.
O banner aparece no sítio errado
A posição conta os produtos da página atual. Se a sua listagem mostra 12 produtos por página, um banner na posição 20 não aparecerá em nenhuma. Reduza o valor ou aumente o número de produtos por página.
O banner estraga o layout da grelha
Defina o tamanho com os campos Largura na grelha e Altura na grelha em vez de classes de grelha, e esvazie o campo Classe CSS, exceto se o seu tema fornecer uma classe de tamanho. Evite misturar classes de sistemas de grelha diferentes.
O banner desaparece depois de filtrar
Desde a versão 1.2.0, o módulo volta a inserir os banners assim que surgem novas células de produto na listagem, seja qual for o módulo de filtros. Se o banner continuar a desaparecer, abra a consola do navegador: um aviso [DataFirefly Category Banner] indica que a grelha não foi encontrada após a atualização. Indique então o seletor da grelha no painel Definições e contacte o suporte se o problema persistir.
A imagem não é carregada
O módulo aceita ficheiros JPG, PNG, GIF, WebP e SVG até 4 MB. Verifique também se /img/datafireflycategorybanner/ tem permissões de escrita e se as diretivas PHP upload_max_filesize e post_max_size são superiores ao tamanho do ficheiro.
A ligação do banner é recusada
Só são aceites URL que comecem por http://, https:// ou por uma barra. É uma proteção contra a injeção de endereços javascript: ou data:.
O que acontece ao desinstalar?
O módulo elimina as suas tabelas e a pasta /img/datafireflycategorybanner/ com os visuais que contém. Guarde uma cópia das suas imagens se pretender reinstalar mais tarde.