APL Commands (APL 1.0)

(This is not the most recent version of APL. Use the Other Versions option to see the documentation for the most recent version of APL)

Commands are messages that change the visual or audio presentation of the content on the screen. You send commands to the device in response to a spoken utterance with the Alexa.Presentation.APL.ExecuteCommands directive. You use event handlers in your APL document to trigger commands directly, such as the response to a button press.

For specific commands, see APL Standard Commands.

Commands and screen actions

Commands support the following types of actions on the scene:

  • Navigate within a scene
  • Speech
    • Read the audio content of a single component
    • Read the audio content from more than one components

Command evaluation

The individual properties of a command support data-binding. The command is evaluated by using a combination of the source data-binding context augmented with the event property that contains information about what caused the command to be issued and the target properties of the recipient of the command.

Event context

Commands evaluate in their source data-binding context. A command received from Alexa evaluates in the top-level data-binding context. That is, a data-binding context that has a viewport and environment defined, and it has access to named resources. A command issued in response to an APL event (such as a screen touch) evaluates in a local data-binding context where the command is defined. For example, consider this TouchWrapper sample.

{
  "type": "TouchWrapper",
  "bind": [
    "name": "myRandomData",
    "value": 24.3
  ],
  "onPress": {
    "type": "SendEvent",
    "arguments": [ "The value is ${myRandomData}" ]
  }
}

Pressing the TouchWrapper sets the first argument to "The value is 24.3".

Event definition

The source data-binding context is extended with event data when a command is evaluated. All of the event data is available under the event property. The event property contains the source sub-property, which is system-provided information about the component that caused the event.

"event": {
  "source": {
    "type": COMPONENT_TYPE,
    "handler": EVENT_HANDLER,
    "id": SOURCE_COMPONENT_ID,  // If assigned
    "value": SOURCE_COMPONENT_VALUE
  },
  "target": {
    PROP1: VALUE1,
    PROP2: VALUE2,
    ...
  }
}

Source

The source section of the payload is meta-information about what caused the event to be generated. The source section is generated by the APL runtime, not the skill author. This information may be used by the skill developer, but is also intended to be used by analytics. The source object contains the following values:

Property Type Required Description
type String Yes The type of the component that initiated this message.
handler String Yes The name of the event handler that initiated this message. For example, "Press", "Checked". Event handlers are normally named "onXXXX". By convention, the handler is reported as "XXXX".
id String Yes The id of the component that initiated this message.
value Any Yes The value of the component that initiated this message.

The following table lists the standard source values:

Component type Value
TouchWrapper Checked state
Pager Current page index
ScrollView, Sequence Percentage of scroll view height from top

Refer to the individual component definitions for the specific source value that will be exposed.

See also: APL standard commands.

Target

The target property provides state information about the component receiving the event. The values in the target property are defined on a component by component basis. Some standard target values are listed below, but the target values will vary by component.

Property Type Description Reported By
color Color Current color Text
height Number Height in dp Component
id String Component ID Component
opacity Number Opacity of the component Component
source String Image source URL Image
text String Displayed text Text
width Number Width in dp Component

Expression evaluation

  • Some commands take the componentId value as a target. However, if the component issues the command, and the command targets the same component, the componentId value may be omitted. If you use the ExecuteCommands directive, then componentId must be specified.

  • Command data-binding expressions are evaluated when the command runs, not when the command is defined. For example, an ExecuteCommands directive may contain data-bound expressions that refer to the global data-binding context. These expressions are evaluated when the command runs on the device, not when the command is constructed in the cloud.

  • Both event handlers and the ExecuteCommands directive take an array of commands to run. The array is treated the same as a Sequential command with a repeatCount of 0.

Was this page helpful?

Last updated: Nov 28, 2023