APL Document (APL 2023.3)

(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)

An Alexa Presentation Language (APL) document is a JSON object that defines a template to display on a device with a screen. The APL document controls the structure and layout. You send the document to the device with the Alexa.Presentation.APL.RenderDocument directive.

Sample APL documents

This example shows an APL document that inflates a single Text component.

{
  "type": "APL",
  "version": "2023.3",
  "mainTemplate": {
    "item": {
      "type": "Text",
      "text": "Hello, world"
    }
  }
}

A richer APL document might include imported packages, resource definitions, style definitions, vector graphics, custom layouts, export information, and background colors.

{
  "type": "APL",
  "version": "2023.3",
  "description": "A sample APL document",
  "background": "#C87F70",
  "import": [
    {
      "name": "sample-import",
      "source": "https://example.com/packages/fictitious-package-import-example",
      "version": "1.0"
    },
    {
      "name": "alexa-layouts",
      "version": "1.7.0"
    }
  ],
  "export": {
    "resources": [
      "CompanyBlue"
    ],
    "layouts": [
      {
        "name": "myBody",
        "description": "Two stacked text blocks"
      }
    ]
  },
  "resources": [
    {
      "colors": {
        "CompanyBlue": "#0022f3"
      }
    }
  ],
  "styles": {
    "textBlockStyle": {
      "values": [
        {
          "fontSize": 24,
          "color": "@CompanyBlue"
        }
      ]
    }
  },
  "theme": "light",
  "graphics": {
    "AmazonPlayTrailer": {
      "type": "AVG",
      "version": "1.2",
      "parameters": [
        {
          "name": "fillColor",
          "type": "color",
          "default": "black"
        }
      ],
      "width": 48,
      "height": 48,
      "items": {
        "type": "path",
        "pathData": "M24,2C11.869,2,2,11.869,2,24s9.869,22,22,22s22-9.869,22-22S36.131,2,24,2z M24,44C12.972,44,4,35.028,4,24 C4,12.972,12.972,4,24,4s20,8.972,20,20C44,35.028,35.028,44,24,44z M19,34.799V13.201c0-1.004,1.041-1.563,1.829-0.937 l13.53,10.799c0.604,0.479,0.573,1.394-0.031,1.874L20.845,35.736C20.057,36.362,19,35.804,19,34.799z",
        "fillColor": "${fillColor}"
      }
    }
  },
  "layouts": {
    "myBody": {
      "parameters": [
        "block1",
        "block2"
      ],
      "item": {
        "type": "Container",
        "direction": "column",
        "items": [
          {
            "type": "Text",
            "text": "${block1}",
            "style": "textBlockStyle"
          },
          {
            "type": "Text",
            "text": "${block2}",
            "style": "textBlockStyle"
          }
        ]
      }
    }
  },
  "mainTemplate": {
    "parameters": [
      "myDocumentData"
    ],
    "item": {
      "type": "BodyTemplate3",
      "title": "${payload.myTitle}",
      "scrollItem": {
        "type": "myBody",
        "block1": "${myDocumentData.myTextBlock1}",
        "block2": "${myDocumentData.myTextBlock2}"
      }
    }
  }
}

Document properties

An APL document has the following top-level properties.

background

The background property is an optional property that initializes the color of the background as the APL document loads. You can set the background property to either a Color or Gradient. Setting the background to a consistent color or gradient keeps the user experience seamless as Alexa switches between different documents.

Because the device parses and interprets the property before loading packages and resources, you can't reference any resources in the background property. The data-binding expressions are limited to the properties in the initial data-binding context. The following are examples of valid background specifications:

"background": "darkgreen"
"background": "rgb(10,255,10)"
"background": {
  "type": "linear",
  "colorRange": [ "darkgreen", "white" ],
  "inputRange": [ 0, 0.25 ],
  "angle": 90
}
"background": "${viewport.theme == 'dark' ? 'darkgreen' : 'lightgreen'}"

When the background property is not specified, the device displays its the default background color. When the background property is partially transparent, the default background color of the device shows through.

commands

The commands property is an object mapping command name to user-defined command definitions.

environment

Overrides system default environment settings. You can access environment data with the environment property in the data-binding context.

Most system default environment settings aren't editable. The following table summarizes the settings you can override with the document-level environment property.

