Barra de portes grátis (dffreeshipbar): guia completo

Guia completo do módulo dffreeshipbar 2.3.0 para PrestaShop 8 e 9: instalação, limiares por país e por estado, posições de apresentação (incluindo a página de produto e o carrinho lateral do Creative Elements), mensagens, aparência, transportadoras, várias moedas e resolução de problemas.

Visão geral

O dffreeshipbar apresenta uma barra de progresso que indica ao cliente quanto falta gastar para beneficiar de portes grátis. Quando o limiar é atingido, a mensagem passa a uma confirmação.

O módulo funciona com os seus próprios limiares, guardados em tabelas próprias. Nunca lê a variável nativa PS_SHIPPING_FREE_PRICE: pode deixá-la a 0 e gerir os portes grátis com escalões da transportadora sem conflitos.

A sua particularidade é a resolução territorial em dois níveis: um limiar pode ser definido por país e por estado do PrestaShop. Territórios associados ao mesmo país, como os departamentos ultramarinos franceses ou, em Portugal, os Açores e a Madeira quando configurados como estados, podem assim ser tratados de forma diferente.

Requisitos

• PrestaShop 8.0 a 9.x
• PHP 7.4 no mínimo (8.0 a 8.3 suportadas)
• Tema Classic, Hummingbird ou um tema personalizado que chame os hooks padrão
• Creative Elements (opcional) para a posição no carrinho lateral

Instalação

1. No back office, aceder a Módulos → Gestor de módulos → Enviar um módulo.
2. Enviar o ficheiro dffreeshipbar-2.3.0.zip.
3. Clicar em Instalar e depois em Configurar.

O módulo cria duas tabelas (PREFIX_dffreeshipbar_country e PREFIX_dffreeshipbar_state, cada uma com uma coluna id_shop) e regista os hooks displayHeader, displayBanner, displayNav2, displayNavFullWidth, displayShoppingCartFooter, displayCheckoutSummaryTop, displayProductAdditionalInfo, displayCEShoppingCartFooter e actionCarrierUpdate.

O ecrã de configuração

O ecrã encontra-se em Módulos → DataFirefly – Barra de portes grátis → Configurar. No topo, uma faixa de resumo indica o estado do módulo, o número de territórios com limiar e de territórios excluídos, o limiar global, o filtro de transportadoras e as posições ativas. Cada bloco abre o separador correspondente.

A configuração divide-se em cinco separadores: Geral, Territórios, Transportadoras, Mensagens e Aparência. O separador ativo mantém-se após guardar.

Separador Geral

Limiar global

• Use a global fallback threshold: em Não, a barra só aparece nos territórios configurados. Em Sim, qualquer território não configurado recebe o montante indicado.
• Global fallback threshold: o montante aplicado em último recurso.

Várias moedas

Todos os montantes do módulo introduzem-se na moeda predefinida da loja. Para um visitante que paga noutra moeda, o limiar é convertido à taxa de câmbio do PrestaShop antes da comparação com o carrinho, e os montantes apresentados são formatados na sua moeda.

Exigir uma morada de entrega

Antes de ser introduzida uma morada, o destino é apenas uma estimativa e o estado é desconhecido. Três modos:

• Never: a barra aparece logo durante a navegação, com base no país estimado.
• For countries with states (recomendado): a barra fica visível em todo o lado exceto nos países cujos estados possam ter condições diferentes, onde aguarda a morada.
• Always: nada enquanto o carrinho não tiver morada.

Base de cálculo

• Comparar totais com IVA: deve corresponder à base dos escalões da transportadora, caso contrário a barra e o checkout divergem.
• Incluir as regras de carrinho no total: um carrinho de 70 € com um vale de 10 € é então avaliado em 60 €.

Os portes nunca contam para o progresso.

Grupos de clientes

Sem nenhuma caixa marcada, todos os clientes veem a barra. Marque grupos para a reservar a eles, por exemplo a particulares quando as empresas têm outras condições de envio. Um visitante sem sessão iniciada pertence ao grupo «Visitante».

Ocultar enquanto o carrinho estiver vazio

A barra aparece com o primeiro produto adicionado. A página de produto mantém-na em todos os casos, porque é aí que o cliente decide adicionar.

