APL Authoring Tool

See also APL Overview.

If you have previously developed skills that include screen display, you are familiar with display templates. The APL Authoring Tool allows you to build APL from scratch, or to pick a sample template to use as a basis for your work. Whatever your starting point, you can edit the content as desired in the APL Authoring Tool.

Open the APL authoring tool

Click https://developer.amazon.com/alexa/console/ask/displays/? to open the authoring tool page directly.

Alternatively, if you are creating or editing a skill in the developer console, click the Display link on the left to open the tool. The authoring tool page then opens in another tab.

Either way, the content you create in the authoring tool is not linked to any of your skills unless you copy or export this content, and then use it in your skill responses that you develop in your skill service.

Start with a sample template, with uploaded content, or from scratch

On the APL authoring tool page, you can select one of the templates, or you can "Start from scratch", or you can "Upload Code" that you already have.

APL Authoring Tool: Choose Template
APL Authoring Tool: Choose Template

Start with a sample template

When you select a template, you can then add or modify its content to suit your skill. The samples included with the authoring tool are based on the display templates that you may have used previously to build Alexa skills with screen content. For example, the Long Text Sample is similar to BodyTemplate1.

APL Authoring Tool: Long Text Sample
APL Authoring Tool: Long Text Sample

You can use these samples to familiarize yourself with the structure of APL by examining the Data JSON content on all of the tabs that makes up the sample.

By default, the components that form the layout are listed in a hierarchy in the bottom left section of the screen. Click a component to see its contents in the bottom middle section. A form appears in the bottom center, which lists the parameters for that component. You can enter the values for each of the component fields, leaving out optional values if desired. The form helps guide your work and ensure that each component contains valid JSON.

APL Authoring Tool: Component Form
APL Authoring Tool: Container Form

To add a component, click in the layout where you want to add it. Click + and enter the component information in the Add Component window. To remove a component, select it and click the trash can icon.

When you edit a component, click to another component and return to the original one you changed, any changes you have previously made are still present. See Export your work to save it for information about saving versions of your work.

Use the toggle at the lower right to switch between the component view and the raw code view. In the raw code view, you can see the entire document in JSON file including all the components, and you can make edits directly. Ensure that the JSON remains valid.

APL Authoring Tool--Toggle Between Component View as Shown and Raw Code View

The Document, Resources, and Styles content associated with this package can be viewed in the bottom right-hand section. Click to display the JSON content you want to view. You can edit this content, as with components in the layout. You can click in and out, and your changes will be preserved. The Document content for Long Text Sample is shown in the following figure.

APL Authoring Tool: Document content
APL Authoring Tool: Document content

Upload code to the APL Authoring Tool

If you already have JSON constructed, select Upload Code and upload that JSON file to the editor. You can then alter it as desired. The process of editing is the same as if you start with a sample template.

Start from scratch

If you select "Start from scratch" on the main page, you will have to create the components yourself. See Alexa Presentation Overview for instructions on how to create your own components.

Data JSON

When you select a sample, the Data JSON tab at the lower left shows a collection of data sources that work together with this sample. Thus, BodyTemplate1 includes background images, text content, and a logo URL image reference. You can modify the content of this Data JSON to match the data that you want to use.

APL Authoring Tool: Data JSON
APL Authoring Tool: Data JSON

Export your work to save it

To save your work in the authoring tool, click Export Code. The JSON file that is exported will contain the content, including all of your changes, from all the tabs. You can upload this file and work on it some other time. To ensure your work is saved, export the code on a regular basis, as closing the tab or opening another template will mean that you lose your changes.