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.

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.

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.

The following example shows the full document. This examples adds a Speech to indicate which volume setting is used. Note that the audio sandbox is considered a device without a screen, so you hear the louder volume for the audio sound.

---

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"
}

Related topics

• APL for Audio Reference
• APL Document
• Data-binding Evaluation

---

---

Last updated: Nov 28, 2023