Sticky Add to Cart para PrestaShop: guia completo

Apresentação

O DataFirefly Sticky Add to Cart apresenta uma barra «Adicionar ao carrinho» persistente nas páginas de produto da sua loja PrestaShop 8 ou 9. Em telemóvel, uma barra compacta fixa-se no fundo do ecrã. Em computador, uma barra lateral flutuante desliza a partir da direita (ou, à sua escolha, uma barra no fundo idêntica à de telemóvel). A barra inclui um seletor compacto de variante, um seletor de quantidade e o preço atualizado em tempo real.

A adição ao carrinho é feita por um pedido AJAX direto ao controlador de carrinho do PrestaShop: o módulo nunca manipula o formulário nem o botão nativo do seu tema, o que garante uma coexistência sem conflitos.

Instalação

1. No seu back-office PrestaShop, abra Módulos > Gestor de módulos.
2. Clique em Carregar um módulo e selecione o ficheiro dfstickyaddtocart.zip.
3. Depois de instalado o módulo, clique em Configurar.
4. Limpe a cache do PrestaShop: Parâmetros avançados > Desempenho > Limpar cache.

Configuração

Todas as definições estão em Módulos > Gestor de módulos > DataFirefly Sticky Add to Cart > Configurar.

Apresentação

• Ativar o módulo: interruptor global.
• Mostrar em telemóvel: ativa a barra no fundo em ecrãs com menos de 992 px.
• Mostrar em computador: ativa a apresentação em ecrãs de 992 px ou mais.
• Apresentação em computador: dois modos, Barra lateral flutuante (à direita), um cartão de 320 px que desliza a partir da margem direita, ou Barra no fundo, idêntica ao resultado em telemóvel mas centrada em 1280 px.
• Desvio superior em computador (px): distância entre o topo da janela e a barra lateral flutuante. Aumente este valor se o seu tema tiver um cabeçalho fixo (90 px por predefinição).

Conteúdo da barra

• Mostrar a imagem do produto: miniatura da imagem de capa.
• Mostrar o seletor de variante: lista pendente compacta das combinações (ocultada automaticamente se o produto não tiver combinações).
• Mostrar o seletor de quantidade: botões de menos e mais (apresentado em computador; em telemóvel, a quantidade fica em 1 para preservar a compacidade).
• Ocultar quando o botão principal está visível: a barra só aparece quando o botão «Adicionar ao carrinho» original sai do viewport (recomendado). Desative para ter uma barra permanentemente visível.

Cores