Posições de apresentação

• Topo da página: faixa visível em todo o site.
• Página de produto: ver a secção dedicada abaixo.
• Carrinho e checkout: bloco na página do carrinho e no processo de encomenda.
• Carrinho lateral do Creative Elements: ver a secção dedicada abaixo.

Para uma colocação livre, o módulo implementa WidgetInterface:

{widget name='dffreeshipbar'}
{widget name='dffreeshipbar' position='cart'}

A barra na página de produto

A barra aparece sob o botão de adicionar ao carrinho (hook displayProductAdditionalInfo). Além do progresso atual, uma linha indica o efeito de adicionar o produto apresentado:

• se o produto chegar para atingir o limiar: «Adicione este produto e a sua encomenda tem portes grátis»;
• caso contrário: «Com este produto, faltam apenas 2,50 € para portes grátis».

O cálculo usa o preço da combinação selecionada multiplicado pela quantidade indicada, com a mesma base de IVA do carrinho e os preços específicos do cliente. Repete-se quando o cliente muda de combinação ou de quantidade.

O carrinho lateral do Creative Elements

Numa loja cujo cabeçalho é construído com o Creative Elements, a barra integra-se no carrinho lateral do widget Carrinho no estilo Sidebar, através do hook displayCEShoppingCartFooter que esse widget executa. O estilo Classic não abre carrinho lateral.

A definição Posição no carrinho lateral oferece três locais: sob o título, acima do resumo ou acima dos botões de checkout.

A barra atualiza-se em Ajax a cada adição ao carrinho e a cada remoção no carrinho lateral, sem recarregar, e o indicador desliza a partir do valor anterior. O Creative Elements só reconstrói a lista de produtos e o resumo: a barra mantém-se no lugar entre atualizações.

Separador Territórios

A tabela lista todos os países ativos da loja e, sob cada país com estados, os seus estados, recuados. Um campo de pesquisa e um filtro de territórios configurados facilitam a navegação. Os montantes estão na moeda predefinida.

Ordem de resolução

Para uma morada de entrega, o módulo procura por esta ordem e para no primeiro resultado: o estado da morada, depois o país, depois o limiar global, se estiver ativo. Sem resultado, a barra não é apresentada.

Caixa e montante: dois efeitos diferentes

• Caixa desmarcada: a barra fica oculta para esse território, sem herança do país nem do limiar global.
• Caixa marcada, montante vazio: a regra é eliminada e o território herda do nível superior.
• Caixa marcada, montante indicado: aplica-se esse montante.

Exemplo: apenas França continental

• França: marcada, montante 65.
• Córsega: marcada, montante vazio; herda os 65 €.
• Guadalupe, Martinica, Guiana Francesa, Reunião, Maiote: desmarcadas.
• Limiar global: desativado.

Separador Transportadoras

Três modos: todas as transportadoras, apresentação reservada às transportadoras marcadas, ou ocultação para as transportadoras marcadas. As regras são guardadas no id_reference da transportadora: o PrestaShop recria uma transportadora a cada alteração, mas a sua referência mantém-se.

A definição Antes da escolha da transportadora decide se a barra aparece no catálogo e no carrinho enquanto nenhuma transportadora foi escolhida.

Separador Mensagens

Cinco mensagens personalizam-se para cada idioma ativo:

• Carrinho vazio
• Carrinho em curso
• Limiar atingido
• Página de produto: este produto dá portes grátis
• Página de produto: montante em falta após adicionar o produto

Estão disponíveis dois marcadores: {amount} para o montante em falta e {threshold} para o limiar. São substituídos pelo montante formatado na moeda do visitante, a negrito. Exemplo em português: Faltam apenas {amount} para portes grátis! O texto é apresentado tal como está: o HTML introduzido não é interpretado. Um campo vazio mantém o texto fornecido, que para o português está em inglês. Preencha por isso as cinco mensagens para o seu idioma português.

Separador Aparência