Environment values are calculated before resources are evaluated and the document is inflated. The values evaluate in a limited data-binding context.

To set a property of environment to value from a data source, pass the name of the data source in the parameters property. The document adds each data source in parameters to the limited data binding context used to evaluate environment.

The following examples show how to bind environment.layoutDirection and environment.lang to values in a data source. In this example, the data source is called MyData.

{
    "type": "APL",
    "version": "2023.3",
    "environment": {
        "parameters": [
            "MyData"
        ],
        "lang": "${MyData.dataLanguage}",
        "layoutDirection": "${MyData.dataLayoutDirection}"
    },
    "mainTemplate": {
        "parameters": [
            "MyData"
        ],
        "items": {
            "type": "Container",
            "direction": "row",
            "width": "100%",
            "height": "100%",
            "data": [
                "Language: ${environment.lang}",
                "Layout Direction: ${environment.layoutDirection}",
                "Text: ${MyData.textPhrase}"
            ],
            "item": {
                "type": "Text",
                "height": "100%",
                "text": "${data}",
                "spacing": "10dp"
            }
        }
    }
}

{
    "MyData": {
        "dataLanguage": "es-US",
        "dataLayoutDirection": "RTL",
        "textPhrase": "Text to display"
    }
}

In this example, the lang and layoutDirection environment properties are set to "es-US" and "RTL". With the RTL layout direction, the Container arranges the three text items from right to left and aligns them to the right side of the container.

The limited data-binding context available in the document environment property contains the following properties:

• environment
• viewport
• Math
• String
• Time

The limited data-binding context doesn't contain the current time or display state.

The environment property in the data-binding context returns system-supplied default values for lang and layoutDirection.

lang

Overrides the system-default language setting for the entire document. This property determines the default font selection for the Text and EditText components.

Set environment.lang to a BCP-47 string, such as "en-US". When not specified, environment.lang defaults to an empty string. Setting this property to ensure proper font selection is recommended. You can override this property for an individual Text or EditText component as needed. For details about the component-level lang property, see the following:

• Text component lang property
• EditText component lang property

In your document logic, you can use the environment.lang property in the data-binding context to access the document-level value for lang.

The following example sets the language to "ja-JP" to ensure that the Text component uses the Japanese version of the "Noto Sans CJK" font.

{
    "type": "APL",
    "version": "2023.3",
    "environment": {
        "lang": "ja-JP"
    },
    "mainTemplate": {
        "item": {
            "type": "Text",
            "fontFamily": "Noto Sans CJK",
            "text": "こんにちは"
        }
    }
}

An individual device might not have all language-specific fonts. When possible, always test your experience on the target device.

layoutDirection

Overrides the system-default layoutDirection for the entire document. This property determines the direction to lay out the components in the mainTemplate array. Set to one of the following:

• LTR – Lay out components in the left-to-right direction.
• RTL– Lay out components in the the right-to-left direction.

You can override the document-level layoutDirection for an individual component as needed. For details about the component-level layoutDirection property, see layoutDirection.

When not specified, the default document layoutDirection is LTR.

In your document logic, you can use the environment.layoutDirection property in the data-binding context to access the document-level value for layoutDirection.

The following example draws two text boxes, with the first aligned on the far right and the second to the left of the first:

For details about how layoutDirection affects components, see layoutDirection.

parameters

Contains an optional array of named data sources supplied with the APL document. These named data sources are bound into the limited data-binding context used to evaluate the environment properties.

Use parameters to bind the environment properties to data in a data source.

The items in parameters must either match or be a subset of the parameters used in the mainTemplate property.

For example, the following example correctly sets environment.parameters to a data source called MyData.

{
    "type": "APL",
    "version": "2023.3",
    "environment": {
        "parameters": [
            "MyData"
        ],
        "lang": "${MyData.dataLanguage}",
        "layoutDirection": "${MyData.dataLayoutDirection}"
    },
    "mainTemplate": {
        "parameters": [
            "MyData",
            "AnotherDataSource"
        ],
        "items": []
    }
}

export

The export property identifies the resources, graphics, layouts, and styles defined in the document that you intend for others to use within documents or packages that import this document as a package. The export property is informational. The APL rendering engine doesn't restrict access to any of the resources, graphics, layouts, or styles defined in a package.

