Box Builder (Mix & Match): guia completo

Apresentação

O Box Builder (Mix & Match) (dfboxbuilder) acrescenta uma página onde os seus clientes compõem o próprio conjunto com os produtos que escolher. Selecionam artigos numa grelha, acompanham uma barra de progresso, veem o preço do conjunto e a poupança atualizarem-se e adicionam o conjunto ao carrinho. O conjunto enche-se por número de artigos ou ao peso. Cada conjunto é uma linha do carrinho com o seu próprio preço; a composição fica legível no carrinho, na encomenda e na fatura.

Compatibilidade

• PrestaShop 8.x e 9.x
• PHP 7.4 a 8.x
• Loja única e multiloja
• Interface do módulo em francês, inglês, espanhol, alemão e italiano; nos outros idiomas, os textos do módulo aparecem em inglês (podem ser traduzidos no PrestaShop)
• Tema Classic, Hummingbird e temas personalizados (configurador em JavaScript nativo, sem jQuery)
• Sem dependências (nem Composer nem framework)

Instalação e atualização

1. No back-office, abra Módulos > Gestor de módulos.
2. Clique em Carregar um módulo e selecione dfboxbuilder.zip.
3. Abra a entrada Box Builder acrescentada ao menu para criar o primeiro conjunto.

Para atualizar, carregue o novo ZIP da mesma forma: os scripts de atualização correm automaticamente (novas colunas, novos hooks, URL amigáveis geradas a partir dos nomes dos conjuntos). Os conjuntos existentes continuam a encher-se por número de artigos.

Definições do módulo

O painel Settings, por cima da lista de conjuntos, tem três opções:

