1. CPQ
  2. How-To Articles
  3. Configurator Design

How to create a nested configurator

Article last updated:

Nested configurators are the best way to create complex configurators: they're powerful, but modular and manageable at the same time.  This walkthrough will guide you step by step in creating a nested configurator.  You'll see the entire process below, from sketching out your initial design to sharing data between configurators.  This walkthrough is also the foundation for learning about other nesting features, like nesting pricing rules and nesting 3D scenes.

Prerequisites

Step-by-step guide

We'll follow these steps in creating our nested configurator:


Design your Application

A few minutes of planning can save hours of work later.  Here, we'll review a hypothetical business need and how we can create a configurator to answer that need.  

For our example, we need to create a configurator that helps people configure their own building.  It can be a small retail store or a high-rise office tower... or anything in between.  The requirements are:

Create your Child (Nested) configurator

  1. A building fills a standard piece of land (say, a city block)
  2. That building can have one or more floors.
  3. Each floor can be Residential (homes where people live), Commercial (offices where they work), or Retail (stores where they shop).
  4. No floor can be "mixed use" – it's completely one type.
  5. A building, however, can be "mixed use" – where different floors have different uses.  For example, the first floor may be Retail, and the second and third are Residential.
  6. All floors have the same shipping address (the building address).  However, each floor has it's own mailing address (the shipping address, plus the floor number).

Given these requirements, a nested configurator setup is ideal.  The key is the phrase "one or more" – if you have a business need where you don't know the quantity or types of a sub-component, creating a nested configurator for that sub-component is often a good idea.  Here, we will create a parent "building" configurator, which can have one or more "floor" nested configurators.

Configurator 1: Parent "Building"

  • Stores information that is the same across all floors (for example, street address).
  • Can aggregate information about its children, and store that for use (for example, a count of how many floors it has to calculate how tall it is).
  • Can write data onto the children that they don't know on their own.  For example, a floor on its own doesn't know if it's street level or if it's the penthouse.  That context is provided by the parent building.  The building configurator can write onto each floor configurator a "floor number", for example.


Configurator 2: Nested Child "Floor"

  • Stores information which is unique to each floor (for example, what type of floor it is (Residential, Commercial, or Retail)
  • Can receive data from the parent, like floor number, to calculate other unique information (like the mailing address).

It's a good idea to start with the smallest component, and build up from there.  Often you may wonder where to put a certain property of your overall configuration: is this a property of the parent or a property of the child?  By creating your child first, you can get the details out of the way and then build up.

  1. Create a new configurator called "Building Floor".
  2. Give it a field "Use", data type "Text", control "Select", and enter the three uses as select options from our requirements.



Create your Parent configurator

  1. Create a new configurator called "Building".
  2. Rename the default page to "Floors".  Rename the default group underneath it to "Floor Information"
  3. Create a field "Floor Count", data type "Number", control "Slider", default value 1, precision 0, step 1, constrain value, and set the minimum to 1 and maximum to whatever you like!  (We'll use a max of 10.)


Relate the two configurators

We have the basics to get started.  To nest one configurator inside another, open the parent configurator. 

  1. Open the "Building" configurator, and click the "Referenced Configurators" section to make the "+" icon appear. 
  2. Click it to add a new reference. 
  3. For the "Configurator Type", enter the "Building Floor" configurator you've just created.  Since we want to add this child configurator through rules, not through the user's clicks, we will leave the "User can add..." field blank. 
  4. Note that "nest scenes" and "nest price object" are both left checked.  We won't use these features here, but it sets the groundwork for using these features in the future.

  5. We want to make it easy for our user to adjust the number of floors.  Instead of the user adding and removing the nested floor configurators manually, they will simply slide the "Floor Count" slider, and our Value rule will ensure the number of nested children matches the count they specify.

    In the parent "Building" configurator, create a new Value Rule, call it "Maintain Nested Floors", with this code.  (You'll use the "text", "concatenate", and "cast" blocks as you set the "myName" variable.)



    The value rule first adds any floors if they don't exist, stamping a name on each when it is created.  Then it deletes any extra floors that may by lying around (for example, if we drag the slider from 10 down to 3, we need to delete the 7 unwanted floors).


Test your design!  Launch the parent "Building" configurator, and you should see one "Floor" configurator nested underneath the "Floor" page. Drag the Floor Count larger to see more nested configurators appear.

Help

Did you see an error?  Remember to set the default value of "Floor Count" to 1 as described above.

Pass data between your configurators

We've seen how a parent can name the children when they are created.  But other information can be passed between parent and child, too.  With nested configurators, the parent does most of the passing of information.  A Snap rule on the parent does the work of looping through all the child configurators –  to either write data onto each one, or to read information from them to write back to the parent.  Let's do both here.

Gather data from all the children, to write to the parent

Each building should know its own height.  Since this information is based on the nested Floors, loop through the children to determine the building height.

  1. In the "Building Floor" configurator, add a new "Floor Height" number field, with a numberbox control.  Set the "enabled" of that field to false, so it won't get accidentally edited.  (We're measuring our floor height in meters... As a nice extra, you can optionally add a suffix to that field, to help your users understand the unit of measure.)
  2. In the "Building Floor" configurator, add a new Value rule, called "Calculate Floor Height", with the following Snap code:
  3. Test your code.  Launch your "Building Floor" configurator (you can launch it directly, without the parent configurator), and see the floor height change as you select different uses.  This is best practice: each child configurator should be able to be launched on its own without errors.

    Now that each floor child has a height, teach the building parent how to gather that information into the overall building height.   

  4. In the "Building" configurator, add a new "Building Height" number field, with a numberbox control.  Set the "enabled" of that field to false, so it won't get accidentally edited.
  5. In the "Building" configurator, add a new Value rule, called "Calculate Building Height", with the following Snap code:
  6. Test your code again.  This time, launch your "Building" configurator, and ensure the building height changes with each new floor added, or floor use adjusted:

Gather data from the parent, to write to the children

You can also write information from the parent to the child.  Let's deliver mail to our building.  While the building has one shipping address, each floor has its own mailing address.  The floor on its own doesn't know any of this information (where it is in the city, or what floor it is in the building), so the parent configurator must write this onto each child.

  1. On the "Building Floor" Configurator, add a "Mailing Address" field as shown below.  

    Note that we put some warning text into the default value.  Since we want our child configurators to be able to run on their own, but the data in this field comes from the parent configurator, it's a good idea to fill such fields with default data, or a warning message.  In this way, when the nested configurator is launched on its own, it's clear to everyone why the field is blank.  Furthermore, if you see this warning in your final design, you know you have a problem and how to fix it.

  2. In the "Building" Configurator, add a "Shipping Address" Multiline Textbox field.  Set the default value to "1234 Main Street, Anytown, USA".

  3. Again in the "Building" Configurator, create a new Value rule "Set Nested Addresses" with the following code:



  4. Test your code again.  This time, launch your "Building" configurator, and ensure the mailing address on each child floor is set by the parent configurator:


You're done!  You now can create buildings of various heights, each with a different set of floors.


Optimization

Did you notice that now we have two value rules in the parent, both of which are looping through the nested children?  In simpler applications, it's fine to loop through the same collection of children more than once.  It's usually a good idea to write your rules to be somewhat independent of each other, as we've done here.

However, if you find a situation where performance is more important than code legibility, you can combine loops like this into one rule with one block of code. That one loop not only creates and names the children, but also sets attributes on them:



Next steps

You've nested configurators.  Why not add some visuals to your configurator? Learn more about nesting 3D scenes.

Related articles



Was this article helpful?