Component (Character Displays)

Note: Learn how to improve your skills with APL with Build visually rich experiences using APL at the Alexa Learning Lab.

A component is a primitive element that displays on the viewport.

Common Component properties

Common Component properties

All components support the following properties.

Property	Type	Default	Dynamic	Description
description	String	""	No	Optional description of this component.
bind	Array of Binding	[]	No	Expressions to add to the data binding context
display	String	normal	Yes	Control if the component is displayed on the screen.
height	Dimension	auto	No	The requested height of the component.
id	String	""	No	Reference name of the component, used for navigation and events.
maxHeight	Dimension	<none>	No	The maximum allowed height of this component.
maxWidth	Dimension	<none>	No	The maximum allowed width of this component.
minHeight	Dimension	0	No	The minimum allowed height of this component.
minWidth	Dimension	0	No	The minimum allowed width of this component.
onMount	Array of command	[]	No	Command to run when the component is first displayed.
paddingBottom	Absolute Dimension	0	No	Space to add to the bottom of this component.
paddingLeft	Absolute Dimension	0	No	Space to add to the left of this component.
paddingRight	Absolute Dimension	0	No	Space to add to the right of this component.
paddingTop	Absolute Dimension	0	No	Space to add to the top of this component.
type	String	REQUIRED	No	The type of the component.
when	Boolean	true	No	If it evaluates to false, this component does not inflate.
width	Dimension	auto	No	The requested width of this component.

The Default column lists the default values of properties. All REQUIRED properties must be set or the component will not be displayed.

The Dynamic column identifies properties that may be dynamically changed (see SetValue command). Using SetValue to set a dynamic property overrides any style values. There is no mechanism to unset a dynamic property.

bind

The bind property of a component extends the data-binding context for the component and its children. The bind property specifies an ordered set of data-bindings that extend the current context. Bindings are ordered; later bindings may use previous definitions. Each binding object in the binding array contains the following:

Property	Type	Default	Description
name	String	REQUIRED	The name to use for this binding. Must be a valid name.
value	Any	REQUIRED	The value to assign to this binding.
type	any, boolean, string, number, dimension	any	Property type.

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

Binding values can be changed dynamically using the SetValue command. Because the SetValue command is also used to change properties of a component, it is recommended that bound properties be named starting with a capital letter so that they never conflict with intrinsic component properties. For example, use "MyCounter" or "MY_COUNTER" instead of "myCounter".

display

The display property of a component controls whether or not it appears on the screen and how it affects the layout calculation. The default display setting, "normal", shows the component normally. When the the display setting is "invisible", the component still occupies space in the layout but does not draw or respond to events. A setting of "none" completely removes the component from the display hierarchy; it does not affect the layout.

Name	Description
invisible	The component is not drawn, but takes up space. The component does not respond to events.
none	Remove the component. The component is not part of the layout and does not respond events.
normal	Draw the component normally.

height and width

Width, height, minWidth, minHeight, maxWidth, and maxHeight are dimensional properties. Minimum width and height values default to 0; the component can disappear. Maximum width and height properties default to none, indicating that the component can scale arbitrarily. If unspecified, the width and height values will revert to the components natural size.

id

A developer-assigned string value used to locate a particular component in the view hierarchy. The valid characters in an id are [_a-zA-Z0-9]+. The id is not required to be unique, but it is recommended.

onMount

Commands to run when this component attaches from the component hierarchy. Mount commands are used for visual transitions between screens. The event.source.value is left unset during mount.

The onMount command runs at document load time. Component onMount commands always run even if the component itself is invisible or otherwise not displayed on the screen.

The event generated has the form:

"event": {
  "source": {
    "source": NAME,
    "handler": "Mount",
    "id": ID,          // ID of the component
    "uid": UID,        // Runtime-generated unique ID of the component
    "value": null      // No value reported
  }
}

The event source property is set to the name of the component; for example, "Pager", "Container", etc.

padding

Padding values – paddingBottom, paddingTop, paddingLeft, and paddingRight – are dimensions that add space around a component. APL-T uses the border-box model for calculating the total width and height of an element. Note that padding values do not support relative (percentage) dimensions – paddings must be specified in absolute dimensions.

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. The type property must be specified (it's the only required property).

when

If true, inflate the component. If false, ignore the component and all child components.

Last updated: Feb 05, 2021