• Cor de fundo: fundo da barra (branco por predefinição).
• Cor do botão: botão de adição ao carrinho (azul-turquesa #2fb5d2 por predefinição).
• Cor do texto do botão: designação do botão.
• Cor do texto: nome do produto e designações.
• Cor do preço: opcional; se ficar vazia, é usada a cor do botão.

Funcionamento

Deteção de visibilidade

O módulo observa o bloco «Adicionar ao carrinho» original com a API IntersectionObserver do navegador. Assim que esse bloco sai do viewport (o utilizador desceu na página), a barra fixa aparece com uma animação de deslize. Assim que volta a ficar visível, a barra desaparece. Este mecanismo é nativo do navegador e não acrescenta qualquer custo de desempenho ao deslocamento.

Seletor de variante

Nos produtos com combinações, o seletor compacto mostra cada combinação com o seu preço e a sua disponibilidade (as combinações em rutura ficam desativadas). A seleção é local à barra fixa: não altera a interface de variantes da página principal. Quando o cliente muda de variante a partir da página principal, a barra fixa sincroniza-se automaticamente através do evento updatedProduct do PrestaShop.

Adição ao carrinho

O clique no botão fixo envia um pedido AJAX POST diretamente ao controlador de carrinho do PrestaShop (o mesmo endpoint do tema), com a combinação e a quantidade escolhidas na barra. Em caso de sucesso, o módulo emite o evento updateCart: o contador do carrinho no cabeçalho e a pré-visualização do carrinho do seu tema atualizam-se normalmente, e o botão fixo mostra uma marca de confirmação.

Apresentação em telemóvel

Em telemóvel, a barra adapta-se automaticamente:

• Produto sem variantes: uma só linha, com miniatura, nome, preço e botão. Abaixo dos 600 px, a designação do botão dá lugar ao ícone de carrinho; abaixo dos 380 px, a miniatura é ocultada.
• Produto com variantes: duas linhas, com miniatura, nome, preço e botão na primeira, e o seletor de variante em largura total na segunda.

A barra respeita a zona safe-area-inset-bottom dos iPhone com entalhe e a preferência prefers-reduced-motion dos utilizadores sensíveis às animações.

Compatibilidade com o tema

O módulo visa os seletores CSS padrão do tema Classic e dos seus derivados: .product-add-to-cart, .add-to-cart, button[data-button-action="add-to-cart"] e form#add-to-cart-or-refresh. A grande maioria dos temas do mercado segue estas convenções.

Se o seu tema usar classes diferentes, há duas funções a adaptar no início do ficheiro views/js/dfstickyaddtocart.js: getMainBtn() (seletor do botão nativo) e getMainForm() (seletor do formulário de produto). São os dois únicos pontos de contacto com o seu tema.

Resolução de problemas

A barra não aparece

1. Confirme que o módulo está ativo na sua configuração e que a apresentação está ativa para o dispositivo testado (telemóvel ou computador).
2. Limpe a cache do PrestaShop (Parâmetros avançados > Desempenho) e recarregue a página com Ctrl+Shift+R.
3. Se a opção «Ocultar quando o botão principal está visível» estiver ativa, a barra só aparece depois de descer para lá do botão original: é o comportamento esperado.
4. Verifique na consola do navegador que nenhum erro de JavaScript de outro módulo está a bloquear a execução da página.

A adição ao carrinho não funciona

1. Abra a consola do navegador: o módulo regista aí os seus erros com o prefixo [dfsticky].
2. Verifique no separador Rede o pedido POST para o controlador de carrinho: o código HTTP e o corpo da resposta indicam a causa exata (rutura de stock, quantidade mínima, entre outras).
3. O módulo tolera os avisos do PHP em ambiente de desenvolvimento (extrai o JSON mesmo quando é precedido de avisos), mas continua a recomendar-se um ambiente de produção limpo.

A barra lateral sobrepõe-se ao cabeçalho do tema

Aumente o valor de Desvio superior em computador (px) na configuração, até a barra lateral se posicionar por baixo do seu cabeçalho fixo.

Perguntas frequentes técnicas

O módulo torna as páginas mais lentas?

Não. Os recursos (cerca de 7 KB de CSS e 12 KB de JavaScript) só são carregados no controlador product. Sem bibliotecas externas e sem listeners de deslocamento: a visibilidade é gerida pelo IntersectionObserver.

É compatível com multiloja?

Sim. Todos os valores são guardados pela classe Configuration do PrestaShop, com o contexto multiloja nativo: cada loja pode ter as suas próprias cores e definições.

Que hooks são utilizados?

actionFrontControllerSetMedia (registo dos recursos), displayFooterProduct (apresentação da marcação) e displayHeader (micro-CSS crítico contra o efeito de intermitência).

Os textos são traduzíveis?

Sim. Todas as cadeias passam pelo sistema de tradução do PrestaShop. O módulo é entregue em francês, inglês, espanhol e alemão; acrescente outros idiomas em Internacional > Traduções.

Registo de versões

1.0.3

• Análise tolerante das respostas do controlador de carrinho: o JSON é corretamente extraído mesmo quando é precedido de avisos do PHP (ambientes de desenvolvimento).
• Corpo do pedido em formato URL-encoded, igual à serialização nativa do tema, para máxima compatibilidade.
• Eliminação definitiva de qualquer acionamento programático do botão nativo: os dois botões passam a ser totalmente independentes.

1.0.2

• Eliminação da apresentação da janela de confirmação devolvida pelo controlador de carrinho, que podia deixar uma camada invisível a bloquear os cliques em algumas páginas. A confirmação passa pelo evento updateCart e pela marca no botão fixo.
• Limpeza defensiva das janelas órfãs no carregamento da página.

1.0.1

• Passagem à adição ao carrinho por pedido AJAX direto: o módulo deixa de alterar o formulário de produto e de depender do estado do DOM do tema.
• Referências do DOM resolvidas no momento, para resistir à substituição do formulário pelo motor de combinações.
• Reinicialização de segurança do indicador de carregamento.

1.0.0

• Versão inicial: barra fixa em telemóvel e computador, seletor compacto de variante, seletor de quantidade, personalização de cores, acessibilidade ARIA, multiloja e FR/EN/ES/DE.