Component (Character Displays)

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

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.

Was this page helpful?

Last updated: Nov 28, 2023