APL Base Component Properties (APL 1.7)

(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 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. See below the table for more information about the meaning of the columns.

The Default column lists the default values of properties. All REQUIRED properties must be set or the component will not inflate. A value of <none> means the property doesn't have a default value. The interpretation of <none> is property-dependent. For example, not setting the speech property prevents a component from running the SpeakItem command. Not setting maxHeight allows the component to grow arbitrarily tall, which is equivalent to setting maxHeight to a very large number.

The Styled column identifies properties that you can set from a style. Directly specifying a component property overrides any style-defined values. In the following example the Text component always has an opacity of 0.5 regardless of what might be defined in 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.

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, only the first one is used. The second action is ignored even when the first action is not 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. The following table lists the standard actions.

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"
    }
  ]
}

Standard actions which rely on the default event handlers work when the action is assigned to a touchable component. These actions have no effect on other types of components.

bind

The bind property of a component extends the data-binding context for the component and its children. The bind property also specifies an ordered set of data-bindings that extend the current context. Bindings are ordered, and later bindings may use previous definitions.

bind properties

Each binding object in the binding array contains the following properties

bind evaluation

The bind property evaluates after the when property and before any other properties. Bindings are added to the data-binding context in array order; later bindings can use the results from earlier bindings. For example:

{
  "type": "Text",
  "bind": [
    { "name": "FirstName", "value": "Jasmine" },
    { "name": "LastName", "value": "Smith"},
    { "name": "Title", "value": "Dr."},
    { "name": "FormalName", "value": "${Title} ${LastName}" }
  ],
  "text": "Should I call you ${FirstName} or ${FormalName}?"
}

In this example, FormalName depends upon the prior definitions of Title and LastName. The final text will be “Should I call you Jasmine or Dr. Smith?”. This example is contrived; in actual use the values of FirstName, LastName, and Title would be bound to elements provided in the raw data.

You can change binding values dynamically with the SetValue command. Because the SetValue command can also change properties of a component, capitalize your bound property names so that they won't conflict with intrinsic component properties. For example, use "MyCounter" or "MY_COUNTER" instead of "myCounter".

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 controls whether or not it appears on the screen and how it affects the layout calculation. Set to one of the following values:

Data-binding context, ordinals, and indices used when constructing components are not affected by the display property. For example, in a container with three children, if the first child is set to display=none, it is still be data-bound with index=0 and the next child has index=1.

The following table may be useful when understanding the different ways to hide and show content:

The Focusable? column is for accepting keyboard focus. The Touchable? column is for responding to touch events. Note that when display is set to invisible or none, the touch events pass through the component as if it was not there and are processed by the next component down in the stacking order. The normal display components do not pass touch events through, but they only respond to touch events if they are not disabled.

The descendants of a component with display==invisible are not drawn. In other words, an invisible component will not have visible descendants. Similarly, when a component has display==none, it and all of its descendants are removed from the display hierarchy and take no space on the screen.

entity, entities

Opaque entity data. Alexa devices pass the entity data back to the skill as context.

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.

height and width

The properties width, height, minWidth, minHeight, maxWidth, and maxHeight are dimensional properties.

Minimum width and height values default to 0, which means the component can disappear. Maximum width and height properties default to none, which indicates that the component can scale arbitrarily. If unspecified, the width and height values revert to the component's natural size.

Use relative dimensions for the component height and properties 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:

• Build Responsive APL Documents
• Support Tablets and Other Devices that Can Change Size

id

An identifier you can define for this instance of the component. This is used to locate a particular component in the view hierarchy. Although recommended, the id isn't required to be unique.

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 TouchWrapper is pressed. By setting inheritParentState, 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.
• 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:

• Container
• Text
• EditText
• Touchable components
• Pager
• Sequence
• GridSequence

The recommended way to set layoutDirection is to use data-binding and set the direction in your data source. Set layoutDirection on the top-level Container component in your document and let the child components inherit the setting. Use the bind property on the Container to create a variable to reference in the Container child properties if needed.

