Experiment with APL Examples in the Authoring Tool

The Alexa Presentation Language topics in the documentation include JSON examples that illustrate how to build APL documents and data sources. You can copy these examples into the APL authoring tool to see how they work and experiment with your own changes. You don't need a working skill to test most of these examples.

About the APL code examples

Examples that show complete APL documents include two parts: the APL document, and a data source. You must copy both of these parts to the authoring tool to see the example in action.

Longer examples are collapsed on the page. Click the button for the example to expand the code.

For example, you might see buttons like the following. Click Example document: AlexaHeadline example to see the full document. See Data source: headlineExampleData to see the full data source.

Example document: AlexaHeadline example  

{
  "type": "APL",
  "version": "2024.2",
  "import": [
    {
      "name": "alexa-layouts",
      "version": "1.7.0"
    }
  ],
  "mainTemplate": {
    "parameters": [
      "headlineExampleData"
    ],
    "items": [
      {
        "type": "Container",
        "height": "100vh",
        "items": [
          {
            "type": "AlexaHeadline",
            "backgroundImageSource": "${headlineExampleData.backgroundImage}",
            "headerAttributionImage": "${headlineExampleData.logoUrl}",
            "primaryText": "${headlineExampleData.textContent.primaryText}",
            "secondaryText": "${headlineExampleData.textContent.secondaryText}",
            "footerHintText": "${headlineExampleData.properties.hintText}"
          }
        ]
      }
    ]
  }
}

Data source: headlineExampleData  

{
  "headlineExampleData": {
    "type": "object",
    "backgroundImage": "https://d2o906d8ln7ui1.cloudfront.net/images/BT6_Background.png",
    "logoUrl": "https://d2o906d8ln7ui1.cloudfront.net/images/cheeseskillicon.png",
    "textContent": {
      "primaryText": "Welcome to The Daily Cheese",
      "secondaryText": "Today's cheese is gouda."
    },
    "properties": {
      "hintText": "What is today's cheesy joke?"
    },
    "transformers": [
      {
        "inputPath": "hintText",
        "transformer": "textToHint"
      }
    ]
  }
}

The APL documentation includes both full document examples and smaller code snippets. To determine whether an example is a full document, note whether it has a type property set to APL. Full document examples always include this property.

Copy a full document and data source to the authoring tool

The APL authoring tool lets you build an APL document and its associated data source, then preview how it looks on different viewports. When you open the authoring tool from a skill in the developer console, you can save your APL documents with the skill so you can return them later.

For details about using the tool, see Build Documents in the Developer Console.

A full document always begins with a type property set to APL.

To copy a full document into the authoring tool

1. On the documentation page, expand the example code if necessary.

2. Click the Copy code button.

   

3. In another browser window, open the developer console.
4. Open an existing skill or create a new skill. The skill does not need to have a working endpoint to use the authoring tool.

5. In the left-hand navigation, click Multimodal Responses.

   The authoring tool opens in a new window or tab, and displays any existing documents saved with this skill.

6. Click Visual.
7. Click Create Visual Response.
8. Click Blank Document. This creates a new, blank APL document and data source.
9. Click Code View.

10. Delete all the existing JSON code from the edit pane, then paste in the code copied in step 2.

    The preview pane might show a blank document, because the data is missing.

11. Copy in the data source as described next.

The data source for a document usually follows the document in the topic. The JSON is an object with one or more key/object pairs. For example, the following data source is called headlineExampleData:

{
  "headlineExampleData": {
    "property": "value"
  }
}

To copy a data source into the authoring tool

1. On the documentation page, expand the data source example if necessary.
2. Click the Copy code button.
3. Navigate back to the authoring tool and return to the APL document created earlier.
4. In the toolbar, click the DATA button ( )
5. Delete the existing contents from the edit pane, then paste in the code copied in step 2.

At this point, you should see the full document in the preview pane. Experiment with changing the components and data to learn how the sample works.

Use the authoring tool live preview mode

For some APL features, you must use the authoring tool live preview mode to see preview the feature. Click Live Preview Mode to start preview mode. For details about features the authoring tool supports, see Preview tap events, commands, and video.

Related topics

• Display Text on the Screen
• Combine Content with Backgrounds, Borders, and Headers
• Add Visuals and Audio to Your Skill

Last updated: Mar 11, 2024