How it works

This is the most important page in the docs. Read it before you start configuring — almost every “the plugin doesn’t work” question turns out to be a misunderstanding of the model described here.

The mental model: replacement, not assignment

Shopware natively supports one CMS layout per category, per product, per landing page. The plugin does not change that — it does not allow you to assign multiple layouts to one category. Instead, it acts as a replacement layer at request time:

1. Shopware loads the page and resolves the base layout the normal way — the one you set on the category (or product, or landing page).
2. The plugin looks at every layout that has rules assigned to it.
3. If a rule matches the current request (sales channel, customer, date, etc.), the plugin swaps the base layout for that alternative and renders the alternative instead.
4. If no rule matches, the base layout is rendered as usual.

The critical consequence: every category, product or landing page that you want the plugin to act on must already have a base layout assigned via the normal Shopware UI. If a category has no CMS layout, the plugin has nothing to replace, and the page will not render correctly.

Caution

Removing the layout from a category does not mean “let the plugin pick one”. It means “no layout”. The plugin replaces a base — it does not pick one from nothing.

The three knobs

For each of the three page kinds — Product, Category (navigation), Landing page — the plugin exposes three knobs:

1. Replacement mode — when is a base layout eligible for replacement?
2. Replaceable layouts — (only relevant for the “Assigned to replaceable layouts” mode) the explicit allow-list of base layouts that can be replaced.
3. Replacement types — what CMS page types are allowed to act as a replacement? (e.g. can a landingpage-type layout replace a product_list-type base?)

All three live in Settings → Extensions → Advanced Layouts Assigner.

Replacement modes

The mode controls whether the plugin tries to replace at all for a given base layout. The options differ slightly per page kind:

Page kind	Options
Product page	Without assigned layout · Assigned to replaceable layouts · Without assigned layout or assigned to replaceable layouts · All
Category page	With default layout · Assigned to replaceable layouts · All
Landing page	With default layout · Assigned to replaceable layouts · All

• Without assigned layout (Product page only) — replace only when the product itself has no specific layout (and Shopware would otherwise use the default).
• With default layout (Category / Landing page) — replace only when the page is using Shopware’s configured default layout (the one set in Settings → Shopping Experiences → Default layouts). Custom per-category layouts are not touched.
• Assigned to replaceable layouts — replace only when the base layout is one of the layouts you’ve explicitly listed in Replaceable layouts for … below the mode select.
• All — replace any base layout when a rule matches. Simplest, and the right choice when you want all category pages on a given sales channel to use a different layout. This is the mode the multi-sales-channel recipe recommends.

See Replacement modes for the full matrix and examples.

Replacement types

Even when a base layout is eligible for replacement, the plugin still has to decide which alternative layouts to consider. That decision is bounded by the Replacement types card at the bottom of the settings page. For each “incoming” page kind, you list the CMS page types that may be used as alternatives:

Incoming page	Default replacement types	Can be widened to
Product page	product_detail	page, landingpage, product_list
Shop page (page)	page	landingpage, product_list
Landing page	landingpage	page, product_list
Listing page (product_list)	product_list	page, landingpage

If the relevant entry is empty, the plugin will not look for any alternative at all for that page kind — even if rules match. The post-install routine seeds the obvious type as default for each kind, so you usually only widen this list when you want, say, a landing page layout to replace a listing.

Rules on the layout

The actual matching is done by rules assigned to the alternative layout, not on the category or product. To assign rules:

1. Content → Shopping Experiences → open layout
2. Layout assignment in the right sidebar
3. Assign layout button
4. Rules tab (added by this plugin, sits next to Categories / Products / Landing pages)
5. Pick the rules and Confirm.

A layout is a candidate replacement only if all its assigned rules match the current request (rules are AND-ed together). Within a single rule the standard Shopware container logic applies (AND containers, OR containers, etc.).

The matching loop, step by step

Concretely, when a customer hits a category page on a given sales channel:

1. Shopware loads the page and the base layout assigned to the category.
2. The plugin computes the replacement types allowed for that base type (e.g. for product_list → the Listing page entry under Replacement types).
3. The plugin checks the replacement mode for category pages:
   • With default layout → continue only if the base layout is Shopware’s default.
   • Assigned to replaceable layouts → continue only if the base layout is in the Replaceable layouts for category pages list.
   • All → continue.
   • Otherwise → return, no replacement.
4. The plugin loads every CMS page with rules assigned, ordered by rule.priority (lowest priority first, in line with Shopware’s own rule sorting). It walks them in pages of 100 (up to a hard cap — see Performance).
5. For each candidate, it evaluates all assigned rules against the current request (sales channel, navigation id, customer, date, etc.).
6. The first candidate whose rules all match is used. The plugin re-renders the layout for the page and hands it to Shopware.
7. If nothing matches, the base layout stays.

The same loop runs for products (via ProductPageLoadedEvent) and landing pages (via LandingPageLoadedEvent), with their respective replacement modes and types.

Three custom rule conditions

In addition to Shopware’s stock rule conditions, the plugin adds three of its own:

• Is homepage [P2Lab Layouts Assigner] — matches only on the sales channel’s navigation root (its homepage). See the warning about combining it with other conditions.
• Item in category [P2Lab Layouts Assigner] — matches when the product or category being viewed is in (or is itself) one of the listed categories.
• Item in category with children [P2Lab Layouts Assigner] — same as above but also matches descendant categories (uses the category path to walk the tree).

See Custom rule conditions for details.

Per-sales-channel configuration

Every setting in the plugin’s configuration form is per sales channel. Use the sales channel switcher at the top of Settings → Extensions → Advanced Layouts Assigner to maintain different replacement modes, replaceable layouts and replacement types per channel — falling back to the “All sales channels” scope for shared defaults.

This is how the plugin keeps the same category tree usable by two sales channels with completely different layout strategies.

Next: walk it through

Now that the model is clear, walk through a minimal example: First layout replacement.