• Cores: fundo, barra, texto e mensagem de sucesso, com um seletor de cor e um campo hexadecimal sincronizados.
• Ícone: camião, encomenda, presente ou nenhum. Os ícones são SVG e um visto substitui o ícone quando o limiar é atingido.
• Animação: riscas animadas durante o progresso, desativadas automaticamente para os visitantes que pediram ao sistema para reduzir o movimento.
• Faixa que se pode fechar: acrescenta um botão de fecho à faixa do topo da página. Depois de fechada, fica oculta até o navegador ser fechado. As restantes posições não são afetadas.

Uma pré-visualização em direto mostra a faixa superior, a página de produto e o limiar atingido, e atualiza-se a cada alteração antes de guardar.

Atualização em tempo real

Cada posição imprime um contentor, mesmo quando a barra não tem nada para mostrar. Após um evento de carrinho, morada, passo do checkout, combinação ou quantidade, um único pedido obtém a barra de todas as posições da página, e cada contentor é preenchido ou esvaziado no lugar. Uma barra oculta no carregamento pode assim aparecer sem recarregar, e o inverso.

O script escuta os eventos do PrestaShop updateCart, updatedCart, updatedAddressForm, changedCheckoutStep, updateDeliveryForm e updatedProduct. Para provocar uma atualização a partir do seu próprio código:

document.dispatchEvent(new Event('dffreeshipbar:refresh'));

Multiloja

Os limiares têm um id_shop: cada loja tem as suas regras. Selecione o contexto da loja no topo do back office antes de abrir a configuração.

Atualização a partir de uma versão anterior

Substituir o ZIP executa automaticamente os scripts de migração. Os seus limiares são mantidos. As novas opções começam desativadas numa loja existente: página de produto, ocultação com carrinho vazio, faixa que se pode fechar e restrição por grupo. As cores guardadas por versões anteriores são normalizadas para #rrggbb, e as caches Smarty e opcache são limpas.

Resolução de problemas

A barra não aparece em lado nenhum

1. A faixa de resumo indica que nenhum território tem limiar?
2. O módulo e as posições pretendidas estão ativos?
3. A exigência de morada está em Always enquanto testa sem morada?
4. Há grupos de clientes marcados aos quais a sua conta de teste não pertence?
5. A opção para carrinho vazio está ativa com o carrinho vazio?

A barra aparece onde não devia

Verifique se a caixa do território está mesmo desmarcada, e não apenas se o montante foi esvaziado.

Nada no carrinho lateral do Creative Elements

• O widget Carrinho tem de usar o estilo Sidebar.
• A opção do carrinho lateral do Creative Elements tem de estar ativa.
• Após uma atualização a partir da 2.1.0 ou anterior, limpe a cache em Parâmetros avançados → Desempenho.

O montante não corresponde ao checkout

• A definição de IVA tem de corresponder à base dos escalões da transportadora.
• Um vale pode fazer o carrinho voltar a ficar abaixo do limiar.
• O módulo não lê os seus escalões: transponha para o módulo qualquer alteração de escalão.

A barra não se atualiza após adicionar ao carrinho

A atualização baseia-se nos eventos JavaScript do PrestaShop. Se um módulo de carrinho de terceiros não os emitir, dispare dffreeshipbar:refresh a partir do código dele. Verifique também a consola: um erro JavaScript anterior impede a instalação da escuta.

Desinstalação

A desinstalação elimina as duas tabelas de limiares e todas as chaves de configuração com o prefixo DFFREESHIPBAR_, mensagens incluídas. Exporte as duas tabelas se prevê reinstalar.

FAQ rápida

• O módulo lê PS_SHIPPING_FREE_PRICE? Nunca.
• O módulo lê os escalões da transportadora? Não, os limiares introduzem-se manualmente. Uma sincronização automática é possível como desenvolvimento à medida.
• Os meus portes grátis dependem também do peso. Está previsto? Não, o módulo mede apenas um montante.
• Posso usar negrito ou uma ligação numa mensagem? Não, o texto é protegido. Os montantes dos marcadores ficam a negrito automaticamente.
• Uma faixa fechada volta a aparecer? Na próxima abertura do navegador.

Suporte e atualizações

O módulo inclui 12 meses de atualizações e suporte. Suporte por email em francês ou inglês, resposta em 24 horas úteis. Contacte o suporte DataFirefly indicando as versões do PrestaShop, do PHP e do módulo, o tema utilizado, e o território e a transportadora em causa.