Multi-child Component Properties

A multi-child component is an abstract component that arranges and displays multiple child components

Multi-child components

The following components are multi-child components:

Properties

All multi-child components have the following properties:

Property Type Default Styled Dynamic Description

data

Array

—

No

No

Data to bind into this multi-child component.

firstItem

Array of components and layouts

—

No

No

A component to display before all others.

item, items

Array of components and layouts

[]

No

No

The components or layouts to display.

lastItem

Array of components and layouts

—

No

No

A component to include after all others.

onChildrenChanged

Array of commands

[]

No

No

Commands to run when the children of the component change.

data

An array of data. If the data array is bound, the multi-child component uses the data array inflation method. This means that the components in items are inflated one time for each value in data.

firstItem

A single component or layout to pre-pend to the multi-child component using the single child inflation method.

item, items

An array of components and layouts to display.

When the data property has a value, the multi-child component uses the data array inflation method.

When the data property does not have a value, the multi-child component uses the simple array of child components inflation method.

lastItem

A single component or layout to append to the multi-child component using the single child inflation method.

onChildrenChanged

onChildrenChanged requires APL 2023.3 or later. Provide an alternate experience for devices running older versions of APL.

The onChildrenChanged handler runs when the child components are inserted or removed from the component.

The list of child components can change due to any of the following:

Property updates for a child component don't cause an onChildrenChanged event.

The event generated has the following form.

{
    "event": {
      "source": {
        "type": COMPONENT_TYPE,
        "handler": "ChildrenChanged",
        ...                   // Component source properties
      },
      "changes": [            // Array of all changed children
        {
          "index": NUMBER,    // Current item index for the insert operation, not included for remove
          "uid": STRING,
          "action": "insert|remove"
        }
        ...
      ],
      "length": NUMBER        // Length of the children list after the change
    }
}

Refer to Event source for a description of event.source properties. The event.source.value property is set to the value of the component.

The onChildrenChanged handler runs in fast mode in the component data-binding context. It also runs one time for each child change.

The following example shows how you could use onChildrenChanged to scroll to the start of the list when new items are pre-pended to the list:

{
  "onChildrenChanged": {
    "type": "Select",
    "data": "${event.changes}",
    "commands": {
      "when": "${data.action == 'insert' && data.index < event.source.firstVisibleChild}",
      "type": "ScrollToIndex",
      "sequencer": "SCROLLER",
      "index": 0
    }
  }
}
Was this page helpful?

Last updated: Feb 29, 2024