Nested Sets


Epicor CPQ configurators can be nested in a parent-child structure.  Through this technique, portions of any child configurator's UI can appear within the UI of the parent configurator.  The simplest and most common way for children to appear within the parent is as pages in the parent UI configurator. However, Nested Sets allow you to show nested child configurators within your parent configurator in various other ways.


Examples

You can have a child configurator appear within your parent configurator as a Page by default, or you can use a Nested Set to have it appear as a Container, a Group, a tab within a Tab Control, or an Expander within an Accordion.


Child Content Appearance within Parent Example UI

Entire child configurator

(all pages)

Appears as one or more Pages in the parent.

In this example, a parent "Building" configurator creates as many child "floor" configurators as the user requests when she slides the "floor count" field in the parent.  The resulting child configurators appear as separate pages, indented under the parent's "floor" page.  The entire child's UI can be seen.

The overview of nested configurators describes how these child pages can appear...

  • either indented under a parent's page (as here),
  • or as first-level pages themselves

Contents of a specific page or container from the child configurators

Appears as one or more Containers within a nested set control of the parent. This nested set control is usually invisible.

In this example, a user of a parent configurator clicks a "new" button to create a child "Attendee" configurator.  The contents of a child container of 3 fields in a horizontal layout is shown multiple times in a container in the parent with vertical layout, just above an "add row" button on that parent page.  No other portion of the child's UI outside the specified container is displayed.

Contents of a specific page or container from the child configurators

Appears as one or more Expanders within a nested set control that looks like an Accordion in the parent.

In this example, a user of a "building" configurator clicks an "add door" button to create a new child "door" configurator.  A simple container from that child's UI is shown.  It has an select field, along with two small buttons to clone or delete itself from the parent. Any other portion of the child's UI is not displayed.

Contents of a specific page or container from the child configurators

Appears as one or more Groups within a nested set control of the parent. This nested set control is usually invisible.


Contents of a specific page or container from the child configurators Appears as one or more Tabs within a nested set control that looks like a Tab Control in the parent.


Add a Nested Set

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

Position

  1. Create your parent and child configurators.
  2. In the parent configurator, create a new referenced configurator entry to relate the child to the parent.
  3. In that referenced configurator entry... 
    • For "Configurator Type" select your child configurator.
    • For "Element for Nested Sets" you can either leave it blank (if you want the child to appear as a page in the parent), or 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.

Update the UI

Write some Snap code

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 that 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. repeat this pattern for other child-level buttons, such as a button to clone a child.


Nested Set Properties

Name A name which is displayed in the design tree and used in Snap rules. The name must be unique to the configurator.
Visible Specifies whether this nested set is shown to the user by default or not. This property can be changed in the visibility rules.
Display

Specify how this nested set should appear within the parent, as children are added or removed:

  • Container
  • Group
  • Tab Control
  • Accordion


Container-based position properties appear for this element (and any interface element) when it is placed within a container, and help align it within the container.

For example, if you place this UI element within a container, the following properties will appear.  Take it out of the container, and place it on a page, and these properties will disappear.

Furthermore, the actual position properties themselves change, depending on that parent container's Item Layout.

  • Not seeing any of the "Position" properties below for this UI element?
    Place this element into a container, and then return to this element's properties list. The "Position" accordion will now appear in the properties list.

  • Not seeing the right kinds of "Position" properties for this UI element?
    Change the parent container's item layout to horizontal, vertical, or absolute.  Then return to this UI element. The position properties available for items within that layout (marked by green checkmarks below) will appear.

Property Available when in a horizontal layout Available when in a vertical layout Available when in an absolute layout Description

Relative Size

y

y

n

  • auto (default)
    • sizes the item just large enough to be drawn on-screen and no more. 
    • The item's size is independent: No size relation exists between this item and any other items in the container.
  • x1-x6
    • sizes this item in relation to any other items in the container that also have an x1-x6 relative size.
      For example, if a "First Name" field has a size of x1, and a "Last Name" field also has a size of x1, then they will be the same size.  Change "Last Name" to x2 to make it twice the size of the "First Name" field.
    • The item's size is dependent on other items in the container: change the xN size of another item, or change the items in the container, and this item's size changes slightly to continue to follow the size relations you've defined.

When using relative sizes, try setting all items within the container to  the relative size of "x1" as a starting point, and then adjust the xN levels as necessary.  Mixing items with "auto" and "xN" settings is allowed, but may be difficult to manage.

Alignment

y

y

n

Controls how this item within a container is aligned in the cross axis of the container's layout.

  1. If the parent container's ItemLayout is set to horizontal, then this controls the vertical alignment of the items.
  2. If the parent container's ItemLayout is set to vertical, then this controls the horizontal alignment of the items.
  • stretch
    the item will stretch across the entire cross axis, if possible.  If the item size cannot be adjusted, it will appear centered.
  • start
    the item will appear at the start of the cross axis
  • center
    the item will appear in the center of the cross axis
  • end
    the item will appear at the end of the cross axis

Left

Top

Right

Bottom

Width

Height

n

n

y

The distance between the edge of the parent container and this element.  By default, each is "auto".  Usually, you would set only 2 of these properties, leaving the rest to "auto", or you may distort this image or element.  For example, to align an item's upper-right corner to the upper-right corner of the parent container, set "Top" to 0px, and "Right" to 0px, leaving all other distances to "auto".

Opacity

n

n

y

The visibility of items or backgrounds behind this item.  Use any decimal number from 0 to 1. Set to 0 to make this item completely transparent.  Set to 1 to make the item completely opaque.


Order

y

y

y

Specifies the order in which this item is drawn in the container. Use a whole number, such as 0 or 132.  Default: 0.  Larger numbers are drawn later, and appear closer to the user.

  • Numbers are relative to each other: an item with order "3" will be drawn before an item with order "4". 
  • Order numbers do not need to be consecutive: the next item could have order "50".
    • Order numbers do not need to be unique: if two items have the same order number, such as "0", they will be shown in the order they are defined in the design tree.


Use Zero Padding y y y

By default, UI elements have some padding around them for legibility on all devices, and for ease of use on touch-enabled devices.  However, in some cases you may want specific UI elements to have no padding around them at all (to touch each other).  This can be useful to create a portion of your UI which needs a very high information density. For example, to create a grid of fields that appear like cells in a spreadsheet.




Was this article helpful?