Store Owner’s Guide – Beyond Basics

Scenarios ↑ Back to top

When setting up a kit-builder, you may often need to incorporate some kind of conditional business logic into the product configuration process.

The Composite type includes a framework that has been designed with this in mind: Scenarios. Out of the box, Scenarios make it possible to:

  • Introduce option dependencies.
  • Implement conditional flows.

How Scenarios Work ↑ Back to top

The effect of a Scenario is determined by two elements:

  1. The Configuration of the Scenario, which describes one or more Composite configuration states.
  2. The Actions enabled on the Scenario, which define what the Scenario should do with the defined state(s).

Option Dependencies

To tackle the problem of option dependencies, Scenarios follow a state-based approach, rather than a rule-based approach. Scenarios expect you to define all valid configurations of a Composite, and the underlying dependencies are enforced as a consequence of this process.

To define all valid configurations of a Composite using Scenarios:

  1. Use the Configuration section to define a valid state, and add as many Scenarios as needed to cover all valid states.
  2. Enable the Activate Options Action on the Scenarios you created.

Conditional Flows

To tackle the problem of conditional flows, Scenarios follow a rule-based approach. You choose one or more Component(s) to hide, and define when this action should be triggered.

To conditionally hide Components:

  1. Use the Configuration section to define when the Component(s) should be hidden.
  2. Enable the Hide Components Action and choose which Component(s) to hide.

Creating Scenarios

To create a Scenario:

  1. Go to Product Data > Scenarios.
  2. Click Add Scenario.
  3. Assign a Name and – optionally – a Description to the created Scenario. This information is only meant to facilitate Scenarios management and cannot be viewed by customers.
  4. Locate the Configuration section, then define a state by choosing Components and including or excluding product/variation selections. Choose is or is not using the drop-down of each Component to include or exclude the specified products/variations. To add all products and variations without selecting them one by one, choose Any Product or Variation.
  5. Tick an Action associated with the created Scenario: Activate Options or Hide Components.

Option Dependencies ↑ Back to top

The process of defining valid configuration states to enforce option dependencies can be better understood by looking at a practical example. The Full Frame DSLR Kit composite product:

The Full Frame DSLR Kit composite product.

The kit consists of the following Components:

  • Camera Body
  • Lens
  • Memory Card

In this example, the available Cameras only work with Lenses of the same manufacturer. Additionally, each Camera works with a specific Memory Card type. For simplicity, the Full Frame DSLR Kit used in this example includes only 2 Cameras, 6 Lenses and 2 Memory Cards.

Unless we define some Scenarios, customers will be able to select and purchase any Camera, Lens and Memory Card combination, including potentially incompatible parts. To ensure that only compatible products can be selected and purchased together, we’ll use Scenarios to define all Full Frame DSLR Kit configurations that customers are allowed to choose.

The available options be combined in 24 different Full Frame DSLR Kit ways. However, out of these 24 configurations, only 6 satisfy our compatibility requirements.

These 6 configurations are reduced to the following 2 Scenarios, since a single Scenario may represent multiple configuration states. In this case, the “Canon Group” Scenario includes 3 Lens options:

Valid configurations of the Full Frame DSLR Kit.

The effect of the created Scenarios is easier to understand by looking at what happens after choosing the Canon DSLR camera in the first step: The Nikon lens is unavailable in the next step:

Incompatible Lens options are greyed-out.

The same can be observed with Memory Card options.

Disabled product/variation selections are greyed-out by default. You can hide them with this snippet.
Optional Components have a No Selection state that can included or excluded in Scenarios.

In the Full Frame DSLR Kit example, No Selection has been included in the Memory Card Component in both Scenarios. This allows customers to skip the (optional) Memory Card Component without choosing an option.

Component Masking

You may have noticed that when including/excluding Component Options to define a set of configuration states in a Scenario, it is not necessary to do so for every Component. This partial definition of states is called Component Masking.

As the count of Components, Component Options, or dependencies increases, the process of defining valid configuration states with Scenarios can become quite tedious. To make things easier, the extension allows you to focus on fewer Components (and fewer dependency relationships) at a time, by allowing you to ignore some Components and define partial states.

