# Configurador de Produto por Etapas: guia completo

> Apresentação O Configurador de Produto por Etapas acrescenta à página de produto um percurso guiado: o cliente escolhe as suas opções (tamanho, suporte, cor, moldura…), escreve um texto, envia um…

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

## Apresentação

O Configurador de Produto por Etapas acrescenta à página de produto um percurso guiado: o cliente escolhe as suas opções (tamanho, suporte, cor, moldura…), escreve um texto, envia um ficheiro, e o preço atualiza-se a cada escolha. O suplemento é calculado no servidor e transportado por uma personalização nativa do PrestaShop, pelo que acompanha o carrinho, a encomenda e a fatura.

O módulo substitui com vantagem as combinações quando um produto junta muitas opções: não é criada nenhuma combinação, cada opção tem o seu preço e o seu peso, e um mesmo configurador pode servir todo um catálogo.

- **Configurador**: um conjunto de campos, associado a um ou vários produtos e, se necessário, a categorias.
- **Campo**: uma etapa do percurso (lista, botões de rádio, amostras, miniaturas, texto, envio…).
- **Opção**: uma escolha proposta num campo, com preço, peso, referência e imagem.

## Instalação e atualização

1. No back-office, abra **Módulos → Gestor de módulos → Enviar um módulo** e envie o ZIP do módulo.
2. Clique em **Configurar** para aceder às definições de apresentação e aos dados de demonstração.
3. Os configuradores gerem-se em **Módulos → Configuradores de produto**.

Compatibilidade: PrestaShop 1.7.7 a 9.x, PHP 7.1 ou superior (conforme a versão do PrestaShop). O módulo não usa Composer nem jQuery e não exige alterações ao tema. A interface do módulo existe em francês, inglês, espanhol, alemão, italiano, polaco e neerlandês; num back-office em português, os rótulos aparecem em francês. Os nomes indicados neste guia são traduções desses rótulos.

Para atualizar, basta enviar o novo ZIP. O esquema da base de dados, os hooks e as caches atualizam-se automaticamente, mesmo que os ficheiros tenham sido copiados à mão sem passar pelo gestor de módulos. Os configuradores existentes são mantidos.

## Definições de apresentação

A página **Configurar** do módulo reúne as definições comuns a todos os configuradores:

- **Modo de apresentação**: bloco integrado na página de produto (recomendado com um page builder), botão «Configurar» que abre uma janela em ecrã inteiro, ou substituição completa da página de produto.
- **Colocação**: automática (hook `displayProductAdditionalInfo` do tema) ou manual (é o próprio a colocar o configurador, ver a secção Creative Elements).
- **Ocultar o botão de carrinho nativo do tema**: evita adicionar ao carrinho sem passar pelo configurador.
- **Seletor de quantidade no configurador**: no modo integrado, mostra a quantidade junto ao botão «Adicionar ao carrinho» do configurador e oculta a do tema.
- **Mostrar o nome e a descrição do configurador**: desative quando o título e o texto do produto já são geridos pelo tema ou pelo page builder.
- **Mostrar a barra de etapas** e **Numerar as etapas**: a fila de etiquetas por cima dos campos e os números antes de cada título podem ocultar-se separadamente.
- **Depois de adicionar ao carrinho**: janela com o detalhe da personalização, janela nativa do tema (módulo de carrinho `ps_shoppingcart`) ou uma simples mensagem por baixo do botão.

## Criar um configurador

Em **Módulos → Configuradores de produto**, clique em **Novo configurador**. A partir da página de um produto no back-office (página de produto antiga), o botão «Criar um configurador para este produto» preenche o produto.

### Produtos e categorias associados

- **Produtos associados**: escreva um nome, uma referência ou um ID e clique no resultado. Acrescente tantos produtos quantos precisar; a cruz de uma etiqueta remove o produto.
- **Categorias associadas**: assinale as categorias cujos produtos devem todos receber o configurador. O filtro por cima da lista encontra uma categoria pelo nome. A opção **Incluir subcategorias** estende a associação a toda a árvore.

Cada produto mantém o seu próprio preço base. Se um produto estiver associado a vários configuradores ativos, a associação direta ao produto prevalece sobre a associação por categoria, e depois o configurador mais antigo. Um aviso indica os produtos em causa.

### Definições gerais

- **Nome interno (opcional)**: serve para encontrar o configurador na lista. Se ficar vazio, assume o nome do primeiro produto associado. Só aparece na página de produto se a definição correspondente estiver ativa.
- **Ativo**: um configurador inativo não aparece em nenhum produto.
- **Bloquear a adição se inválido**: o botão «Adicionar ao carrinho» fica desativado enquanto faltar um campo obrigatório.
- **Modo de preço**: preço do produto + opções (caso geral), ou preço base personalizado + opções.

