DataFirefly Size Guide — Documentation

Overview

DataFirefly Size Guide adds a complete size guide system to your PrestaShop shop, with charts assignable by category, manufacturer, brand × category combo or product, EU/US/UK/FR/JP conversion tables, an interactive size calculator, an indexable SEO page per category, and a post-purchase feedback widget with an aggregated bias score.

The module targets apparel and footwear shops where more than 20% of returns come down to a size problem. It turns that friction into a reassuring buying journey: the customer sees the right chart automatically, can enter their measurements for a personalised recommendation, and you collect qualified feedback that reveals badly graded products.

Compatibility

• PrestaShop 8.0.x, 8.1.x, 8.2.x, 9.0.x
• PHP 8.1, 8.2, 8.3
• Multistore (every assignment is scoped by id_shop)
• Polylang FR/EN/ES/DE/IT/NL/PL out of the box
• Classic, Hummingbird and custom themes (8 different positions available)

Installation

1. Upload the dfsizeguide.zip archive from Modules → Module Manager → Upload a module.
2. Click Install. The 13 preset charts (women’s and men’s tops and bottoms, dresses, bras, women’s, men’s and kids’ shoes, kids’ clothing, gloves, hats, rings, belts) are created automatically in 7 languages, and a default assignment is created on the women’s tops chart.
3. As soon as the install finishes, the “Size guide” tab appears on every product page with no further configuration.
4. Go to Modules → DataFirefly Size Guide → Configure to adjust the positions, the default unit, the calculator tolerance and the features you want enabled.

Key concepts

The five-tier chart resolver

When a customer lands on a product page, the module looks for the chart to display by walking a strict priority:

1. Product — if you explicitly assigned a chart to that exact product, it wins.
2. Category + Manufacturer — otherwise, the chart assigned to the pair formed by one of the product’s categories and its brand. More specific than either dimension alone, so this tier beats the next two. Categories are walked from the deepest to the most general.
3. Manufacturer — otherwise, the chart assigned to the product’s brand.
4. Category — otherwise, the first of the product’s categories that has a chart, starting with the deepest one.
5. Default — otherwise, the chart marked as the global fallback.

This hierarchy lets you maintain a single chart per brand or per department without touching individual product pages, while keeping surgical overrides available.

Narrowing a rule: exclusions and strict combos

The Category and Default tiers apply to every brand by nature. Two independent mechanisms narrow them.

Exclusions carve specific brands or products out of a rule’s scope. An excluded product skips that rule and keeps falling through: parent category, then the global fallback, then no guide at all. Each target type accepts what makes sense for it:

• Default and Category — brand and product exclusions
• Manufacturer and Category + Manufacturer — product exclusions
• Product — none, the target already names one product

The Strict category + manufacturer combos setting, in the module configuration, works differently: as soon as a category holds at least one combo, it becomes exclusive to the brands that have one there. Products of the other brands in that category inherit neither the category rule nor the default guide. A chart assigned explicitly to their brand still applies, since that assignment is deliberate, and a product with no manufacturer keeps the ordinary fallbacks. The setting is off by default.

Column types

Every chart is built from typed columns:

• “Size” column — one text value per row (S, M, 38, XL). Used for international conversions (EU, US, UK, FR, JP).
• “Measurement” column — a numeric min/max range per row (e.g. bust 88–92 cm). Used to state which body measurements match each size.

The interactive calculator works exclusively from the “measurement” columns.

Grouped columns: one measurement, several variants

Some charts describe the same measurement across several columns. On a bra chart, the cup B, C, D and E columns are not four measurements: it is one bust circumference in variants. Asking the customer for all four makes no sense, she only has one.

By giving those columns the same group code in the editor, the calculator shows a single field for the group. The answer then combines the row’s size with the variant label of the matching column: 4B instead of 4. One measurement can land in several variants, in which case all of them are offered.

Three fields per measurement column, shown in the editor on measurement columns only:

