APL Data-Binding Syntax (APL 1.7 to 2023.1)

(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)

You use data-binding syntax to write expressions that Alexa evaluates when displaying your Alexa Presentation Language (APL) document. You use data-binding expressions to bind component properties to your data source, and to write conditional logic to hide and show components depending on criteria such as the viewport characteristics.

About data binding expressions

You use data binding expressions inside JSON strings. A data binding expression has the form "${expression}". You can use any number of expressions inside a string, for example: "${2}+${2} = ${2+2}".

Expressions are evaluated within the current data-binding context. The data-binding context is a global dictionary that supports boolean values, numbers, strings, arrays, objects, null, and references to defined resources.

Supported value types

Identifier

An identifier is a name used to identify a data-binding variable. Identifiers must follow the C identifier naming convention: [a-zA-Z_][a-zA-Z0-9_]*. This means that the identifier must start with an upper or lower-case ASCII letter or underscore, followed by zero or more ASCII letters, numbers, or the underscore:

${data}
${_myWord23}
${__AnUgly26_letter__examplE}

String literals

Strings are defined using either single or double quotes. The starting and ending quote must match. Escape quotes, carriage returns, and line-feed characters.

	${"Double-quoted string"}
	${'Single-quoted string'}
	${"Inner quote: \" or '"}

Expressions can be nested inside of a string.

	${"Two plus two is ${2+2}"}

Numbers

Positive, negative, and floating point numbers are supported. Scientific notation isn't supported. All numbers are internally stored as doubles:

${1}
${-34.75}
${64000000000}

Boolean values

Boolean values of true and false are supported.

	${true}
	${false}

null

The null constant is supported.

	${null}

Array

Define arrays inside of a data-binding expression by providing a comma-separated list of expressions within square brackets:

${["A", "B", "C"].length}     // Evaluates to 3
${["on","off"][0]}            // Evaluates to "on"
${[true,"true",1][0]}         // Evaluates to boolean true

Maps

Define a map object inside of a data-binding expression by providing a string key and value pairs within curly brackets.

${{"A": 1, "B": 2}["A"]}    // Evaluates to 1

Resources

Resources defined in the data-binding context use the reserved character @. For example:

${@myBlue}
${@isLandscape ? @myWideValue : @myNarrowValue}

APL packages define resources exposed in data-binding.

Absolute dimensions

A dimensional suffix converts a number into an absolute viewport dimension. The valid dimensional suffixes are dp, px, vh, and vw:

${23 dp}     // 23 display-independent pixels
${10 px}     // 10 pixels
${50 vw}     // 50% of the width of the viewport
${100vh}     // 100% of the height of the viewport

Dimensional suffixes must be attached to a number, not a more complex expression. For example ${(20*20) dp} isn't valid, but ${20*20dp} is valid.

Truthy and coercion

Data-binding expressions involve different data types. These types can convert into other types. The following table gives an example of the different conversions. The examples shown in the table assume a viewport width of 512dp and a dpi of 320.

Boolean coercion

A truthy value is a value that's considered true when evaluated in a boolean context. All values are truthy except for false, 0, "", a zero absolute or relative dimension, and null.

Number coercion

The Boolean true value converts to the number 1. String values are converted using the C++ std::stod method, which is influenced by the locale. Absolute dimensions convert to the number of display-independent pixels in the absolute dimension. Relative dimensions convert to the percentage value (for example, 32% converts to 0.32). Everything else converts to 0.

String coercion

Internal types convert to strings according to the rules shown in the following table:

The specific format of non-integer numbers isn't defined, but should follow the C++ standard for sprintf(buf, "%f", value). The format might change based on the locale.

Color coercion

Color values are stored internally as 32-bit Red-Green-Blue-Alpha (RGBA) values. Numeric values are treated as unsigned 32-bit integers and converted directly. String values are parsed according to the rules in Data Types - Color.

Absolute dimension coercion

Numeric values are assumed to be measurements in dp and are converted to absolute dimensions. String values are parsed according to the rules in Data Types - Dimension. All other values are 0.

Relative dimension coercion

Numeric values are assumed to be percentages and are converted directly. For example, 0.5 converts to 50%. Strings are parsed according to the rules in Data Types - Dimension. All other values are 0.

Operators

APL supports the following types of operators: arithmetic, logical, comparison, null coalescing, and ternary.

Arithmetic operators

APL supports the standard arithmetic operations for addition, subtraction, multiplication, division, and remainder.

${1+2}  // 3
${1-2}  // -1
${1*2}  // 2
${1/2}  // 0.5
${1%2}  // 1.

