APL Layout (APL 1.5 and earlier)
(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)
An Alexa Presentation Language (APL) layout is a named composite component, defined in an APL document or package. The layout is a function that expands or inflates into a collection of other named layouts and primitive components. An APL layout supports passing arguments in a parameters array. Inflating an APL layout is conditional, as different components can be inflated based on the current data-binding context.
About layouts
You define layouts in the layouts
property of an APL document or package. This property takes a string/object map. You can then invoke the layout in your document by setting the type
property of a component to the name of the layout.
For example, consider a HeaderLayoutExample
layout that accepts two parameters: title
and logo
. Within the layout, a Text
component uses the value provided in the title
parameter and an Image
component uses the value provided in the logo
parameter.
The HeaderLayoutExample
layout inflates into a column-based Container
on a round viewport and places the logo before the title. The layout inflates into a row-based Container
on a rectangular viewport, which places the logo after the title on the same row.
The following example shows the APL code for HeaderLayoutExample
.
{
"layouts": {
"HeaderLayoutExample": {
"description": "A basic header with a title and a logo",
"parameters": [
{
"name": "title",
"type": "string"
},
{
"name": "logo",
"type": "string",
"default": "https://d2o906d8ln7ui1.cloudfront.net/images/cheeseskillicon.png"
}
],
"items": [
{
"when": "${viewport.shape == 'round'}",
"type": "Container",
"direction": "column",
"alignItems": "center",
"padding": [64,32],
"items": [
{
"type": "Image",
"source": "${logo}",
"height": 36,
"width": 36
},
{
"type": "Text",
"text": "${title}",
"style": "textStyleBody",
"maxLines": 1
}
]
},
{
"type": "Container",
"direction": "row",
"padding": [64,32],
"width": "100%",
"justifyContent": "spaceBetween",
"items": [
{
"type": "Text",
"text": "${title}",
"width": "90%",
"style": "textStyleBody",
"maxLines": 2
},
{
"type": "Image",
"source": "${logo}",
"height": 50,
"width": 50
}
]
}
]
}
}
}
To invoke the layout in your document, use the layout name for the component type
and then pass in the parameters. The following example shows how you invoke the HeaderLayoutExample
layout.
{
"mainTemplate": {
"parameters": [
"payload"
],
"items": [
{
"type": "HeaderLayoutExample",
"title": "This is the text to use for the title"
}
]
}
}
Layout properties
A layout object has the properties shown in the following table.
Property | Type | Required | Description |
---|---|---|---|
|
String |
No |
Provides a description of this layout. |
|
Array of Component |
Yes |
The component to inflate. When |
|
Array of parameters |
No |
An array of parameters you can pass to this layout. |
item, items
The item
property is either a single component or, if items
, an array of components. Other layouts can also be part of the items
, provided they have already been imported or defined earlier in the layouts
object. See Data-binding evaluation.
When items
contains an array, the layout inflates the first component where the when
condition is true
.
parameters
The parameters are named values that you pass a layout when invoking it. Each parameter is an object with the properties shown in the following table.
Property | Type | Required | Description |
---|---|---|---|
|
Any |
No |
The default value to apply if this parameter is not specified. Defaults to empty. |
|
String |
No |
An optional description that explains the purpose of this parameter. |
|
String/etc |
Yes |
The unique parameter name. Names must start with an upper-case or lower-case letter and can't contain white space. |
|
Type |
No |
The type of the parameter. Defaults to |
For convenience, you can use a simple parameter name instead of the parameter object. For example, define the parameter as title
instead of { "name": "title", ... }
. This allows for more compact code when you don't need default values or type coercion for the values you pass to the parameter. Using the full parameter object is recommended for clarity.
Layout inflation
APL uses the following algorithm to inflate a layout:
- Evaluate each parameter and add the parameter to the data-binding context.
- Evaluate the
item
oritems
property using the single child inflation algorithm. - Pass any properties assigned to the layout, but not matching a named parameter, item, or type to the item for evaluation.
For example, the following code defines a simple layout.
"myLayout": {
"parameters": [
"title",
"subtitle"
],
"item": [
{
"when": "${viewport.width > viewport.height}",
"type": "Text",
"text": "<b>${title}:</b> ${subtitle}",
"style": "textStyleDisplay1"
},
{
"type": "Text",
"text": "<b>${title}</b><br>${subtitle}",
"style": "textStyleDisplay2"
}
]
}
The following example invokes this layout and passes in three parameters: title
, subtitle
, and color
. The color
parameter is not specified as a property in myLayout
.
{
"type": "myLayout",
"title": "Frankenstein",
"subtitle": "or, The Modern Prometheus",
"color": "green"
}
Assume the user's device has a landscape screen. The inflation logic does the following:
- Add the "title" and "subtitle" parameters to the data-binding context.
- Evaluate the
item
property and find the first component where thewhen
condition evaluates to true. Because the user's device has a landscape screen, APL selects the first component in theitems
array. - Pass any extra properties to the selected
item
. This example passed acolor
property to the layout, which doesn't match any of the defined properties formyLayout
. Therefore, pass this property on to the selected item.
The net result is a Text
component that looks like the following.
{
"type": "Text",
"text": "<b>Frankenstein</b>: or, the Modern Prometheus",
"style": "textStyleDisplay1",
"color": "green"
}
Last updated: Nov 28, 2023