Document (Character Displays)

An APL-T document is a JSON object with a well-defined structure. The document defines a template to display on a device with a character display (such as the Echo Dot with clock). The document controls the overall structure and layout. You send the document to the device with the Alexa.Presentation.APLT.RenderDocument directive.

Examples

A trivial APL-T document can inflate just a single component. It will be drawn in top-left corner of the display:

{
  "type": "APLT",
  "version": "1.0",
  "mainTemplate": {
    "items": [
      {
        "type": "Text",
        "text": "HI."
      }
    ]
  }
}

A richer APL-T document includes multiple components that may be nested:

{
  "type": "APLT",
  "version": "1.0",
  "description": "This is a more complex example",
  "layouts": {},
  "resources": [],
  "mainTemplate": {
    "items": [
      {
        "id": "myPager",
        "type": "Pager",
        "items": [
          {
            "type": "Text",
            "text": "P9: 1"
          },
          {
            "type": "Text",
            "text": "P9: 2"
          }
        ]
      }
    ]
  },
  "onMount": {
    "type": "AutoPage",
    "componentId": "myPager",
    "delay": 500,
    "count": 2,
    "duration": 500
  },
  "settings": {
    "idleTimeout": 10000
  }
}

Properties

The following table summarizes the top-level properties in an APL-T document object.

Property Type Required Description
description String No An optional description of this document
layouts Map No Custom layouts (Layout)
mainTemplate Array of Components Yes The starting layout
onMount Array of commands No Command to run when the document is first displayed
resources Array of resources No Resource definitions (Resources)
settings Map No Document-wide settings
type "APLT" Yes Must be "APLT"
version "1.0" Yes Version string of the APL-T specification. Currently "1.0"

mainTemplate

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 provided by the RenderDocument directive that initiated the display of the APL-T document. For more information, refer to the RenderDocument directive for APL-T interface.

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 document is first displayed on the screen, the following sequence of actions is followed:

  1. Run in parallel all of the onMount component 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>"
}

settings

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

Property Type Default Description
idleTimeout Number <system> Time before document closes due to inactivity

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

{
  "type": "APLT",
  "version": "1.0",
  "settings": {
    "idleTimeout": 120000
  }
}

idleTimeout

Recommended time in milliseconds that the document should be kept 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. Refer to lifecycle_section for a discussion of the document lifecycle.

version

The version property specifies the version of the APL-T specification that the APL-T document uses. The version property is used by the APL-T rendering engine to identify required features and ensure rendering accuracy. It is the responsibility of the author of an APL-T document to ensure that the version property is correctly set.

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

Was this page helpful?

Last updated: May 10, 2024