Create and Edit an APL Document

An APL document is a JSON structure that defines a template for a skill response. The document can define either a visual response or an audio response.

Use the authoring tool to create an APL document from a pre-built template, from a Lottie animation, or from a blank document.

Create and manage APL documents

Within the authoring tool, you can create visual responses and audio responses.

  • A visual response uses the APL document format. When you send the document to Alexa with the RenderDocument directive, Alexa displays the content on the device.
  • An audio response uses the APLA document format. When you send the document to Alexa with the RenderDocument directive, Alexa plays the audio generated by the document.

The following procedures show how to create visual and audio responses in the authoring tool.

To create a new visual response

  1. In the developer console, open the skill for which you want to create this document.
  2. In the left-hand navigation, click Multimodal Responses.
  3. Click Visual. The authoring tool filters the list of APL documents to display visual responses previously saved with the skill.

  4. Click Create Visual Response.
  5. Choose how you want to create your document:
    • To start from a sample template, find the template in either the Responsive Templates or Explore APL section. Click the template you want to use. For information about the templates, see Use a pre-built template.
    • To start from a blank document and build your own, click Blank Document.
    • To import an existing JSON document click Upload. For details about how to format your document for upload, see Import an APL document from a JSON file.
    • To import an existing Lottie animation, click Upload. For details about how to convert a Lottie animation to an APL animation, see Import a Lottie Animation.

    The new document opens in the authoring tool.

  6. Update and preview your document. See the following:
  7. In the upper-right corner, click Save (Save icon ) to save the document with your skill. When prompted, enter a name for the document.

To create a new audio response

  1. In the developer console, open the skill for which you want to create this document.
  2. In the left-hand navigation, click Multimodal Responses.
  3. Click Audio. The authoring tool filters the list of APL documents to display audio responses previously saved with the skill.

  4. Click Create Audio Response.
  5. Update and preview your document. See the following:
  6. In the upper-right corner, click Save (Save icon ) to save the document with your skill. When prompted, enter a name for the document.

To manage existing documents

  1. In the developer console, open the skill that the document was saved to.
  2. In the left-hand navigation, click Multimodal Responses.

    The authoring tool opens in a new window or tab, and displays the Audio filter.

  3. Click either Audio or Visual to see the list of existing documents.
  4. From the list of documents, click the link for the action you want to do:
    • Edit – Open the document in the authoring tool.
    • Clone – Make a copy of the document in the same skill.
    • Delete – Delete the document.
    • Download – Download a JSON file with the document, datasources, and sources. This is equivalent to exporting the document. For details, see Import and Export APL Documents.

Use a pre-built template

For a visual response, the authoring tool provides a library of sample documents you can use as a starting point. These templates are organized into the following sections:

  • Responsive templates – Full screen templates that look good on different devices with screens. For example, the Text List template presents a scrolling list of text items with a background and header. You provide the content to display in a data source.
  • Explore APL – Additional templates that illustrate more designs and APL possibilities.

Each responsive template uses a data source to provide the content displayed in the layout. After you select a template, click DATA to see the data source. For example, Text List includes a background image and the list items. Modify the content of the data source JSON to see how the template displays different content.

For more information about navigating the authoring tool interface, see Build a visual response.

Library of responsive templates and APL examples
Library of responsive templates and APL examples

Build a visual response

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 and the JSON code view for the document and the data sources.

2

Top toolbar — Buttons to preview, save, and export the document.

3

Viewport profiles toolbar — Buttons to switch the preview pane between different viewport profiles. Viewports are organized by device type (such as "Hub" and "Mobile") and then viewport (such as "Medium Hub"). Select specific example devices from the drop down list. For more details, see Preview a visual response.

4

Size range drop-down list — For viewport profiles that support a range of sizes, this list displays sizes of popular devices within the range.

5

Document preview pane — Displays an approximation of how your document looks on different viewports. When in normal authoring mode, click on the preview pane to select components. You can also drag components to change your design. To test touch events and commands, switch to preview mode. For more details, see Preview a visual response.

6

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.

7

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.

Toolbar buttons

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. For the full syntax, see APL Document.

DATA toolbar button

DATA — Displays the JSON code for your data sources. For the full syntax of a data source, see APL Data Sources.

SOURCES toolbar button

SOURCES — Displays the JSON code for sources required to test the aplAudioToSpeech transformer with your document. See Test the APL for Audio transformer.

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

Select a component or layout in the pane to highlight it on the preview pane.

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.

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. You can also click a component in the preview pane to highlight it in Layouts
  • Drag components within the preview to rearrange them.

Build an audio response

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

Authoring tool for an audio response
Authoring tool for an audio response
UI element Description

1

Left-hand toolbar – Buttons to switch between the JSON code for the document and the data sources.

2

Top toolbar – Buttons to save and export the document.

3

Edit pane – Pane for editing the JSON code for the document and the data sources.

4

Preview button / Preview controls – Buttons for previewing the audio. For details about previewing an audio response, see Preview an audio response.

Toolbar buttons

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

Toolbar button Description

APLA icon

APLA – Displays JSON code for the entire document. For the full syntax, see Document (APL for Audio).

DATA toolbar button

DATA – Displays the JSON code for your data sources.

After you update the JSON code for your APL for audio document, you can generate and preview the audio. For details, see Preview an audio response.

Edit the JSON code for the document and data sources

The authoring tool includes JSON editors for the document and for the data sources.

The JSON editor provides basic validation for JSON syntax errors, such as misplaced commas. For a visual response, the editor also shows warnings if you include properties that don't belong on a component.

JSON editor for the document

APL icon APLA icon

The APL or APLA toolbar button displays the JSON for the full document.

For a visual response, you can also use the additional toolbar buttons to view and edit the JSON for specific parts of the document, such as the styles and resources properties.

For the full syntax for an APL document, see the following:

JSON editor for the data sources

DATA icon

The DATA toolbar button displays the JSON for the data sources for the document. Use this editor to build a JSON structure that your document can access with data binding.

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 for a visual response.

{
  "headlineTemplateData": {
    "type": "object",
    "objectId": "headlineSample",
    "properties": {
      "backgroundImage": {
        "contentDescription": null,
        "smallSourceUrl": null,
        "largeSourceUrl": null,
        "sources": [
          {
            "url": "https://d2o906d8ln7ui1.cloudfront.net/images/templates_v3/headline/HeadlineBackground_Dark.png",
            "size": "large"
          }
        ]
      },
      "textContent": {
        "primaryText": {
          "type": "PlainText",
          "text": "Welcome to The Daily Plant Facts"
        }
      },
      "logoUrl": "https://d2o906d8ln7ui1.cloudfront.net/images/templates_v3/logo/logo-modern-botanical-white.png",
      "hintText": "Try, \"Alexa, what is the plant fact of the day?\"",
      "welcomeSpeechSSML": "<speak><amazon:emotion name='excited' intensity='medium'>Welcome to The Daily Plant Facts</amazon:emotion></speak>"
    },
    "transformers": [
      {
        "inputPath": "welcomeSpeechSSML",
        "transformer": "ssmlToSpeech",
        "outputName": "welcomeSpeech"
      }
    ]
  }
}

Assuming that the mainTemplate.parameters array in your document contains payload, you can reference properties in this data source with the following syntax: ${payload.headlineTemplateData.properties.textContent.primaryText.text}.

When you send the document to Alexa with the RenderDocument directive, your skill code must build out and include the data sources as part of RenderDocument in the datasources property. Alexa doesn't use the data sources saved in the authoring tool when rendering the actual response from a skill.

For more about data sources and data binding, see the following: