# Product Carousel Pro: carrosséis de produtos ilimitados (dfproductcarousel) > O Product Carousel Pro cria carrosséis de produtos ilimitados em qualquer ponto da sua loja PrestaShop: mais vendidos, novidades, promoções, produtos de uma categoria ou seleção manual ordenada à mão,… - Página: - Idioma: pt - Atualizado em: 2026-09-09 - Outros idiomas: [fr](https://www.datafirefly.com/documentation/dfproductcarousel/index.md), [en](https://www.datafirefly.com/en/documentation/dfproductcarousel/index.md), [es](https://www.datafirefly.com/es/documentation/dfproductcarousel/index.md), [de](https://www.datafirefly.com/de/documentation/dfproductcarousel/index.md), [it](https://www.datafirefly.com/it/documentation/dfproductcarousel/index.md), [pl](https://www.datafirefly.com/pl/documentation/dfproductcarousel/index.md), [nl](https://www.datafirefly.com/nl/documentation/dfproductcarousel/index.md) - Índice: O Product Carousel Pro cria carrosséis de produtos ilimitados em qualquer ponto da sua loja PrestaShop: mais vendidos, novidades, promoções, produtos de uma categoria ou seleção manual ordenada à mão, apresentados em seis hooks padrão ou nos seus próprios hooks personalizados criados na altura. A particularidade do módulo: os cartões de produto são gerados pelo template de miniatura do seu tema ativo, através do ProductAssembler e do ProductPresenter. Preços, etiquetas, pré-visualização rápida e adição ao carrinho funcionam exatamente como nas suas páginas de categoria. Esta documentação cobre a versão **1.0.0** do módulo, compatível com PrestaShop **8.0.0 a 9.x**. Sem overrides de classe, sem dependências Composer e com JavaScript nativo sem jQuery. ## Instalação 1. No seu back-office PrestaShop, abra **Módulos > Gestor de módulos**. 2. Clique em **Carregar um módulo** e coloque o ficheiro `dfproductcarousel.zip`. 3. Aparece um separador **Product Carousel Pro** no menu **Módulos**: é aí que tudo acontece (o botão Configurar do módulo também remete para lá). O módulo cria três tabelas (carrosséis, títulos multi-idioma e associação a lojas) e regista-se em seis hooks de apresentação, além de `actionFrontControllerSetMedia` para os seus recursos. Os hooks personalizados que criar em seguida registam-se automaticamente ao gravar o carrossel em causa. ## Criar um carrossel Na lista, clique em **Adicionar um carrossel**. O formulário está organizado em cinco blocos: Conteúdo, Colocação, Disposição, Estilo e Comportamento. - **Nome interno**: visível apenas no back-office, para se orientar na lista. - **Título e subtítulo**: multi-idioma, apresentados por cima do carrossel. Deixe o título vazio para não mostrar cabeçalho nenhum. A lista de carrosséis permite depois a ativação com um clique, a duplicação (a cópia é criada desativada) e as ações em massa de eliminação. Os títulos e subtítulos são campos multi-idioma que preenche você mesmo, mas as restantes cadeias do módulo são entregues em francês, inglês, espanhol, alemão e italiano, sem português. Traduza-as em **Internacional > Traduções** se quiser um back-office totalmente em português. ## Fontes de produtos Cada carrossel escolhe a sua fonte entre seis: - **Mais vendidos**: os produtos mais vendidos da loja. - **Novidades**: os produtos marcados como novos (o prazo é o da sua definição do PrestaShop «Número de dias durante os quais o produto é considerado novo»). - **Promoções**: os produtos com uma redução em curso. - **Produtos de uma categoria**: escolha a categoria na árvore de seleção; os produtos seguem a ordem da categoria. - **Categoria inicial**: os produtos da categoria raiz da loja, o equivalente aos «produtos em destaque» nativos. - **Seleção manual**: escolhe os produtos um a um. O campo **Número máximo de produtos** limita o número de produtos carregados, seja qual for a fonte. ### A seleção manual Escreva pelo menos dois caracteres no campo de pesquisa: a sugestão automática encontra os seus produtos por nome ou por referência. Cada produto em que clicar é acrescentado à lista abaixo, com a sua pega de deslocação: reordene por arrastar e largar, e o front-office apresenta os produtos exatamente por essa ordem. Os produtos desativados ou invisíveis no catálogo são filtrados automaticamente na apresentação, sem partir o carrossel. ## Escolher a colocação ### Hooks padrão São propostos seis hooks na lista pendente: - `displayHome`: página inicial; - `displayContentWrapperTop` e `displayContentWrapperBottom`: acima e abaixo do conteúdo principal, na maioria das páginas; - `displayFooterBefore`: mesmo antes do rodapé; - `displayFooterProduct`: no fundo da ficha de produto, a localização clássica da venda cruzada; - `displayShoppingCartFooter`: por baixo do resumo do carrinho. Vários carrosséis podem partilhar o mesmo hook: empilham-se pela ordem do respetivo campo **Posição**. ### Hooks personalizados Selecione **Hook personalizado** na lista e escreva um nome no campo que aparece, por exemplo `MeuCarrossel`. Ao gravar, o módulo limpa o nome (apenas letras e números), prefixa-o como `displayMeuCarrossel` se for necessário, regista-o junto do PrestaShop e passa a escutá-lo. Coloque depois a chamada no template à sua escolha: ``` {hook h='displayMeuCarrossel'} ``` O hook criado passa a constar da lista pendente para os carrosséis seguintes. Pode criar tantos hooks quantos precisar. ### Sintaxe de widget Para mostrar um carrossel específico independentemente do seu hook, use a sintaxe de widget com o identificador visível na primeira coluna da lista: ``` {widget name='dfproductcarousel' carousel=3} ``` É prático numa página CMS ou num template à medida. O carrossel tem de estar ativo para ser apresentado. ## Disposição - **Produtos por fila**: três valores independentes, de 1 a 8, para computador (992 px e mais), tablet (768 a 991 px) e telemóvel (menos de 768 px). A configuração clássica é 4 / 3 / 1. - **Modo de deslocamento**: «Um produto de cada vez» avança um cartão por clique, «Fila completa» avança uma página inteira. - **Espaçamento**: a distância em píxeis entre os cartões (20 px por predefinição). - **Largura total**: o carrossel sai do seu contentor para ocupar toda a largura do ecrã, com muito bom efeito na página inicial com o skin Secção escura. As colunas responsivas são aplicadas por um bloco CSS próprio de cada carrossel, ainda antes do carregamento do JavaScript: não há qualquer desvio de disposição na primeira apresentação, incluindo em telemóvel. ## Estilo ### Os cinco skins - **Clássico**: os cartões de produto do tema estritamente intactos. É a escolha predefinida e a mais segura. - **Minimal**: elimina sombras e contornos, para um resultado plano. - **Cartão**: sombra projetada, cantos arredondados e ligeira elevação ao passar o rato. - **Contorno**: um filete fino à volta de cada cartão, que assume a cor de destaque ao passar o rato. - **Secção escura**: coloca todo o carrossel sobre um fundo escuro, com título e paginação adaptados. ### Definições complementares - **Alinhamento do título**: à esquerda, ao centro ou à direita, com o sublinhado de destaque a acompanhar. - **Cor de destaque**: usada nas setas ao passar o rato, na paginação ativa e no sublinhado do título. Deixe vazio para herdar a cor principal do seu tema. - **Setas**: apresentadas ou não, em três estilos (círculo, quadrado, minimal sem fundo). - **Paginação**: pontos ou barras, gerada automaticamente conforme o número de páginas. ## Comportamento - **Reprodução automática**: deslocamento automático com atraso configurável (5000 ms por predefinição, 1000 ms no mínimo). A reprodução é suspensa quando o separador do navegador fica oculto. - **Pausa ao passar o rato**: suspende a reprodução automática enquanto o cursor estiver sobre o carrossel. - **Ciclo infinito**: o carrossel recomeça do início sem solavancos, graças à clonagem transparente das extremidades. Sem esta opção, as setas desativam-se ao chegar ao fim. Seja qual for a definição, o carrossel controla-se com o dedo (deslize tátil e com o rato, com proteção contra cliques acidentais no fim do gesto) e com o teclado (setas esquerda e direita quando o carrossel tem o foco), e respeita o sentido de leitura RTL e a preferência de sistema `prefers-reduced-motion`. ## Apresentação nativa do tema: como funciona - Os produtos são montados e apresentados pelo `ProductAssembler` e pelo `ProductPresenter`, os mecanismos que o próprio PrestaShop usa nas suas listagens. - Cada cartão é depois gerado pelo template `catalog/_partials/miniatures/product.tpl` do seu tema ativo: preços, promoções, etiquetas, pré-visualização rápida e adição ao carrinho são os do tema, sem qualquer adaptação. - O módulo nunca escreve nos ficheiros do tema: carrega a sua própria folha de estilo para a mecânica do carrossel, depois do CSS do tema. - Um produto com erro é ignorado em silêncio, em vez de partir o carrossel todo. Vai mudar de tema? O carrossel adota os novos cartões de produto de imediato, sem qualquer alteração de configuração. ## Multiloja Cada carrossel fica associado às lojas do contexto no momento em que é gravado. Para criar um carrossel numa loja específica, coloque-se no contexto dela através do seletor multiloja antes de o criar. Um carrossel gravado no contexto «Todas as lojas» aparece em todo o lado. ## Resolução de problemas - **O carrossel não aparece**: confirme por esta ordem que o carrossel está ativo, que a sua fonte devolve pelo menos um produto (uma categoria vazia ou uma seleção manual de produtos desativados produzem um carrossel mudo) e que o hook escolhido existe mesmo na página consultada, e limpe a cache do PrestaShop (Parâmetros avançados > Desempenho). - **O hook personalizado não mostra nada**: o nome em `{hook h='...'}` tem de corresponder exatamente ao nome registado, prefixo `display` incluído, visível na coluna Hook da lista. Depois de acrescentar a chamada num template, limpe a cache do Smarty. - **As setas não aparecem**: são ocultadas automaticamente quando todos os produtos cabem numa única fila. Acrescente produtos ou reduza o número de colunas. - **O skin Cartão ou Contorno fica mal com o meu tema**: alguns temas já aplicam sombras e contornos às suas miniaturas. Volte ao skin Clássico, que não mexe em nada, ou ao Minimal, que neutraliza os efeitos do tema. - **Dois carrosséis pela ordem errada no mesmo hook**: ajuste o campo Posição de cada um, já que a apresentação segue a ordem crescente. - **A pesquisa de produtos não propõe nada**: a pesquisa começa aos dois caracteres e consulta os nomes e as referências do idioma em edição. ## Desinstalação A desinstalação elimina as três tabelas, o separador do back-office e os hooks registados. O seu tema e os seus templates ficam intactos; apenas as chamadas `{hook h='...'}` que acrescentou manualmente nos seus templates devem ser retiradas por si (um hook sem módulo à escuta simplesmente não mostra nada e não gera qualquer erro).