APL Resources

---

Resources are named entities accessible through data binding and value resolution. You define resources in resource blocks within Alexa Presentation Language (APL) documents and packages. Resources can be defined conditionally based on viewport parameters.

Resources are evaluated in the course of APL document and package loading. During component inflation, resources are static and don't change. In APL 2023.2 and later, you can use deferred evaluation to include dynamic data within resource definitions. For details and examples, see Deferred evaluation.

Sample resource definition

The following example illustrates a resource definition.

This example picks values for the colors accent and myBlue based on whether the theme is light or dark. It also defaults the leftRight dimension to 72, but changes this resource to 25 percent of the screen width (in dp) if the screen is round.

Resources are defined in blocks, where a block is an object with an optional when clause and a set of types.

Properties

The properties of each resource block are:

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.
easing, easings	Map of easing functions	No	A mapping from name to easing function definition.
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.

The resource blocks are processed in array order, with later definitions overriding earlier definitions.

A resource definition can refer to a resource defined in an earlier block by using the @name syntax.

Resource blocks can nest inside other resource blocks. For example:

boolean, booleans

Boolean resources are stored as true/false values. Any non-Boolean assigned to a Boolean resource is converted according to the "truthy" rules. For details, see Truthy and Coercion

"boolean": {
  "bool1": true,       // true
  "bool2": 23.4,       // true
  "bool3": "hello!",   // true
  "bool4": false,      // false
  "bool5": 0,          // false
  "bool6": ""          // false
}

color, colors

Color values are stored as colors, which are 32-bit RGBA values. For details about how to write string expressions that convert to colors, see Color. For general coercion rules, see Color coercion

"colors": {
  "myRed1": "#ff0000ff",    // Normal Red
  "myRed2": "#ff0000",      // Short version (drops the alpha),
  "myRed3": "#f00",         // Super-short version (each R,G,B is doubled)
  "myRed4": "red",          // Take advantage of built-in color names
  "myRed5": "rgb(255,0,0)", // RGB function
  "myRed6": 4278190335      // Not recommended: hex value of 0xff0000ff
}

dimension, dimensions

Dimensional resources store absolute, relative, or special dimensions. For details about the different types of dimensions, see Dimension. For details about how other types convert to dimensions, see Absolute dimension coercion

"dimensions": {
  "myDim1": "150dp",  // 150 dp
  "myDim2": "300px",  // 150 dp on a 320 dpi screen.
  "myDim3": "100vw",  // 1024 dp on a 160 dpi screen with width 1024 pixels.
  "myDim4": "50vh",   // 400 dp on a 160 dpi screen with height 800 pixels.
  "myDim5": "50",     // 50 dp
  "myDim6": "50%",    // 50% (relative dimension)
  "myDim7": "auto"    // auto (special dimension)
}

easing, easings

Easing functions are single-valued functions traditionally used to define how an animated property changes over time. For details about easing functions, see Easing function.

gradient, gradients

Gradients are defined following the rules in Gradient.

number, numbers

Number resources are stored as double precision floating point values internally. For details about how non-numeric values convert to numbers, see Number coercion.

"numbers": {
  "myNum1": null,       // 0
  "myNum2": false,      // 0
  "myNum3": true,       // 1
  "myNum4": "@myDim1",  // 150 (by the dimension definition above)
  "myNum5": "@myDim6"   // 0.5 (by the dimension definition above)
}

string, strings

String values are stored as strings. Other types can convert to strings. For the string conversion rules, see String coercion.

"strings": {
   "string1": null,          // ""
   "string2": "",            // ""
   "string3": false,         // "false"
   "string4": 23,            // "23"
   "string5": "${@myRed1}",  // "#ff0000ff" (by the color definition above)
   "string6": "${@myDim1}",  // "150dp" (by the dimension definition above)
   "string7": "${@myDim6}",  // "50%" (by the dimension definition above)
}

Related topics

• APL Document
• Data-binding Syntax

---

---

Last updated: Nov 28, 2023