# Substituir o Botão Adicionar ao Carrinho nas Listagens PrestaShop: instalação e configuração

> Apresentação O módulo substitui o botão Adicionar ao carrinho das miniaturas de produto (páginas de categoria, pesquisa, página inicial, carrosséis, produtos relacionados) por um botão que leva à página do…

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

## Apresentação

O módulo substitui o botão **Adicionar ao carrinho** das miniaturas de produto (páginas de categoria, pesquisa, página inicial, carrosséis, produtos relacionados) por um botão que leva à página do produto. Aí o cliente escolhe o peso, o tamanho ou o formato antes de adicionar ao carrinho. Define regras: que produtos são abrangidos, que texto mostra o botão e se o preço mais baixo das combinações é mostrado com «A partir de».

## Instalação

1. Em **Módulos > Gestor de módulos**, clique em **Carregar um módulo** e envie o ficheiro `dflistingbutton-1.0.0.zip`.
2. O módulo cria as tabelas `ps_dflb_rule`, `ps_dflb_rule_lang`, `ps_dflb_rule_shop`, `ps_dflb_rule_category` e `ps_dflb_rule_product`, e adiciona o menu **Catálogo > Botões das listagens**.
3. É criada uma regra de exemplo desativada, «Exemplo: todos os produtos com combinações». Pode ativá-la tal como está ou eliminá-la.
4. Depois de criar ou ativar uma regra, abra uma página de categoria da loja. Se o botão não aparecer, limpe a cache em **Parâmetros avançados > Desempenho**.

## Criar uma regra

Em **Catálogo > Botões das listagens**, clique em **Adicionar uma regra**. O formulário tem três blocos.

### Regra e segmentação

- **Nome da regra**: nome interno, não visível para os clientes.
- **Ativa**: uma regra desativada é ignorada.
- **Prioridade**: quando várias regras correspondem a um produto, vence a que tem o número mais baixo. Valor predefinido: 10.
- **Aplica-se a**: _Todos os produtos_, _Categorias_ ou _Produtos específicos_.
- **Categorias**: árvore de caixas de seleção com um campo de filtro. Para este tipo de regra é obrigatória pelo menos uma categoria.
- **Incluir subcategorias**: os produtos de todas as subcategorias das categorias selecionadas também são abrangidos.
- **Correspondência de categoria**: _O produto está numa das categorias_ (contam todas as categorias associadas ao produto) ou _Apenas a categoria predefinida do produto_.
- **Produtos**: para o tipo _Produtos específicos_, pesquisa por nome, referência ou ID.
- **Condição**: _Sem condição_, _Produtos com combinações_ ou _Produtos que usam um grupo de atributos_. Com _Produtos com combinações_, os produtos simples da mesma categoria mantêm o botão Adicionar ao carrinho.
- **Grupo de atributos**: para a última condição, por exemplo Peso ou Tamanho. Só são abrangidos os produtos com uma combinação que usa esse grupo.
- **Produtos excluídos**: estes produtos nunca recebem o botão desta regra, seja qual for a segmentação.
- **Associação de loja**: em multiloja, escolha as lojas onde a regra se aplica.

### Botão

- **Texto do botão**: um texto por idioma, por exemplo «Ver todos os pesos disponíveis». Um idioma vazio usa o primeiro texto introduzido.
- **Estilo**: _Botão principal do tema_ (classes `btn btn-primary`), _Botão com contorno do tema_ (`btn btn-outline-primary`) ou _Cores personalizadas_, com cor de fundo, cor do texto e pré-visualização.
- **Ícone**: seta, opções, balança, olho ou nenhum.
- **Largura total**: o botão ocupa toda a largura da miniatura.
- **Classes CSS adicionais**: adicionadas ao botão, úteis para reutilizar uma classe do seu tema.
- **Ocultar o seletor de quantidade**: oculta o campo de quantidade que alguns temas mostram nas listagens.

### Preço nas listagens

Este bloco só diz respeito aos produtos com pelo menos duas combinações.

- **Mostrar o preço mais baixo das combinações**: o PrestaShop calcula o preço de cada combinação (impostos, grupo do cliente, preços específicos e descontos incluídos). Se o mais baixo for diferente do preço mostrado pelo tema, substitui-o, e o preço anterior riscado e a etiqueta de desconto da miniatura ficam ocultos.
- **Adicionar o prefixo «A partir de»**: adicionado antes do preço apenas se os preços das combinações forem diferentes e o preço mostrado for o mais baixo. Se desativar a opção anterior e a combinação predefinida não for a mais barata, o prefixo não é mostrado, para não anunciar um preço errado.
- **Texto do prefixo**: um texto por idioma («A partir de», «From», «Desde», etc.).

