APL Base Component Properties (2024.1)
(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)
A component is a primitive element that displays on the viewport.
In Alexa Presentation Language (APL), components are primitive visual components rendered by the client. For example, a Text
component displays text on the screen. All APL components share a set of base properties.
Properties
All components support the following properties.
Property | Type | Default | Styled | Dynamic | Description | Version added |
---|---|---|---|---|---|---|
accessibilityLabel |
String | — | No | Yes | Voice-over reads this string when the user selects this component | 1.1 |
action , actions |
Array of actions | [] | Yes | No | Programmatic equivalents for complex touch interactions | |
bind |
Array of Binding | — | No | No | Expressions to add to the data binding context | 1.0 |
description |
String | — | No | No | Optional description of this component | 1.0 |
checked |
Boolean | false |
No | Yes | When true , this component has the checked state set. |
1.1 |
disabled |
Boolean | false |
No | Yes | When true , this component doesn't respond to touch or focus. |
1.1 |
display |
String (invisible , none , normal ) |
normal | Yes | Yes | Determines whether the component displays on the screen. | 1.1 |
entities , entity |
Array of Entities | — | No | Yes | Opaque data used to clarify references in Alexa | 1.0 |
handleTick |
Array of tick handlers | [] | No | No | Tick handlers to invoke as time passes | |
handleVisibilityChange |
Array of visibility change handlers | [] |
No | No | Visibility handlers to invoke when visibility of the component changes. | |
height |
Positive Dimension | auto |
Yes | Yes | The requested height of the component. | 1.0 |
id |
String | — | No | No | Reference name of the component, used for navigation and events. A valid component ID match the regular expression [_a-zA-Z][_a-zA-Z0-9]* . |
1.0 |
inheritParentState |
Boolean | false |
No | No | When true , replace the component state with the state of the parent component. |
1.0 |
layoutDirection |
String. Set to LTR , RTL , inherit |
"inherit" | Yes | Yes | The direction in which the component renders. Set this property for either left-to-right or right-to-left languages. | 1.7 |
maxHeight |
Positive Dimension | <none> | Yes | Yes | The maximum allowed height of this component. | 1.0 |
maxWidth |
Positive Dimension | <none> | Yes | Yes | The maximum allowed width of this component. | 1.0 |
minHeight |
Non-negative Dimension | 0 | Yes | Yes | The minimum allowed height of this component. | 1.0 |
minWidth |
Non-negative Dimension | 0 | Yes | Yes | The minimum allowed width of this component. | 1.0 |
onMount |
Array of command | — | No | No | Command to run when the component is first displayed. | 1.1 |
onCursorEnter |
Array of command | [] | No | No | Commands to run when a cursor (mouse pointer) enters the active region for the component. | 1.2 |
onCursorExit |
Array of command | [] | No | No | Commands to run when a cursor (mouse pointer) exits the active region for the component. | 1.2 |
onSpeechMark |
Array of command | [] | No | No | Commands to run when the audio specified in the speech property encounters a speech mark. |
2023.1 |
opacity |
Number | 1.0 | Yes | Yes | Opacity of this component and children. | 1.0 |
padding |
Array of non-negative Absolute Dimension | [] | Yes | Yes | Space to add on the sides of the component | 1.6 |
paddingBottom |
Non-negative Absolute Dimension | 0 | Yes | Yes | Space to add to the bottom of this component. | 1.0 |
paddingEnd |
Non-negative Absolute Dimension | <none> | Yes | Yes | Space to add to the end edge of this component. The end edge is either the left or right side of the component, depending on the layoutDirection for the component. |
1.7 |
paddingLeft |
Non-negative Absolute Dimension | 0 | Yes | Yes | Space to add to the left of this component. | 1.0 |
paddingRight |
Non-negative Absolute Dimension | 0 | Yes | Yes | Space to add to the right of this component. | 1.0 |
paddingStart |
Non-negative Absolute Dimension | <none> | Yes | Yes | Space to add to the start edge of this component. The start edge is either the left or right side of the component, depending on the layoutDirection for the component. |
1.7 |
paddingTop |
Non-negative Absolute Dimension | 0 | Yes | Yes | Space to add to the top of this component. | 1.0 |
preserve |
Array of string | — |
No | No | Properties to save when reinflating the document with the Reinflate command. |
1.6 |
role |
String | — | Yes | No | Role or purpose of the component | |
shadowColor |
Color | transparent | Yes | Yes | Shadow color | 1.2 |
shadowHorizontalOffset |
Absolute Dimension | 0 | Yes | Yes | Horizontal offset of the shadow | 1.2 |
shadowRadius |
Non-negative Absolute Dimension | 0 | Yes | Yes | Shadow blur radius | 1.2 |
shadowVerticalOffset |
Absolute Dimension | 0 | Yes | Yes | Vertical offset of the shadow | 1.2 |
speech |
Opaque | <none> | No | No | Transformed speech information for audio playback | 1.0 |
style |
Style | — | No | No | Named style or styles to apply. | 1.0 |
transform |
Array of transform | — | No | Yes | Array of transformations. | 1.1 |
type |
String | Required | No | No | The type of the component. | 1.0 |
when |
Boolean | true |
No | No | If it evaluates to false , this component doesn't inflate. |
1.0 |
width |
Positive Dimension | auto |
Yes | Yes | The requested width of this component. | 1.0 |
The "Default" column lists the default values of properties. All Required properties must be set or the component doesn't inflate. Properties with no default display a dash (—) in the "Default" column. The interpretation of no default is property-dependent. For example, not setting the speech
property prevents a component from speaking text when you run the SpeakItem command. Not setting maxHeight
lets the component grow arbitrarily tall, which is equivalent to setting maxHeight
to a large number.
The "Styled" column identifies properties that you can set from a style. Directly specifying a value for a component property overrides any style-defined values. In the following example, the Text
component always has an opacity of 0.5 regardless of the definition of myTextStyle
:
{
"type": "Text",
"opacity": 0.5,
"style": "myTextStyle"
}
The "Dynamic" column identifies properties that you can change dynamically with the SetValue command. Setting a dynamic property with SetValue
overrides any style values. There is no mechanism to unset a dynamic property.
When a component is the source or target of an event, the following values are reported in event.source
or event.target
:
{
"bind": Map, // Access to component data-binding context
"checked": Boolean, // Checked state
"disabled": Boolean, // Disabled state
"focused": Boolean, // Focused state
"height": Number, // Height of the component, in dp (includes the padding)
"id": ID, // ID of the component
"opacity": Number, // Opacity of the component [0-1]
"pressed": Boolean, // Pressed state
"type": TYPE, // Component type (e.g., "Frame", "Image")
"uid": UID, // Runtime-generated unique ID of the component
"width": Number // Width of the component, in dp (includes the padding)
}
Component-specific values are added to event.source
and event.target
.
accessibilityLabel
A text string used by a screen reader in accessibility mode.
actions
Assistive technology can programmatically interact with on-screen components when the user can't due to a disability. A component defines a set of actions
for use with this type of technology. The actions
property contains a list of action objects, where each action object has a name
and a set of commands
to run. The name
of the action can be one of the standard actions or a custom action.
The following example shows a TouchWrapper
that defines one standard action (activate
) and one custom action (thumbsup
).
{
"type": "TouchWrapper",
"actions": [
{
"name": "activate",
"label": "Reply to user",
"command": {
"type": "SendEvent",
"arguments": "Activated by action invocation"
}
},
{
"name": "thumbsup",
"label": "Mark positively",
"command": {
"type": "SetValue",
"property": "Rating",
"value": 1
}
}
]
}
The actions
property is an array of objects with the properties shown in the following table.
Name | Type | Default | Description |
---|---|---|---|
command , commands |
Array of commands | — |
An array of commands to run when this action is triggered. |
enabled |
Boolean | true |
When true , the user can invoke this action. |
label |
String | REQUIRED | A localized description of this action for presentation to the user |
name |
String | REQUIRED | The name of the action to perform |
The label
property provides a localized description of the action. Examples of labels include "remove item," and "reply."
The enabled
property determines whether the action can be invoked. Disabled actions might be presented by an accessibility system, but marked as not available.
If two actions in the action list have the same name
property, the first one is used. The second action is ignored even when the first action isn't enabled.
Standard actions are reserved names associated with standard event handlers. When you provide a standard action in the action list without a command array, invoking the action invokes the designated event handler. There are two types of standard actions: implicit and explicit. To enable an explicit action, you must specify the action in the component actions
property. Implicit actions are enabled by default, but you can override the commands.
The following table lists the standard actions.
Name | Components | Type | Default event handler | Description |
---|---|---|---|---|
|
Explicit |
|
Equivalent to a single press and release, or a single tap. | |
|
Explicit |
Equivalent to double-tapping the component. | ||
|
Explicit |
Equivalent to long-press on a component. | ||
|
Implicit |
None |
Equivalent to scrolling the component one page backward. The scrolling action invokes any usual handlers that are invoked as a result of scrolling. | |
|
Implicit |
None |
Equivalent to scrolling component one page forward. The scrolling action invokes any usual handlers that are invoked as a result of scrolling. | |
|
Explicit |
Equivalent to a swipe gesture on a component. | ||
|
Explicit |
|
Equivalent to a single tap. |
The following example shows a TouchWrapper
component that defines an activate
action. The activate
action doesn't have a command array. Therefore, invoking this action invokes the commands defined in the onPress
property.
{
"type": "TouchWrapper",
"onPress": {
"type": "SendEvent",
"arguments": "I was pressed!"
},
"actions": [
{
"name": "activate",
"label": "message to server"
}
]
}
Because the Tap gesture is analogous to a "press," the onTap
handler runs as a fallback in cases where an "activate" action would have resulted in a call to onPress
but that event handler isn't provided.
In the following example, the "activate" action calls the onTap
handler because the "activate" action doesn't have a command array and the onPress
handler isn't provided.
{
"type": "TouchWrapper",
"gestures": [
{
"type": "Tap",
"onTap": {
"type": "SendEvent",
"arguments": "This is called for the activate action"
}
}
],
"actions": [
{
"name": "activate",
"label": "message to server"
}
]
}
You can disable the implicit standard actions. The following example disables accessibility scrolling for a Pager
.
{ "type": "Pager", "actions": [ { "name": "scrollforward", "label": "Disabled scrolling", "enabled": false } ] }
bind
The bind
property of a component extends the data-binding context for the component and its children with local bound variables. For details about bound variables, see APL Bound Variables.
checked
The checked
property sets the checked
state of the component. You can use component states when you define styles.
Use the SetValue
command to change the checked
state on a component.
Set the inheritParentState
property to true
on child components to inherit the checked
state of the parent.
disabled
The disabled
property sets the disabled
state of the component. You can use component states when you define styles.
Use the SetValue
command to change the disabled
state on a component.
Set the inheritParentState
property to true
on child components to inherit the disabled
state of the parent.
display
The display
property of a component determines whether the component displays on the screen and how the component affects the layout calculation. Set to one of the following values shown in the following table.
Name | Description |
---|---|
invisible |
The component isn't drawn, but takes up space. The component doesn't respond to touch events. |
none |
Remove the component. The component isn't part of the layout and doesn't respond to touch. |
normal |
Draw the component. |
The display
property doesn't affect the data-binding context, ordinals, and indices used when constructing components. For example, in a container with three children, if the first child has display=none
, that child is still data-bound with index=0
and the next child has index=1
.
The following table shows the different ways to hide and show content:
Display | Disabled | Opacity | Visible? | Occupies Space? | Focusable? | Touchable? | Touch and hover passes through? |
---|---|---|---|---|---|---|---|
normal | false |
> 0 | Yes | Yes | Yes | Yes | No |
normal | true |
> 0 | Yes | Yes | No | No | No |
normal | false |
0 | No | Yes | Yes | Yes | No |
normal | true |
0 | No | Yes | No | No | No |
invisible | any | any | No | Yes | No | No | Yes |
none | any | any | No | No | No | No | Yes, but the component takes no space |
The Focusable? column is for accepting keyboard focus. The Touchable? column is for responding to touch events. When display
is invisible
or none
, the touch events pass through the component as if it wasn't there and are processed by the next component down in the stacking order. The normal
display components don't pass touch events through, but they only respond to touch events when disabled
is false
.
The descendants of a component with display=invisible
aren't drawn. This means that an invisible component doesn't have visible descendants. Similarly, when a component has display=none
, the component and all its descendants are removed from the display hierarchy and take no space on the screen.
entities, entity
Opaque entity
data. Alexa devices pass the entity data back to the skill as context. Use this property to provide information about the purpose of the component to use in your skill code.
Set this property to an array of objects. Each object can have the properties id
, type
, and value
. Any other properties aren't included in the visual context.
For details about the visual context, see APL Visual Context in the Skill Request.
handleTick
An array of tick event handlers to run as time passes.
The event generated for a tick event handler has the following form.
"event": {
"source": {
"type": "COMPONENT_TYPE", // The type of the component (e.g., "Pager", "TouchWrapper")
"handler": "Tick",
... // Component source properties
}
}
The event.source.type
property contains the name of the component, such as "TouchWrapper
" or "ScrollView
". Refer to Event source for a description of event.source
properties.
The component tick event handler runs in the component data-binding context.
handleVisibilityChange
An array of visibility change handlers to run when the visible region or overall opacity of the component changes.
The component visibility change handler runs in the component data-binding context.
height
Value used to calculate the final height of the component. You can set height
in one of four different ways:
- Absolute dimension – A value such as
100dp
,25vh
, or24px
fixes the height of the component. A pure number such as50.2
is interpreted as adp
value. Therefore,50.2
is the same as"50.2dp"
. For more about absolute dimensions, see Absolute dimensions. - Relative dimension – A value such as
25%
sets the height of the component to a percentage height of its parent component. The parent component must have a defined dimension for this to work. If the parent component has aheight
ofauto
, using a relative height for a child component is undefined and sets to zero. For more about relative dimensions, see relative dimensions. - Auto dimension – With
auto
, the component takes on the height of its children plus any padding. For aFrame
, the height also incudes the height of its borders. - Dimension not set – When the
height
of a component isn't specified, the height reverts to the default height for the component. Refer to the specific component documentation for default heights.
You can set height
to a value that's smaller than the sum of the vertical padding, borders, and heights of any contained children. In this scenario, the component clips the contents to the final component height.
Use relative dimensions for the component height
whenever possible. A component with relative dimensions for the size can adjust to differently-sized screens. For more about making sure your documents look good on different devices, see the following:
id
An identifier you can define for an instance of the component. The id
locates a particular component in the view hierarchy. The regular expression for a valid id
is [_a-zA-Z][_a-zA-Z0-9]*
. Although recommended, the id
isn't required to be unique. Internally, APL assigns each component an internal ID (uid
).
The following example shows a Container
with a Text
and Image
component.
{
"type": "Container",
"items": [
{
"type": "Text",
"id": "myText"
},
{
"type": "Image"
}
]
}
The Container
, Text
, and Image
are each assigned unique internal id values such as :1001
, :1002
, and :1003
respectively. Alexa reports both the generated internal uid
and developer-assigned id
values in the visual context.
You can use the id
for component in the selector syntax to target a component with a command.
inheritParentState
Replaces the component state with the state of the parent of the component. Used for components that should visually change appearance based on the state of the parent. For example, you might want a Text component inside of a TouchWrapper to change color when the user presses the TouchWrapper
. If you set inheritParentState
to true
, the Text
component changes state whenever the TouchWrapper
changes state.
layoutDirection
Specifies the direction in which the component renders. Set this property to one of the following:
inherit
– (Default). The component inherits the layoutDirection from its parent. When the component is directly undermainTemplate
, the component inherits thelayoutDirection
specified in the document.LTR
– The component uses the left-to-right direction.RTL
– The component uses the right-to-left direction.
The layoutDirection
for the component determines how the paddingStart
and paddingEnd
properties override paddingLeft
and paddingRight
.
The layoutDirection
property determines the internal layout of the following components:
The recommended way to set layoutDirection
is to set the document-level layoutDirection
to a value in your data source. Use the component-level layoutDirection
if a specific component in your layout requires a different setting than the overall document-level layoutDirection
.
The following example displays multiple text blocks in a Container
. All the text blocks use the document default layoutDirection
except one, which overrides the value.
In this example, changing the exampleDataSource.responseLanguage.layoutDirection
in the data source automatically changes the layout shown on the screen. Use the locale provided in the request sent to your skill to determine the values for layoutDirection
and lang
and then pass these values to APL in your data source.
For details about supporting different languages and determining the locale of the request, see Develop Skills in Multiple Languages.
alexa-layouts
package also support the layoutDirection
parameter. For details about how to set this property on the responsive components, see Support for Right-to-left Languages (Responsive Components and Templates).maxHeight
A dimension that limits the maximum height of a component. The component is never taller than the maxHeight
. The maxHeight
property should always be greater than or equal to the minHeight
property. If the maxHeight
property isn't specified, it's assumed to be infinite.
maxWidth
A dimension that limits the maximum width of a component. The component is never wider than the maxWidth
. The maxWidth
property should always be greater than or equal to the minWidth
property. If the maxWidth
isn't specified, it's assumed to be infinite.
minHeight
A dimension that limits the minimum height of a component. The component is never shorter than the minHeight
. The minHeight
property should always be less than or equal to the maxHeight
property. If the minHeight
property isn't specified, it's assumed to be zero.
minWidth
A dimension that limits the minimum width of a component. The component is never narrower than the minWidth
. The minWidth
property should always be less than or equal to the maxWidth
property. If the minWidth
property isn't specified, it's assumed to be zero.
onCursorEnter
Commands to run when a cursor enters the active region for a component.
The event.source.value
property contains the standard source value for the component. For details, see: Event source property.
A component where the disabled state is true
doesn't respond to changes in cursor events and doesn't run any commands assigned to the onCursorEnter
event handler. If the cursor is over a disabled component and then component is enabled, an onCursorEnter
event is generated for the component.
The event generated has the following form.
"event": {
"source": {
"type": COMPONENT_TYPE, // The type of the component (e.g., "Pager", "TouchWrapper")
"handler": "CursorEnter",
... // Component source properties
}
}
The event.source.type
property contains the name of the component, such as "TouchWrapper
" or "ScrollView
". Refer to Event source for a description of event.source
properties.
The onCursorEnter
event handler runs in fast mode in the component data-binding context..
onCursorExit
Commands to run when a cursor exits the active region for a component.
The event.source.value
property contains the standard source value for the component. For details, see: Event source property.
A component where the Disabled state is true
doesn't respond to changes in cursor events and doesn't run any commands assigned to the onCursorExit
event handler. If the cursor is over a disabled component and then component is enabled, an onCursorExit
event is generated for the component.
The event generated has the following form.
"event": {
"source": {
"type": "COMPONENT_TYPE", // The type of the component (e.g., "Pager", "TouchWrapper")
"handler": "CursorExit",
... // Component source properties
}
}
The event.source.type
property contains the name of the component, such as "TouchWrapper
" or "ScrollView
". Refer to Event source for a description of event.source
properties.
The onCursorExit event handler runs in fast mode in the component data-binding context..
onMount
Commands to run when the component is first displayed. Use the mount commands for visual transitions between screens. The event.source.value
remains unset during mount.
The onMount
command runs when the document loads. Component onMount
commands run even if the component itself is invisible or otherwise not displayed on the screen.
The event generated has the following form.
"event": {
"source": {
"type": "COMPONENT_TYPE", // The type of the component (e.g., "Pager", "TouchWrapper")
"handler": "Mount",
... // Component source properties
}
}
The event.source.type
property contains the name of the component, such as "TouchWrapper
" or "ScrollView
". Refer to Event source for a description of event.source
properties.
The onMount
event handler runs in normal mode in the component data-binding context. For details about how the component-level and document-level onMount
handlers interact, see the document onMount
property.
onSpeechMark
Commands to run when the audio specified in the speech
property encounters a speech mark.
For more details about speech marks, see Speech Marks - Amazon Polly
The event.source.value
property contains the standard source value for the component. For details, see: Event source property.
The onSpeechMark
event runs during the duration of the SpeakItem
command when the speech
property on the component is set to audio that contains speech marks.
The event generated has the following form.
"event": {
"source": {
"type": COMPONENT_TYPE, // The type of the component (e.g., "Pager", "TouchWrapper")
"handler": "SpeechMark",
... // Component source properties
},
"markType": MARK_TYPE, // Type of speech mark
"markTime": NUMBER, // Start time of speech mark, in milliseconds
"markValue": STRING
}
Each speech mark has a type, as shown in the following table.
Type | Description |
---|---|
|
Indicates a sentence element in the input text. |
|
Indicates a word element in the text. |
|
Describes the face and mouth movements corresponding to each phoneme in the speech. |
|
Describes a |
For example, a word
speech mark generated when the SpeakItem
command reads the word "right" generates the following event.
"event": {
"source": {
"type": "Text",
"handler": "SpeechMark",
},
"markType": "word",
"markTime": 3562,
"markValue": "right"
}
The onSpeechMark
event handler runs in fast mode in the component data-binding context..
The following example shows an APL document that uses SpeakItem
to read a short paragraph containing directional words. The onSpeechMark
handler runs commands that display a vector graphic arrow that corresponds to the words in the paragraph. For example, the arrow points to the right when Alexa reads the word "right" and points down when Alexa reads the word "down." The example uses a when
condition on the onSpeechMark
handler to update the vector graphic based on the words "right," "left," "up," "down," and "disappear."
opacity
Applies a uniform opacity
to this component and the children of the component. The opacity
is a number from 0 through 1. Numbers outside this range are clipped to the range. The actual displayed opacity of a component is the product of the opacity
value and all the ancestor opacity values.
For example, if the opacity for the current component is 0.5 and its parent opacity is 0.8, the actual displayed opacity of the component is 0.4. Setting the opacity to 0 hides the component, but doesn't remove it from the component hierarchy.
padding
The padding
properties add space around a component. The calculated component width
and height
define the outer bounds of the component and the clipping boundary. The values you provide for padding specify the space between the outer bounds of the component and the content. The values you provide for the padding properties must be non-negative, absolute dimensions.
![The component layout model. The width and height properties set the bounds of the component. The padding properties inset the visible content of the component from the bounds.](https://m.media-amazon.com/images/G/01/mobile-apps/dex/ask-apl/reference/paddingModel._TTH_.png)
You can specify the padding values with the padding
property and with separate properties for each side of the component:
padding
– Accepts an array of values to set padding for multiple sides of the component.paddingBottom
– Padding for the bottom of the component.paddingLeft
– Padding for the left side of the component.paddingRight
– Padding for the right side of the component.paddingTop
– Padding for the top of the component.paddingStart
– Padding to override either the left or right padding, depending on thelayoutDirection
for the component. For details, see paddingStart, paddingEnd.paddingEnd
– Padding to override either the left or right padding, depending on thelayoutDirection
for the component. For details, see paddingStart, paddingEnd.
The padding
property is an array of one to four values, ordered by left
, top
, right
, and bottom
. When you provide fewer than four values in this array, the padding
property expands to a four-element array according to the rules shown in the following table.
Array mapping | Description |
---|---|
|
Assign the X value to all four sides. |
|
Assign the X value to both the left and right sides. Assign the Y value to the top and bottom. |
|
Assign the X value to the left side. Assign the Y value to the top and bottom. Assign the Z value to the right side. |
The other four padding properties override the values specified in padding
for the specific side. The following examples show three equivalent ways to specify padding. Each example results in padding set to 10 for the left and right, 20 for the top, and 40 for the bottom.
The single padding
property with four values sets the left padding to 10, the top to 20, the right to 10, and the bottom to 40.
{
"padding": [10,20,10,40]
}
The single padding
property with two values sets the left and right padding to 10 and the top and bottom to 20. Then, the paddingBottom
property overrides the bottom to change it to 40.
{
"padding": [10,20],
"paddingBottom": 40
}
The single padding
property with one value sets the padding for all four sides to 10. Then, the paddingTop
overrides the top padding and sets it to 20. The paddingBottom
overrides the bottom padding and sets it to 40.
{
"padding": 10,
"paddingTop": "20dp",
"paddingBottom": 40
}
paddingStart, paddingEnd
When specified, the paddingStart
and paddingEnd
properties override paddingLeft
and paddingRight
. The override depends on the layoutDirection
property.
Property | Left-to-right ("LTR") | Right-to-left ("RTL") |
---|---|---|
|
Overrides |
Overrides |
|
Overrides |
Overrides |
For example, when layoutDirection
is LTR
, the following component has 15 for the left padding and 20 for the right padding. When layoutDirection
is RTL
, the component has 15 for the right padding and 20 for the left:
{
"paddingLeft": 10,
"paddingRight": 10,
"paddingStart": 15,
"paddingEnd": 20
}
paddingStart
and paddingEnd
properties require APL 1.7 or later. You can set both these properties and the paddingLeft
/ paddingRight
properties for your component. Earlier versions of APL ignore the newer properties.preserve
An array of dynamic component properties and bound properties to save when reinflating the document with the Reinflate
command. The Reinflate
command preserves these properties if the old component id
matches the new id
. The component properties specified in preserve
aren't saved if the component doesn't have an id
.
The following example saves the checked
state of a TouchWrapper
.
{
"type": "TouchWrapper",
"id": "MyUniqueID",
"preserve": ["checked"]
}
You can also save bound properties. The following example defines a bound property called Counter
and a TouchWrapper
that increments Counter
. The preserve
array contains the name of this bound property. This saves the value in Counter
when the document reinflates.
{
"type": "TouchWrapper",
"id": "MyCounterButton",
"bind": [
{
"name": "Counter",
"value": 0
}
],
"preserve": [
"Counter"
],
"items": {
"type": "Text",
"text": "You have pushed this button ${Counter} times"
},
"onPress": [
{
"type": "SetValue",
"property": "Counter",
"value": "${Counter + 1}"
}
]
}
In addition to dynamic properties and bound properties, some components have component-specific preserve
property names for saving component-specific data. For example, components that scroll include preserve
properties for saving the scroll position. See the preserve
property on the following components:
The preserve
properties evaluate in the data-binding context of the component with the event
properties augmented by the new configuration values. This allows a dynamic choice of which properties to preserve.
role
The role
provides machine-readable information about the purpose of the component. Some assistive technologies use this information. For example, a screen reader might use the role
when describing a component displayed on the screen.
APL supports the following roles on components:
adjustable
– The component can be "adjusted" (for instance, a slider is adjustable).alert
– A region with important information to be presented to the user.button
– An input that triggers general actions when clicked or pressed. Related to thelink
role.checkbox
– A check box which can be checked, unchecked, or have mixed checked state.combobox
– Represents a combo box, which allows the user to select among several choices.header
– Acts as a header for a content section (for example, the title of a navigation bar).image
– The component should be treated as an image. Useimagebutton
if this component also acts as a button.imagebutton
– The component is an image that also works as a button.keyboardkey
– The component acts as a keyboard key.link
– An input when triggered causes the user agent to navigate to a new resource or display.list
– A region containing a list oflistitem
.listitem
– An individual item in a list. Alistitem
must havelist
ancestor.menu
– The component is a menu of choices.menubar
– The component is a container of multiple menus.menuitem
– Represents an item within amenu
.progressbar
– The component indicates progress of a task.radio
– The component acts as a radio button.radiogroup
– The component contains a group ofradio
buttons.scrollbar
– Represents a scroll bar that controls the scrolling of a region.search
– A text field component that should also be treated as a search field.spinbutton
– A button which opens a list of choices.summary
– Used when a component can be used to provide a quick summary of current conditions in the app when the app first launches.switch
– Represent a switch which can be turned on and off, as opposed to checked/unchecked.tab
– Represents a tab. Atab
should have atablist
ancestor.tablist
– A region containing a list oftab
components.text
– The component should be treated as static text that can't change.timer
– A region displaying a counter that indicates elapsed time or time remaining.toolbar
– Used to represent a tool bar (a container of action buttons or components).
shadowColor
The color of the shadow. This color normally contains some transparency. The overall opacity
is also applied to the shadow color.
shadowHorizontalOffset
The horizontal drawing offset of the shadow. Positive numbers move the shadow to the right; negative numbers move it to the left.
shadowRadius
The blur radius of the shadow.
shadowVerticalOffset
The vertical drawing offset of the shadow. Positive numbers move the shadow down; negative numbers move it up.
speech
Opaque data provided by a transformer that converts content to speech. The following transformers output audio that you can use with the speech
property:
Use a data-binding expression to bind the speech
property to the output of the transformer. Then use the SpeakItem
or SpeakList
commands to tell Alexa to speak the content.
style
A named style to use to set properties on the component.
transform
The transformation array is an array of transformation values applied to the component. For example:
"transform": [ { "rotate": 30 }, { "scaleX": 1.5 }, { "translateX": 10 }]
Each individual transform is an object with a single property and associated value. Transformations are applied from right to left (following the web standard). In the previous example the component first shifts 10 dp to the right, scales up by 50%, and then rotates about its center 30 degrees.
Each element in the transformation array is one of the following:
Property | Group | Type | Default | Description |
---|---|---|---|---|
rotate | Rotate | Number | 0.0 | Rotation angle, in degrees. Positive angles rotate in the clockwise direction. |
scale | Scale | Number | 1.0 | Uniform scaling in both X and Y. |
scaleX | Scale | Number | 1.0 | Scaling in the X direction (overrides "scale" if in same group) |
scaleY | Scale | Number | 1.0 | Scaling in the Y direction (overrides "scale" if in same group) |
skewX | Skew | Number | 1.0 | Skew angle for the X-axis, in degrees. X-axis lines remain horizontal. |
skewY | Skew | Number | 1.0 | Skew angle for the Y-axis, in degrees. Y-axis lines remain vertical. |
translateX | Move | Dimension | 0.0 | Distance to translate the object to the right. |
translateY | Move | Dimension | 0.0 | Distance to translate the object down. |
You can gather transformation properties from the same group into a single object. For example, the following are equivalent:
[ { "scaleX": 3.0, "scaleY": 2.0} ]
[ { "scale": 3.0, "scaleY": 2.0 } ]
[ { "scaleX": 3.0 }, { "scaleY": 2.0 } ]
[ { "scale": 2.0 }, { "scaleX": 1.5 } ]
Transformations are cumulative. The final example scales the X-axis by 1.5, and then scales both axes by 2.0, giving a final scaling of { "scaleX": 3.0, "scaleY": 2.0 }
.
Transformations apply to components after the document layout is calculated using the default bounds for the component. As a result, transformations don't effect the document flow for any components other than the transformed component and its children.
The translation values support both absolute dimensions (such as 10px
or 20dp
) as well as relative dimensions (such as 30%
). The relative dimensions are calculated based on the unscaled component width and height. The following example rotates a component 45 degrees about its bottom-right corner:
"transform": [
{ "translateX": "50%", "translateY": "50%" },
{ "rotate": 45 },
{ "translateX": "-50%", "translateY": "-50%" }
]
The default bounds of a component are the bounds of a component before the transformations defined in the transform
property are applied.
The transformed bounds of a component are the bounds of a component after the transformations defined in the transform
property are applied.
type
Specifies the particular component to inflate. It can be one of the primitive components listed in this section or can be a named layout.
when
If the when
expression is true
, inflate the component. If false
, ignore the component and all child components.
width
Value used to calculate the final width of the component. You can set width
in one of four different ways:
- Absolute dimension – A value such as
100dp
,25vh
, or24px
fixes the width of the component. A pure number such as50.2
is interpreted as adp
value. Therefore,50.2
is the same as"50.2dp"
. For more about absolute dimensions, see Absolute dimensions. - Relative dimension – A value such as
25%
sets the width of the component to a percentage width of its parent component. The parent component must have a defined dimension for this to work. If the parent component has awidth
ofauto
, using a relative width for a child component is undefined and sets to zero. For more about relative dimensions, see relative dimensions. - Auto dimension – With
auto
, the component takes on the width of its children plus any padding. For aFrame
, the width also incudes the width of its borders. - Dimension not set – When the
width
of a component isn't specified, the width reverts to the default width for the component. Refer to the specific component documentation for default widths.
You can set width
to a value that's smaller than the sum of the horizontal padding, borders, and widths of any contained children. In this scenario, the component clips the contents to the final component width.
Use relative dimensions for the component width
whenever possible. A component with relative dimensions for the size can adjust to differently-sized screens. For more about making sure your documents look good on different devices, see the following:
Shadow notes
Text components generate shadows that follow the text shape. All other types of components generate shadows that are rectangular boxes surrounding the transformed bounds of the component (including the padding). Component shadows are clipped to their parent container.
Component shadows are drawn in standard drawing order. That means that the shadow of a component later in the drawing order overlaps components drawn earlier. Add space around the components to make sure that the component shadows don't overlap or get clipped unnecessarily.
Related topics
- APL Components
- Actionable Component Properties
- Touchable Component Properties
- Multi-child Component Properties
- Alexa Design Guide: Alexa Presentation Language
Last updated: Feb 29, 2024