The following example uses data-binding and the bind property to set layoutDirection in the top-level Container component to a value in the data source. The second child component in the Container uses the ternary operator to select an appropriate left-facing or right-facing arrow defined in resources based on the value of layoutDirection.

Example document: Bind layoutDirection to a data source  

{
    "type": "APL",
    "version": "1.7",
    "theme": "dark",
    "import": [],
    "mainTemplate": {
        "parameters": [
            "payload"
        ],
        "items": [
            {
                "type": "Container",
                "height": "100%",
                "width": "100%",
                "bind": [
                    {
                        "name": "layoutDirection",
                        "value": "${payload.exampleDataSource.responseLanguage.layoutDirection}"
                    },
                    {
                        "name": "lang",
                        "value": "${payload.exampleDataSource.responseLanguage.language}"
                    }
                ],
                "layoutDirection": "${layoutDirection}",
                "items": [
                    {
                        "type": "Text",
                        "text": "${payload.exampleDataSource.textContent.textToDisplay}"
                    },
                    {
                        "type": "Text",
                        "text": "${layoutDirection == 'LTR' ? @leftArrow : @rightArrow }",
                        "textAlign": "center"
                    }
                ]
            }
        ]
    },
    "resources": [
        {
            "strings": {
                "rightArrow": "→"
            }
        },
        {
            "strings": {
                "leftArrow": "←"
            }
        }
    ]
}

Data source: Bind layoutDirection to a data source  

{
    "exampleDataSource": {
        "description": "Example of a data source the skill provides for an English request.",
        "responseLanguage": {
            "layoutDirection": "LTR",
            "language": "en-US"
        },
        "textContent": {
            "textToDisplay": "This is a text component. The next component uses a conditional statement to display a different arrow depending on whether <code>layoutDirection</code> is LTR or RTL."
        }
    }
}

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 right 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.

onMount

Commands to run when the component is first displayed. Mount commands are used for visual transitions between screens. The event.source.value is left 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. For details about how the component-level and document-level onMount handlers interact, see the document onMount property.

onCursorEnter

Commands to run when a cursor enters the component's active region.

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.

onCursorExit

Commands to run when a cursor exits the component's active region.

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.

opacity

Applies a uniform opacity to this component and the component's child components. 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 current component's opacity is 0.5 and its parent opacity is 0.8, then 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.

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 the layoutDirection for the component. For details, see paddingStart, paddingEnd.
• paddingEnd – Padding to override either the left or right padding, depending on the layoutDirection 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 using the rules shown in the following table.

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.

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
}

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 Counterand 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:

• GridSequence
• Pager
• ScrollView
• Sequence
• Video

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. The "link" role is related.
• 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. Use imagebutton 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 of listitem.
• listitem – An individual item in a list. A listitem must have list ancestor.
• menu – The component is a menu of choices.
• menubar – The component is a container of multiple menus.
• menuitem – Represents an item within a menu.
• progressbar – The component indicates progress of a task.
• radio – The component acts as a radio button.
• radiogroup – The component contains a group of radio 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. A tab should have a tablist ancestor.
• tablist – A region containing a list of tab components.
• text – The component should be treated as static text that cannot 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 are supported:

• ssmlToSpeech
• textToSpeech
• aplAudioToSpeech

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 above example the component is first shifted 10 dp to the right, scaled up by 50%, and then rotated about its center 30 degrees. Each element in the transformation array is one of the following:

Transformation properties from the same group may be gathered 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 } ]

Note that transformations are cumulative. The final example scales the X-axis by 1.5, 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", "20dp") as well as relative dimensions (such as "30%"). The relative dimensions are calculated in terms of 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.

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 will overlap components drawn earlier. It is recommended that sufficient space be added around components to ensure 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

Last updated: Jun 18, 2024