The export property lets you identify which elements you intend to share and which elements are internal to the package and not intended to be directly used. Verification and authoring tools should use export information to help the APL author build a well-structured document.

The export property is a map with the following keys:

Each entry in each of these arrays is an object with the following properties:

For convenience, you can shorten an entry without a description to a single string containing the name of the entity.

This example shows the export property that includes graphics, layouts, resources, and styles:

{
  "export": {
    "resources": [
      {
        "name": "CompanyRed",
        "description": "Stock color for rendering the company logo"
      },
      {
        "name": "CompanyBlue",
        "description": "For people who don't like red"
      },
      {
        "name": "CompanyGreen" // Description omitted
      },
      "CompanyGray" // May simplify to single string when the description is omitted
    ],
    "layouts": [
      {
        "name": "MediaControl",
        "description": "Media controller with a play and pause button."
      }
    ],
    "graphics": [
      "PlayButton",
      "PauseButton"
    ],
    "styles": [
      "PlayButtonStyle",
      "PauseButtonStyle"
    ]
  }
}

The properties listed in export must be defined in the current document.

extensions

The extensions property lists the APL extensions to request. You can request an extension in both documents and packages. List the requested extensions by name and URI in the extensions property.

This example requests three extensions. Note that the remotebutton and fishfeeder extensions shown in this example are fictitious.

{
  "extensions": [
    {
      "name": "Back",
      "uri": "aplext:backstack:10"
    },
    {
      "name": "Button",
      "uri": "aplext:remotebutton:13"
    },
    {
      "name": "Fish",
      "uri": "aplext:fishfeeder:10",
      "required": true
    }
  ]
}

Each requested extension is a map with keys shown in the following table.

The name property defines how to identify the extension within the APL document. The document uses the name property in three locations:

1. The names and URIs of all requested and provided extensions are exposed as environment properties. Use this property in your document to determine whether a particular extension is available.
2. The extension name is used a namespace when writing extension event handlers. This lets the document receive events from the extension and act upon those events.
3. The extension name is used as a namespace to run extension commands. This lets the document send a command to the extension.
4. The extension name is used to retrieve settings from the settings specific to that extension. This lets the extension configure itself at load time, if needed.

Set the optional required property to true to indicate that the document can't render unless the requested extension exists and responds to the extension registration message.

For more about how extensions work and how to interact with extensions, see APL Extensions.

For a list of the available extensions, see Available Extensions.

graphics

The graphics property defines a collection of named vector graphics you can use within the document. See Alexa Vector Graphics Format for details about the format for vector graphics.

handleKeyDown

An array of keyboard event handlers to run when a key is pressed on the keyboard or when a key auto-repeats. The keyDown event is generated whenever possible; for example pressing the "shift" key should generate a keyDown event.

The event generated has the form:

"event": {
  "source": {
   "type": "Document",
    "handler": "KeyDown",
    "id": null,        // No value reported
    "uid": null,       // No value reported
    "value": null      // No value reported
  },
  "keyboard": {
    "altKey":   Boolean
    "code":     String,
    "ctrlKey":  Boolean,
    "key":      String,
    "metaKey":  Boolean,
    "repeat":   Boolean,
    "shiftKey": Boolean
  }
}

For more details on the keyboard property, refer to the keyboard events documentation.

handleKeyUp

An array of keyboard event handlers to run when a key is released on the keyboard. The keyUp event is generated whenver possible and not just for text entry. For example, releasing the "shift" key on a keyboard should generate a keyUp event.

The event generated has the form:

"event": {
  "source": {
   "type": "Document",
    "handler": "KeyUp",
    "id": null,        // No value reported
    "uid": null,       // No value reported
    "value": null      // No value reported
  },
  "keyboard": {
    "altKey":   Boolean
    "code":     String,
    "ctrlKey":  Boolean,
    "key":      String,
    "metaKey":  Boolean,
    "repeat":   Boolean,
    "shiftKey": Boolean
  }
}

For more details on the keyboard property, refer to the keyboard events documentation.

handleTick

An array of tick event handlers to run as time passes.

The event generated for a tick event handler has the following form.

"event": {
  "source": {
    "type": "Document",
    "handler": "Tick",
    "id": null,       // No value reported
    "uid": null,      // No value reported
    "value": null     // No value reported
  }
}

