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.

For more information, see 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 must 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.

    The authoring tool opens 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 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. In the upper-right corner, click Save (Save icon ) to save the document with your skill.
  7. Click Export (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 that the document was saved with.
  2. In the left-hand navigation, click Display.

    The authoring tool opens 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. To see these resources and styles, look at the JSON for the full document or click Resources or Styles in the left-hand toolbar.

For more information about navigating the authoring tool interface, see Build the document with components and data.

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. The following example illustrates the required import format, with details removed for brevity.

{
  "document": {
    "type": "APL",
    "version": "1.3",
    "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 combined file is similar to the output you get when you download the code for a template from the authoring tool.

The following example shows the overall structure of the file to upload both a document and data source, with the details removed for brevity.

{
  "document": {
    "type": "APL",
    "version": "1.3",
    "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
UI element 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 toolbar button

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

APL toolbar button

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

DATA toolbar button

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

STYLES toolbar button

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

DOCUMENT toolbar button

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

RESOURCES toolbar button

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

GRAPHICS toolbar button

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

SETTINGS toolbar button

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

COMMANDS toolbar button

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

ONMOUNT toolbar button

ONMOUNT — Displays the JSON code for the onMount property. This code can contain 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 pane shows the mainTemplate first, followed by any custom layouts defined in the layouts property. You can drag the components within the Layouts pane to rearrange the hierarchy.

Authoring tool Layouts pane
Authoring tool Layouts pane
UI element Description

1

Layouts — See all the components in your document in a hierarchical view. Select a component, and then click the “+” button 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. In the upper-right corner of the pane, click the "+" button.
  3. Select the Component, and then 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. In the upper-right corner of the pane, click the "+" button.
  3. In the drop-down list, select Create a Custom Layout.
  4. Enter the Custom Layout Name, and then click Add.
  5. Add components to the new layout as needed.

To update the properties for a component

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

View and edit the JSON for your document (APL)

The APL toolbar button (APL icon ) 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 don't belong on a component.

Use the additional toolbar buttons 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 toolbar button (DATA icon ) 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.

The following example shows 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 then 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 below the document preview pane 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 information about the properties of these viewports, see Alexa Viewport Profiles Package.

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

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.

To create a custom viewport

  1. In the viewport toolbar below the document preview pane, click the + button.
  2. Change the properties of the custom viewport by setting 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 reopen the authoring tool, you must recreate 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 action just saves your work for later but doesn't associate the document with your skill's Lambda function or web service. You must 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. In the upper-right corner, click Save (Save icon ).
  2. If prompted, enter a name for the document.
  3. If your document isn't already associated with a skill, you must also select the skill from the drop-down list.

    Your document isn't associated with a skill 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 then 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 then click Clone.
  4. From the drop-down list, select the Skill, and then click Clone.

Export the document and data source

When you export your document and data source, the action 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 reimport this file later.

To use your document in your skill code

  • In the upper-right corner, click the Export Code button (Export Code button ).