DataFirefly Guia de Tamanhos: documentação

Visão geral

DataFirefly Guia de Tamanhos acrescenta à sua loja PrestaShop um sistema completo de guias de tamanhos modulares por categoria, fabricante ou produto, com tabelas de correspondência EU/US/UK/FR/JP, calculadora interativa de recomendação de tamanho, página SEO indexável dedicada por categoria e widget de feedback pós-compra com pontuação de desvio agregada.

O módulo destina-se a lojas de vestuário e calçado em que mais de 20% das devoluções estão ligadas a um problema de tamanho. Transforma essa fricção num percurso de compra tranquilizador: o cliente vê automaticamente a tabela certa, pode introduzir as suas medidas para obter uma recomendação personalizada, e a loja recolhe feedback qualificado que permite detetar os produtos com graduação incorreta.

Compatibilidade

• PrestaShop 8.0.x, 8.1.x, 8.2.x, 9.0.x
• PHP 8.1, 8.2, 8.3
• Multiloja (todas as atribuições são delimitadas por id_shop)
• Traduções FR/EN/ES/DE/IT/NL/PL prontas a usar
• Temas classic, hummingbird e temas personalizados (7 posições diferentes disponíveis)

Instalação

1. Carregue o ZIP dfsizeguide.zip em Módulos → Gestor de módulos → Carregar um módulo.
2. Clique em Instalar. As 13 tabelas predefinidas (vestuário de senhora e de homem, parte de cima e parte de baixo, vestidos, soutiens, calçado de senhora, de homem e de criança, vestuário de criança, luvas, chapéus, anéis, cintos) são criadas automaticamente em 7 idiomas, e é criada uma atribuição por defeito na tabela de vestuário de senhora.
3. Logo após a instalação, o separador “Guia de tamanhos” aparece em todas as páginas de produto sem configuração adicional.
4. Aceda a Módulos → DataFirefly Guia de Tamanhos → Configurar para ajustar as posições, a unidade por defeito e as funcionalidades ativas.

Conceitos-chave

O resolvedor de tabelas com 5 níveis

Quando um cliente chega a uma página de produto, o módulo procura a tabela a mostrar seguindo uma prioridade estrita:

1. Produto: se atribuiu explicitamente uma tabela a esse produto específico, é ela que ganha.
2. Categoria + Fabricante: caso contrário, a tabela atribuída ao par formado por uma categoria do produto e a sua marca. Por ser mais específico do que cada uma das duas dimensões isoladas, este nível sobrepõe-se aos dois seguintes. As categorias são percorridas da mais profunda para a mais geral.
3. Fabricante: caso contrário, a tabela atribuída à marca do produto.
4. Categoria: caso contrário, a primeira categoria do produto que tenha uma tabela, a começar pela mais profunda (respeito pela especificidade).
5. Por defeito: caso contrário, a tabela marcada como fallback global.

Esta hierarquia permite manter uma única tabela por marca ou por secção sem tocar nas páginas de produto individuais, mantendo a possibilidade de uma substituição cirúrgica.

Tipos de colunas

Cada tabela é composta por colunas tipadas:

• Coluna “tamanho”: um único valor textual por linha (S, M, 38, XL). Usada para as correspondências internacionais (EU, US, UK, FR, JP).
• Coluna “medida”: um intervalo numérico mín./máx. por linha (ex.: perímetro do peito 88–92 cm). Usada para indicar as medidas que correspondem a cada tamanho.

A calculadora interativa baseia-se exclusivamente nas colunas “medida” para determinar o tamanho recomendado.

Configuração

Posições na página de produto

O módulo disponibiliza 7 posições ativáveis individualmente em Configurar → Posições na página de produto:

• Separador de produto (ativo por defeito, recomendado): hook displayProductExtraContent, acrescenta um separador próprio ao lado de “Descrição” e “Detalhes”. Funciona na quase totalidade dos temas PS 1.7+.
• Por baixo do preço: hook displayProductPriceBlock (tipo after_price), apresenta uma ligação compacta logo abaixo do preço.
• Junto ao botão “Adicionar ao carrinho”: hook displayProductActions, apresenta um botão compacto.
• Por baixo das informações do produto: hook displayProductAdditionalInfo, apresenta um botão em destaque.
• No bloco de confiança: hook displayReassurance, integra-se visualmente com os outros argumentos (entrega, devoluções).
• Depois das imagens do produto: hook displayAfterProductThumbs, apresenta um botão compacto logo abaixo da galeria.
• No fundo da página de produto: hook displayFooterProduct, apresenta um botão em destaque no rodapé.

Pode ativar várias posições em paralelo: a janela modal do guia é instanciada uma única vez no DOM (anti-duplicação), e os botões adicionais abrem a mesma modal.

O separador de produto é a única posição que apresenta a tabela inline. As outras 6 posições apresentam um botão que abre a modal.

Parâmetros gerais

• Unidade por defeito: cm ou polegadas. O cliente pode alternar em tempo real, e a preferência é mantida no cálculo.
• Calculadora interativa: ativa a introdução das medidas e a recomendação de tamanho (ativa por defeito).
• Feedback dos clientes pós-compra: ativa o widget que pergunta ao cliente se o tamanho era adequado (ativo por defeito).
• Dados estruturados JSON-LD: ativa a injeção da marcação Schema.org para melhorar o SEO (ativa por defeito).
• Cor de destaque: cor dos botões, da unidade ativa e da linha realçada. A harmonizar com o seu tema; a tonalidade de hover é calculada automaticamente.
• Slug da página SEO: prefixo do URL das páginas de guia dedicadas (por defeito size-guide, a traduzir para guia-de-tamanhos se quiser um URL em português).

Criar e editar uma tabela

Menu Módulos → Guias de tamanhos → Tabelas. Clique em “Adicionar” para criar uma nova tabela, ou no ícone de lápis para editar uma tabela existente.

Campos da tabela

• Código interno: identificador técnico único (ex.: senhora-vestidos-2026). Usado nos URLs SEO e nos registos.
• Tipo: vestuário parte de cima, vestuário parte de baixo, vestido, calçado ou personalizado.
• Nome: etiqueta multilingue apresentada aos clientes (título do separador, título da modal, h1 da página SEO).
• Introdução (HTML): conteúdo multilingue apresentado acima da tabela.
• Instruções de medição (HTML): bloco expansível que explica como tirar cada medida.
• Rodapé (HTML): conteúdo multilingue apresentado abaixo da tabela (aviso, ligação para a política de devoluções, etc.).
• Meta title / Meta description: para a página SEO dedicada.
• Ativa: interruptor on/off. Uma tabela inativa nunca é servida, mesmo que esteja atribuída.

Editar a grelha

Por baixo do formulário da tabela, um editor visual permite construir a grelha:

1. Clique em Coluna tamanho para adicionar uma coluna textual. Preencha o código (ex.: eu, intl) e a etiqueta multilingue.
2. Clique em Coluna medida para adicionar uma coluna numérica. Preencha o código (ex.: chest_cm) e a unidade (cm, polegadas, mm).
3. Clique em Linha para adicionar uma linha. Preencha as células: texto simples para as colunas “tamanho”, valores mín./máx. para as colunas “medida”.
4. Clique em Guardar. A gravação é feita numa transação SQL atómica: ou é tudo guardado, ou nada é.

Duplicar uma tabela

O botão Duplicar da lista copia a tabela, as suas traduções, as suas colunas e respetivas etiquetas, as suas linhas e todas as células. Útil para derivar uma variante de uma tabela existente em vez de partir de uma grelha vazia.