• Conjuntos na página inicial: bloco no hook displayHome.
• Cor de destaque: cor da barra de progresso, dos separadores dos passos e dos destaques. Indique a cor principal do seu tema (por exemplo #8a5a2b); deixe vazio para o azul predefinido. A cor do texto por cima é escolhida automaticamente para se manter legível.
• Depois de adicionar um conjunto ao carrinho: ir para a página do carrinho (predefinição) ou ficar no configurador. Ao ficar, o bloco do carrinho do tema é atualizado e abre a sua janela de confirmação; depois o cliente pode compor outro conjunto.

Na lista de conjuntos, o menu de cada linha propõe Open the builder page (abrir a página do configurador) e Duplicate (duplicar). A cópia retoma preços, tarifas decrescentes, espaços, fontes, modelos, restrições e grupos; é criada inativa. Para um conjunto ao peso, as colunas Min e Max mostram os pesos.

Criar um conjunto

O formulário de um conjunto tem seis separadores.

Geral

• Nome, descrição, texto do botão: por idioma.
• URL amigável: por idioma, gerada a partir do nome se ficar vazia. Com as URL amigáveis do PrestaShop ativas, a página do conjunto tem o endereço /box/ID-url-amigavel.
• Forma de encher (Fill the box by): número de artigos (Number of items, predefinição) ou peso (Weight), ver Conjuntos ao peso.
• Artigos mín. / máx. (enchimento por número de artigos): limites da composição (0 = sem máximo).
• Peso mínimo / máximo (enchimento ao peso): na unidade de peso da loja; 0 = sem máximo, o mesmo valor para um peso exato.
• Permitir o mesmo artigo várias vezes e unidades máximas por artigo.
• Ocultar produtos esgotados: caso contrário, ficam visíveis mas não podem ser adicionados.
• Preenchimento aleatório, gravar e partilhar, ativo.

Disponibilidade

• Disponível de / até: período de venda. Antes da data de início, a página do conjunto indica a partir de quando está disponível; depois da data de fim, o conjunto é retirado dos carrinhos que ainda o contêm.
• Stock limitado (conjuntos): número máximo de conjuntos vendidos, somando todas as lojas, sem encomendas canceladas (0 = ilimitado). O formulário mostra os vendidos e os restantes; a página do conjunto mostra quantos restam.
• Mostrar no catálogo: em lado nenhum (predefinição), categorias e pesquisa, só categorias ou só pesquisa, com as categorias onde colocar o conjunto.
• Grupos de clientes: nenhum grupo assinalado = todos. Caso contrário, só os grupos assinalados veem e encomendam o conjunto.
• Propor o conjunto nas fichas de produto: acrescenta uma proposta na ficha de cada produto que o conjunto contém.

Preços

Todos os preços são introduzidos sem IVA, na moeda predefinida. O conjunto tem a sua própria regra de impostos, aplicada no carrinho conforme a morada do cliente.

• Preço fixo: um preço único, seja qual for o conteúdo.
• Escalões de volume: o preço depende do número de artigos (ex. a partir de 3 artigos: 25 €, a partir de 6: 45 €). O cliente vê quantos artigos faltam para o preço mais baixo.
• Soma dos produtos com desconto: soma dos preços dos artigos menos uma percentagem. Os preços dos artigos aparecem então na grelha.
• Preço por espaço: cada espaço tem um preço por artigo (requer espaços).
• Preço ao peso (Price per weight): peso total dos artigos vezes um preço por unidade de peso (ao kg se a loja usa kg). As tarifas decrescentes opcionais mudam esse preço a partir de um peso do conjunto, e todo o conjunto passa à nova tarifa: com 30 € o kg e 26 € o kg a partir de 1 kg, um conjunto de 1,05 kg custa 27,30 €. O cliente vê o preço ao quilo atual e quantos gramas faltam para a tarifa mais baixa. Este modelo também funciona com conjuntos enchidos por número de artigos.

Mostrar a poupança compara o preço do conjunto com o dos artigos comprados em separado, aos preços atuais do seu catálogo.

Recompensas ao completar: produto oferecido e/ou portes grátis, concedidos por uma regra de carrinho com código secreto, de utilização única, válida só enquanto o conjunto está no carrinho. O texto da recompensa aparece no configurador.

Opções de oferta:

• Mensagem de oferta com comprimento máximo (1 a 500 caracteres). A mensagem aparece na encomenda no back-office e na fatura.
• Embrulho de oferta com o seu preço sem IVA (0 = gratuito), somado ao preço do conjunto.

Composição

Os produtos elegíveis vêm de produtos adicionados um a um (pesquisa por nome, referência ou ID) ou de categorias inteiras. Cada combinação de um produto torna-se um artigo selecionável, com o seu próprio stock, preço e peso.

Espaços dão estrutura ao conjunto, por exemplo “2 salgados + 1 doce”. Cada espaço tem um nome por idioma, um mínimo, um máximo, um preço por artigo (modelo por espaço) e fontes próprias. Na loja, os espaços tornam-se passos numerados.

Modelos

Conjuntos pré-compostos que o cliente aplica num clique e depois ajusta. Os produtos de um modelo também têm de ser elegíveis no conjunto.

Restrições

Pares de produtos que não podem estar no mesmo conjunto. O configurador impede a combinação e o servidor recusa-a.

Conjuntos ao peso

Para uma caixa de bombons, um sortido de chás ou uma caixa de produtos a granel, o cliente enche o conjunto até um peso em vez de contar artigos.

1. Separador Geral: forma de encher = Weight e depois um peso mínimo e/ou máximo. Exemplo: 1 e 1,2 para um conjunto de 1 a 1,2 kg; 1 e 1 para exatamente 1 kg. Pelo menos um dos dois é obrigatório.
2. Separador Preços: todos os modelos de preço funcionam. Preço ao peso vende o conjunto ao quilo, com tarifas decrescentes se necessário; um preço fixo serve para uma caixa vendida a 35 € seja qual for o sortido.
3. Verifique o peso dos produtos: ficha de produto, separador Envio, e impacto no peso de cada combinação.

• Peso de um artigo: peso do produto + impacto da combinação, o mesmo valor que o PrestaShop usa para os portes.
• Produtos sem peso: não são propostos num conjunto ao peso nem num conjunto com preço ao peso, e o bloco das fichas de produto não propõe o conjunto na sua página. O formulário do conjunto mostra quantos produtos elegíveis estão nesta situação.
• Configurador: peso em cada cartão, no resumo e na vista rápida; contador e barra de progresso em g / kg (“800 g / 1,2 kg”, mínimo assinalado); um artigo que ultrapassaria o máximo fica desativado com a indicação de que não cabe no peso restante; enquanto o mínimo não for atingido, o cliente vê quantos gramas faltam.
• Regras de artigos: no modo peso, os artigos mín. / máx. do conjunto não se aplicam; os espaços, os duplicados, as unidades máximas por artigo e as incompatibilidades continuam ativos.
• Preenchimento aleatório enche o conjunto dentro do intervalo de peso.
• Carrinho, encomenda e fatura: o peso total aparece com a composição.
• Apresentação dos pesos: em gramas abaixo de 1 kg, em quilos acima, com o separador decimal do idioma do visitante.

Na loja

O configurador

• Passos: com espaços, separadores numerados mostram o avanço. Quando um passo fica cheio, o configurador passa ao seguinte; aparece um botão de passo seguinte assim que um passo está completo.
• Grelha: acima de 8 produtos, aparecem uma pesquisa (que ignora acentos), um filtro por categoria e a ordenação por nome ou preço. Um clique na imagem ou no nome abre a vista rápida (imagem, descrição, ligação para a ficha, botão Adicionar). Os artigos escolhidos têm um botão “-“.
• Resumo: contador com a regra (mín. 5, máx. 6, ou em peso para um conjunto ao peso), barra de progresso com o mínimo assinalado, pré-visualização da caixa (uma casa por artigo), preço, poupança, recompensa a desbloquear e opções de oferta. O que falta aparece a azul; o vermelho fica reservado para bloqueios reais.
• Telemóvel: grelha em duas colunas, modelos e passos com deslocação horizontal, barra fixa com o número de artigos (ou o peso) e o preço, que se transforma em botão de carrinho quando o conjunto é válido.
• Preenchimento aleatório enche o conjunto dentro das regras; gravar e partilhar cria uma ligação que volta a carregar a composição.

O preço é sempre recalculado pelo servidor a partir do seu catálogo; uma composição enviada pelo navegador é verificada de novo (produtos, combinações, espaços, peso, stock) antes de ser adicionada ao carrinho.

Editar um conjunto a partir do carrinho

No carrinho e no checkout, a composição do conjunto é seguida de uma ligação de edição (Edit this box quando a interface está em inglês). Abre o configurador com a composição e as opções de oferta. Ao confirmar, o conjunto é substituído no mesmo lugar, com a mesma quantidade. No tema Classic, a composição e a ligação estão na janela de personalização da linha do carrinho.

Apresentação e angariação

• Página do conjunto: ligação para a página do configurador no formulário e na lista. Endereço /box/ID-url-amigavel com URL amigáveis, etiqueta canónica, seletor de idioma que aponta para a URL do idioma escolhido.
• Página inicial: bloco com os conjuntos disponíveis (definição do módulo).
• Widget: o bloco pode ser associado a qualquer hook de apresentação (Design > Posições) ou colocado num template: {widget name='dfboxbuilder'}, {widget name='dfboxbuilder' id_dfbox=3} ou {widget name='dfboxbuilder' title='Os nossos conjuntos'}.
• Fichas de produto: bloco com uma proposta (até 3 conjuntos) que abre o configurador com o produto já adicionado.
• Catálogo: com a opção de mostrar no catálogo, o conjunto aparece nas categorias escolhidas e/ou na pesquisa. O preço apresentado é o preço “desde” (composição válida mais barata, com IVA e desconto de grupo; para um conjunto ao peso, ao peso mínimo ou na tarifa decrescente mais vantajosa); um conjunto de preço fixo mostra o seu preço. A ligação abre o configurador e não há botão de adicionar ao carrinho.

Nos blocos só aparecem conjuntos ativos, dentro do período de venda, não esgotados e permitidos ao grupo do visitante. Desativar um conjunto desativa também o seu produto técnico, que desaparece das listas.

Carrinho, encomendas e stock

• Preço por linha: o preço do conjunto é guardado na sua linha do carrinho; dois conjuntos com composições diferentes mantêm cada um o seu preço. Os descontos de grupo de clientes aplicam-se; as regras de preço do catálogo e os descontos por quantidade não se aplicam aos conjuntos.
• Stock dos componentes: verificado ao adicionar, em todo o carrinho (outros conjuntos e produtos comprados isoladamente). Se o cliente aumentar a quantidade de um conjunto para além do stock, ela é reduzida ao máximo possível na página do carrinho, com uma mensagem.
• Encomendas: o stock de cada componente é descontado na validação da encomenda, reposto se a encomenda passar a cancelada ou erro de pagamento, e descontado de novo se for reativada. Uma encomenda criada diretamente em erro não desconta stock.
• Conjuntos indisponíveis: um conjunto eliminado, desativado, terminado, ainda não iniciado ou reservado a outro grupo é retirado do carrinho nas páginas de carrinho e encomenda, também depois de voltar a encomendar.
• Back-office e fatura: a composição (por espaço), o embrulho, a mensagem de oferta e, para um conjunto ao peso, o peso total aparecem na encomenda e na fatura.

Estatísticas

O botão Analytics da lista abre um painel com escolha de período (7, 30, 90 ou 365 dias):

• conjuntos encomendados, volume de negócios sem IVA, média de artigos por conjunto, conversão (encomendas / visitas);
• por conjunto: visitas ao configurador, adições ao carrinho, encomendas, conjuntos, taxa de adição, conversão, volume de negócios e preço médio;
• artigos mais escolhidos e combinações mais encomendadas.

As visitas e adições são contadas desde a versão 1.2.0, sem robôs; as encomendas canceladas são excluídas.

Acompanhamento com Google Analytics 4

Depois de um conjunto ser adicionado, o configurador envia um evento add_to_cart para window.dataLayer (se o Google Tag Manager ou o gtag.js estiverem presentes) com currency, value e o artigo dfbox-ID. É também emitido um evento dfbox:added em document com os mesmos dados, para outras ferramentas.

Perguntas frequentes e resolução de problemas

Os botões não fazem nada ou a página fica vazia

Limpe a cache do PrestaShop (Parâmetros avançados > Desempenho) e, durante os testes, desative a junção de ficheiros JS/CSS. Verifique se o conjunto está ativo, associado à loja e com pelo menos uma fonte de produtos.

A grelha está vazia

As fontes têm de conter produtos ativos e disponíveis para encomenda na loja atual. Com os produtos esgotados ocultos, os produtos sem stock não aparecem. Num conjunto ao peso ou com preço ao peso, os produtos sem peso também não aparecem.

Um produto não aparece num conjunto ao peso

Não tem peso. Indique-o na ficha de produto, separador Envio, ou no impacto no peso das suas combinações. O aviso no topo do formulário do conjunto indica quantos produtos elegíveis estão nesta situação.

Um conjunto visível numa categoria mostra 0,00 €

Atualize o módulo para a versão 1.2.1 ou posterior: as listas passam a mostrar o preço “desde”.

O conjunto não aparece para um cliente

Verifique as datas de venda, o stock limitado e os grupos de clientes no separador Disponibilidade.

A ligação de edição não aparece

Só é apresentada no carrinho e no checkout, para um conjunto ainda disponível. No tema Classic, abra a janela de personalização da linha.

O stock dos componentes não desce

É descontado na validação da encomenda, não ao adicionar ao carrinho, e só com a gestão de stock ativa. Uma encomenda cancelada repõe o stock.