Preview an APL Document

Note: Learn how to improve your skills with APL with Build visually rich experiences using APL at the Alexa Learning Lab.

Use the 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 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, 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

Note: The viewports represent devices with screens. There isn't a viewport that represents a device with a character display such as the Echo Dot with clock.

Viewports are organized by device type and then viewport

To preview the document with a specific profile

Click the device type, such as Hub, and then click the 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

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

To preview your document in a custom viewport

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

Preview tap events, commands, and video

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 tap 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 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 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 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 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 running 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 Preview Interactions 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 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 preview mode

Click the Preview Interactions again.

Preview an audio response

To preview an audio response

In the authoring tool, click Preview button to generate the audio the first time.
Click Play to hear the audio response.
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.

Audio time line displayed after you click Refresh — Audio time line displayed after you click Preview

UI Element	Description
	Refresh button – Click to regenerate the audio response. You must regenerate the response to reflect your changes to the JSON.
	Play button – Click to play back the response.
	Repeat button – Click to repeatedly play the entire response or a portion of the response. Click again to turn off the repeat.
	Audio response time line – Displays a wave form representing the audio response. You can click within the time line to listen to different parts of the response. To start playback from a different position or jump to a different position during playback, click in the time line. To select a portion of the response to play, click and drag in the time line. To move a previously-selected portion of the response to a different section of the time line, click and drag the selection. To clear a previously-selected portion of the response, click inside the selected area.

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

Open the APL document for your visual response 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 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": {}
     }
   }
 }
```

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

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

Last updated: Sep 12, 2022