import

The import property defines a list of named APL imports. You can use the resources, styles, layouts, and other items defined in the imported packages within this document. For details, see APL Import.

layouts

The layouts property is a map of layout name to layout definition. For details, see APL Layout.

mainTemplate

The mainTemplate property is the layout to inflate when the document first displays on the screen. You send Alexa the RenderDocument directive to display your document.

The parameters array defines properties that bind to the data sources provided in the RenderDocument directive that inflated the document.

The item or items array defines the components or layouts to display. The mainTemplate uses the single child inflation algorithm to choose the items to display. Therefore, when the array contains multiple components, the document inflates the first component for which when evalutates to true. To display multiple components, group them into a single multi-child component.

onConfigChange

The commands to run when the document changes configuration. A change to any of the following properties invokes onConfigChange:

• viewport.height
• viewport.width
• viewport.theme
• viewport.mode
• environment.disallowVideo
• environment.fontScale
• environment.screenMode
• environment.screenReader

The event generated for the onConfigChange handler has the following form.

"event": {
  "source": {
    "type": "Document",
    "handler": "ConfigChange",
    "id": null,        // No value reported
    "uid": null,       // No value reported
    "value": null      // No value reported
  },
  // Viewport properties
  "height": INTEGER,         // The updated height of the view, in DP
  "width": INTEGER,          // The updated width of the view, in DP
  "theme": STRING,           // The updated theme of the view
  "viewportMode": STRING,    // The updated viewport mode ("auto", "hub", "mobile", etc)

  // Configuration properties
  "fontScale": NUMBER,       // The updated font scaling factor
  "screenMode": STRING,      // The updated screen mode ("normal" or "high-contrast")
  "screenReader": BOOLEAN,   // True if the screen reader is turned on

  // Synthesized properties
  "sizeChanged": BOOLEAN,    // True if the width or the height changed value
  "rotated": BOOLEAN,        // True if the width/height swapped values
}

Note that seven updated properties and two synthesized properties are available in the event. The sizeChanged property is a Boolean that is true if the width or height changed value. The rotate property is a Boolean that is true if the width and height swap values, such as because the device switched between landscape and portrait orientation.

To reinflate the document on any configuration change, run the Reinflate command:

{
  "type": "APL",
  "version": "2024.3",
  "onConfigChange": {
    "type": "Reinflate"
  }
}

To reinflate the document when the screen size changes by a certain amount, add a when statement to the command and use the properties in the event to determine the new size. The following example reinflates the document when the screen changes by at least 25 percent.

{
  "type": "APL",
  "version": "2024.3",
  "onConfigChange": {
    "type": "Reinflate",
    "when": "${Math.abs(viewport.width - event.width) > 0.25 * viewport.width || Math.abs(viewport.height - event.height > 0.25 * viewport.height)}"
  }
}

You can choose whether to run Reinflate on a configuration change. Note that the viewport and environment properties in the data-binding context are constant values set when a document inflates. If you don't reinflate the document on a configuration change the values in these environment and viewport properties might not reflect the actual device configuration.

If you don't run Reinflate, but want to refer to the most current environment properties, extract the values from the event and store them in a bound variable.

For details about resizing and reinflating options, see Support Tablets and Other Devices that Can Change Size.

The onConfigChange event handler runs in fast mode.

onDisplayStateChange

An array of commands to run whenever the display state of the document changes. The display state of the document is one of the values shown in the following table.

Hidden documents should use a minimum of system resources. Background documents should restrict their animations and not assume they have the user's focus.

The handler generates an event with the following form.

"event": {
  "source": {
    "type": "Document",
    "handler": "DisplayStateChange",
    "id": null,        // No value reported
    "uid": null,       // No value reported
    "value": null      // No value reported
  },

  "displayState": STRING     // The new display state ("hidden", "background", or "foreground")
}

The display state change event handler doesn't run when the document first inflates. Use the global data-binding property displayState to determine the display state at document inflation.

The display state change event handler runs in fast mode.

onMount

The command to run when this document is first displayed on the screen. This command runs after the component onMount commands run.

When the device first displays the document on the screen, the following sequence of actions takes place:

1. Run in parallel all of the component onMount commands.
2. Run the document onMount command.

