Selector (APL for Audio)

A Selector component renders a single audio clip, selected from an array of possible clips. You provide Selector with an array of child components that define each audio clip. The Selector then renders the audio for the first child component where the when property evaluates to true.

Properties

The Selector component has the base component properties and the following component-specific properties:

Property Type Default Description
item(s) Array of components No The array of child components.
data Array [ ] An array of data to map against the component.
strategy String normal The strategy used to select the child. Valid values are normal, randomItem, randomData, randomItemRandomData

item(s)

The child component to render. If more than one child is supplied, the Selector component renders the first one selected by the when property.

data

An array of data to iterate over and evaluate.

  1. When the data array is empty, Selector renders the first component in the items array where when evaluates to true. The component uses the single child inflation method.

  2. When the data array contains items, the Selector component iterates the data array and checks each component in the items array for a true when property for each item in the data array. The data-binding context is extended with the data, index, and length properties. The Selector component finishes when it selects and renders a single component. It doesn't continue iterating over the data array.

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

These properties are set when the data array property contains at least one item.

strategy

The selection strategy to determine which item to render. The specified strategy determines how the Selector component chooses which item to render.

The strategy values trigger the following behaviors:

  • normal – Render the first item where the when clause evaluates to true.
    • If the data array is empty, the Selector component picks and renders the first component in the items array where the when clause equals true.
    • If the data array is not empty, the Selector component checks each component in the components array in order looking for a when clause that equals true in the data array. The data-binding context is extended by binding the data, index, and length properties. The Selector component finishes after rendering a single component and then stops iterating over the data array.
  • randomItem – Render a random item whose when clause evaluates to true.
    • If the data array is empty, the Selector component evaluates the when clauses of all child components and selects one to render where the when clause equals true.
    • If the data array is not empty, the Selector component performs the random selection operation once per item in the data array in order. The data-binding context is extended by binding data, index, and length properties. The Selector component finishes after rendering a single component and then stops iterating over the data array.
  • randomData – Renders either the first item where the when clause evaluates to true or an item chosen from a random index in the data array:
    • If the data array is empty, the Selector component picks and renders the first component in the items array where the when clause equals true. Similar to normal strategy.
    • If the data array is not empty, the Selector component performs the normal strategy on a random index of the data array. If no component is rendered, the Selector performs the normal strategy on another random index in the data array. This process repeats until either rendering a single component is rendered, or exhausting all items in the data array.
  • randomItemRandomData – Uses the randomItem strategy for an empty data array and uses the randomData strategy for a non-empty data array.
    • If the data array is empty, the Selector component evaluates the when clauses of all child components and selects one to render where the when clause equals true. Similar to randomItem strategy.
    • If the data array is not empty, the Selector component performs the normal strategy on a random index of the data array. If no component is rendered, the Selector performs the normal strategy on another random index in the data array. This process repeats until either rendering a single component is rendered, or exhausting all items in the data array. Similar to the randomData strategy.

Examples

Basic Selector

The following example demonstrates a basic Selector component in a document bound to a data source. When ${payload.myData.name} contains an empty string, the Selector renders the first Speech component. Otherwise, the Selector renders the second Speech component, which also includes the data name property.

With the following data source, the Selector creates an audio clip with the speech "Hi, John!"

Copied to clipboard.

{
  "myData": {
    "name": "John"
  }
}

If you change the content of the Data Sources tab to the following, the document generates an audio clip with the speech "Hello! I don't yet know your name."

Copied to clipboard.

{
  "myData": {
    "name": ""
  }
}

Locale Selector

The following example demonstrates a Selector that uses the user's locale to determine whether to say "hello" in English or Spanish.

Copied to clipboard.

{
  "type": "Selector",
  "items": [
    {
      "type": "Speech",
      "when": "${environment.alexaLocale == 'en-US'}",
      "contentType": "PlainText",
      "content": "Hello!"
    },
    {
      "type": "Speech",
      "when": "${environment.alexaLocale == 'es-ES'}",
      "contentType": "SSML",
      "content": "<speak><voice name='Conchita'>Hola!</voice></speak>"
    }
  ]
}

When the user's device uses the English (US) locale, the environment.alexaLocale value returns en-US. The Selector generates the speech "Hello!" When the user's device uses the Spanish (Spain) locale, environment.alexaLocale returns es-ES, so the Selector generates the speech "Hola!" In this example, the second Speech component uses SSML to render the speech with the "Conchita" voice.

Was this page helpful?

Last updated: Nov 28, 2023