Addition and subtraction work for pairs of numbers, absolute dimensions, and relative dimensions. When a number is combined with either an absolute or relative dimension, the number is coerced into the appropriate dimension.

The addition operator also acts as a string-concatenation operator if either the left or right operand is a string.

${27+''}     // '27'
${1+' dog'}  // '1 dog'
${'have '+3} // 'have 3'

Multiplication, division, and the remainder operator work for pairs of numbers. Multiplication also works if the one of the operands is a relative or absolute dimension and the other is a number. This calculation results in a dimension. Division works if the first operand is a relative or absolute dimension and the second is a number. This calculation results in a dimension.

The remainder operator behaves as in JavaScript.

${10 % 3}  // 1
${-1 % 2}  // -1
${3 % -6}  // 3
${6.5 % 2} // 0.5

Logical operators

APL supports the standard logical and/or/not operators.

${true || false}   // true
${true && false}   // false
${!true}           // false

The && returns the first operand if it isn't truthy and the second otherwise. The || operator returns the first operand if it's truthy and the second otherwise.

${7 && 2}    // 2
${null && 3} // null
${7 || 2}    // 7
${0 || -16}  // -16

Comparison operators

Comparison operators return boolean values.

${1 < 2}
${75 <= 100}
${3 > -1}
${4 >= 4}
${myNullValue == null}
${(2>1) == true}
${1 != 2}

The comparison operators don't apply to arrays and objects.

Comparison operators don't perform type coercion. For example, the expression ${1=='1'} returns false. The following table lists the valid comparisons. All other comparisons return false.

The == operator in APL is similar to the === operator in JavaScript.

Null coalescing

The ?? operator is the null-coalescing operator. It returns the left-hand operand if the operand isn't null; otherwise it returns the right-hand operand. You can chain the null-coalescing operator.

${person.name ?? person.surname ?? 'Hey, you!'}

The null-coalescing operator returns the left-hand operand if it's anything but null:

${1==2 ?? 'Dog'}   // returns false
${1==2 || 'Dog'}   // returns 'Dog'

Ternary operator

The ternary conditional operator ${a ? b : c} evaluates the left-hand operand. If it evaluates to true or a truthy value, the middle operand is returned. Otherwise the right-hand operand is returned.

${person.rank > 8 ? 'General' : 'Private'}

Array and object access

Array

Array access uses the [] operator, where the operand must be an integer. Arrays also support the .length operator to return the length of the array. Accessing an element outside of the array bounds returns null.

${myArray[4]}     // 5th element in the array (0-indexed)
${myArray.length} // Length of the array
${myArray[-1])}   // Last element in the array
${myArray[myArray.length]}  // Returns null (out of bounds)

Passing a negative index counts backwards through the array.

${a[-1] == a[a.length - 1]}  // True

Object

Objects support the . operator and the [] array access operator with string values.

${myObject.name}    // The 'name' property of myObject
${myObject['name']} // The 'name' property of myObject

If the property isn't defined, the expression returns null.

Calling the . or [] operator on null returns null.

${myNullObject.address.zipcode}  // Returns null

The right-side operand of the dot operator must be a valid identifier.

Function calls

Data-binding supports a limited number of built-in functions. Functions use the following form.

functionName( arg1, arg2, … )

Functions don't require arguments. A function returns a single value. The following examples show a variety of function expressions.

${Math.floor(1.1)}       // 1
${Math.ceil(1.2)}        // 2
${Math.round(1.2)}       // 1
${Math.min(1,2,3,4)}     // 1
${Math.max(1,2,3,4)}     // 4
${String.toUpperCase('Hello')}    // HELLO
${String.toLowerCase('Hello')}    // hello
${String.slice('Hello', 1, -1)}   // ell

The available functions are grouped by top-level property:

• Array functions
• Math functions
• String functions
• Time functions

Array functions

The top-level Array property is a collection of functions and constants for manipulating arrays.

The examples in the Example column use the following array: a = [101,102,103,104,105,106].

Math functions

The top-level Math property is a collection of functions and constants for numerical calculations.

String functions

The top-level String property is a collection of functions for manipulating strings.

The string length and slice functions work on Unicode code points, not bytes.

Time functions

The top-level Time property is a collection of functions that convert from time values in milliseconds into years, months, days, hours, minutes, and seconds. The examples in the table assume a bound time value T=1567786974710, which in human-readable terms is Friday September 6, 2019 at 16:22:54 and 710 milliseconds.

To construct a basic digital clock, the developer could use the Time functions to build a 24-hour clock out of a Text component and the localTime property:

