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