Select Command

Select requires APL 1.3 or later. Provide an alternate experience for devices running older versions of APL.

Select a single command from an array of commands and data.

Properties

The Select command has the properties shown in the following table, in addition to the common command properties. Set the type property to Select.

In the following table, the "Default" column shows "Required" for properties that must have a value for the command to run. Otherwise it displays the default value, which might be none.

Property Type Default Description
commands Array of Commands REQUIRED An ordered list of commands to select from
data Array [] A list of data to map against the commands
otherwise Array of Commands [] An array of commands to run if no command is selected from the commands array

When the data array is empty, the Select command runs the first command in the commands array where when evaluates to true.

commands

An array of commands. The first command in the array with a true when clause runs.

data

The array of data to iterate over. During iteration the data-binding context is extended with the following properties:

Name Description
data Data assigned from the data array property
index The 0-based index of the current data item
length The total number of data items in the data array

Note that these properties are set when the data array property contains at least one item.

otherwise

The otherwise commands run when none of the commands in the commands property run. The otherwise commands do not have access to the data property. For example:

{
  "type": "Select",
  "commands": {
    "when": "${data.breed == breed}",
    "type": "SetValue",
    "property": "text",
    "componentId": "${textIdToUpdate}",
    "value": "Your dog is ${data.description}"
  },
  "otherwise": {
    "type": "SetValue",
    "property": "text",
    "componentId": "${textIdToUpdate}",
    "value": "Your dog is indescribable!"
  },
  "data": "${dogBreedData}"
}

Contents of the dogBreedData array:

{
  "dogBreedData": [
    {
      "breed": "Affenpinscher",
      "description": "loyal, curious, and amusing"
    },
    {
      "breed": "Bassett Hound",
      "description": "endearing with floppy ears"
    },
    {
      "breed": "Beagle",
      "description": "happy-go-lucky and cheerful"
    }
  ]
}

In the above example, passing the breed "Mixed Mutt" falls throught to the otherwise and updates the provided Text component text with "Your dog is indescribable!"

The otherwise property provides fallback behavior for when nothing from the data array matches.

Select command examples

Select command with no data property

In this example, assume age is 7. The command iterates the commands array until it reaches the third command. The when statement for this command evaluates to true, so Select runs the SetValue command and updates the specified text property to the value "Kid".

{
  "type": "Select",
  "commands": [
    {
      "when": "${age < 2}",
      "type": "SetValue",
      "property": "text",
      "value": "Infant",
      "componentId": "${textIdToUpdate}"
    },
    {
      "when": "${age < 5}",
      "type": "SetValue",
      "property": "text",
      "value": "Toddler",
      "componentId": "${textIdToUpdate}"
    },
    {
      "when": "${age < 13}",
      "type": "SetValue",
      "property": "text",
      "value": "Kid",
      "componentId": "${textIdToUpdate}"
    },
    {
      "when": "${age < 18}",
      "type": "SetValue",
      "property": "text",
      "value": "Teen",
      "componentId": "${textIdToUpdate}"
    },
    {
      "type": "SetValue",
      "property": "text",
      "value": "Adult",
      "componentId": "${textIdToUpdate}"
    }
  ]
}

Select command with the data array

When you provide the data array, the Select command checks each command in the commands array for a true when clause one time per item in the data array. The data-binding context is extended by binding data, index, and length properties. The Select command finishes after it runs a single command; it does not continue iterating over the data array.

In this example, assume age is 17. The command iterates through data array. The when statement for the command evaluates to true for the data provided in the fourth item (17 < 18), so Select stops iterating through the data array and runs the SetValue command, which updates the specified text property to "Your category is Teen".

{
  "type": "Select",
  "commands": {
    "when": "${!data.until || age < data.until}",
    "type": "SetValue",
    "property": "text",
    "value": "Your category is ${data.category}",
    "componentId": "${textIdToUpdate}"
  },
  "data": [
    {
      "until": 2,
      "category": "Infant"
    },
    {
      "until": 5,
      "category": "Toddler"
    },
    {
      "until": 13,
      "category": "Kid"
    },
    {
      "until": 18,
      "category": "Teen"
    },
    {
      "category": "Adult"
    }
  ]
}

You can combine multiple commands with a data array. Select still runs only a single command in the commands array. For example:

{
  "type": "Select",
  "commands": [
    {
      "when": "${searchCategory == data.category && data.rating >= 8.0}",
      "type": "SetValue",
      "property": "text",
      "componentId": "${textIdToUpdate}",
      "value": "Here's a great movie for your category: <em>${data.title}</em>"
    },
    {
      "when": "${searchCategory == data.category}",
      "type": "SetValue",
      "property": "text",
      "componentId": "${textIdToUpdate}",
      "value": "Here's an okay movie for your category: <em>${data.title}</em>"
    }
  ],
  "data": "${movieData}"
}

In this example, movieData is bound to an array of movies sorted by category and rating, with the highest rated movies first:

{
  "movieData": [
    {"title":"Avatar","category":"Adventure","rating":7.8},
    {"title":"Aladdin","category":"Adventure","rating":7.1},
    {"title":"Coco","category":"Animation","rating":8.4},
    {"title":"Toy Story 4","category":"Animation","rating":8},
    {"title":"The Lion King","category":"Animation","rating":7}
  ]
}

If SearchCategory is "Animation", Select iterates until it reaches the third item in data, which matches both of the criteria in the first when statement. The first command then runs and updates the text property of the movieResultTextComponent component with the text "Here's a great movie for your category: Coco".

If SearchCategory is "Adventure", Select chooses the first item in data since this item matches the criteria for the second when statement. The second command then runs and updates the text property of movieResultTextComponent to "Here's an okay movie for your category: Avatar".

Was this page helpful?

Last updated: frontmatter-missing