APL Commands

Commands are messages that change the visual or audio presentation of the content on the screen. They may be received from Alexa, normally in response to a spoken utterance, or may be generated by event handlers in the APL document, such as in response to a button press. Commands are used to navigate the content, switch between scenes in the Document, and synchronize speech with visual presentation.

For specific commands, see APL Standard Commands and APL Media 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 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 evaluates. 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.

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 section 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.

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

See also: APL standard commands and APL Media Commands.