APL Document (APL 1.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 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": "1.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": "1.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.0",
      "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": [
      "payload"
    ],
    "item": {
      "type": "BodyTemplate3",
      "title": "${payload.myTitle}",
      "scrollItem": {
        "type": "myBody",
        "block1": "${payload.myTextBlock1}",
        "block2": "${payload.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.

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.

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.

import

The import property defines a list of named APL packages that are required to inflate the templates and/or resources from this document. The imported packages are specified in a list of package references, where each entry in the list has the following properties:

Here is an example that uses the alexa-layouts package provided in the Alexa Design System for APL, and an external package.

  "import": [
    {
      "name": "alexa-layouts",
      "version": "1.7.0"
    },
    {
      "name": "my-own-package",
      "source": "https://www.example.com/my-custom-package.json",
      "version": "1.0"
    }	
  ]

An APL package is a JSON file that may be hosted on another site, such as Amazon S3. Ensure that Cross-Origin Resource Sharing is supported for any APL resources hosted on an HTTPS endpoint.

Package imports form a directed dependency graph. Resource, style, and layout lookup is depth-first, following the package import order. For example, if document A depends on packages B and C, and documents B and C depend on the package D, then the search order for the definition of a resource will be A, B, C, and then D. Thus, package A can override any of the resources, styles, or layouts defined in B, C, or D. Dependency loops are forbidden.

Packages may be downloaded by one of two mechanisms. If the source property is specified, the package will be downloaded from that location. If the source property is not specified, the package will be retrieved from an Alexa-supported central repository of packages, using the package name and version properties. Packages will be cached by the device runtime software. Two packages are considered to be identical if their name and version properties match (even if they have specified different source properties). The time to live (TTL) of a package will be determined by the TTL received during download. It is recommended that packages under active development be assigned a unique prerelease or build tag each time the package is modified to ensure that the runtime will correctly reload the package.

layouts

The layouts property is a map of layout name to layout definition. See APL Layout.

mainTemplate

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

The parameters defined in the mainTemplate are bound to data sources provided in the RenderDocument directive that inflated the document.

The mainTemplate is the layout that will be inflated when the document is first shown on the screen. The parameters defined in the mainTemplate will be bound to data sources provided by the RenderDocument directive that initiated the display of the APL document. See RenderDocument.

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:

For example, to set a two minutes default idle timeout, specify:

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

The information contained in the settings property are not accessible through data-binding or elsewhere in the APL document. They only serve to provide configuration information to the process displaying the APL document.

A device or runtime using APL may add custom device- or runtime-specific settings. To avoid conflicts with future global settings properties, it is recommended that the name of any custom device- or runtime-specific settings property starts with a hyphen or an uppercase letter. For example, "-idleTimeoutWhenDark" or "IdleTimeoutWhenDark".

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.

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 version property is used by the APL rendering engine to identify required features and ensure rendering accuracy.

An APL rendering engine should refuse to render a document if it does not support the document's version number. We generally expect that rendering engines will be backward-compatible; that is, a "1.3" engine will also support "1.0" documents.

The current version of the APL specification is "1.3". If a document has an older version number such as "1.0", but tries to use newer features from the 1.1 or later specification (such as the AnimateItem command), then the rendering behavior is undefined. The rendering engine is only obligated to render the "1.0" features and may choose to 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 == '1.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: Feb 29, 2024