Group Products as Variants for PrestaShop: Module Documentation (dfproductlinker)

The DF ProductLinker module (dfproductlinker) links separate product pages so they show as one item with a color, size or any other attribute selector. Each variant stays a full product with its own URL. It is the reverse of DF ProductSplitter, which splits a product with combinations into separate products.

Installation

1. Download the ZIP from your DataFirefly customer account.
2. In the back office, go to Modules > Module Manager > Upload a module and send the ZIP.
3. On installation, the module creates its tables and the Catalog > Linked variants tab.
4. Open the module configuration to check the selector position.

The module runs on PrestaShop 8.0 to 9.x with the same ZIP, in multistore and multilingual setups. Its strings ship in French, English, Spanish, German, Italian, Dutch, Polish and Portuguese.

How it works: groups and axes

A group brings several products together. An axis is a native PrestaShop attribute group, such as Color or Size: values, hex colors, textures and translations entered in Catalog > Attributes & Features are reused as they are. Each product of the group gets a value on each axis.

A product can belong to one group only. The products themselves are not modified: groups are stored in the module’s tables.

Creating a group

Go to Catalog > Linked variants then Add a group.

1. Enter the group name. It is used internally and as a fallback name in structured data.
2. Under Axes, click Add an axis. The module first suggests a color-type attribute group. For each axis, choose the display (automatic, color swatch, product photo thumbnail, text button, drop-down list) and the structured data property (color, size, material, pattern, or not declared).
3. Under Products of the group, search products by name, reference or ID. Arrow keys and Enter select a result. Products already in another group are greyed out.
4. For each product, check the value of each axis. It is pre-filled when it appears in the product name. A missing value is highlighted in orange, and the status line under the table shows how many products are affected, or whether two products share the same values.
5. Save. The module warns you if you leave the page with unsaved changes.

The order of the group rows is the order of the swatches on the shop. The Sort by attribute order button arranges the rows in the order set in the catalog, handy for sizes S, M, L, XL.

What shoppers see

On each page of the group, the selector shows the axis name and the current value, for example Color: Red, then the available values. On hover, the label shows the pointed value. The current value is outlined; the others are links to the matching page.

• With several axes, clicking a color opens the product that keeps the current size. If that combination does not exist, the module opens the closest variant, preferring a product in stock, and the swatch gets a dashed border.
• An out-of-stock variant is faded and struck through, or hidden depending on the setting.
• A color value with no hex code or texture is shown as text in a pill-shaped swatch.
• The selector also appears in the quick view of category pages, above the add-to-cart button.

Module settings

• Selector position: before the native combinations block (recommended), after that block, in the displayProductAdditionalInfo hook, or only in the displayDfProductLinker theme hook.
• CSS selector of the native combinations block: .product-variants, .product__variants by default. If nothing matches in your theme, the selector stays in the hook.
• Axis label, price of each variant (image and button modes), image format of thumbnails.
• Out-of-stock variants: faded or hidden.
• Accent color, swatch shape (round or square with rounded corners) and size. The medium size gives a 44 px touch area, recommended on mobile.
• Swatches in product listings, maximum number of swatches, and image change on hover.
• Single product per group, visibility of the other products and product shown: see the next section.
• Canonical URL of the variants and ProductGroup structured data: see the SEO section.

For custom placement, choose the theme hook position and add this line to your theme’s product template: {hook h='displayDfProductLinker' product=$product}.

Single product per group in category pages

This option shows a single card per group in category listings. The other products of the group switch to Search only visibility (or Nowhere, depending on the setting): their pages stay online with their URL, and the card swatches link to them.

• Product shown: the first of the group, or the first in stock. In the second case, the product shown is recalculated on every stock movement.
• The original visibility of each product is saved. It is restored when you disable the option, deactivate the group, remove a product from its group or uninstall the module.
• If you manually change the visibility of a hidden product, your value becomes the new original value.
• The Resynchronise the visibility button in the configuration reapplies the rule to every group. Use it if products were edited by an employee without permission on the module, since PrestaShop then does not trigger the module’s hooks.

SEO: structured data and canonical URL

The module adds a ProductGroup JSON-LD block with hasVariant and variesBy on each page of the group. Each variant is listed with its name, URL, reference, EAN13 when valid, image, value on each axis, the price shown to the shopper and its availability. The group name is taken from the product name without its values, in the visitor’s language. Disable the option if another module already outputs this block.

By default, each variant keeps a self-referencing canonical URL: each color is indexed on its own. If your color pages are near duplicates, the Canonical to the main product of the group option points the canonical of every variant to the main product, meaning the product shown in listings when the single product per group option is on, otherwise the first active product of the group.

Auto-grouping assistant

From the group list, click Auto-grouping assistant. It finds products that are the same item in several colors or sizes.

1. Choose a category, or the whole catalog.
2. Tick the attribute groups to detect, for example Color and Size. The values must exist as attribute values and appear in the product name.
3. Choose the rule: identical names once the values are removed, or references sharing the same root (TSH01-RED and TSH01-BLUE).
4. Click Preview, untick the groups to skip, then Create the selected groups.

Products already in a group are skipped, and the scan covers 5,000 products per run.

CSV import and export

The CSV import / export button opens the dedicated page. The export writes one line per product, in the same format as the import. Columns:

group_id;group_name;group_active;axes;product_id;product_reference;product_name;values
;T-shirt Basic;1;Color|Size;;TSH01-NAVY-M;;Color:Navy blue|Size:M

• A group is matched by group_id, otherwise by its exact name. Each group present in the file is replaced by its lines; groups absent from the file are not modified.
• A product is found by product_id, otherwise by product_reference, which must be unique in the catalog. product_name is informative.
• values holds Axis:Value pairs separated by |, using attribute group and value names in any language of the shop.
• The ; or , separator is detected automatically. UTF-8 file, 5 MB maximum.

The import runs in two steps: Analyze the file shows the groups created or replaced, the attribute values that will be created and every rejected line with its reason; Run the import then executes it. Two options: Move products that already belong to another group and Create missing attribute values (their color stays empty, to be completed in the catalog).

Back-office product page

In the Modules tab of the product page, the DF ProductLinker panel shows the product’s group and the value of each product of the group, with a link to edit the group. If the product is in no group, a link creates a group from this product.

Frequently asked questions

The selector does not appear on a page

Check that the group is active, that the page belongs to the group, that at least two products of the group are active and that at least one axis has two different values. If you chose the theme hook position, the displayDfProductLinker hook must be present in the product template.

The selector shows below the add-to-cart button

The CSS selector of the native combinations block matches no element in your theme. Enter the class of your theme’s combinations block in the configuration.

Swatches do not appear in listings

The option must be enabled, and the first axis of the group must be displayed as color swatches or photo thumbnails. Your theme must call the native displayProductListReviews hook in the product miniature, as the Classic theme does.

Can I combine the module with native combinations?

Yes. A common case: one product per color, each with size combinations. The module’s selector handles colors, the native block handles sizes.