APL Layout
An APL layout is a named composite component, defined in an APL document or package. An APL layout can be thought of as a function that expands (inflates) into a collection of other named layouts and primitive components. An APL layout supports passing arguments in a parameters array. The inflation of the APL layout is conditional, as different components can be inflated based on the current data-binding context.
Sample layout
In this example, the header layout accepts two parameters: title and logo. The title parameter is passed to a Text component, and the logo parameter is passed to an Image. The Header component inflates into a column-based Container on a round viewport and places the logo above the title. On a rectangular viewport, the logo is placed to the right of the title.
{
"Header": {
"description": "A basic header with a title and a logo",
"parameters": [
{
"name": "title",
"type": "string"
},
{
"name": "logo",
"type": "string",
"default": "http://images.amazon.com/default_logo.png"
}
],
"items": [
{
"when": "${viewport.shape == 'round'}",
"type": "Container",
"direction": "column",
"items": [
{
"type": "Image",
"source": "${logo}",
"height": 36,
"width": 36
},
{
"type": "Text",
"text": "${title}",
"style": "textStylePrimary2"
}
]
},
{
"type": "Container",
"direction": "row",
"paddingLeft": 20,
"items": [
{
"type": "Text",
"text": "${title}",
"style": "textStyleSecondary2"
},
{
"type": "Image",
"source": "${logo}",
"height": 40,
"width": 40
}
]
}
]
}
}
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| description | String | No | A description of this layout |
| item | Component: Properties | Yes | The component to inflate. If an array is passed, the first item with a matching when clause will be inflated. |
| parameters | Array of PARAMETER | No | An array of parameters that can be passed to this layout. |
item(s)
The item property is either a single component or, if items, an array of components. Other layouts can also be part of the item(s), provided they have already been imported or defined earlier in the layouts object. See Data-binding evaluation.
parameters
The parameters are named values that can be passed to a layout. Each parameter is an object with the following properties:
| Property | Type | Required | Description |
|---|---|---|---|
| default | Any | No | The default value to apply if this parameter is not specified. Defaults to empty. |
| description | String | No | A user-provided description of the purpose of this parameter. |
| name | String | Yes | The parameter name |
| type | Type | No | The type of the parameter. Defaults to "any". |
The parameter type is a string that defines the type of the value expected in the parameter. It should be one of the following:
- any
- array
- boolean
- color
- component
- dimension
- integer
- map
- number
- object
- string
The parameter name should be a unique name starting with an upper- or lower-case letter and containing no white space.
For convenience, a simple parameter name may be used instead of the parameter object (such as "title" instead of { "name": "title", ... }. This format is not recommended, but it does allow compact layout definition for those cases where no type coercion or default values are required.
Layout inflation
Layouts are inflated with the following algorithm:
- Each parameter is evaluated and added to the data-binding context.
- The item property is evaluated using the single child algorithm.
- Properties assigned to the layout but not matching a named parameter, item, or type are passed to the item for evaluation.
Consider a sample layout definition:
"myLayout": {
"parameters": [
"title",
"subtitle"
],
"item": [
{
"when": "${viewport.width > viewport.height}",
"type": "Text",
"text": "<b>${title}:</b> ${subtitle}",
"style": "textStyleHeading1"
},
{
"type": "Text",
"text": "<b>${title}</b><br>${subtitle}",
"style": "textStyleHeading2"
}
]
}
Now invoke the layout with:
{
"type": "myLayout",
"title": "Frankenstein",
"subtitle": "or, The Modern Prometheus",
"color": "green"
}
The inflation logic proceeds as follows.
First, the "title" and "subtitle" parameters are added to the data-binding context.
Next, the item property is evaluated. Assuming that this code executes on a landscape screen, the first
component in the item array is selected.
Finally, the extra properties from the original invocation are passed to the component. In this case, the color property. The net result is the Text component will be created (after data-binding) with:
{
"type": "Text",
"text": "<b>Frankenstein</b>: or, the Modern Prometheus",
"style": "textStyleHeading1",
"color": "green"
}
