Resources (APL for Audio)

Resources are named entities you can access through data-binding and value resolution. You define resources in blocks within APL for audio documents. You can create conditional resources based on values in the environment property.

Resource blocks

An APL document evaluates resources when loading. After the document begins inflating components, the resources are static and can't be changed.

The following example shows a resource definition that sets a number variable called fixedVolume to a value depending on whether the user's device has a screen or character display.

Copied to clipboard.

{
  "resources": [
    {
      "number": {
        "fixedVolume": 0.5
      },
      "boolean": {
        "isHeadless": "${!environment.aplVersion && !environment.apltVersion}"
      }
    },
    {
      "when": "${@isHeadless}",
      "number": {
        "fixedVolume": 1.0
      }
    }
  ]
}

The example has two resource blocks. The first block sets fixedVolume to a default value (0.5) and sets isHeadless to a Boolean that represents whether the user's device has a screen. The isHeadless variable is false when the device has either a screen or a character display, and is true when the device is a speaker with no visual display of any kind.

The second block sets fixedVolume again when isHeadless is true. The results of this block override the original fixedVolume value.

To use a resource in your document, use the @ syntax. The following example shows an Audio component with a Volume that uses the fixedVolume resource.

Copied to clipboard.

{
    "type": "Audio",
    "source": "https://amazon.com/rainforestSoundEffect.mp3"
    "filter": [
        {
            "type": "Volume",
            "amount": "@fixedVolume"
        }
    ],
}

On a device with no screen or character display, the above example sets the Volume filter amount to 1.0. On a device with a screen or character display, the example sets the Volume filter amount property to 0.5.

Resource properties

Define resources in the resources property in the APL document. The resources property takes an array of resource blocks, where each block is an object with an optional when clause and a set of types.

The following table shows the properties for a resource block.

Property Type Required Description
boolean, booleans Map of Boolean No A mapping from Boolean name to Boolean value
description String No A description of this resource block
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 When true, use the definitions in this resource block. Defaults to true.

The resource blocks are processed in array order. The resources defined in a later block override resources with the same name defined earlier.

Within a resource block, the properties are evaluated in the following order:

  • when
  • boolean
  • booleans
  • number
  • numbers
  • string
  • strings

Within a resource definition, to refer to a resource defined in an earlier block, use the @name syntax.

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 about these rules, see Truthy and coercion.

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

number, numbers

Number resources are stored as double precision floating point values.

For details about how non-numeric values convert to numbers, see Number coercion.

"numbers": {
  "myNum1": null,       // 0
  "myNum2": false,      // 0
  "myNum3": true,       // 1
  "myNum4": 150         // 150 
  "myNum5": 0.5         // 0.5
}

string, strings

String values are stored as strings. For details about how other types are converted to strings, see String coercion.

"strings": {
   "string1": null,          // ""
   "string2": "",            // ""
   "string3": false,         // "false"
   "string4": 23             // "23"
}