## Os campos

Clique em **Adicionar um campo**, escolha o tipo, introduza a etiqueta em cada idioma (seletor de idioma no topo do formulário) e assinale **Obrigatório** se necessário. Por baixo do título pode aparecer um texto de ajuda.

### Tipos de campo

- **Lista pendente**, **Botões de rádio**, **Amostras de cor**, **Miniaturas de imagem**: uma escolha entre opções.
- **Caixas de seleção**: várias escolhas possíveis (acabamentos, embrulho de oferta…).
- **Campo de texto**, **Área de texto**, **Número**, **Data**, **Envio de ficheiro**: introdução livre. Uma única opção «portadora» define então a tarifa (por exemplo 0,20 € por carácter).

### Opções

Cada opção tem uma etiqueta multilingue, um impacto no preço e o seu tipo (montante fixo, percentagem do preço base, por carácter, por unidade, fórmula), uma cor para as amostras, uma miniatura para as miniaturas de imagem, um **peso** em kg, uma **referência**, o estado «predefinida» e a disponibilidade. Uma opção indisponível continua visível mas a cinzento.

### Reordenar campos e opções

Arraste um campo pela sua pega para mudar a ordem das etapas; o botão **Recolher tudo** facilita a operação num configurador longo. As opções reordenam-se da mesma forma com a sua pega. A ordem é guardada com o configurador.

### Mostrar apenas se…

Um campo pode aparecer apenas quando uma opção concreta de outro campo é escolhida. Exemplo: o campo «Moldura» só aparece se «Impressão emoldurada» for escolhida em «Tipo». No bloco **Mostrar apenas se…**, selecione a opção ou opções ativadoras (Ctrl ou Cmd + clique para escolher várias: o campo aparece se uma delas for escolhida). Sem seleção, o campo aparece sempre.

As dependências em cadeia são geridas: se um campo ativador estiver oculto, os campos que dependem dele também ficam ocultos. Um campo oculto não entra no preço nem na encomenda, mesmo que seja obrigatório.

Na lista só aparecem as opções já guardadas. Depois de criar novas opções, guarde o configurador uma vez e só então defina as condições.

### Link de informação (janela)

Cada campo pode mostrar, à direita do título, um link como «Guia de materiais» ou «Guia de tamanhos». Um clique abre uma janela por cima da página.

- **Texto do link**: a etiqueta mostrada, em cada idioma. Vazio: sem link.
- **Conteúdo da janela**: HTML (texto, tabela, imagens) e as etiquetas `{hook …}` e `{widget …}`, executadas como no widget Shortcode do Creative Elements. Para uma paginação rica, crie a janela como modelo guardado no Creative Elements e cole o seu shortcode.

Scripts e iframes são recusados ao guardar por razões de segurança: um aviso indica-o e o conteúdo anterior é mantido.

## Preço e peso

Os impactos introduzem-se **sem impostos** na moeda predefinida. A página de produto mostra o preço base, o total das opções e o total com IVA, atualizados a cada escolha. Esse total é apenas uma apresentação: o preço real é recalculado no servidor a partir das escolhas do cliente e transportado pela personalização nativa do PrestaShop. Alterar a página ou os pedidos no navegador não muda o preço faturado.

O PrestaShop soma o **peso** das opções escolhidas ao peso do carrinho. Os escalões de peso das suas transportadoras aplicam-se portanto normalmente, e o preço das opções conta no total usado para o limiar de portes grátis.

Para portes que dependem do tamanho, atribua a cada formato um peso real ou volumétrico (por exemplo 40 × 60 emoldurado = 2,5 kg). Os limites de dimensões das transportadoras só leem as dimensões do produto, não as opções escolhidas.

## Pré-visualização visual (opcional)

No bloco **Pré-visualização visual** do configurador, ative a pré-visualização e envie uma imagem de fundo (PNG transparente recomendado). Cada campo pode então colocar uma camada de imagem, tingir a silhueta ou mostrar o texto do cliente numa zona que desenha com o rato. O cliente pode escolher o tipo de letra, o tamanho e a cor do texto, e as cores podem ser ligadas a outro campo. Ao adicionar ao carrinho, o visual final é composto e guardado com a encomenda.

Pré-visualização desativada: não é mostrada nenhuma pré-visualização, as imagens do tema ou do page builder nunca são alteradas e as definições de pré-visualização dos campos ficam ocultas no editor (continuam guardadas se voltar a ativar a pré-visualização).

## Creative Elements e page builders

