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

Rulers and Device Presets — Toggle the rulers displayed around the viewport preview. The rulers provide shortcuts for different sized viewports within the same viewport profile. The Device Presets lets you select specific Alexa devices to preview.

4

Viewport profiles toolbar — Buttons to switch the preview pane between different viewport profiles. For viewport profiles that support a size range, actual viewport sizes for popular devices display under the viewport profile icons. Use these to verify that your APL document works in all the popular devices that fall within the viewport profile. You can also click on the breakpoints in the rulers to toggle between different viewports sizes.

5

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

6

Menu to push your document to a device associated with your Amazon developer account. Make sure the device name is displayed, then click the button to see your document on the physical device.

7

Components palette — Displays all the core APL components. 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 or layout.

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 to preview the document on different viewport profiles. The icons represent the viewport profiles available in the viewport profiles package:

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

For viewport profiles that support a size range, actual viewport sizes for popular devices display under the viewport profile icons. Use these to verify that your APL document works in all the popular devices that fall within the viewport profile. Click the size indicators (breakpoints) on the ruler to toggle between different viewport sizes. Make sure that your document works on the smallest width/height within a range but also responds to the largest width/height by filling out the extra space. To learn how to create responsive APL documents, see Build Responsive APL Documents.

Click alternate sizes or click the ruler breakpoints
Click alternate sizes or click the ruler breakpoints

To preview in a viewport that represents a specific device, select the device from the Device Presets menu in the upper right.

For more details about the properties of these viewport profiles, see Alexa Viewport Profiles Package.

Create a custom viewport

Create a custom viewport to see how your design looks on devices that are different from the provided profiles.

To create a custom viewport

  1. In the viewport toolbar, click the Custom and then select Add New.
  2. Change the properties of the custom viewport by setting the Width, Height, and Density.
  3. Click the New Viewport text and give the viewport a name, then click Save.

The custom viewport remains available during your current browser session. Access your custom viewports under the Custom menu. You can use the custom viewport with other documents in your skill as long as you remain within the same browser session.

When you close the browser, the custom viewports are deleted.

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 ).