Consider a Composite Product with the following simple structure:

Component Name Component Options
Component 1 Products X & Y
Component 2 Products A, B & C
Component 3 Products K & L

The following dependencies exist:

  • X is compatible with A and B.
  • Y is compatible with B and C.
  • A is compatible with K only.
  • B is compatible with L only.

Without Component Masking

One way to define all valid configuration states in this case is to:

  1. Make a list of all selection combinations: [ 2 selections in Component 1 ] x [ 3 selections in Component 2 ] x [ 2 selections in Component 3 ] = 12.
  2. Go through each state and determine whether it’s a valid one. If so, create a new Scenario and use the Configuration section to define the state.
  3. Tick the Enable Configuration action.

The result — 5 valid states:

  • X-A-K
  • X-B-L
  • Y-B-L
  • Y-C-K
  • Y-C-L

These 5 states can be merged into 3 Scenarios:

  • X-A-K
  • XY-B-L
  • Y-C-KL

With Component Masking

Component masking makes it possible to transform the dependencies into Scenarios in a more intuitive manner:

  • X-AB-masked
  • Y-BC-masked
  • masked-A-K
  • masked-B-L
Adding a large number of Scenarios manually can be impractical. For demanding applications, the Composite Products Filters API can be used to create custom Scenario definitions programmatically.
Note: We are unable to provide support for customizations under our Support Policy. For WordPress/WooCommerce customizations and integrations, we highly recommend Codeable, or a Certified WooExpert.

Conditional Flows ↑ Back to top

In addition to creating option dependencies, Scenarios can be used to conditionally disable and hide individual Components based on product/variation selections.

This allows you to create multiple configuration flows by introducing or removing Components as product/variation selections are being made.


To conditionally hide a Component:

  1. Go to Product Data > Scenarios.
  2. Click Add Scenario.
  3. Assign a Name and/or Description to the created Scenario.
  4. Define selection matching conditions in the Configuration section by including or excluding products/variations. Choose is or is not in the drop-down associated with each Component to include or exclude the specified products/variations. To add all products and variations without selecting them one by one, choose Any Product or Variation.
  5. Tick the Hide Components action.
  6. Choose one or more Components to hide.

Selecting Multiple Component Options ↑ Back to top

Out of the box, it is only possible to select one option under each Component.

However, it’s possible to choose multiple products under a single Component by using Product Bundles in combination with Composite Products.

The concept is easier to understand with an example based on the Full Frame DSLR Kit. Our objective is to offer the following optional products in an additional Accessories Component:

  • Backpack
  • Lens Cover
  • Dust

Customers will be able to choose any combination of accessories, without being limited to a single selection.

Accessories Component with multiple optional items.

The Accessories component can be created by following these steps:

  1. Using the Product Bundles extension, create a new product bundle and add the products that you want to appear in the Accessories Component inside this bundle, ensuring they are all Optional. Then, set its Catalog visibility status to Hidden. For guidance, refer to the Product Bundles documentation.
  2. Create the Accessories Component and add this newly created bundle as its only Component Option.
  3. In the Advanced Settings section of the Accessories Component, locate the Selected Option group and check the Hide Title and Hide Thumbnail options.

Remember that the visibility of Bundle container/parent cart/order items in customer-facing templates is controlled by the Item Grouping option. When a Bundle is purchased in a Component and Item Grouping > None is selected, the cart/order item associated with the Component (which doubles as the container/parent cart/order item of the Bundle) remains visible. However, the title of the Product Bundle is hidden. The result — bundled products appear to be grouped by the Component and the existence of the Product Bundle is transperent to customers.

Item Grouping: Grouped (left) vs None (right).
When using this technique to offer multiple optional products under a single Component, keep in mind that some Composite Products features will be unavailable. In the previous example:

  • The products listed under the Accessories Component cannot be paginated, sorted, or filtered.
  • You cannot use Scenarios to make the products listed under the Accessories Component conditionally available.

Questions & Support ↑ Back to top

Have a question? Please fill out this pre-sales form.
Already purchased and need assistance? Get in touch with us via the Help Desk!

WooCommerce - the most customizable eCommerce platform for building your online business.

Back to the top