These commands are effectively gathered into the following meta-command:

{
  "type": "Sequential",
  "commands": [
    {
      "type": "Parallel",
      "commands": "<COMPONENT_ON_MOUNT_COMMANDS>"
    }
  ],
  "finally": "<DOCUMENT_ON_MOUNT_COMMAND>"
}

The reason for this structure is because a touch event or an external command could be issued against the document while the component onMount commands are running. If the event occurs while the component onMount commands are running, the component onMount commands stop and the document onMount command runs in fast mode. If the event occurs while the document onMount command is running, the document onMount command stops.

The event generated has the form:

"event": {
  "source": {
    "type": "Document",
    "handler": "Mount",
    "id": null,        // No value reported
    "uid": null,       // No value reported
    "value": null      // No value reported
  }
}

resources

The resources property is an array of resource blocks. See Resources.

settings

The settings property holds a map of key-value pairs that define document-wide properties. The following properties are defined:

The following example sets a two minutes default idle timeout.

{ "type": "APL", "version": "2023.3", "settings": { "idleTimeout": 120000 } }

The properties in the settings property aren't accessible through data-binding or elsewhere in the APL document. The the settings properties provide configuration information to the process displaying the APL document.

idleTimeout

Recommended time in milliseconds that the document should remain on the screen before closing due to inactivity. This value is a recommendation, not a guarantee. Specific devices may choose to ignore or bound the idle timeout value.

supportsResizing

Determines the action to take when the system detects a change in the width and height of the screen, such as when the user rotates a tablet to change orientation. Set supportsResizing to true to do the following:

• Enable automatic resizing. The APL runtime resizes the layout to fit the new screen size.
• Run the commands in the onConfigChange handler. You can use this handler to run commands when using automatic resizing. You can also use this handler to run the Reinflate command.

For details about resizing and reinflating options, see Support Tablets and Other Devices that Can Change Size.

styles

The styles property is an object mapping style name to style definition. See Styles

theme

If specified, the theme value overrides the viewport.theme property in the data-binding context. See Viewport object – Theme.

version

The version property specifies the version of APL that the APL document uses. The APL rendering engine uses the version property to identify required features and ensure rendering accuracy.

An APL rendering engine should refuse to render a document if the engine doesn't support the document's version number. Rendering engines should be backward-compatible. A "2023.3" engine also supports "2023.2" and earlier documents.

The current version of the APL specification is "2023.3". If a document has an older version number such as "1.0", but uses newer features from the 1.1 or later specification (such as the AnimateItem command), the rendering behavior is undefined. The rendering engine must render the "1.0" features, but can ignore newer features.

To create a document that uses newer features, but still works correctly on devices with older versions of APL, wrap the newer features in a conditional block with the environment.aplVersion property.

{
  "when": "${environment.aplVersion == '2023.3'}",
  "type": "VectorGraphic",
  "source": "sample-vector-graphic",
  "position": "absolute",
  "fillColor": "yellow",
  "top": "3vh",
  "left": "3vw"
}

Inflation of An APL document

The APL document is inflated into an on-screen display, using the following steps:

1. Put the list of import packages on the package processing queue.

2. For each package on the queue:

• Add the package to the directed graph of package dependencies

• Check if the package is available either in the (a) on-device cache, or (b) the packages portion of the directive. If the package is not on-device, use the source value of the import list to download the package from the named URL.

• Add the packages import list to the package processing queue

3. Construct an initial data-binding context with a viewport property.

4. Construct an initial set of named resources using the built-in resources for the device.

5. Traversing the directed graph of package dependencies in depth-first order, for each package:

For each resource block in the resources array:

Evaluate the when clause in the current data-binding context. If the when clause evaluates to false, skip this block. Otherwise, if the when clause evaluates to true:

• Evaluate each boolean in the boolean map and add to the resources

• Evaluate each color in the colors map and add to the resources

• Evaluate each number in the numbers map and add to the resources

• Evaluate each string in the strings map and add to the resources

• Evaluate each dimension in the dimensions map and add to the resources

6. For each parameter in the mainTemplate:

• Identify a data source with the same name

• Update the data-binding context to set that name to the value in the data source.

7. Inflate the mainTemplate following standard layout inflation logic.

Last updated: Nov 28, 2023