• Group — the code shared by the columns describing the same measurement (e.g. bust). Left empty, the column stays independent.
• Variant — the suffix appended to the size in the result (e.g. B, C, D).
• Group label — the wording of the shared calculator field (e.g. “Bust”). Fill it in on one column of the group.

Charts with no grouping keep the original behaviour exactly: one field per column, one answer per row.

Configuration

Positions on the product page

The module exposes 8 individually switchable positions in Configure → Product page positions:

• Product tab (on by default, recommended) — displayProductExtraContent hook, adds a clean tab next to “Description” and “Details”. Works on nearly every PS 1.7+ theme.
• Under price — displayProductPriceBlock hook (after_price type), renders a compact link right below the price.
• Near the “Add to cart” button — displayProductActions hook, renders a compact button.
• Under product info — displayProductAdditionalInfo hook, renders a prominent button.
• In the reassurance block — displayReassurance hook, blends in with your other selling points (shipping, returns).
• After product images — displayAfterProductThumbs hook, renders a compact button right below the gallery.
• Product page footer — displayFooterProduct hook, renders a prominent button at the bottom.
• Quick view — shows the guide in the quick view popup, at whichever of the positions above your theme renders there.

You can enable several positions at once: the guide modal is instantiated only once in the DOM, and the extra buttons open that same modal.

The product tab is the only position that renders the chart inline. The others render a button that opens the modal.

General settings

• Default unit — cm or inches. The customer can switch on the fly, and the preference carries into the calculation.
• Interactive calculator — enables measurement entry and the size recommendation (on by default).
• Close sizes tolerance (cm) — after the sizes that fit exactly, the calculator lists the neighbouring ones within this margin. 0 hides that second list, and is the default. Overridable chart by chart.
• Strict category + manufacturer combos — see above. Off by default.
• Post-purchase customer feedback — enables the widget asking the customer whether the size was right (on by default).
• JSON-LD structured data — enables the Schema.org markup injection (on by default).
• Accent colour — colour of the buttons, the active unit and the highlighted row. Match it to your theme; the hover shade is computed automatically.
• SEO page slug — URL prefix for the dedicated guide pages (size-guide by default).

Creating and editing a chart

Menu Modules → Size guides → Charts. Click “Add” for a new chart, or the pencil icon to edit an existing one.

Chart fields

• Internal code — unique technical identifier (e.g. women-dresses-2026). Used in SEO URLs and logs.
• Type — textile top, textile bottom, dress, bra, shoes, kids, gloves, hats, rings, belts or custom.
• Name — multilingual label shown to customers (tab title, modal title, SEO page h1).
• Introduction (HTML) — multilingual content displayed above the chart.
• Measurement instructions (HTML) — collapsible box explaining how to take each measurement.
• Footer (HTML) — multilingual content displayed below the chart (disclaimer, link to the returns policy, and so on).
• Meta title / Meta description — for the dedicated SEO page.
• Close sizes tolerance (cm) — overrides the shop setting for this chart only. Leave it empty to inherit, enter 0 to hide the close sizes list here. This is the field to use when the same shop sells bras and shoes: 3 cm is a neighbourhood on the former and four full sizes on the latter.
• Active — on/off switch. An inactive chart is never served, even when assigned.

Editing the table

Below the chart form, a visual editor builds the table:

1. Click Size column to add a text column. Fill in the code (e.g. eu, intl) and the multilingual label.
2. Click Measurement column to add a numeric column. Fill in the code (e.g. chest_cm) and the unit (cm, inch, mm). Three extra fields appear on this column type: group, variant and group label, described above.
3. Click Row to add a row. Fill the cells: plain text for “size” columns, min/max values for “measurement” columns.
4. Click Save. The save runs inside an atomic SQL transaction — either everything is written, or nothing is.

Duplicating a chart

The Duplicate button on the list copies the chart, its translations, its columns and their labels, its rows and every cell. Useful to derive a variant of an existing chart rather than starting from an empty table.

