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
• Create and edit APL documents
• Build the document with components and data
• Preview your document
• Test the APL for Audio transformer
• View your document in different viewports
• Save the document with a skill
• Export the document and data source
• Related topics

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, the authoring tool displays an approximation of how the document renders on a device with a screen. You can also preview touch events and commands.

You save your document with your skill. 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 Multimodal Responses.

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

3. Click Visual. The authoring tool filters the list of documents to display visual responses previously saved with the skill.

4. Click Create Visual Response.
5. 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.

6. Update and preview the document as described in Build the document with components and data and View your document in different viewports.
7. In the upper-right corner, click Save ( ) to save the document with your skill.
8. Click Export ( ) 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 Multimodal Responses.

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

3. Click Visual.

   The authoring tool filters the list of documents to display visual responses previously saved with the skill.

4. 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 might have used in the past 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 JSON file to upload must have the following structure:

{
  "document": {},
  "datasources": {
    "dataSourceName": {}
  },
  "sources": {
    "sourceName": {}
  }
}

For example, the following JSON file imports a document without any data sources or sources.

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

This example illustrates a file with both document and datasource properties.

{
  "document": {
    "type": "APL",
    "version": "1.5",
    "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\""
    }
  }
}

This example shows a document with a data source and sources for testing with an APL for Audio document.

JSON structured to import into authoring tool

{
  "document": {
    "type": "APL",
    "version": "1.5",
    "settings": {},
    "theme": "dark",
    "import": [
      {
        "name": "alexa-layouts",
        "version": "1.2.0"
      }
    ],
    "resources": [],
    "styles": {},
    "onMount": [],
    "graphics": {},
    "commands": {},
    "layouts": {},
    "mainTemplate": {
      "parameters": [
        "payload"
      ],
      "items": [
        {
          "type": "Container",
          "height": "100%",
          "width": "100%",
          "alignItems": "center",
          "justifyContent": "center",
          "items": [
            {
              "type": "AlexaButton",
              "alignSelf": "center",
              "buttonText": "Play the SSML to Speech!",
              "speech": "${payload.helloData.properties.ssmlHelloSpeech}",
              "primaryAction": [
                {
                  "type": "SpeakItem"
                }
              ],
              "spacing": "@spacingLarge"
            },
            {
              "type": "AlexaButton",
              "alignSelf": "center",
              "buttonText": "Play the APLA to Speech!",
              "speech": "${payload.helloData.properties.aplaHelloSpeech.url}",
              "primaryAction": {
                "type": "SpeakItem"
              },
              "spacing": "@spacingLarge"
            }
          ]
        }
      ]
    }
  },
  "datasources": {
    "helloData": {
      "properties": {
        "testSSMLSpeech": "<speak>This is normal SSML speech using the original transformer.</speak>",
        "user": {
          "name": ""
        }
      },
      "transformers": [
        {
          "inputPath": "testSSMLSpeech",
          "outputName": "ssmlHelloSpeech",
          "transformer": "ssmlToSpeech"
        },
        {
          "template": "helloApla",
          "outputName": "aplaHelloSpeech",
          "transformer": "aplAudioToSpeech"
        }
      ]
    }
  },
  "sources": {
    "helloApla": {
      "version": "0.9",
      "type": "APLA",
      "mainTemplate": {
        "parameters": [
          "payload"
        ],
        "item": {
          "type": "Mixer",
          "items": [
            {
              "type": "Selector",
              "items": [
                {
                  "type": "Speech",
                  "when": "${payload.helloData.properties.user.name == ''}",
                  "content": "Hello! I don't know your name, but welcome to A.P.L.A anyway!"
                },
                {
                  "type": "Speech",
                  "content": "Hi ${payload.helloData.properties.user.name}! Welcome to A.P.L.A!"
                }
              ]
            },
            {
              "type": "Sequencer",
              "items": [
                {
                  "type": "Audio",
                  "source": "soundbank://soundlibrary/scifi/amzn_sfx_scifi_radar_low_01"
                },
                {
                  "type": "Audio",
                  "source": "soundbank://soundlibrary/scifi/amzn_sfx_scifi_radar_low_01"
                }
              ]
            }
          ]
        }
      }
    }
  }
}

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.

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

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.

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

Preview your document

Use preview mode to preview touch events, commands, video, and other aspects of document. Preview mode disables the tools for authoring the document. Clicking in the preview pane triggers touch events as it would on a device.

Use preview mode to test the following:

• Commands – Test any commands triggered within the document. For example, test a SpeakItem command triggered by onMount or a touch event.
• APL for Audio Transformer – Your document can use the APL for Audio transformer (aplAudioToSpeech) to convert an APL for Audio document into audio for use with the SpeakItem or SpeakList command. You can test this integration in the authoring tool in preview mode. For details, see Test the APL for Audio transformer.
• Execute onMount – The document-level onMount command automatically runs when you start preview mode, as it does when the document loads on a device. Any component-level onMount commands also run when the component is displayed.
• Video playback – The Video component plays as it does on a device.
• Transformers – Transformers work as they do on a device.
• Touch events – Click on the touchable areas of your document to select an item.
• Navigation – For a Pager component, click and drag in the document to "swipe" through pages. For Sequence and ScrollView components, use a mouse scroll wheel to scroll the content.

