Context

In the last exercise, you used the responsive Alexa Headline template to render a visual using APL. In doing so, you hard-coded many values for the fields the template used, such as the URLs for "headerAttributionImage" and "backgroundImageSource" and the text values for "primaryText" and "footerHintText".

Now, suppose you need a different image URL, or want to change the words on the screen, but you want to use the same document structure. For example, in the Tic-Tac-Toe skill, there will be different screens to welcome the user, when user wins, when Alexa wins, and so on. Although these screens display different information, their format is similar. To support these scenarios, you could manage different APL documents for each varied situation your skill supports. However, this can become a big logistical challenge because it needs to happen in your Alexa skill backend code. Eventually, this can become un-manageable, especially when you consider localizing your skill to more languages.

One great alternative to creating so many APL document variations is to use an APL feature called data binding. Data binding allows you to reuse an APL document's structure and modify the content at rendering time. This helps separate the presentation logic (the APL document) from the data source. The visual part of the response is called the Alexa.Presentation.APLRenderDocument directive. Alexa-enabled devices with screens render visuals when the render document directive is sent from your skill backend.

To reference data in a data source, you must first pass a parameter into your APL document's mainTemplate.

Parameters of mainTemplate

To introduce a simple data source, you must first include a parameter into your mainTemplate. In the following example, we use the "information" parameter.

{
    "type": "APL",
    "version": "1.7",
    "theme": "dark",
    "import": [
        {
            "name": "alexa-layouts",
            "version": "1.4.0"
        }
    ],
    "mainTemplate": {
        "parameters": [
            "information"
        ],
        "items": [
            {

            }
        ]
    }
}

The "information" parameter references a new object that you must create separately in the Data JSON structure. There, you'll move all your text and links to images for the Welcome screen, and you will add additional resources for the rest of the screens you want to handle in this APL document.

Eventually, your APL document is stored in your skill's backend as a JSON file, and the values you use in the data sources object will pass over from your skill's backend.

So, because data binding is very important, it requires a wise decision about the Data JSON structure you want to use.