Two things to know. Assignments are not copied: they are unique per target, so duplicating them would steal the original chart’s targets. And the copy is created inactive, so it cannot be served before you have reviewed it. The internal code is derived automatically (women-top becomes women-top-copy) since it has to stay unique.

Assigning a chart

Menu Modules → Size guides → Assignments.

1. Pick the chart to assign from the list.
2. Pick the target type: Default (global fallback), Category, Manufacturer, Category + Manufacturer, or Product.
3. Depending on the type, a second field appears for the category (in an indented tree), the brand (dropdown) or the product ID (direct entry).
4. Fill in the exclusions if needed, described just below.
5. Click Add / Update. If an assignment already exists for that target, it is overwritten (upsert).

Every assignment is scoped per shop in multistore. You can have a different chart for the same category on two shops of the same group.

Excluding brands or products

Two fields appear depending on the chosen target type:

• Brands to exclude — multi-select list, offered on the Category and Default targets. Ctrl or Cmd to select several, click again to deselect.
• Products to exclude — comma-separated IDs (e.g. 12, 45, 78), offered on every target except Product.

Exclusions appear in the assignment table, resolved to names, under the target they belong to. They are deleted along with the assignment, and dropped when you switch the rule to a type that is already specific to a brand or a product.

A product excluded from a combo does not trigger strict mode: excluding means “keep falling through”, so the exclusion cannot be the very thing that blocks the fallbacks.

Editing an assignment

The pencil at the end of the row reloads the assignment into the form, with its chart, target type, target and exclusions. You can then change the chart, but also move the assignment to another target or turn a plain assignment into a category + manufacturer combo. The row is highlighted in the list, and a Cancel button lets you back out without changing anything.

Moving an assignment onto a target another one already holds is refused with an explicit message, since each target can carry only one chart.

The size calculator

The calculator appears below the chart, only when the chart has at least one “measurement” column.

How the recommendation is built

The customer enters their measurements, one field per measurement group in the chart. On submit:

1. Values are normalised to centimetres (converted automatically when inches were selected: ×2.54).
2. The module first keeps the exact fits: rows whose every range contains the value entered for the matching group. When a group holds several variants, each matching variant yields a separate result.
3. It then keeps the close sizes, widening each range by the tolerance in both directions and dropping whatever the first group already listed. This second group only appears when the tolerance is above 0.
4. If nothing matches, tolerance included, the module points at the least distant row rather than answering nothing.
5. The size is taken first from the column matching the shop language, then eu, fr, intl, uk, us, jp.

Example

A bra chart with one underbust column and four grouped cup columns. The customer enters 87 cm underbust and 101 cm bust, and the chart is set to a 3 cm tolerance.

• Exact fits: 4B and 4C. 87 falls inside row 4’s 83–87 range, and 101 falls inside both cup B (99–101) and cup C (101–103) on that row.
• Close sizes: 5B and 4D. With 3 cm of margin, 87 reaches row 5 (88–92) whose cup B is 104–106, and 101 reaches row 4’s cup D (103–105).

What the customer sees

Exact fits render as filled pills, close sizes as outlined pills with the margin applied. Matching rows are highlighted in the chart above, and fields left empty are reported.

Post-purchase customer feedback

A “Was the size right?” widget appears at the bottom of the product page with 5 choices: too small, slightly small, perfect, slightly large, too large. It is rendered only when:

• The customer is logged in (active session).
• The customer actually bought that product (joined against orders and order_detail, valid status).
• The customer has not already given feedback on that product.

The gating is entirely server-side, with no way around it.

Feedback dashboard

Menu Modules → Size guides → Customer feedback. A summary above the table shows how many answers fall in each of the 5 levels. Below it, the full list of feedback per product with the customer ID, the size purchased and the date.

Bias score

For every product with at least 3 pieces of feedback, a bias score is computed:

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

