APL Resources

(This is not the most recent version of APL. Use the Other Versions option to see the documentation for the most recent version of APL)

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

Here is a sample resource definition within an APL document:

{
  "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 Map of Boolean No Mapping from boolean name to boolean value.
color, colors Map of COLOR No Mapping from color name to color value.
description String No Description of this resource block.
dimension, dimensions Map of DIMENSION No 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 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 may refer to a resource defined in an earlier block using the @name syntax.

Resource blocks may 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"
          }
        }
      ]
    }
  ]
}