Preview an APL Document

Use the Alexa Presentation Language (APL) authoring tool to preview how your document renders to your users.

For a visual response, you can see how the document looks on devices of different sizes and preview tap events, commands, video, and other aspects of the document. For an audio response, you can listen to the audio clip generated by the document.

Preview a visual response

For a visual response, you can view your document in different viewports as you build. Use live preview mode to further test tap events, commands, and other aspects of your document.

View your document in different viewports

Click the icons for the different viewports in the viewport toolbar. The viewports are organized by the type of device, and then viewport:

• Hub
  • Hub Round Small
  • Hub Landscape Small
  • Hub Landscape Medium
  • Hub Landscape Large
  • Hub Landscape Extra Large
  • Hub Portrait Medium
• TV
  • TV Landscape Extra Large
• Mobile
  • Mobile Small
  • Mobile Medium
  • Mobile Large
• Custom

To preview the document with a specific profile

• Click the device type, such as Hub, and then click the icon for the viewport you want to see, such as the Hub Landscape Medium icon.

For viewport profiles that support a size range, actual viewport sizes for popular devices display in a drop-down list 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. 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 the document with a specific device

• Select the device from the Device Presets menu in the upper right.

Viewport profile resources (viewport profiles package)

The viewports in the authoring tool correspond to the viewport profile resources available in the viewport profiles package:

• Hub Round Small – hubRoundSmall
• Hub Landscape Small – hubLandscapeSmall
• Hub Landscape Medium – hubLandscapeMedium
• Hub Landscape Large – hubLandscapeLarge
• Hub Landscape Extra Large – hubLandscapeXLarge
• Hub Portrait Medium – hubPortraitMedium
• TV Landscape Extra Large – tvLandscapeXLarge
• Mobile Small – mobileSmall
• Mobile Medium – mobileMedium
• Mobile Large – mobileLarge

For example, suppose your document uses a when statement on a component as shown in the following example.

{
  "type": "Text",
  "when": "${@viewportProfile == @hubLandscapeSmall}",
  "text": "Display this text on small, landscape hubs."
}

When you preview the document in the authoring tool and select Hub Landscape Small, the document displays this Text component. When you select any other profile, this Text component doesn't display.

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

Create and view a custom viewport

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

Custom viewports remain available while the document is open in the authoring tool. When you close the browser or navigate away from the open document, the custom viewports are deleted.

To create a custom viewport

1. In the top viewport toolbar, click Custom, and then click the plus (+) button.
2. Enter a name for the viewport, then enter the Width, Height, and Density.
3. Click the checkmark to save the custom viewport.

To preview your document in a custom viewport

1. In the top viewport toolbar, click Custom.
2. In the custom toolbar, click the name of the custom viewport to view.

Preview tap events, commands, and video

Use live preview mode to preview touch events, commands, video, and other aspects of document. Live preview mode disables the tools for authoring the document. Clicking in the preview pane triggers tap events as it would on a device. Live preview mode also displays a log window to show the output of the Log command.

Use live 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 tap event.
• APL and APL for audio integration – 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 live preview mode. For details, see Test the APL and APL for audio integration.
• Run onMount commands – The document-level onMount command automatically runs when you start live 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.
• Tap events – Click 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.

Live 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 live preview mode, use the Viewport profiles toolbar to preview in different viewports. Switching to a different viewport stops any running commands or video. When the document displays with the new viewport, the preview resets to the initial state of the document.

To open live preview mode

In the authoring tool, click Live Preview Mode.

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

Replay the preview

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

To exit live preview mode

Click Live Preview Mode again.

Debug a document with the log window

Use the log window to display logging messages sent with the Log command. This can be useful for debugging your document. To display the log window, click Live Preview Mode.

The log window displays an item each time the Log command runs. Each item displays:

• The time the command ran.
• The log level, as specified in the level property of the command.
• The log message, as specified in the message property of the command.
• The value the arguments property of the command.

The following image shows examples of all the available log levels.

To generate log messages, your document must run the Log command. Add the command to an event handler. The following example runs the Log command in three situations:

1. When the document onMount handler runs after the document inflates.
2. When the user clicks the button that runs the AutoPage command.
3. Each time the Pager changes pages.

• APL Document
• Data Sources

{
  "type": "APL",
  "version": "2024.2",
  "import": [
    {
      "name": "alexa-layouts",
      "version": "1.7.0"
    }
  ],
  "mainTemplate": {
    "parameters": [
      "pagerData"
    ],
    "items": {
      "type": "Container",
      "width": "100%",
      "height": "100%",
      "items": [
        {
          "type": "AlexaHeader",
          "headerTitle": "${pagerData.title}"
        },
        {
          "type": "Pager",
          "id": "myPager",
          "data": "${pagerData.colors}",
          "width": "50%",
          "height": "50%",
          "alignSelf": "center",
          "items": [
            {
              "type": "Frame",
              "borderWidth": 10,
              "background": "${data}",
              "item": {
                "type": "Text",
                "width": "100%",
                "height": "100%",
                "textAlign": "center",
                "textAlignVertical": "center",
                "text": "Page ${index+1} of ${pagerData.colors.length}."
              }
            }
          ],
          "onPageChanged": [
            {
              "type": "Log",
              "level": "info",
              "message": "Page has changed!",
              "arguments": [
                "New page index is ${event.source.page}"
              ]
            }
          ]
        },
        {
          "type": "AlexaButton",
          "buttonText": "Start AutoPage Command",
          "spacing": "@spacingMedium",
          "alignSelf": "center",
          "primaryAction": [
            {
              "type": "Log",
              "level": "info",
              "message": "User clicked the button!",
              "arguments": [
                "${event.source.type}"
              ]
            },
            {
              "type": "AutoPage",
              "componentId": "myPager",
              "transitionDuration": 2000,
              "duration": 2000
            }
          ]
        }
      ]
    }
  },
  "onMount": [
    {
      "type": "Log",
      "level": "debug",
      "message": "onMount fired!",
      "arguments": [
        "${event.source}"
      ]
    }
  ]
}

{
  "pagerData": {
    "title": "Log Command Example",
    "backgroundColor": "@colorYellow800",
    "colors": [
      "@colorYellow800",
      "@colorTeal800",
      "@colorGreen800",
      "@colorBlue800"
    ]
  }
}

Log messages remain in the log window until you either click Clear or exit the document.

Preview an audio response

To preview an audio response

1. In the authoring tool, click Preview button to generate the audio the first time.
2. Click Play to hear the audio response.
3. As you make changes to the JSON, click Refresh to re-generate the audio response with your changes.

After you generate the audio response, the authoring tool displays a time line that represents the audio. You can navigate this time line to play back portions of your response.

Test the APL and APL for audio integration

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. 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. Open the APL document for your visual response in the authoring tool.

2. 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 APL for audio documents

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

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

3. 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"
          }
        ]
      }
    }
   

4. 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"
    }
   

5. Click Preview Interactions and invoke the SpeakItem or SpeakList 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.

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

For details about RenderDocument see Alexa.Presentation.APL Interface Reference.

Related topics

• Build Documents in the Developer Console
• Create and Edit an APL Document

Last updated: Mar 11, 2024