Construct an APL document with the Authoring Tool

The APL Authoring Tool lets you build an APL document and preview how it looks. You can build a document from scratch or start from a sample template. When finished, you can export the JSON code for your document to use within your skill.

See also Understand Alexa Presentation Language.

Understand the APL authoring tool

The authoring tool lets you create and preview APL documents. You can build your document visually or edit the JSON directly. As you build, you can view an approximation of how the document will appear on a device with a screen.

You can then save these documents with your skill so that you can access them later. To use the document in a skill, you need to copy or export the JSON code and then include the JSON as part of the RenderDocument) directive.

Create and edit APL documents

Normally, you create a new document from within an existing skill. You can then save the document with the skill and return to it later for edits. You can create your document from a sample template, from scratch, or by uploading an existing document.

To create a new document for a specific skill

  1. In the developer console, open the skill for which you want to create this document.
  2. In the left-hand navigation, click Display. This opens the authoring tool in a new window or tab and displays any existing documents saved with this skill.
  3. Click Create Template.
  4. Do one of the following:
    • To use a sample template as a starting point, click one of the templates. See Sample templates.
    • To start from a completely blank document and build your own, click Start from scratch.
    • To import an existing JSON document from your computer, click Upload Code and choose the file to import. See Format for importing documents and data.

    Regardless of the option you choose, the new document opens in the authoring tool.

  5. Update and preview the document as described in Build the document with components and data and View your document in different viewports.
  6. Click the Save icon (Save icon ) to save the document with your skill.
  7. Use the Export icon (Export Code button ) to export the JSON for your document to use in the RenderDocument directive in your skill code.

To edit an existing document saved with a specific skill

  1. In the developer console, open the skill the document was saved with.
  2. In the left-hand navigation, click Display. This opens the authoring tool in a new window or tab and displays any existing documents saved with this skill.
  3. Click Edit for the document to open.

Sample templates

The sample templates available in the authoring tool are based on the display templates that you may have used previously to build Alexa skills with screen content. For example, the Long Text Sample is similar to BodyTemplate1.

Each template uses a data source to provide the content displayed within the layout. Click DATA to see the data source. For example, BodyTemplate1 includes background images, text content, and a logo URL image reference. You can modify the content of this data JSON to see how the template displays different content.

Each template defines resources and styles that are then used within the mainTemplate for the document. To see these, look at the JSON for the full document, or click Resources or Styles in the left-hand toolbar.

See Build the document with components and data, later, for more about navigating the authoring tool interface.

Format for importing documents and data

When you import a document with the Upload Code option, the authoring tool expects the document to be within a single top-level "document" property, like this (details have been removed for brevity):

{
  "document": {
    "type": "APL",
    "version": "1.2",
    "theme": "dark",
    "import": [],
    "resources": [],
    "styles": {},
    "layouts": {},
    "mainTemplate": {
      "parameters": [
        "payload"
      ],
      "items": [
      ]
    }
  }
}

You can also include a data source with your import. APL documents often use separate data sources to separate the template design from the data displayed. To include a data source when you upload code, combine the JSON for your document and your data into a single JSON file with two top-level properties: document and datasources. This is similar to the output you get when you download the code for a template from the authoring tool.

This example shows the overall structure of the file to upload (details have been removed for brevity):

{
  "document": {
    "type": "APL",
    "version": "1.2",
    "theme": "dark",
    "import": [],
    "resources": [],
    "styles": {},
    "layouts": {},
    "mainTemplate": {
      "parameters": [
        "payload"
      ],
      "items": []
    }
  },
  "datasources": {
    "bodyTemplate7Data": {
      "type": "object",
      "objectId": "bt7Sample",
      "title": "Today's Daily Photo of Cheese",
      "backgroundImage": {},
      "image": {},
      "logoUrl": "https://d2o906d8ln7ui1.cloudfront.net/images/cheeseskillicon.png",
      "hintText": "Try, \"Alexa, search for blue cheese\""
    }
  }
}

Alternatively, you can also paste or create your data source directly in the authoring tool.

Build the document with components and data

The core areas of the authoring tool are visible all the time.

Main authoring tool interface
Main authoring tool interface
Description

1

Left-hand toolbar: Switch between a graphical view of your document's components, the JSON code for the document, and the JSON data source.

2

Top toolbar: Buttons to save and export the document.

3

Document preview pane: Displays an approximation of how your document looks on different viewports.

4

Viewport toolbar: Buttons to switch the preview pane between different viewports. You can also push your document to a device associated with your Amazon developer account.

5

Components palette: Displays all the core APL components you can add to your document. You can drag components from this palette onto the display shown in the preview pane to build your document.

The following table summarizes the options on the left-hand toolbar.

Toolbar button Description

GUI

Displays the Layouts pane, which provides a graphical view of your document's components.

APL

Displays JSON code for the entire document. See APL Document for the full syntax.

DATA

Displays the JSON code for your data sources. See APL Data Sources.

STYLES

Displays the JSON code for the styles property of the document. See APL Style Definition and Evaluation.

DOCUMENT

Displays the JSON code for the import property, as well as additional top-level Document properties.

RESOURCES

Displays the JSON code for the resources array. See APL Resources.

GRAPHICS

Displays the JSON code for the graphics property. This can contain a collection of Alexa Vector Graphics that you can use within your document.

SETTINGS

