APL Resources

Resources are named entities accessible through data-binding and value resolution. Resources are defined in resource blocks within 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 may not be changed.

Sample resource definition

The following example illustrates a resource definition.

{
  "type": "APL",
  "resources": [
    {
      "colors": {
        "accent": "#00CAFF",
        "myBlue": "#66DFFF"
      },
      "dimension": {
        "leftRight": "72dp"
      },
      "string": {
        "logo": "images/logo200x200.png"
      }
    },
    {
      "when": "${viewport.shape == 'round'}",
      "dimension": {
        "leftRight": "${viewport.width * 0.25}"
      }
    },
    {
      "when": "${viewport.theme == 'light'}",
      "colors": {
        "accent": "#0070BA",
        "myBlue": "#005A95"
      }
    },
    {
      "description": "Use a larger logo on a large screen",
      "when": "${viewport.width > 1200}",
      "string": {
        "logo": "images/logo300x300.png"
      }
    }
  ]
}

This example picks values for the colors accent and myBlue based on whether the theme is light or dark. It also sets the leftRight dimension to 72 normally, but 25% 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 Easings 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 will be 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 using the @name syntax.

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

{
  "resources": [
    {
      "dimensions": {
        "myFontSize": "28dp",
        "myLeftRightPadding": "60dp"
      }
    },
    {
      "when": "${viewport.shape == 'round'}",
      "resources": [
        {
          "dimensions": {
            "myFontSize": "30dp",
            "myLeftRightPadding": "80dp"
          }
        },
        {
          "when": "${viewport.width < 400}",
          "dimensions": {
            "myFontSize": "20dp",
            "myLeftRightPadding": "45dp"
          }
        }
      ]
    }
  ]
}

boolean, booleans

Boolean resources are stored as true/false values. Any non-Boolean assigned to a Boolean resource is converted using 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 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 will be converted 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)
}