Authoring APL-A Templates

The best way to get started with APL-A is to use the APL-A authoring tool in the developer console. Go to your skill project in the developer console and click on “Multimodal Responses” in the left-hand menu. This will bring up the APL authoring tool where you can create APL-A templates and APL visual templates (which we’ll learn more about in Chapter 10, ​Creating Visual Responses​:

If you’ve ever created and saved an APL-A template for the skill in the authoring tool before, you’ll see a list of previously created APL-A templates. If this is to be your first APL-A template, however, you’ll see “No Saved Audio Responses” and be presented with a “Create Audio Response” button. Click the button to enter the APL-A editor, shown here.

On the left-hand side of the APL-A editor, you’ll notice two buttons labeled “APLA” and “Data”. Clicking these buttons will switch between the APL-A editor and a separate editor in which you can define some sample model data. Ultimately, the model data given to an APL-A template will be provided by a skill’s request handler. But for purposes of testing an APL-A in the editor, you can setup some test data after clicking the “Data” button.

When you first create a new APL-A template, the editor will be pre-populated with a sample APL-A template that highlights many commonly used APL-A components. Feel free to explore the sample template, tweak it, and test it out by clicking the “Preview” button at the bottom. When you click the “Preview” button, it will be replaced with three buttons for refreshing the audio, playing the audio, and looping. If you make changes to the template, you’ll need to click the refresh button for the new APL-A template to be processed before clicking the play button.

When you’re ready to create your own custom APL-A template, delete all of the text in the editor and start with the following essential APL-A skeleton template:

Aside from some template metadata, such as the type of document and version, the main thing to notice is the mainTemplate entry. This is where you’ll define much of the custom sounds and speech you want included in your response. Inside of mainTemplate, you’ll have either an item entry whose value is a single APL-A component, or an items entry whose value is an array of components.

If you choose to use items and specify multiple components in the array, know that only the first component in the array whose when clause evaluates to true will be evaluated. All others will be ignored. We’ll see how to use when in section ​Conditionally Selecting Sounds​.

At this point, the item property in the barebones template is empty. Therefore, this template won’t actually do anything. In fact, if you click the refresh button in the APL-A editor, you’ll get an error saying that the document has no content to render. As we test-drive some of APL-A’s components, we’ll fill it in. Let’s do that now, starting with some of the sound-making APL-A components.