A positive score means the product consistently runs large (shift it one notch down). A negative score means it runs small (shift it one notch up). A score near zero means the grading is sound.

Dedicated SEO page

The module exposes a public route per category: /{slug}/{category-link-rewrite}, where {slug} is the configured prefix (size-guide by default).

Example: https://yourshop.com/size-guide/women-dresses

The page carries a breadcrumb, the chart’s h1 title, the introduction, the measuring instructions and the full table, the calculator (when enabled), the chart’s HTML footer, and JSON-LD WebPage Schema.org markup that helps Google understand the page is a practical guide.

Meta title and meta description come from the chart’s SEO fields. Fill them in properly to capture long-tail searches such as “women’s dress size guide”.

Multilingual and multistore

The module is multilingual at chart level (name, intro, instructions, footer, meta), at column and group label level, and at Polylang label level for the URLs.

In multistore, each assignment (guide → target) is scoped by id_shop. You can therefore serve chart A for the “Shoes” category on the French shop, and chart B for the same category on the German one.

Technical structure

Database

9 tables prefixed dfsg_: dfsg_guide, dfsg_guide_lang, dfsg_column, dfsg_column_lang, dfsg_row, dfsg_cell, dfsg_assignment, dfsg_assignment_exclusion, dfsg_feedback. Every table is dropped cleanly on uninstall.

Hooks used

• actionFrontControllerSetMedia — front-end CSS/JS injection
• displayBackOfficeHeader — admin CSS/JS injection
• displayProductExtraContent — product page tab (recommended)
• displayProductPriceBlock, displayProductActions, displayProductAdditionalInfo, displayReassurance, displayAfterProductThumbs, displayFooterProduct — alternative positions
• displayHeader — JSON-LD injection on product pages
• actionValidateOrder — trigger for future follow-ups (v2)
• moduleRoutes — dedicated SEO page

FAQ

The guide does not show on my product page, what should I check?

First check in Configure → Product page positions that at least one position is enabled (Product tab by default). If your custom theme does not render PrestaShop’s native hooks, enable several positions in parallel: at least one of the seven should work. Also check that there is at least one active chart and a default assignment in Size guides → Assignments. If strict combo mode is on, check finally that the product does not belong to a category holding combos that do not cover its brand.

I created a brand × category combo but the other brands still show a chart

That is the normal behaviour of the resolution chain: a combo gives one brand priority, it does not exclude the others, which keep falling through to the category rule and then to the default guide created at install. To make the category exclusive to the brands that have a combo there, enable Strict category + manufacturer combos in the module configuration. To leave out only two or three brands, keep the category rule and fill in Brands to exclude instead.

The guide will not open from the quick view

Check that the Quick view position is enabled in the configuration: when it is not, the module deliberately loads neither its stylesheet nor its script on listing pages, so the button cannot work from a quick view. Then check that at least one position your quick view renders is active: themes do not all render the same hooks there, and the product tab is never rendered in a quick view.

Can charts be imported from a CSV?

Not yet. The visual editor builds and edits charts on the fly, column by column and row by row. CSV import is under consideration for a later version.

Does the calculator work without JavaScript?

No, the calculator is interactive and needs JavaScript for the AJAX call to the server. The static chart, however, renders perfectly without JS, which preserves accessibility and indexing.

Is there a risk of duplicate JSON-LD markup?

No. The displayHeader hook emits a single JSON-LD script per product page, and the dedicated SEO page has its own separate WebPage markup. Google’s Schema.org validator reports no duplication.

Compatible with the PrestaShop 8 to 9 migration?

Yes. The module declares ps_versions_compliancy from 8.0.0 to 9.99.99, uses the ObjectModel and HelperForm classes that remain supported in PS 9, and relies on no deprecated API.

How do I purge all module data?

Uninstalling through the Module Manager drops every dfsg_* table and every DFSG_* configuration entry. Nothing is left in the database.

Support

Email: support@datafirefly.com. Answer within 5 business days, in French or English.