# Slider e banners da página inicial: documentação

> Apresentação O DF Home Banners apresenta uma grelha de destaque completa na página inicial da sua loja, composta por cinco zonas: um slider principal (com vários slides), um banner lateral…

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

## Apresentação

O DF Home Banners apresenta uma grelha de destaque completa na página inicial da sua loja, composta por cinco zonas: um slider principal (com vários slides), um banner lateral superior, um banner lateral inferior, um banner largo à esquerda e um banner largo à direita. Em computador, o slider ocupa cerca de 75 % da largura, com os dois banners laterais empilhados à sua direita, e os dois banners largos aparecem por baixo. Em telemóvel, a grelha empilha-se numa só coluna.

O módulo foi pensado para a velocidade: conversão para WebP no carregamento, pré-carregamento da imagem de LCP, carregamento diferido, atributos de dimensões contra o CLS, 3 KB de JavaScript nativo e cache Smarty. Sem dependências: nem Composer, nem jQuery.

## Instalação

1. No seu back-office PrestaShop, vá a **Módulos > Gestor de módulos > Carregar um módulo**.
2. Selecione o ficheiro `dfhomebanners.zip` descarregado a partir da sua conta DataFirefly.
3. O módulo instala-se e cria um separador **DF Home Banners** no menu Melhorar, bem como as suas tabelas e a pasta de carregamento das imagens.

Pré-requisitos: PrestaShop 8.0 ou superior e PHP com a extensão GD (presente na quase totalidade dos alojamentos). A função `imagewebp` do GD é usada para a conversão WebP; se estiver ausente, o módulo funciona à mesma com os ficheiros JPEG ou PNG de origem.

## Configuração do módulo

A página de configuração (Módulos > DF Home Banners > Configurar) contém:

- **Tempo de reprodução automática do slider** em milissegundos, com um mínimo de 2000. O slider faz pausa ao passar o rato, quando o separador do navegador fica oculto, e respeita a preferência de sistema `prefers-reduced-motion`.
- **Cinco interruptores de apresentação em telemóvel**, um por zona. Uma zona desativada fica oculta abaixo dos 768 px e as suas imagens nunca são descarregadas pelo visitante em telemóvel: passam a carregamento diferido, e uma imagem diferida e oculta não é pedida pelo navegador. Se o slider for cortado em telemóvel, o seu pré-carregamento de LCP fica automaticamente restrito ao computador.

Cada gravação da configuração limpa a cache do módulo, pelo que o efeito é imediato no front-office.

## Gerir os banners

A gestão faz-se no separador **DF Home Banners** do menu Melhorar. A lista mostra todos os banners com a respetiva zona, título, datas, posição e estado, com filtros e ativação com um clique.

### Criar um banner

Clique em Adicionar e preencha:

- **Zona**: o slider principal aceita vários banners (um por slide); cada uma das quatro zonas fixas apresenta o primeiro banner ativo, segundo a ordem das posições.
- **Imagem**: um campo por idioma. Formatos aceites: JPEG, PNG e WebP. A imagem é redimensionada para a largura máxima da sua zona (1400 px no slider, 560 px nas laterais, 900 px nas largas) e depois convertida para WebP com qualidade 82, conservando um ficheiro de recurso em JPEG ou PNG. As dimensões finais são guardadas e injetadas nos atributos `width` e `height` para eliminar o CLS.
- **Imagem para telemóvel**: opcional, um campo por idioma. Enquadre-a para o formato vertical; é redimensionada para 768 px, convertida para WebP e servida abaixo dos 768 px de viewport, através da etiqueta `picture`. Funciona nas cinco zonas, slider e quatro banners: útil sobretudo quando a imagem de desktop contém texto que fica ilegível no telemóvel (um banner largo de 900x260 px, por exemplo).
- **Utilizar esta imagem para todos os idiomas**: caixa de seleção apresentada acima dos campos Imagem, e outra acima dos campos Imagem móvel, assim que a loja tem mais de um idioma. Quando marcada, só fica visível o campo do idioma predefinido: a imagem carregada é processada uma única vez e servida em todos os idiomas, sem ficheiros duplicados no disco. Desmarque-a para fornecer uma imagem diferente por idioma (por exemplo, com texto traduzido na imagem). Vem marcada por predefinição num banner novo, e num banner existente quando todos os idiomas já utilizam o mesmo ficheiro.
- **Título / texto alternativo**: usado como atributo `alt` da imagem, por idioma.
- **Ligação**: escolha o tipo na lista: produto (pesquisa por nome ou referência), categoria, fabricante e página CMS (pesquisa por nome), ou URL personalizado. Os URL de produto, categoria, fabricante e CMS são gerados automaticamente pelo PrestaShop no idioma e na loja do visitante, com a reescrita de URL incluída. O URL personalizado introduz-se por idioma e pode ficar vazio, para um banner sem ligação.
- **Posição**: ordem de apresentação na zona (crescente).