Dois pontos a ter em conta. As atribuições não são copiadas: são únicas por alvo, pelo que duplicá-las roubaria os alvos à tabela de origem. E a cópia é criada inativa, para que não possa ser servida antes da sua revisão. O código interno é derivado automaticamente (senhora-cima passa a senhora-cima-copy), já que tem de permanecer único.

Atribuir uma tabela

Menu Módulos → Guias de tamanhos → Atribuições.

1. Escolha a tabela a atribuir na lista.
2. Escolha o tipo de alvo: Por defeito (fallback global), Categoria, Fabricante, Categoria + Fabricante ou Produto.
3. Consoante o tipo, aparece um segundo campo para escolher a categoria (numa árvore indentada), a marca (lista pendente) ou o ID do produto (introdução direta).
4. Clique em Adicionar / Atualizar. Se já existir uma atribuição para esse alvo, é substituída (upsert).

Todas as atribuições são delimitadas por loja em modo multiloja. Pode ter uma tabela diferente para a mesma categoria em duas lojas do mesmo grupo.

Modificar uma atribuição

O lápis no fim da linha recarrega a atribuição no formulário, com a sua tabela, o seu tipo de alvo e o seu alvo. Pode então mudar a tabela, mas também deslocar a atribuição para outro alvo ou transformar uma atribuição simples numa combinação categoria + fabricante. A linha em causa é realçada na lista, e um botão Cancelar permite sair sem alterar nada.

Deslocar uma atribuição para um alvo já ocupado por outra é recusado com uma mensagem explícita, uma vez que cada alvo só pode ter uma única tabela.

A calculadora de tamanho

A calculadora aparece por baixo da tabela, apenas se a tabela tiver pelo menos uma coluna “medida”.

Algoritmo de pontuação

O cliente introduz as suas medidas nos campos (um campo por coluna “medida”). Ao submeter:

1. Os valores são normalizados em centímetros (conversão automática se o utilizador escolheu polegadas: ×2,54).
2. Para cada linha da tabela, o módulo calcula uma pontuação: +2 pontos se a medida do cliente cair exatamente no intervalo mín./máx. da célula, +1 ponto se estiver próxima (a ±5% do intervalo), 0 pontos caso contrário.
3. A linha com a pontuação mais elevada é declarada vencedora.
4. Em caso de empate, é escolhida a linha cujos intervalos estão mais centrados nos valores do cliente.
5. O tamanho recomendado é extraído prioritariamente da coluna eu, depois fr, intl, uk, us, jp.

Feedback ao utilizador

A calculadora apresenta o tamanho recomendado com uma pontuação de confiança em percentagem, o top 3 das candidatas possíveis, cada uma com a sua pontuação, o realce da linha recomendada na tabela acima, e a lista das medidas que não correspondem a nenhuma linha (com aviso).

Feedback dos clientes pós-compra

Um widget “O tamanho era adequado?” aparece no fundo da página de produto com 5 opções: demasiado pequeno, um pouco pequeno, perfeito, um pouco grande, demasiado grande. É apresentado apenas nas seguintes condições:

• O cliente tem sessão iniciada (sessão ativa).
• O cliente comprou efetivamente esse produto (join com orders e order_detail, estado válido).
• O cliente ainda não deu a sua opinião sobre esse produto.

A verificação é feita integralmente do lado do servidor, sem risco de contorno.

Painel do feedback

Menu Módulos → Guias de tamanhos → Feedback dos clientes. Uma síntese acima da tabela mostra o número de respostas em cada categoria nos 5 níveis. Por baixo, a lista completa do feedback por produto com o ID do cliente, o tamanho comprado e a data.

Pontuação de desvio

Para cada produto com pelo menos 3 respostas, é calculada uma pontuação de desvio:

score = ((too_large × 2 + slightly_large) − (too_small × 2 + slightly_small)) / total

Uma pontuação positiva indica que o produto veste sistematicamente grande (a corrigir um tamanho para baixo). Uma pontuação negativa indica que veste pequeno (a corrigir um tamanho para cima). Uma pontuação próxima de zero indica uma boa graduação.

