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

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

Here is a simple APL document that inflates a single Text component.

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

A richer APL document can include imported packages, resource definitions, style definitions, data sources, and custom layouts.

{
  "type": "APL",
  "version": "1.0",
  "description": "This is a sample use of BodyTemplate3",
  "import": [
    {
      "name": "sample-import",
      "source": "https://example.com/packages/fictitious-package-import-example",
      "version": "1.0"
    },
    {
      "name": "alexa-layouts",
      "version": "1.0.0"
    }
  ],
  "resources": [
    {
      "colors": {
        "myBlue": "#0022f3"
      }
    }
  ],
  "styles": {
    "textBlockStyle": {
      "fontSize": 24,
      "color": "@myBlue"
    }
  },
  "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

The properties in the top-level APL document object are:

Property Type Required Description
description String No An optional description of this document.
import Array of IMPORTS No A list of references to external APL packages.
layouts Map of LAYOUT No Custom complex components. See Layout.
mainTemplate LAYOUT Yes, in top-level documents The starting Layout.
resources RESOURCES No Resource definitions. See Resources.
styles Map of STYLES No A map of style definitions. See Styles.
type String Yes Must be "APL".
version String Yes Version string of the APL specification. Currently "1.0".

The mainTemplate property is required in a top-level APL document. This defines the layout that will be inflated and displayed first on the screen. The mainTemplate property is only used by the top-level APL document. A mainTemplate appearing in an imported package is ignored.

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:

Property Type Required Description
name String Yes The name of the Package to import
version String Yes The version of the Package to import.
source URL No If provided, a URL to download the package from.

Here is an example that uses the alexa-layouts package, and an external package.

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

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 a defined layout. This is the layout that will be inflated when the document is first instantiated on the screen.

The parameters defined in the mainTemplate will be bound to data sources provided in the 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.

resources

The resources property is an array of resource blocks.

styles

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

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.


Was this page helpful?

Last updated: Feb 29, 2024