Preview mode doesn't support testing the SendEvent command. To test SendEvent, use a device or the simulator and test your document within the skill.

As you test in preview mode, use the Viewport profiles toolbar to preview in different viewports. Switching to a different viewport stops any executing commands or video. When the document displays with the new viewport, the preview resets to the initial state of the document.

To open preview mode

In the authoring tool, click the Enter Preview Mode button ( ) in the upper-right corner.

The authoring tool disables the editing controls, displays a preview of your document, and runs any applicable onMount commands.

Replay the preview

Click the Replay button to restart preview mode. Replay stops any executing commands or video and then resets the preview to the initial state of the document. For example, this re-executes any document-level onMount commands and resets any Pager components to display the configured initial page.

To exit preview mode

Click the Exit Preview Mode button ( ) in the upper right corner.

Test the APL for Audio transformer

The aplAudioToSpeech transformer converts an APL for Audio document into audio you can bind to the speech property of an APL component. You can then use the SpeakList or SpeakItem command to play that audio.

When you use the aplAudioToSpeech transformer in your skill, you must provide an APLA document for the audio in the sources property of the RenderDocument directive. The SOURCES section of the authoring tool simulates this property. You fill in this section with the same object you would provide in sources. This lets you test commands that depend on the output of the transformer aplAudioToSpeech transformer.

To test the APL for Audio transformer in the authoring tool

1. In the authoring tool, click SOURCES. Provide the same JSON object you would include in the sources property of RenderDocument. This is a JSON object containing a map of APLA documents

   For example, the following JSON in SOURCES creates a mapping between "helloApla" and an APLA document (details removed for brevity).

    {
      "helloApla": {
        "version": "0.9",
        "type": "APLA",
        "mainTemplate": {
          "parameters": [
            "payload"
          ],
          "item": {}
        }
      }
    }
   

2. In the DATA section, paste or create your data source. Include the aplAudioToSpeech transformer. Set the template field of the transformer to the key you defined for your APLA document in the SOURCES section.

    {
      "helloData": {
        "properties": {
          "user": {
            "name": ""
          }
        },
        "transformers": [        
          {
            "template": "helloApla",
            "outputName": "aplaHelloSpeech",
            "transformer": "aplAudioToSpeech"
          }
        ]
      }
    }
   

3. In your APL document, bind the speech property of a component to the output of the aplAudioToSpeech transformer. Set the SpeakItem or SpeakList command to target that component.

   In this example, the outputName is aplaHelloSpeech. Therefore, the generated audio is payload.helloData.properties.aplaHelloSpeech.url.

    {
      "type": "AlexaButton",
      "alignSelf": "center",
      "buttonText": "Play the APL Audio!",
      "speech": "${payload.helloData.properties.aplaHelloSpeech.url}",
      "primaryAction": {
        "type": "SpeakItem"
      },
      "spacing": "@spacingLarge"
    }
   

4. Start preview mode ( ) and invoke the command. The authoring tool generates the APLA audio and plays it as a device.

For details about setting up and using the aplAudioToSpeech transformer, see Transformers.

For details about building APL for Audio documents, see APL for Audio Reference.

You can adjust the APL for Audio document in the SOURCES section as needed, then update your skill's RenderDocument response to return the revised document.

To incorporate changes in your skill

1. Export your document. This creates a JSON file with the document, datasources, and sources top-level properties.
2. Update your skill code to return a RenderDocument directive with same three top-level properties. For details about RenderDocument see Alexa.Presentation.APL Interface Reference.

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

You can switch between viewports when authoring and in preview mode.

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.

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 ( ).
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 Multimodal Responses.
3. Click Visual.
4. 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 Multimodal Responses.
3. Click Visual.
4. In the list of documents, find the document to copy, and then click Clone.

5. From the drop-down list, select the Skill, and then click Clone.

   Tip: To duplicate the document and save it in the same skill, leave the Skill drop-down set to Current Skill.

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, datasources, and sources properties. If you make changes outside of the authoring tool, you can re-import this file later.

To use your document in your skill code

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

You can also provide a link to your document when you return RenderDocument. Linking to the response instead of embedding the response in your code simplifies the code and lets a skill designer work on the response in the authoring tool independently of the code.

A link to a document in the authoring tool has the following syntax:

• APL – doc://alexa/apl/documents/<document-name>
• APL for Audio – doc://alexa/apla/documents/<document-name>

For details about linking to a document for a visual response, see Use a linked document with RenderDocument (Alexa.Presentation.APL).

For details about linking to a saved document for an audio response, see Update your skill to use a linked document (Alexa.Presentation.APLA).

Related topics

• Understand Alexa Presentation Language
• Use APL with the ASK SDK v2
• APL Document
• How to Build a Multimodal Alexa Skill