Nodes and controls

Nodes and controls organize widgets into groups:

  • Nodes are like pages, where each page is a set of items that are usually displayed together.

  • Controls are like rows in those pages, where each row is a rich-media item.

For example, you can create a two-node widget, where the first node contains a set of form items that the user enters, and a second node is a confirmation page with text displaying what the user previously entered.

  • Using multiple nodes is relevant mostly when using advanced rich media.

  • Using one node and one or two controls is the norm for most basic rich-media use cases.

Define nodes

The key nodes at the top level of the JSON specify nodes and define an array of JSON objects. The initialView widget property defines the start-up node. This property is described in Widget properties.

Each object in the array contains the id and controls properties, and optionally the context property, which are described below:

Property Description Required
context

Contains visual styling options for the node. All properties are optional.

Although you can specify visual styling options in CSS, you can also define the following simple styling options at the content level:

  • widgetContainerBorderColor—Accepts a hex color code. If specified, this also applies a solid border of one pixel width.

  • widgetContainerBackgroundColor—Accepts a hex color code.

  • widgetContainerBorderRadius—Accepts an integer, which indicates the number of pixels.

  • widgetContainerPadding—Accepts an integer, which indicates the number of pixels.

no
controls

Contains one or more keys that correspond to the desired index for each control. Keys are integers starting with 0.

Defines the rich widget items inside the node, and the order in which they are rendered.

yes
id

Name of the node, which must be unique within the widget.

Used in references to the node and the values entered into controls inside the node.

yes

Define controls

An integer key that corresponds to the index of the control, starting with zero, specifies the control. The index in the key defines the order of the controls. The value for each key is an object containing the values for that control.

Although each type of rich-media widget supports a different set of properties, some properties are supported by many or all controls:

Property Description Required
context

Contains visual styling options for the control. All properties are optional. Although you can specify visual styling options in CSS, you can also define some simple styling options at the content level.

Supported options depend on the widget. For more information, see Widget reference.
no
enabled

When defined, the control has a disabled HTML attribute until the EVENTNAME occurs and the CONDITION is true.

Contains the following two key/value pairs:

  • trigger”: “EVENTNAME

  • guard”: “CONDITION

Note: For details about conditional logic, see Guard conditions.

no
event

For interactive widget types, defines an event that fires whenever either:

  • the input changes (for form-type controls)

  • the control is activated (for controls such as buttons).

Contains the following key/value pair: “event”: “EVENTNAME

no
id Name of the control, which must be unique within the node. Used in references to the control and the values entered by the user. yes
type

A Rich Media type. This determines which other parameters you can set for the widget. The type for each widget is listed in the corresponding topic in the Widget reference.

yes
validation Available key/value pairs depend on the widget type.

For interactive widget types. Supported validation conditions depend on the widget. For more information, see Widget reference.

no
visible

When defined, the control is not displayed until the EVENTNAME occurs and the CONDITION is true.

Contains the following two key/value pairs:

  • trigger”: “EVENTNAME

  • guard”: “CONDITION

Note: For details about conditional logic, see Guard conditions.

no