Página SEO dedicada

O módulo disponibiliza uma rota pública por categoria: /{slug}/{category-link-rewrite}, em que {slug} é o prefixo configurado (por defeito size-guide).

Exemplo: https://asualoja.pt/guia-de-tamanhos/vestidos-senhora

A página contém um caminho de navegação, o título h1 da tabela, a introdução, as instruções de medição e a tabela completa, a calculadora (se ativa), o rodapé HTML da tabela, e uma marcação JSON-LD WebPage Schema.org que ajuda o Google a perceber que a página é um guia prático.

As etiquetas meta title e meta description vêm dos campos SEO da tabela. Configure-as corretamente para captar pesquisas de cauda longa do tipo “guia de tamanhos vestidos senhora”.

Multilingue e multiloja

O módulo é multilingue ao nível das tabelas (nome, introdução, instruções, rodapé, meta), ao nível das etiquetas das colunas e ao nível das etiquetas de tradução dos URLs.

Em multiloja, cada atribuição (guia → alvo) é delimitada por id_shop. Pode assim mostrar a tabela A para a categoria “Calçado” na loja portuguesa e a tabela B para a mesma categoria na loja espanhola.

Estrutura técnica

Base de dados

8 tabelas com o prefixo dfsg_: dfsg_guide, dfsg_guide_lang, dfsg_column, dfsg_column_lang, dfsg_row, dfsg_cell, dfsg_assignment, dfsg_feedback. Todas as tabelas são removidas de forma limpa na desinstalação.

Hooks utilizados

• actionFrontControllerSetMedia: injeção de CSS/JS no front-office
• displayBackOfficeHeader: injeção de CSS/JS no back-office
• displayProductExtraContent: separador na página de produto (recomendado)
• displayProductPriceBlock, displayProductActions, displayProductAdditionalInfo, displayReassurance, displayAfterProductThumbs, displayFooterProduct: posições alternativas
• displayHeader: injeção de JSON-LD nas páginas de produto
• actionValidateOrder: gatilho para eventuais lembretes (v2)
• moduleRoutes: página SEO dedicada

FAQ

O guia não aparece na minha página de produto, o que fazer?

Verifique primeiro em Configurar → Posições na página de produto que pelo menos uma posição está ativa (Separador de produto por defeito). Se o seu tema personalizado não apresentar os hooks nativos do PrestaShop, ative várias posições em paralelo: pelo menos uma das 7 deverá funcionar. Verifique também que existe pelo menos uma tabela ativa e uma atribuição por defeito em Guias de tamanhos → Atribuições.

Posso importar tabelas a partir de um CSV?

Ainda não. O editor visual permite construir e modificar as tabelas em tempo real, coluna a coluna e linha a linha. A importação CSV está em estudo para uma versão posterior.

A calculadora funciona sem JavaScript?

Não, a calculadora é interativa e precisa de JavaScript para fazer a chamada AJAX ao servidor. Em contrapartida, a tabela estática é apresentada perfeitamente sem JS, o que preserva a acessibilidade e o SEO.

Existe risco de marcação JSON-LD duplicada?

Não. O hook displayHeader emite um único script JSON-LD por página de produto, e a página SEO dedicada tem a sua própria marcação WebPage distinta. O validador Schema.org do Google não assinala nenhum duplicado.

Compatível com a migração de PrestaShop 8 para 9?

Sim. O módulo declara ps_versions_compliancy de 8.0.0 a 9.99.99, utiliza as classes ObjectModel e HelperForm que continuam suportadas no PS 9, e não utiliza nenhuma API obsoleta.

Como apagar todos os dados do módulo?

A desinstalação através do Gestor de módulos remove todas as tabelas dfsg_* e todas as configurações DFSG_*. Não fica nenhum rasto na base de dados.

Suporte

E-mail: support@datafirefly.com. Resposta em 5 dias úteis, em francês ou em inglês.