Instantiating Nested Configurators

When your user instantiates a nested configurator at run time, you can choose how and where it will appear.  It can be added either at the root level of the page tree, or beneath a page you specify. Instantiation may be done by rules or by user interaction in the UI. Both methods allow for the addition and removal of nested configurators. Other actions, such as copying, may only be done by user interaction.

Instantiation By User Interaction (Configurator Level)

When a configurator is specified to be added at the configurator level, the 'Add' hotspot will appear at the bottom of the tree when ever a root level page has the mouse focus. Clicking the hotspot will add a nested configurator.

'Copy' and 'Remove' hotspot will appear at the top of the middle pane whenever the instantiated configurator has the mouse focus. Clicking the hotspot will copy or remove the configurator with focus.

Instantiation By User Interaction (Page Level)

When a configurator is specified to be added at the page level, the 'Add' hotspot will appear at the top of the middle pane whenever the specified page has the mouse focus. Clicking the hotspot will add a nested configurator.

'Copy' and 'Remove' hotspot will appear at the top of the middle pane whenever the instantiated configurator has the mouse focus. Clicking the hotspot will copy or remove the configurator with focus.

Instantiation Through Rules

Instead of allowing your user to add as many nested configurators as they want, you can add them programmatically to follow business rules.

Adding

Instatiation of nested configurators though the rules is usually done in the 'Loaded' or 'Value' rules. One or more children may be instantiated at the same time. To add a single instance, the 'Add nested configurator' Snap block is usually used as in the following example.

In the above example, the configurator will be added only if an instance with the name "Pin 1" does not already exist.

The 'Set number of nested configurators' Snap block is used to instantiate a total number of children as in this example that sets the quantity to 2.  If there are any more configurators already existing at that location than the number you specify, they will be removed.

Note that if the above example is done in the Loaded rule, which runs only once, the user will be able to add more or delete the current instances during run time. If done in a Value rule, which runs after every user change to the UI, adding or removing an instance manually does not matter: this rule will always set the total number back to two.

Removing

The 'Remove nested configurator' Snap block is used to remove a specific instance. Either the name or object reference may be used to specify which instance to remove. In the below example, the first rule uses the name to remove an instance with the name of "Pin 1". The second rule uses an object reference to remove the 2nd child in the nested configurators collection.

Adding a Nested Set

To add a nested set, you need to update the UI and then write some Snap code.

Updating the UI for nested sets

1. Create your parent and child configurators.
2. In the parent configurator, create a new referenced configurator entry to relate another configurator as a child configurator.
3. In that child (referenced) configurator entry... 
   • For Configurator Type select your child configurator.
   • For Element for Nested Sets select what part of the child will appear over and over in the parent.
     • leave it blank
       (If you want the entire child configurator to appear as a page in the parent)
     • specify the child UI element you would like to appear in the parent. 
       (If the element in the child configurator you want is not available in the list, try adjusting the design of your child configurator: place the element you want to show within a container, and then refer to that container in this step.)
   • For Auto-navigate to new nested configurator elements think about your user experience.  If a new child is added to the parent, do you want the focus to move to that new child?  Or do you want the child to be added without interrupting your user's flow through the parent?  
4. In the parent configurator, add a "nested set" element on some page in the user interface.  This is where one or more of the child configurators will appear.

Writing Snap code to control nested sets

Regardless of how you choose to display your child configurators in a nested set, you must write some code to control when they are created and deleted from the parent at run-time.  Users cannot add or remove children from nested sets manually.  Two approaches can be used:

• For one button at the parent level that adds children (as in the containers example above),
  create a button in the parent configurator UI with the following snap code:
  
• For many buttons – each at the child level – that can delete that specific child (as in the accordion example above),
  1. Create a button in the child configurator within the nested set element you specified. This button sends a message to the parent, asking the parent to delete that specific child by name:
     
     
  2. Create a message rule in the parent, listening for these messages, which performs the actual deletion:
     
  3. If necessary, repeat this pattern for other child-level buttons, such as a button to clone a child.