Define resources

You define resources in blocks, where a block is an object with an optional when clause and a set of types. The following example contains a simple block. By using the APL authoring tool , test the APL document example against a Small Round device.

{
    "type": "APL",
    "version": "1.7",
    "theme": "dark",
    "import": [
        {
            "name": "alexa-layouts",
            "version": "1.4.0"
        }
    ],
    "resources": [
        {
            "when": "${@viewportProfile == @hubRoundSmall}",
            "strings": {
                "paddingTopRow": "40vh"
            }
        }
    ],
    "layouts": {},
    "mainTemplate": {
        "parameters": [],
        "items": [
            {
                "type": "Container",
                "paddingTop": "@paddingTopRow",
                "items": [
                     {
                        "type": "Text",
                        "text": "This is a test"
                    }
                ]
            }
        ]
    }
}

The @paddingTopRow is a string resource set to "40vh" only when the skill renders on a device with a small round screen. The @paddingTopRow is referenced in the container’s "paddingTop" parameter in the previous example. The string resource contains the value "40vh" only if the skill renders on a device with a small round screen. Otherwise, APL just ignores the resource because it’s not defined for other viewport profiles.

There are other types of resources, such as "dimensions", which would have the same effect in the APL document as strings do in the previous example.

"resources": [
      {
            "when": "${@viewportProfile == @hubRoundSmall}",
            "dimensions": {
                "paddingTopRow": "40vh"
            }
        }
    ]

The following table shows the most important properties of each resource block:

Property Type Required Description
boolean, booleans Map of Boolean No A mapping from Boolean name to Boolean value
color, colors Map of Colors No A mapping from color name to color value
description String No A description of this resource block
dimension, dimensions Map of Dimensions No A mapping from dimension name to dimension value.
gradient, gradients Map of Gradients No A mapping from gradient name to gradient definition
number, numbers Map of Numbers No A mapping from a name to a number.
string, strings Map of Strings No A mapping from a name to a string.
when Boolean No If true, this resource block is included. Defaults to true.

For more details, see APL Resources Properties.

APL processes the resource blocks in the order in which they are defined in the array. A later resource block with the same name as an earlier block overrides the earlier definition. In the following example, resource @paddingTopRow defaults to "20vh" unless the skill renders on a device with viewport profile @hubRoundSmall.

"resources": [
        {
            "dimensions": {
                "paddingTopRow": "20vh"
            }
        },
        {
            "when": "${@viewportProfile == @hubRoundSmall}",
            "dimensions": {
                "paddingTopRow": "40vh"
            }
        }
    ]

You can also use the @name syntax in a resource definition to refer to another resource defined earlier.

Exercise 1

Use the following approach that you learned about in Lab 4 to update the APL document shown after the table:

{
  "when": "${@viewportProfile == @hubRoundSmall}",
  "dimensions": {

  },
  "strings": {

  }
},
{
  "when": "${@viewportOrientation == @viewportOrientationLandscape}",
  "dimensions": {

  },
  "strings": {

  }
},
{
  "when": "${@viewportOrientation == @viewportOrientationPortrait}",
  "dimensions": {

  },
  "strings": {

  }
}

Use the strings and dimensions from this table to update the following APL document:

Viewport profile Viewport orientation @paddingTopRow (dimension) @paddingBottomRow (dimension) @bgScale (string) @imageHeight (dimension)
@hubRoundSmall   15vh 40vh best-fill 40%
  @viewportOrientationLandscape 4vh 0vh best-fill 20%
  @viewportOrientationPortrait 30vh 30vh best-fill-down 30%
{
    "type": "APL",
    "version": "1.7",
    "theme": "dark",
    "import": [
        {
            "name": "alexa-layouts",
            "version": "1.4.0"
        }
    ],
    "resources": [],
    "layouts": {},
    "mainTemplate": {
        "parameters": [],
        "items": [
            {
                "type": "Container",
                "paddingTop": "@paddingTopRow",
                "paddingBottom": "@paddingBottomRow",
                "items": [
                    {
                        "type": "AlexaBackground",
                        "backgroundScale": "@bgScale",
                        "backgroundImageSource": "https://d3j5530a0cofat.cloudfront.net/adlc/board.png"
                    },
                    {
                        "type": "AlexaImage",
                        "imageSource": "https://d3j5530a0cofat.cloudfront.net/adlc/cross.png",
                        "imageRoundedCorner": false,
                        "imageHeight": "@imgHeight",
                        "imageAspectRatio": "square",
                        "imageBlurredBackground": false
                    }
                ]
            }
        ]
    }
}

Important: Observe that there is also an AlexaBackgroundImage responsive component now in the APL document that must display the empty Tic-Tac-Toe skill board on any screen and at the proper "backgroundScale". There is also an AlexaImage displaying the X marker at the top row, left column with "imageHeight" set to the resource @imgHeight.

Your APL document must display the following visuals on a small round screen (left), in Landscape mode (center), and in Portrait mode (right) when you define the resources properly.

img

Solution

{
    "type": "APL",
    "version": "1.7",
    "theme": "dark",
    "import": [
        {
            "name": "alexa-layouts",
            "version": "1.4.0"
        }
    ],
    "resources": [
        {
            "when": "${@viewportProfile == @hubRoundSmall}",
            "dimensions": {
                "paddingTopRow": "15vh",
                "paddingBottomRow": "40vh",
                "imgHeight": "40%"
            },
            "strings": {
                "bgScale": "best-fill"
            }
        },
        {
            "when": "${@viewportOrientation == @viewportOrientationLandscape}",
            "dimensions": {
                "paddingTopRow": "4vh",
                "paddingBottomRow": "0vh",
                "imgHeight": "20%"
            },
            "strings": {
                "bgScale": "best-fill"
            }
        },
        {
            "when": "${@viewportOrientation == @viewportOrientationPortrait}",
            "dimensions": {
                "paddingTopRow": "30vh",
                "paddingBottomRow": "30vh",
                "imgHeight": "30%"
            },
            "strings": {
                "bgScale": "best-fill-down"
            }
        }
    ],
    "layouts": {},
    "mainTemplate": {
        "parameters": [],
        "items": [
            {
                "type": "Container",
                "paddingTop": "@paddingTopRow",
                "paddingBottom": "@paddingBottomRow",
                "items": [
                    {
                        "type": "AlexaBackground",
                        "backgroundScale": "@bgScale",
                        "backgroundImageSource": "https://d3j5530a0cofat.cloudfront.net/adlc/board.png"
                    },
                    {
                        "type": "AlexaImage",
                        "imageSource": "https://d3j5530a0cofat.cloudfront.net/adlc/cross.png",
                        "imageRoundedCorner": false,
                        "imageHeight": "@imgHeight",
                        "imageAspectRatio": "square",
                        "imageBlurredBackground": false
                    }
                ]
            }
        ]
    }
}