## Exemplo: queijos e enchidos vendidos ao peso

1. Nome: _Queijos ao peso_. Aplica-se a: _Categorias_. Selecione _Queijos e enchidos_ e mantenha _Incluir subcategorias_.
2. Condição: _Produtos que usam um grupo de atributos_, grupo _Peso_.
3. Texto do botão: «Ver todos os pesos disponíveis» em português, «Ver todas las opciones de peso» em espanhol.
4. Mantenha ativas as opções _Mostrar o preço mais baixo_ e _A partir de_, e guarde.

Na categoria, cada queijo vendido em 250 g, 500 g e 1 kg mostra «A partir de» seguido do preço dos 250 g e o botão para a sua página. Um produto vendido à unidade, sem combinação de peso, mantém o botão Adicionar ao carrinho.

## Definições gerais

A página de configuração do módulo (botão **Definições** por cima da lista de regras) contém:

- **Ativar o módulo**: desativa todas as regras sem as eliminar.
- **Deteção do tema**: _Automático_ (recomendado), _Usar sempre a consulta AJAX_ ou _Apenas hooks_. Veja a secção seguinte.
- **Desativar também a ligação nativa de adicionar ao carrinho**: esvazia no servidor o URL de adicionar ao carrinho dos produtos abrangidos, através do hook `actionPresentProductListing`. Alguns temas mostram então a sua própria ligação «Ver produto»: se ficar com dois botões, deixe esta opção desativada.
- **Ocultar o botão Vista rápida**: apenas nos produtos abrangidos.
- **Ignorar combinações esgotadas para o preço mais baixo**: aplica-se quando a gestão de stock está ativa e o produto não aceita encomendas sem stock. Se todas as combinações estiverem esgotadas, todas são consideradas.

## Compatibilidade com o seu tema

### Como o módulo identifica os produtos

Durante a apresentação de uma miniatura, o módulo é executado nos hooks `displayProductPriceBlock` e `displayProductListReviews`, chamados pelo tema Classic, pelo Hummingbird e pela maioria dos temas. Para cada produto abrangido, imprime uma marca invisível. O script do módulo encontra a miniatura que contém a marca, oculta o botão de carrinho, o formulário de adicionar ao carrinho que o envolve e o seletor de quantidade, e insere o novo botão no lugar do botão oculto.

Se o tema não mostrar nenhum botão de carrinho nas listagens (caso do tema Classic), o botão é colocado logo a seguir ao bloco de preço.

No modo _Automático_, se nenhuma miniatura da página tiver ativado esses hooks, o script envia os ID dos produtos visíveis ao controlador do módulo, que devolve os abrangidos (no máximo 60 produtos por pedido, apenas produtos ativos e visíveis). As miniaturas adicionadas após um filtro por facetas, uma ordenação ou um scroll infinito são tratadas automaticamente.

### Seletores CSS

O bloco **Compatibilidade com o tema (seletores CSS)** da configuração contém os seletores usados pelo script:

- **Contentor da miniatura do produto**: bloco que envolve um produto (`.product-miniature`, `.ajax_block_product`, etc.).
- **Botão Adicionar ao carrinho**: elementos substituídos (`.add-to-cart`, `[data-button-action="add-to-cart"]`, etc.).
- **Seletor de quantidade**, **Preço**, **Preço anterior e desconto**, **Ponto de inserção**, **Botão Vista rápida**.

Acrescente as classes do seu tema à lista, separadas por vírgulas. O botão **Repor os seletores predefinidos** recupera os valores originais.

### Personalizar o estilo

O botão tem a classe `.dflb-btn`, mais `.dflb-full` em largura total e `.dflb-style-custom` com cores personalizadas (variáveis `--dflb-bg` e `--dflb-color`). O prefixo do preço tem a classe `.dflb-from`, e a miniatura tratada recebe `.dflb-has-btn`.

Com um tema muito personalizado, teste numa cópia da loja: página de categoria, pesquisa, página inicial e filtros por facetas.

## O que o módulo não altera

- o produto principal da página do produto e a sua vista rápida;
- o carrinho, o processo de encomenda e a conta de cliente;
- os ficheiros do núcleo e do tema (sem override, sem templates alterados).

## Limitações conhecidas

- O módulo altera a apresentação das listagens. Não bloqueia uma adição ao carrinho feita por outra via (ligação direta, módulo de terceiros).
- O preço mais baixo e o prefixo são aplicados no navegador. O HTML original e os dados estruturados do tema mantêm o preço da combinação predefinida.
- Acima de 150 combinações num mesmo produto, só as 150 primeiras são usadas para calcular o preço mais baixo.