README

A standalone Magento 2 module that links independent products together and renders a variation switcher on Luma/Blank-based Product Detail Pages. Every linked item remains a standalone catalog product with its own PDP and native product-type behavior.

Designed for Luma/Blank-based storefronts — uses Magento layout XML, PHTML, native Swatches APIs, and module LESS. It does not depend on studioraz/magento2-simple-product-link.

This package is a standalone alternative to the Hyvä-oriented module, not a companion package. Do not enable both implementations in the same Magento installation because they intentionally use the same product attribute, admin route, event prefix, and database tables.

Features
How It Works
Requirements
Installation
Configuration
- 1. Create a Link Rule
- 2. Assign Products to a Group
Frontend Behavior
Cache Invalidation
License

Features

Group independent products via a shared text attribute. Simple, virtual, downloadable, configurable, grouped, and bundle products are supported.
Admin-managed Link Rules with variation attributes, catalog-rule conditions, and priority.
Multiple variation attributes per rule (e.g., Color + Size) with drag-and-drop ordering.
Color, image, and text swatches using Magento's native Swatches module.
Out-of-stock indicators — diagonal strikethrough + tooltip, respects catalog display setting.
Zero theme modifications — layout XML inserts the variant switcher after the product price.
Group-aware cache invalidation — rule changes, product group changes, and stock updates automatically purge the correct FPC entries.

How It Works

Products are grouped by assigning the same value to the simple_product_group attribute.
An admin-defined Link Rule specifies which variation attributes to display and which products the rule applies to (via catalog-rule conditions).
On the storefront, the module's plugin appends a variant switcher block immediately after the price. Each variant is a clickable link to the sibling product's PDP.

For composite products, the switcher links whole parent products. It does not replace Magento's configurable, grouped, downloadable, or bundle option renderers and does not carry selected child options between PDPs.

Requirements

Requirement	Version / Notes
Magento	2.4.x
PHP	Per Magento 2.4 requirements
Theme	Magento Luma/Blank or a compatible child theme
`SR_Base` module	Must be installed and enabled

Installation

Via Composer (private repository)

composer require studioraz/magento2-simple-product-link-luma-theme
bin/magento module:enable SR_SimpleProductLinkLumaTheme
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento cache:flush

Manual installation

Copy the module to app/code/SR/SimpleProductLinkLumaTheme/.
Run:

bin/magento module:enable SR_SimpleProductLinkLumaTheme
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento cache:flush

The data patch will automatically create the simple_product_group product attribute on first install.

Configuration

1. Create a Link Rule

Navigate to Admin → Studio Raz → Simple Product Link → Link Rules and click Add New Rule.

Field	Description
Name	Human-readable rule name (required).
Description	Optional notes about the rule's purpose.
Active	Enable or disable the rule.
Variation Attributes	One or more `select`-type attributes (e.g., Color, Size). Drag-and-drop to set display order.
Priority	Integer — higher value = higher priority. When multiple rules match a product, only the highest-priority rule is applied.
Conditions	Standard Magento catalog-rule conditions to target specific products. Leave empty to match all products.

2. Assign Products to a Group

Open a product in Admin → Catalog → Products.
Set the Simple Product Group attribute to a shared group identifier (any arbitrary string, e.g., blue-widget-family).
Repeat for every sibling product in the group. Ensure each product has a different value for the variation attribute(s) defined in the matching rule.

Frontend Behavior

Display Rules

Condition	Result
Product has no `simple_product_group` value	No switcher displayed
Group has only 1 product	No switcher displayed
An attribute has only 1 unique option across group products	That attribute row is hidden
Product type is simple, virtual, downloadable, configurable, grouped, or bundle	Product can participate in the switcher
No active rule matches the product	No switcher displayed

When conditions are met, the switcher renders after the price in product.info.main, with one row per variation attribute.

Swatch Support

Type	Rendering
Color swatch	Colored square with the configured background color.
Image swatch	Square with the swatch image as background.
Text swatch	Text label inside a bordered option.
Regular select	Linked-product thumbnail with the option label exposed through accessible text and tooltip.

Out-of-Stock Handling

Behavior depends on Stores → Configuration → Catalog → Inventory → Display Out of Stock Products:

Yes — The option is visible but not clickable (rendered as <span>). It shows reduced opacity, a diagonal strikethrough line, and a tooltip reading "Option Label – Out of Stock".
No — The option is completely hidden.

Sorting & Display Order

What is sorted	Controlled by	Where to change
Attribute group order (e.g., Color row above Size row)	Variation Attributes sort order in the Link Rule	Admin → Link Rules → Drag-and-drop
Options within a group (e.g., Red, Blue, Green)	Attribute option sort order	Admin → Stores → Attributes → Product → [Attribute] → Manage Options

Cache Invalidation

The module implements a three-layer cache strategy:

Rule changes (create / update / delete) — Flushes the full-page cache entirely via observers on studioraz_simpleproductlink_rule_save_after and _delete_after.
Product group changes — When a product's simple_product_group value is modified, all sibling products in both the old and new groups are invalidated.
Composite stock changes — When a child product's stock changes, the resolver also includes its configurable, grouped, or bundle parents and invalidates the linked groups assigned to those parents.
Cache tag propagation — The switcher block exposes a group cache tag, so Varnish / FPC invalidation can purge related variant pages together.

Troubleshooting

Symptom	Possible Cause	Solution
Variant switcher does not appear	Product has no `simple_product_group` value	Set the attribute on the product and its siblings
Variant switcher does not appear	Group contains only 1 product	Add at least one more sibling with the same group value
Variant switcher does not appear	No active Link Rule matches	Verify rule is active and its conditions include the product
Stale switcher after rule change	FPC not flushed	Flush cache: `bin/magento cache:flush full_page`
Attribute row missing	Only 1 unique option exists in the group for that attribute	Ensure siblings have different values for the variation attribute
Swatches show as text labels	Swatch data not configured	Configure swatches under Admin → Stores → Attributes → Product → [Attribute] → Manage Options

studioraz / magento2-simple-product-link-luma-theme

Maintainers

Package info

Statistics

Security