InsertItem Command

Note: Learn how to improve your skills with APL with Build visually rich experiences using APL at the Alexa Learning Lab.

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

Adds an item to an inflated Alexa Presentation Language (APL) document. If successful, the document adjusts its layout to reflect the change in structure.

You can achieve similar results with single child inflation and the when property. However, to use this technique, you must know the layouts you want to inflate when authoring the APL document. Use the InsertItem command for cases where you don't know the layout and existence of the child components when authoring the document.

Note: The InsertItem command modifies the runtime representation directly, but doesn't change the source document that defined that representation. This means that commands such as Reinflate reset the runtime representation to the original document without the components added by InsertItem. All properties of the inserted item are discarded, including those set to preserve.

Properties

The InsertItem command has the properties shown in the following table, in addition to the common command properties. Set the type property to InsertItem.

In the following table, the "Default" column shows "Required" for properties that must have a value for the command to run. Otherwise it displays the default value, which might be none.

Property	Type	Default	Description
`at`	Integer	`MAX_INT`	The position within the array of existing child items to insert this item. When not set, the command appends the item to the end of the child items for the specified parent component.
`componentId`	Selector	`:source`	The identifier of the parent component. The command inserts the item as a child of the specified component.
`item`, `items`	Array of objects	[]	The component or layout to insert.

at

The array position within the array of existing child items in which to insert the item the item. Negative indices follow the definitions in array. When not specified, the command appends the item to the end of the child items for the specified parent component.

The following rules clamp the value of at to the size of the array to prevent an array out-of-bounds error:

If the at value is larger than the length of the array, InsertItem appends the new item to the end of the array.
If the at value is sufficiently small such that the insertion point would be negative, InsertItem pre-pends the item to the beginning of the array.

The array of child items for a parent component includes all inflated components that are child components of the parent. For example, for a Multi-child component, the array of child items includes:

The firstItem (if defined)
All items in the item array
The lastItem (if defined).

Therefore, if you set at to 0, the command places the inserted item before any defined firstItem. If you append the item to the end, the command places the item after any defined lastItem.

componentId

A selector that identfies the component or layout to target with the new item. If the selector doesn't resolve to an existing component, the InsertItem command does nothing.

item, items

The component or layout to insert. If the array contains multiple items, the first one selected by the when property is used. For details, see Single child inflation.

An inserted item has access to the data-binding syntax of the document just as any other component and can reference extensions declared by the APL Document. For details about extensions, see Extensions.

Situations in which InsertItem has no effect

The InsertItem command has no effect on the inflated document in the following scenarios:

The inserted item renders nothing. For example, if the inserted item has a when that evaluates to false. Malformed APL can also create a situation in which the inserted item doesn't render.
The command targets a parent component that doesn't support child components, such as VectorGraphic.
The command targets a parent component that supports a single child, such as a Frame.

Note: You can insert a component into a single-child component if the parent component doesn't already have a child. You can use the RemoveItem Command to remove the original component first, and then use InsertItem to insert the new component.
The targeted component is a multi-child component but uses data array inflation.

InsertItem and layout adjustments

The following document defines a Container with a single Text component. The Container has the ID main and the Text component has the id hello.

{
  "type": "APL",
  "version": "2023.3",
  "mainTemplate": {
    "items": [
      {
        "type": "Container",
        "id": "main",
        "items": [
          {
            "type": "Text",
            "id": "hello"
            "text": "Hello, world!",
            "textAlign": "center",
            "textAlignVertical": "center",
            "grow": 1
          }
        ]
      }
    ]
  }
}

A wire frame representing a document with a single text component — A wire frame representing the inflation of document with a single Text component

The following InsertItem command appends an additional Text component to the end of the Container.

{
  "commands": [
    {
      "type": "InsertItem",
      "componentId": "main",
      "item": {
        "type": "Text",
        "id": "bye",
        "grow": 1,
        "text": "Goodbye!",
        "textAlign": "center",
        "textAlignVertical": "center"
      }
    }
  ]
}

The layout adjusts to accommodate the additional Text component. The height of the original hello component reduces by half due to the grow property.

A wire frame representing the document after inserting a new Text component

InsertItem examples

Insert into a multi-child component

The following example uses a layout with a Frame component to show a border around the two components. The example runs the InsertItem command five seconds after inflating the document to insert second instance of the TextFrame layout. Refresh the page to reinflate the document and see the InsertItem update.

In the example, the onChildrenChanged handler on the Container uses SendEvent to send the following UserEvent request to the skill after the InsertItem command:

{
  "type": "Alexa.Presentation.APL.UserEvent",
  "requestId": "amzn1.echo-api.request.1",
  "timestamp": "2023-10-20T18:26:45Z",
  "locale": "en-US",
  "arguments": [
    {
      "uid": ":1003",
      "index": 1,
      "action": "insert"
    }
  ],
  "components": {},
  "source": {
    "type": "Container",
    "handler": "ChildrenChanged",
    "id": "main"
  },
  "token": "/insertItemBasicFrameToken"
}

Test the example with a skill to test SendEvent.

Insert into a single-child component

The following example uses InsertItem to insert an item in a TouchWrapper when you tap the component. Because the TouchWrapper can hold a single child, the example first runs RemoveItem to remove the hello layout, and then uses InsertItem to insert the bye layout.

This example doesn't include the onChildrenChanged handler because the handler isn't available for single-child components such as TouchWrapper.

Was this page helpful?

Provide feedback

Last updated: Nov 28, 2023