Displays the JSON code for the settings property. This can contain a set of key-value pairs that define document-wide settings.

COMMANDS

Displays the JSON code for the commands property. This can contain a set of user-defined commands that you can use within your document.

ONMOUNT

Displays the JSON code for the onMount property. This contains an array of commands to execute when the document initially displays on the screen.

Edit your document with the Layouts pane (GUI)

The GUI option in the toolbar displays the Layouts pane, which displays your components and layouts in a hierarchical view. The mainTemplate is shown first, followed by any custom layouts defined in the layouts property. You can drag the components within the Layouts pane to re-arrange the hierarchy.

Authoring tool Layouts pane
Authoring tool Layouts pane
Description

1

Layouts: See all the components in your document in a hierarchical view. Select a component and click the plus to add a child component to the hierarchy.

2

Component properties form: Fill in the properties for the selected component.

To add a component to mainTemplate or a custom layout

  1. In the Layouts pane, select the component that should be the parent of the new component. You must select a component that can contain child components, such as mainTemplate or Container.
  2. Click the "+" button shown in the upper-right corner of the pane.
  3. Select the Component and click Add. If your document includes any custom layouts, you can also choose a layout instead of a component.
  4. In the pane to the right, edit the properties of the new component.

To create a custom layout

  1. In the Layouts pane, select mainTemplate.
  2. Click the "+" button shown in the upper-right corner of the pane.
  3. In the drop-down list, select Create a Custom Layout.
  4. Enter the Custom Layout Name and click Add.
  5. Add components to the new layout as needed.

To update the properties for a component

  • Select the component in th hierarchy, then edit the property values in the pane next to the Layouts pane.

View and edit the JSON for your document (APL)

The APL option in the toolbar displays the JSON for the full document. The JSON editor provides basic validation for JSON syntax errors, such as misplaced commas. The editor also shows warnings if you include properties that do not belong on a component.

Use the additional buttons in the toolbar to view and edit the JSON for specific parts of the document, such as the styles and resources properties.

View and edit the data source for your document (DATA)

The DATA option in the toolbar displays the JSON for your data sources. Each data source must be a top-level property within the curly brackets ({}) and must have the name you use to reference the data source properties in your data-binding expressions.

For example, this is a valid data source:

{
  "bodyTemplate7Data": {
    "type": "object",
    "objectId": "bt7Sample",
    "title": "Today's Daily Photo of Cheese",
    "backgroundImage": {},
    "image": {},
    "logoUrl": "https://d2o906d8ln7ui1.cloudfront.net/images/cheeseskillicon.png",
    "hintText": "Try, \"Alexa, search for blue cheese\""
  }
}

Assuming that the mainTemplate.parameters array in your document contains "payload", you can reference properties in this data source like this: ${payload.bodyTemplate7Data.title}.

As you change the data, the preview pane updates to show how your template looks with the updated data.

Build your document with drag and drop

You can edit your document visually by clicking and dragging components in the document preview pane:

  • Click a component in the components palette and drag it to the document.
  • When you drag a Text, Image, or Video component to an empty preview, the authoring tool automatically puts the component inside a Container.
  • Select GUI in the toolbar and click a component in the Layouts pane to highlight that component on the preview.
  • Drag components within the preview to rearrange them.

View your document in different viewports

As you work on your document, click the icons for the different viewports in the viewport toolbar to see how the document looks on different devices. You can preview with five viewports that correspond to the viewport profiles available in the viewport profiles package:

  • Small Hub (Round)
  • Small Hub (Landscape)
  • Medium Hub
  • Large Hub
  • Extra Large TV

For more about the properties of these viewports, see Alexa Viewport Profiles Package.

You can also create a custom viewport, as described later.

Note that the viewports represent screen devices. There is not a viewport that represents a device with a character display such as the Echo Dot with clock.

Create a custom viewport

You can create a custom viewport to see how your design looks on devices that are different from the five provided profiles.

  1. Click the plus icon.
  2. Change the properties of the viewport that you want to view. You can set the Shape, Pixel Width, Pixel Height, and Pixel Density.
  3. Click Apply.

The custom viewport remains available during your current browser session. If you close the browser and then later re-open the authoring tool, you need to re-create the custom viewport.

Save the document with a skill

You can save your document with a skill so that you can return to it later. This just saves your work for later but does not associate the document with your skill's back end. You need to export the JSON to use it within your skill code.

Be sure to open the authoring tool from the skill where you want to save the document.

Save the document and data source

  1. Click the Save button (Save icon ) in the upper-right corner.
  2. If prompted, enter a name for the document.
  3. If your document is not already associated with a skill, you need to also select the skill from the drop-down list.

    This occurs if you opened the authoring tool with the direct link (https://developer.amazon.com/alexa/console/ask/displays/?) rather than from within a skill.

Open a previously saved document

  1. Open the skill where you saved the document.
  2. Click Displays.
  3. In the list of documents, find the document to open and click Edit.

Clone a document

  1. Open the skill where you saved the document.
  2. Click Displays.
  3. In the list of documents, find the document to copy and click Clone.
  4. Select the Skill from the drop-down list and click Clone.

Export the document and data source

To use your document in your skill code, click the Export Code button (Export Code button ).

This combines the document and data in a single JSON file with top-level document and datasources properties. If you make changes outside of the authoring tool, you can re-import this file later.