### Envio das imagens ao gravar

Quando clica em Guardar, as imagens selecionadas não seguem todas num único pedido. Cada imagem é primeiro reduzida no navegador à largura máxima da sua zona, depois enviada sozinha no seu próprio pedido AJAX e processada pelo servidor (redimensionamento e WebP), uma após a outra. Uma mensagem mostra o progresso imagem a imagem. Quando todas as imagens estão processadas, o formulário é gravado sem qualquer ficheiro. O servidor processa assim sempre uma única imagem de cada vez, mesmo para um banner em 8 idiomas com imagens móveis.

Se uma imagem falhar, a gravação para e a mensagem indica o campo e o motivo (ficheiro demasiado pesado para o limite de carregamento, imagem demasiado grande para a memória PHP, formato não suportado). Corrija esse campo e grave novamente: as imagens já enviadas não voltam a ser carregadas.

Se o JavaScript não estiver disponível, o formulário volta ao envio clássico de todas as imagens de uma vez. Quando substitui uma imagem, o ficheiro antigo só é eliminado depois da gravação, e apenas se nenhum outro idioma ainda o utilizar.

Numa loja portuguesa, preencha mesmo a imagem e o texto alternativo no idioma português: uma zona sem imagem nesse idioma simplesmente não aparece. Repare que o texto embutido na própria imagem não é traduzível pelo PrestaShop; se o seu banner tiver texto gráfico, prepare uma versão portuguesa da imagem em vez de reutilizar a francesa.

Se o banner anunciar uma redução de preço, o Decreto-Lei n.º 66/2021 obriga a indicar o preço mais baixo praticado nos 30 dias anteriores sempre que se anuncia essa redução. Um visual do tipo «-30 % em toda a coleção» deve, por isso, remeter para uma página onde o preço de referência é apresentado corretamente, e as datas de campanha do banner devem coincidir com as da promoção real na loja.

### Agendar com as datas de início e de fim

Os dois campos de datas são opcionais. Formato aceite: `AAAA-MM-DD` ou `AAAA-MM-DD HH:MM:SS`. Uma data de início isolada publica o banner a partir desse momento; uma data de fim isolada retira-o nesse momento; as duas em conjunto delimitam a campanha. Com os campos vazios, o banner é apresentado permanentemente enquanto estiver ativo.

Como o resultado é colocado em cache, o módulo integra um marcador horário na sua chave de cache: um banner agendado aparece ou desaparece na hora seguinte ao seu prazo, sem qualquer intervenção. Qualquer gravação no back-office força a regeneração imediata.

As datas seguem o fuso horário definido em Parâmetros da loja: verifique que está em Europe/Lisbon antes de agendar uma campanha que arranca à meia-noite, sobretudo se o servidor estiver configurado em UTC.

### Multiloja e multi-idioma