{
  "type": "Text",
  "bind": {
    "name": "T",
    "value": "${localTime}"
  },
  "text": "${Time.hours(T)}:${Time.minutes(T)}"
}

This example binds the value of localTime into a local variable T to make the text expression shorter. This clock renders a time like 4:04 PM as 16:4, which might not be what you want. You can use conditional statements to determine the time and include leading/trailing zeros if necessary.

You can also use conditional statement to display a 12-hour clock as shown in this example. This binds both the hours and minutes to local variables, and then uses conditional statements to output the time in a 12-hour format with am or pm.

{
  "type": "Text",
  "bind": [
    {
      "name": "h",
      "value": "${Time.hours(localTime)}"
    },
    {
      "name": "m",
      "value": "${Time.minutes(localTime)}"
    }
  ],
  "text": "${h >= 12 ? h - 12 : h}:${m < 10 ? '0' : ''}${m} ${h >= 12 ? 'pm' : 'am'}"
}

You can also use the Time.format function to simplify the code. This example also uses a conditional statement based on hours to add the "am" or "pm" at the end.

{
  "type": "Text",
  "bind": [
    {
      "name": "h",
      "value": "${Time.hours(localTime)}"
    }
  ],
  "text": "${Time.format('h:mm', localTime) + (h >= 12 ? ' pm' : ' am')}"
}

Example document: Examples of basic clocks  

{
  "type": "APL",
  "version": "2024.2",
  "theme": "dark",
  "import": [
    {
      "name": "alexa-layouts",
      "version": "1.7.0"
    }
  ],
  "mainTemplate": {
    "parameters": [
      "payload"
    ],
    "items": [
      {
        "type": "Container",
        "height": "100vh",
        "width": "100vw",
        "justifyContent": "center",
        "alignItems": "center",
        "items": [
          {
            "type": "Text",
            "bind": [
              {
                "name": "T",
                "value": "${localTime}"
              }
            ],
            "text": "${Time.hours(T)}:${Time.minutes(T)}"
          },
          {
            "type": "Text",
            "bind": [
              {
                "name": "T",
                "value": "${localTime}"
              },
              {
                "name": "m",
                "value": "${Time.minutes(localTime)}"
              }
            ],
            "text": "${Time.hours(T)}:${m < 10 ? '0' : ''}${m}"
          },
          {
            "type": "Text",
            "bind": [
              {
                "name": "h",
                "value": "${Time.hours(localTime)}"
              },
              {
                "name": "m",
                "value": "${Time.minutes(localTime)}"
              }
            ],
            "text": "${h >= 12 ? h - 12 : h}:${m < 10 ? '0' : ''}${m} ${h >= 12 ? 'pm' : 'am'}"
          },
          {
            "type": "Text",
            "bind": [
              {
                "name": "h",
                "value": "${Time.hours(localTime)}"
              }
            ],
            "text": "${Time.format('h:mm', localTime) + (h >= 12 ? ' pm' : ' am')}"
          },
          {
            "type": "Text",
            "bind": [
              {
                "name": "h",
                "value": "${Time.hours(localTime)}"
              }
            ],
            "text": "${Time.format('h:mm:ss', localTime) + (h >= 12 ? ' pm' : ' am')}"
          }
        ]
      }
    ]
  }
}

Time.format

The format function takes a string argument containing the formatting codes and a time value. The following formatting codes are supported:

All the formatting codes return digits only.

The following table shows examples of the formatting functions, using the time value September 6, 2019 at 16:22:54 and 710 milliseconds.

Time formatting also works for relative times from timers. The following table shows examples that use the value 7523194, which corresponds to two hours, five minutes, and 23.194 seconds.

For example, to show elapsedTime after the document has loaded:

{
  "type": "Text",
  "text": "${Time.format('mmm:ss.S', elapsedTime)}"
}

Data-binding string conversion

Because APL is serialized in JSON, all data-bound expressions are defined inside of a JSON string:

{
  "MY_EXPRESSION": "${....}"
}

When there are no spaces between the quotation marks and the data-binding expression, the result of the expression is the result of the data-binding evaluation. For example:

"${true}"               -> Boolean true
"${2+4}"                -> Number 6
"${0 <= 1 && 'three'}"  -> String 'three'

When extra spaces are in the string outside of the data-binding expression or when two data-binding expressions are juxtaposed, the result is a string concatenation:

" ${true}"     -> String ' true'
"${2+4} "      -> String '6 '
"${2+1}${1+2}" -> String '33'

Last updated: Feb 29, 2024