# Alterar a Combinação no Carrinho PrestaShop: instalação e configuração

> Apresentação O módulo permite ao cliente alterar a combinação de um produto (tamanho, cor ou qualquer outro atributo) diretamente na página do carrinho, sem remover a linha. A nova combinação…

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

## Apresentação

O módulo permite ao cliente alterar a combinação de um produto (tamanho, cor ou qualquer outro atributo) diretamente na página do carrinho, sem remover a linha. A nova combinação mantém a quantidade, a morada de entrega e a posição da linha. O stock e a quantidade mínima são verificados pelo servidor antes da troca.

## Instalação

1. Em **Módulos > Gestor de módulos**, clique em **Enviar um módulo** e envie o ficheiro `dfcartcombination-1.0.0.zip`.
2. O módulo liga-se aos hooks `displayCartExtraProductActions` e `actionFrontControllerSetMedia` e cria a tabela `ps_dfcartcombination_log` para o histórico.
3. Abra a configuração do módulo. Está tudo ativo por predefinição, no modo botão com janela.
4. Adicione ao carrinho um produto com pelo menos duas combinações e abra a página do carrinho para verificar a apresentação. Se nada aparecer, limpe a cache em **Parâmetros avançados > Desempenho**.

## Definições

- **Ativar o módulo**: desativado, nada é carregado na página do carrinho.
- **Modo de apresentação**: _Botão com janela de seleção_ (uma ligação «Alterar» por linha) ou _Listas pendentes na linha do carrinho_ (uma lista por grupo de atributos, alteração aplicada ao selecionar).
- **Colocar sob os atributos do produto**: move o seletor para baixo dos atributos da linha. Desative para o deixar onde o tema chama o hook, normalmente na coluna de ações junto ao caixote do lixo.
- **Mostrar o preço por combinação**: preço da combinação escolhida, preço riscado em caso de desconto e diferença face à linha atual. O preço segue a apresentação com ou sem IVA do grupo do cliente.
- **Mostrar o estado do stock**: Em stock, Apenas X disponíveis, Disponível por encomenda ou Esgotado. A mensagem «Apenas X» usa o limite de quantidade restante definido no PrestaShop. Nada é mostrado se a gestão de stock estiver desativada.
- **Mostrar a imagem da combinação**: primeira imagem associada à combinação, caso contrário a imagem de capa do produto.
- **Combinações indisponíveis**: _Mostrar desativadas_ ou _Ocultar_. O valor da linha atual fica sempre visível.
- **Produtos excluídos**: IDs de produtos separados por vírgulas. O seletor não aparece para estes produtos e o servidor recusa qualquer alteração.
- **Cor de destaque**: cor do botão principal e dos valores selecionados.
- **Registar o histórico de alterações**: alimenta as estatísticas apresentadas sob o formulário.

## Lado do cliente

### Modo janela

O botão **Alterar** abre uma janela com a imagem da combinação, o nome do produto e a quantidade da linha. Os grupos de atributos seguem a ordem do catálogo:

- grupos do tipo cor: amostras, com a textura do atributo se existir;
- grupos do tipo rádio ou lista: botões, ou uma lista pendente acima de 8 valores.

Em baixo, o preço, a diferença de preço e o estado do stock da seleção atualizam-se a cada clique. O botão **Atualizar carrinho** fica inativo enquanto a seleção for igual à linha ou estiver indisponível. A janela fecha com Escape, a cruz ou um clique fora, e pode ser usada pelo teclado (setas entre os valores de um grupo). No telemóvel, abre a partir da parte inferior do ecrã.

### Modo listas pendentes

Cada grupo de atributos passa a ser uma lista na linha. A alteração é enviada assim que um valor é escolhido. As linhas de atributos que o tema já mostra (por exemplo «Tamanho: S») são ocultadas para evitar duplicação. Uma mensagem sob as listas indica a atualização em curso ou o eventual erro.

### Combinação inexistente

Se o valor escolhido não existir com os outros atributos selecionados (M Azul ausente do catálogo, por exemplo), o módulo passa para a combinação existente que contém esse valor e mantém mais atributos atuais, dando prioridade a uma combinação encomendável.

## Controlos antes da troca

O navegador envia o produto, a combinação atual e a escolhida. O servidor verifica depois:

- o token da sessão;
- que o produto está ativo e disponível para encomenda, e que o modo catálogo está desativado;
- que a combinação escolhida pertence ao produto e à loja;
- que a linha original ainda está no carrinho, sem personalização;
- que o produto não está ligado a uma regra de carrinho com brinde deste carrinho;
- que a quantidade final atinge a quantidade mínima da combinação;
- que o stock cobre a quantidade final, exceto se a venda sem stock for permitida para o produto.

A nova combinação é adicionada com o método nativo `updateQty` e depois a antiga é removida com `deleteProduct`. Se a remoção falhar, a adição é anulada. Se a combinação escolhida já estiver no carrinho, as quantidades são somadas numa única linha. Caso contrário, a nova linha retoma a data de adição da antiga para manter o seu lugar no carrinho.

Após a troca, o módulo dispara o evento `updateCart` do PrestaShop. O tema recarrega então a lista, os totais e o mini carrinho. Se o tema não reagir em 3 segundos, a página é recarregada.

## Linhas não abrangidas

- produtos sem combinações ou com uma única combinação;
- linhas com personalização (texto, ficheiro);
- produtos oferecidos por uma regra de carrinho;
- produtos excluídos na configuração.

## Histórico e estatísticas

Sob o formulário de configuração, o bloco **Histórico de alterações** mostra:

- o número de alterações e de carrinhos abrangidos em 30 dias;
- o número de carrinhos alterados que se tornaram encomendas, com a taxa;
- os 10 produtos mais alterados;
- as 20 últimas alterações, com a combinação de partida e a escolhida.

O botão **Limpar histórico** elimina os dados da loja atual. Um produto muitas vezes alterado para o tamanho acima indica uma tabela de tamanhos ou uma página de produto a rever.

## Temas e personalização

O tema Classic e a maioria dos temas derivados chamam `displayCartExtraProductActions` em cada linha do carrinho. Se o seu tema não o chamar, o script cria o seletor a partir das ligações de remoção das linhas (`data-id-product` e `data-id-product-attribute`). O ficheiro JavaScript só é carregado na página do carrinho.

Para ajustar o estilo, sobreponha no CSS do tema as variáveis `--dfcc-accent`, `--dfcc-text` e `--dfcc-border`, ou as classes `.dfcc-edit`, `.dfcc-modal__dialog` e `.dfcc-option`.

Com um tema muito personalizado ou um módulo de carrinho lateral, teste a alteração de combinação numa cópia da loja, como convidado e como cliente com sessão iniciada.

## Para programadores

Após cada alteração bem-sucedida, o módulo executa o hook `actionDfCartCombinationChange` com os parâmetros `cart`, `id_product`, `id_product_attribute_from`, `id_product_attribute_to` e `quantity`. Um módulo de terceiros pode ligar-se a ele para sincronizar um CRM ou uma ferramenta de análise.

## Limitações conhecidas

- Na versão 1.0.0, as linhas personalizadas mantêm a sua combinação.
- A alteração faz-se na página do carrinho, não no resumo do processo de encomenda nem no mini carrinho.
- Um módulo de carrinho lateral que não use o evento `updateCart` só se atualiza quando a página é recarregada.