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
• Command evaluation
  • Event context
  • Event definition
• Expression evaluation
• Command Sequencing
  • Sequencer Rules
  • Command Trees
  • Fast mode
  • Command tree termination
  • Sequencer summary

Commands and screen actions

Commands support the following types of actions on the scene:

• Navigate within a scene
  • Scrolling a ScrollView or Sequence
  • Scrolling to bring a component into view
  • Change the page displayed in a Pager
• Change a component within an existing scene
• Update an input control to reflect a new state
• Change the visibility on an existing component.
• Play/pause a video clip within the existing 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
    "uid": RUNTIME_GENERATED_UNIQUE_ID,
    "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:

The following table lists the standard source values:

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

See also: APL standard commands and APL Media 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 vary by 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 executes, 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 is executed 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 execute. The array is treated the same as a Sequential command with a repeatCount of 0.

Command Sequencing

The APL runtime environment is responsible for executing commands. The runtime contains a single command sequencer which is responsible for executing commands.

Sequencer Rules

The sequencer rules are:

• Touching on the screen immediately stops any existing sequence. Any commands in the middle of executing are stopped. All commands are flushed.
• A received ExecuteCommands directive from the cloud stops any currently executing sequence and replaces it with the new commands.
• If a command fails to execute due to being poorly formed or referring to a non-existent component, the command is skipped. Any delay value associated with that command is still processed.
• All event handlers (e.g., onPress) may be associated with one or more commands. If more than one command is assigned to an event handler the set of commands is implicitly wrapped inside Sequential command.

For example, in the following example the onPress event handler has an array of commands. This array is treated as a sequential array to be execute; here the text component will be spoken and the SendEvent will be dispatched after the speech finishes:

{
  "type": "TouchWrapper",
  "items": {
    "type": "Text",
    "id": "myText",
    "speech": VALUE
  },
  "onPress": [
    {
      "type": "SpeakItem",
      "componentId": "myText"
    },
    {
      "type": "SendEvent",
      "arguments": [ "The button was pushed and spoken have I" ]
    }
  ],
}

APL supports a single executing command sequence at one time. When a new command sequence starts, the old command sequence is terminated abruptly and unexecuted commands in the old command sequence are not run. A Source of a command or set of commands is something that triggers execution of commands. A source can be a user interaction or based on some passage of timing triggering an action. The following types of sources exist:

• An Alexa ExecuteCommands directive.
• Touching on the screen
• Dragging on the screen (scrolling)
• Certain Video component events (e.g., onTrackUpdate) that occur in a background video.

The source fires a series of one or more commands to execute, which in turn may consist of additional sets of commands to execute in series or in parallel. Each of the commands may occur instantaneously or may take a period of time.

Command Trees

A command tree is the complete set of commands that gets executed. Command trees come about because commands may be nested or because a command may cause a new event handler to fire. Various primitive commands have nested commands:

• Parallel
• Sequential
• OpenURL

User-defined commands also contain nesting. Primitive commands may also trigger event handlers; for example, the onScroll event may be triggered by Scroll, ScrollToComponent, or event SpeakList.

Command trees can run to completion or they can be terminated before completion. A terminated command tree stops execution of all commands immediately. In short, a source triggers the execution of a command tree. The command tree may run to completion or may be preemptively terminated.

A sample command tree might look as follows:

ExecuteCommand
  + Scroll (distance=-10000)           // Scroll to top
    + onScroll                         // Fires multiple times as the view scrolls to the top
      + SetValue (name="opacity", value=event.source.value * 10) // Change opacity
  + SpeakItem (id)                     // Scroll item into view and run karaoke
    + onScroll                         // Fires multiple times as the view scrolls
      + SetValue (name="opacity"....)
  + PlayVideo (synchronously)
    + onStart                          // Fires once
    + onTrackUpdate                    // Fires each time a new track is displayed
      + SetValue (name="progress"...)  // Update a progress bar display
    + onStop                           // Fires once

In the above example, an Alexa ExecuteCommands message scrolls to the top of the screen, speaks one of the items, and plays a video (presumable in a separate section of the screen). If the user touches on the screen during playback, any running speech, scrolling, or video playback will be halted.

Rules:

• You get a single "live" user-initiated source. If there is an existing, running user-initiated source it is terminated and the new user-initiated source starts.
• Non-user-initiated sources always run to completion. The only exception is that they will be terminated when the APL template is closed. Any number of non-user-initiated sources may be active at the same time.

Fast mode

The commands executed as a part of a command tree may include commands that take a visible amount of time to execute. For example, scrolling a list on the screen, speaking text, or simply delaying an effect. The executing command sequence may trigger event handlers that start new command sequences executing. In the case of the onScroll event handler, this may fire at the display frame rate during a long scroll operation. If the onScroll event handler was allowed to trigger a command sequence that took time to execute (such as speaking text), the system would have to either queue up the spoken text for later processing or it would have to repeatedly interrupt the spoken text with new spoken text.

To avoid having a repeated interruptions of spoken text, APL introduces the concept of normal- and fast mode command execution. Any command sequence spawned from an event handler that may execute at frame rate is executed in fast mode. All other command sequences are executed in normal mode. Fast mode command execution ignores all delay settings in commands and ignores commands that take measurable time to execute. The event handlers have the following behavior:

Events that occur due to user interaction (such as pressing a touch wrapper) always execute in normal mode. Events such as scrolling or time updates always occur in fast mode. Events that can execute in either mode can be triggered by a normal action (such as a video track ending) or by a command that was ultimately triggered by fast mode (such as a video pause from a scroll event). External commands execute in normal mode.

Each command documents its behavior in fast mode. The following table summarizes fast-mode behavior:

Command tree termination

When a command tree is terminated, it needs to go to a consistent state. APL makes a number of assumptions:

• Scrolling should simply stop
• Page turns should be cancelled and return to either the original page or the next page (whichever is closer)
• Speaking should immediately stop
• Scene changes and structural changes to the layout should "jump" to their final position.

"Normal" mode is how commands normally execute. "Fast" mode eliminates all duration for commands. The delay property of the command is ignored. All commands that take time to execute (such as scrolling) are either ignored in fast mode. Individual commands document their behavior in "fast" mode.

Sequencer summary

When a new series of commands are received for processing (either supplied externally or internally due to an action like pressing a buttom), any existing command tree is terminated. The new series of commands are processed in order with fast mode set to false. For each command, do the following:

1. Evaluate the when clause. If it evaluates to false, skip the command and move on the next command in the array.
2. Evaluate the delay property. If it is greater than zero, pause that duration in milliseconds.
3. Evaluate the type of the command. There are three possibilities:
   1. The command could be a standard command such as SendEvent. Check to see if all required command properties have been set. If a required property is missing, ignore the command and continue. If all required properties are set, execute the command and wait until it finishes.
   2. The command could be a user-defined command. Execute the command following the rules defined in that section.
   3. The command could have an unrecognized type. Ignore the command and continue.

Note that standard commands may trigger event handlers. Those event handlers are generally executed in fast mode.