1. Nas definições do módulo, escolha o modo **Integrado** e a colocação **Manual**.
2. Desative a pré-visualização no configurador: as imagens da página continuam a ser as do page builder.
3. No modelo de página de produto do Creative Elements, acrescente um widget **Módulos**, escolha o módulo DataFirefly Configurador e introduza o hook `displayDfProductConfigurator`. Também pode usar um widget **Shortcode** com `{hook h='displayDfProductConfigurator'}`.
4. Coloque esse widget onde quiser, por exemplo por baixo do título e do preço. Nos produtos sem configurador, o widget não mostra nada.
5. Se necessário, desative a numeração, a barra de etapas e o nome do configurador, e ative o seletor de quantidade integrado se o widget «Adicionar ao carrinho» do Creative Elements não estiver na página.

Num tema, o mesmo hook chama-se com `{hook h='displayDfProductConfigurator' product=$product}`. O configurador só é apresentado uma vez por página.

## Depois de adicionar ao carrinho

Com a definição predefinida abre-se uma janela: imagem do produto, preço unitário, detalhe de cada escolha (por exemplo Tipo: Impressão emoldurada, Tamanho: 40 × 60 cm, Moldura: Nogueira), quantidade, e depois o número de artigos, subtotal, portes e total do carrinho, com os botões **Continuar a comprar** e **Finalizar compra**. O modelo `views/templates/front/cart_modal.tpl` pode ser substituído no tema.

A definição «Janela nativa do tema» usa a janela do módulo de carrinho, que não mostra o detalhe da personalização. A definição «Mensagem» mostra um link para o carrinho por baixo do botão.

## Carrinho, encomenda e produção

Cada configuração validada cria uma personalização nativa do PrestaShop: duas configurações diferentes dão duas linhas de carrinho separadas. O resumo legível (Tamanho: 40 × 60 cm · Tipo: Impressão emoldurada · Moldura: Nogueira) aparece no carrinho, na encomenda, na fatura e no back-office. O detalhe da encomenda no back-office mostra um painel **Personalizações** com o resumo campo a campo, os ficheiros enviados pelo cliente e, se a pré-visualização estiver ativa, o visual final.

No tema Classic, uma alteração de quantidade recarrega parte da página de produto por AJAX: o configurador fica no lugar e mantém as escolhas do cliente.

## Duplicar um configurador

Na lista, abra o menu da linha e clique em **Duplicar** (o botão existe também no fundo do editor). A cópia retoma definições, campos, opções, traduções e imagens. As condições «Mostrar apenas se…» e as cores ligadas são religadas aos campos copiados. A cópia é criada **inativa e sem produtos nem categorias associados**, para não ocupar o lugar do original: associe os seus produtos e ative-a.

## Dados de demonstração

A página **Configurar** propõe três importações, que podem ser repetidas sem duplicados:

- **Caneca, jarra, t-shirt**: pré-visualização composta, texto gravado, cores conforme a forma, fórmula de preço, envio de ficheiro.
- **Bordado (emblema e gorro)**: cores ligadas entre vários elementos.
- **Quadro de foto (arte de parede)**: pré-visualização desativada, link «Guia de materiais», tamanhos com peso, tipo de suporte em miniaturas, foto do cliente, cor de fundo, moldura mostrada só para uma impressão emoldurada.

## Resolução de problemas

### O configurador não aparece

- Verifique que o configurador está **ativo** e associado ao produto, diretamente ou através de uma categoria.
- Com colocação manual, verifique que o hook `displayDfProductConfigurator` está no modelo da página de produto.
- Com colocação automática, verifique que o tema chama `displayProductAdditionalInfo` (o tema Classic fá-lo).
- Limpe a cache (**Parâmetros avançados → Desempenho**).

### Uma opção não aparece em «Mostrar apenas se…»

Ainda não está guardada. Guarde o configurador e volte ao campo.

### O link de informação não aparece

O texto do link e o conteúdo da janela têm de estar ambos preenchidos no idioma mostrado.

### O botão «Adicionar ao carrinho» continua a cinzento

Falta um campo obrigatório visível: a mensagem por baixo do total indica qual. Desative «Bloquear a adição se inválido» para deixar o botão ativo e mostrar os erros ao clicar.

### Os portes não mudam com as opções

Verifique que as opções têm um peso e que a transportadora cobra por peso (e não por preço).

## Histórico de versões

- **1.3.0**: PrestaShop 1.7.7 e 1.7.8, vários produtos e categorias por configurador, duplicação, condições escolhidas numa lista de opções, links de informação em janela, hook dedicado para page builders, janela de carrinho, definições de apresentação, arrastar e largar, demo de quadro de foto.
- **1.2.1**: pré-visualização idêntica ao visual final, mensagens do front traduzidas, editor de zonas com as proporções corretas.
- **1.2.0**: cores ligadas, recoloração de visuais, demos num clique, pré-visualização sempre visível.
- **1.1.0**: tipo de letra, tamanho e cor à escolha do cliente, zonas de posicionamento com o rato, visual final e painel de encomenda, três modos de apresentação.
- **1.0.0**: versão inicial.