Em contexto multiloja, cada banner associa-se às lojas à sua escolha, através das caixas de associação do formulário. A imagem, a imagem para telemóvel, a ligação e o texto alternativo definem-se por idioma; um idioma sem imagem simplesmente não recebe nada (o banner não aparece nesse idioma enquanto não houver imagem). A cache é isolada por idioma e por loja.

## Desempenho: o que o módulo faz

- **LCP**: o primeiro slide ativo do slider é anunciado no `head` por uma etiqueta `link rel="preload"` com `fetchpriority="high"`. Com uma imagem para telemóvel, são emitidas duas etiquetas de preload com atributos `media`: cada dispositivo só pré-carrega a sua variante.
- **CLS**: os atributos `width` e `height` são colocados em cada imagem, reservando o espaço antes do carregamento.
- **Peso**: WebP à saída, carregamento diferido em todas as imagens fora do LCP e `decoding="async"` em todo o lado.
- **JavaScript**: cerca de 3 KB de código nativo, carregado em `defer` no fundo da página. Setas, pontos, deslize tátil e reprodução automática.
- **Servidor**: resultado em cache Smarty por idioma e por loja, com uma única consulta SQL agrupada na regeneração. O CSS e o JS são registados apenas no controlador da página inicial.

Para um LCP ótimo, procure um visual de slider abaixo de 150 KB depois da conversão (o módulo mostra o peso obtido). Um JPEG de origem com boa qualidade é suficiente, a conversão para WebP faz o resto.

## Resolução de problemas

### Os banners não aparecem no front-office

- Confirme que o banner está **ativo**, que existe mesmo **uma imagem carregada para o idioma consultado** e que a data atual está dentro do intervalo definido.
- Verifique a **associação à loja** do banner, em multiloja.
- O tema tem de expor o hook `displayHome`, presente em todos os temas baseados no Classic. Se um módulo de slider nativo já ocupar a zona (ps_imageslider), desative-o para evitar a duplicação visual.

### A gravação falha com muitas imagens

Desde a versão 1.4.0, as imagens são carregadas uma a uma e reduzidas no navegador antes do envio, pelo que isto já não deverá acontecer. Se ainda assim surgir uma mensagem de erro, ela indica o campo e a causa. Para um ficheiro demasiado pesado, aumente `upload_max_filesize` e `post_max_size` na configuração PHP ou reduza a imagem. Para uma imagem demasiado grande para a memória, o módulo tenta aumentar `memory_limit` automaticamente; se o seu alojamento não o permitir, redimensione a imagem para menos de 3000 px de largura antes do carregamento. Verifique também que o módulo está na versão 1.4.0 ou superior.

### A imagem móvel de um banner não aparece no telemóvel

Antes da versão 1.4.1, apenas os slides do slider utilizavam a imagem móvel, e os quatro banners fixos mostravam sempre a imagem de desktop. Atualize o módulo para a 1.4.1: a atualização limpa a cache do módulo. Limpe também a eventual cache de página completa (LiteSpeed, Varnish, CDN) e teste abaixo dos 768 px de largura. No separador Rede das ferramentas de programador, deve ser carregado o ficheiro cujo nome contém `image_mobile`.

### A conversão para WebP não acontece

O seu PHP provavelmente não dispõe de `imagewebp`. Nesse caso, o módulo serve os ficheiros JPEG ou PNG de origem, redimensionados. Peça ao seu alojamento que ative o suporte de WebP no GD.

### Uma alteração não aparece de imediato

Grave qualquer banner ou a configuração: a cache do módulo é limpa a cada escrita. Limpe também a cache Smarty global do PrestaShop se a sua loja estiver por trás de uma cache de página completa (Varnish, LiteSpeed, CDN).

## Desinstalação

A desinstalação elimina o separador de administração, as tabelas do módulo e os seus valores de configuração. Os ficheiros de imagem carregados permanecem na pasta do módulo enquanto esta não for eliminada do disco.