APL Conditional Component Inflation

Conditional component inflation determines which components and layouts to inflate in an APL document. For example, the mainTemplate property of an APL document accepts an array of components in the items property, but renders a single component. Conditional component inflation determines which one to inflate. The component inflation algorithms enable lightweight conditional expressions using arrays of components, the when property in primitive components, and data-binding.

Conditional inflation scenarios

Conditional inflation works differently depending on the scenario:

  • Single child – Alexa inflates a single component from an array of possible components.
  • Simple array – Alexa inflates a subset of components from an array of components.
  • Data array – Alexa uses a data array to inflate a set of components.

Single child

A single child is a single component inflated from an array of possible components.

Summary Explanation
Used by User-defined layouts, components that support only a single child (ScrollView, Frame, TouchWrapper), and properties on multi-child components that inflate a single child such as firstItem and lastItem.
Algorithm Given an array of components, evaluate the when property of each component in turn. The first component with a when property that evaluates to true is used. If no component has a true when property, no component is inflated. Note that if the when property is omitted, it defaults to true.
Data-binding None

Sample single child inflation

In this example, a round viewport will inflate the Container, and a rectangular viewport will inflate the Frame.

"myLayout": 
{
  "parameters": [
    "title",
    "logo"
  ],
  "item": [
    {
      "when": "${viewport.shape == 'round'}",
      "type": "Container",...
    },
    {
      "type": "Frame",...
    }
  ]
}

Simple array of child components

A simple array of child components is a subset of components that are inflated from an array of components.

Summary Explanation
Used by Sequence, Container, Pager when no data property is specified.
Algorithm The when property of each component in the array is evaluated. If the when clause evaluates to true, the component is inflated and added to the array of children.
Data-binding The index, length, and ordinal (optional) values are bound. See Data-binding.

The simple array of items approach is used when you have a collection of heterogenous items to inflate.

In this example, which presents a news story in a container, the Text heading is always displayed, an image is displayed only if the viewport width is less than the viewport height, and the Text leader is always displayed.

{
  "type": "Container",
  "items": [
    {
      "type": "Text", 
      "style": "heading", 
      "text": "Mars rover Opportunity is declared dead"
    },
    {
      "type": "Image",
      "when": "${viewport.width < viewport.height}",
      "source": https://www.example.com/mars-rover.jpg
    },
    {
      "type": "Text",
      "style": "leader",
      "text": "After fifteen years without any signal, the Mars rover Opportunity has ..."
    }
  ]
}

Data array

A data array is an array of data that is used to inflate a set of components.

Summary Explanation
Used by Sequence, Container, Pager when the data property is specified.
Algorithm Each element in the data property array is bound in turn to "data" in the data-binding context. For each bound element, the single child algorithm is evaluated to find a single component.
Data-binding The data, index, length, and ordinal (optional) values are bound.

See Data binding.

This approach is used with an array of data of unknown length that you want to concatenate together and display. For example, consider describing the steps in a recipe. The following Container inflates the data appropriately:

{
  "type": "Container",
  "direction": "column",
  "item": {
    "type": "Text",
    "text": "${index+1}. ${data}",
    "spacing": "smallSpace"
  },
  "data": [
    "Preheat the oven to 350 degrees F.",
    "Using a mixer, cream the butter and sugar until smooth",
    "With the mixer on, add one egg at a time to the butter-sugar mixture and beat until smooth",
    "Combine the flour, baking powder, and salt in a separate ...."
  ]
}

Because the component array selects the first item from the array with a true when property, this allows a heterogenous set of data to be inflated. In this example, data items with a "header" property are inflated using a simple Text component. The other data items are inflated as a captioned image.

{
  "type": "Sequence",
  "items": [
    { 
      "when": "${data.header}",
      "type": "Text",
      "text": "${data.header}"
    },
    {
      "type": "Container",
      "direction": "row",
      "numbered": true,
      "items": [ 
        { 
          "type": "Image", 
          "source": "${data.url}"
        },
        {
          "type": "Text",
          "text": "${ordinal}. ${data.caption}"
        }
      ]
    }
  ],
  "data": [
    { 
      "header": "Beach Photos" 
    },
    { 
      "url": "https://images.example.com/photos/248797/xxx.jpg",
      "caption": "Scene 248797"
    },
    { 
      "url": "https://images.example.com/photos/237739/yyy.jpg",
      "caption": "Beach Boat Clouds Daylight 237739" 
    },
    { 
      "header": "Dog Photos" 
    },
    { 
      "url": "https://images.example.com/photos/356378/zzz.jpg",
      "caption": "Adorable Animal Breed Canine 356378" 
    }
  ]
}