# Banner de Categoria: guia completo

> 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…

- Página: <https://www.datafirefly.com/pt/documentation/datafireflycategorybanner/>
- Idioma: pt
- Atualizado em: 2026-10-29
- Outros idiomas: [fr](https://www.datafirefly.com/documentation/datafireflycategorybanner/index.md), [en](https://www.datafirefly.com/en/documentation/datafireflycategorybanner/index.md), [es](https://www.datafirefly.com/es/documentation/datafireflycategorybanner/index.md), [de](https://www.datafirefly.com/de/documentation/datafireflycategorybanner/index.md), [it](https://www.datafirefly.com/it/documentation/datafireflycategorybanner/index.md), [pl](https://www.datafirefly.com/pl/documentation/datafireflycategorybanner/index.md), [nl](https://www.datafirefly.com/nl/documentation/datafireflycategorybanner/index.md)
- Índice: <https://www.datafirefly.com/pt/documentation/llms.txt>

## 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.

![Página de categoria PrestaShop com um banner promocional na grelha de produtos e um banner de saldos de largura total](https://www.datafirefly.com/wp-content/uploads/2026/10/pagina-categoria-banners-grelha-produtos-computador-prestashop-dfcategorybanner-pt.webp)

Um banner de uma célula a seguir ao primeiro produto e um banner de saldos em linha inteira na categoria Arte (tema Hummingbird, PrestaShop 9).

## Instalação

1. Transfira o ficheiro `datafireflycategorybanner.zip` a partir da sua conta de cliente.
2. No back office, abra **Módulos > Gestor de módulos**.
3. Clique em **Carregar um módulo** e largue o ficheiro.
4. 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.

![Lista dos banners de categoria no back office: imagem, categoria, posição, idiomas, tamanho e agendamento](https://www.datafirefly.com/wp-content/uploads/2026/10/lista-banners-categoria-back-office-prestashop-dfcategorybanner-pt.webp)

A lista de banners: categoria, posição, idiomas que têm imagem, tamanho e agendamento.

## 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.

![Formulário do banner: categoria, subcategorias, posição após um produto, primeira página, largura, altura e apresentação da imagem](https://www.datafirefly.com/wp-content/uploads/2026/10/definicoes-posicao-tamanho-banner-prestashop-dfcategorybanner-pt.webp)

Segmentação, posição, tamanho na grelha e apresentação da imagem.

### 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.

![Imagem do banner, imagem móvel, texto alternativo e ligação para cada idioma da loja](https://www.datafirefly.com/wp-content/uploads/2026/10/imagem-banner-movel-alt-ligacao-por-idioma-prestashop-dfcategorybanner-pt.webp)

Para cada idioma: imagem, imagem móvel, texto alternativo e ligação opcional.

## 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.

![Vista móvel de uma categoria PrestaShop: o banner ocupa o lugar de um produto na grelha de duas colunas](https://www.datafirefly.com/wp-content/uploads/2026/10/banner-categoria-telemovel-grelha-produtos-prestashop-dfcategorybanner-pt.webp)

No telemóvel, o banner a seguir ao primeiro produto ocupa o lugar de um produto na grelha de duas colunas.

## 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.

![Banner de envio gratuito em duas colunas e banner de ideias de presente entre os produtos de uma categoria PrestaShop](https://www.datafirefly.com/wp-content/uploads/2026/10/banner-duas-colunas-entre-produtos-computador-prestashop-dfcategorybanner-pt.webp)

Um banner 2 × 1 a seguir ao 4.º produto e um banner 1 × 1 a seguir ao 6.º, em modo de preenchimento.

![Banner de envio gratuito em duas colunas que ocupa toda a largura da grelha de produtos móvel](https://www.datafirefly.com/wp-content/uploads/2026/10/banner-duas-colunas-telemovel-largura-total-prestashop-dfcategorybanner-pt.webp)

Numa grelha móvel de duas colunas, o banner 2 × 1 ocupa toda a largura.

## 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.

![Agendamento do banner: calendário das datas de início e fim na hora da loja](https://www.datafirefly.com/wp-content/uploads/2026/10/agendamento-banner-data-inicio-fim-prestashop-dfcategorybanner-pt.webp)

Datas de início e de fim com o calendário do PrestaShop, na hora da loja.

## 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.

![Banner de saldos de largura total com a sua imagem móvel dedicada num smartphone](https://www.datafirefly.com/wp-content/uploads/2026/10/banner-largura-total-imagem-movel-dedicada-prestashop-dfcategorybanner-pt.webp)

O banner em linha inteira mostra a sua imagem móvel, em formato vertical, num telemóvel.

## 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.
