APL Components
On an Alexa-enabled device with a screen, the viewport is the area of the screen that the user can see. A viewport has a shape, orientation, size, and density. An APL component is a primitive element that displays on the viewport. For example, a Text component displays text on the screen. All APL components share a set of base properties. To learn more about these properties, see APL Base Component Properties. For now, you can focus on the following base component properties:
| Property | Type | Default | Description |
|---|---|---|---|
padding |
Array of non-negative Absolute Dimension | [] | Space to add on the sides of the component. |
paddingBottom |
Non-negative Absolute Dimension | 0 | Space to add to the bottom of this component. |
paddingLeft |
Non-negative Absolute Dimension | 0 | Space to add to the left of this component. |
Absolute dimensions are integers interpreted as display-independent pixels. You can also express them as a string with a unit suffix. The unit suffix must immediately follow the dimension. The dimensions are similar to CSS dimensions. The valid suffixes are listed in the following table:
| Suffix | Description | Example |
|---|---|---|
| dp | Display-independent pixels | 20dp |
| px | Screen pixels | 10px |
| vh | Viewport height, where 100 is the full viewport height. 1 vh is 1% of the viewport height. | 50vh |
| vw | Viewport width, where 100 is the full viewport width. 1 vw is 1% of the viewport width. | 33vw |
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 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.
Relative dimensions are represented by a string of the form "Value%", where Value is a valid JSON number. A percentage dimension is interpreted as a percentage of the containing component bounding box. Because the bounding box has two dimensions (width and height), the appropriate dimension will be chosen if the semantic of the property is inherently horizontal or vertical (such as height). APL doesn't support relative dimensions for the padding properties on all components.
Containers are components that house other components in an alignment of "column" or "row." The mainTemplate picks just one component to display, so if you want to display multiple components, you must place them in a container. Because containers are also components, they retain the basic component properties. Containers are essential to building APL documents. Complex APL documents use a mix of row and column containers to lay out components in a way that scales across different Alexa-enabled devices.
In terms of relative dimensions, the following mainTemplate demonstrates how the child container has its width and height relative to its parent container:
"mainTemplate": {
"parameters": [
"test"
],
"items": [
{
"type": "Container",
"width": "100%",
"height": "100%",
"items": [
{
"type": "Container",
"width": "100%",
"height": "100%",
"items": []
}
]
}
]
}
Text component
Although the Tic-Tac-Toe skill's board doesn’t contain any text (it only has images), it’s a good idea to start with a simple Text component and observe its behavior on the Simulator. In the following APL document, the Text component is within a Container.
{
"type": "APL",
"version": "1.7",
"settings": {},
"theme": "dark",
"import": [
{
"name": "alexa-layouts",
"version": "1.4.0"
}
],
"mainTemplate": {
"parameters": [],
"items": [
{
"type": "Container",
"items": [
{
"type": "Text",
"paddingTop": "20dp",
"paddingLeft": "120dp",
"text": "This is a test"
}
]
}
]
}
}
The text property of the Text component is specific to it, so it’s not one of the APL base component properties.
Important: Click here and then Blank Document to test these snippets against the APL authoring tool in the developer console.
AlexaImage component
To include more than one component within the same container, you can list them as additional items of that container. The following APL document highlights how to have an AlexaImage component under the text. The Alexa image responsive component (AlexaImage) displays a responsive image on the screen. You can display the image with standard aspect ratios (such as portrait or round) and effects, such as rounded corners. This responsive component belongs to the alexa-layouts package and it’s not a primitive APL component.
{
"type": "APL",
"version": "1.7",
"settings": {},
"theme": "dark",
"import": [
{
"name": "alexa-layouts",
"version": "1.4.0"
}
],
"mainTemplate": {
"parameters": [],
"items": [
{
"type": "Container",
"items": [
{
"type": "Text",
"paddingTop": "20dp",
"paddingLeft": "120dp",
"text": "This is a test"
},
{
"type": "AlexaImage",
"imageSource": "https://d3j5530a0cofat.cloudfront.net/adlc/circle.png",
"imageRoundedCorner": false,
"imageScale": "best-fill",
"imageHeight": "19vh",
"imageAspectRatio": "square",
"imageBlurredBackground": false
}
]
}
]
}
}
The main properties of the AlexaImage component and their values set in the previous example are:
- The
imageSourceproperty which specifies the URL of the image. - The
imageAspectRatiodefines the aspect ratio to use for the image bounding box. (This property applies when you provide eitherimageHeightorimageWidth, but not both.) - The
ImageScalewhich applies a best-fill strategy. - The
imageHeightproperty which controls the size of the image and sets it to 19% of the viewport height.
For more details about each of the AlexaImage parameters, see AlexaImage parameters.
AlexaBackground component
AlexaBackground is a simple responsive component to render background images. Its backgroundImageSource property contains the URL of the image to use as background. The following simple example illustrates how to use it.
{
"type": "APL",
"version": "1.7",
"settings": {},
"theme": "dark",
"import": [
{
"name": "alexa-layouts",
"version": "1.4.0"
}
],
"mainTemplate": {
"parameters": [],
"items": [
{
"type": "Container",
"items": [
{
"type": "AlexaBackground",
"backgroundImageSource": "https://d3j5530a0cofat.cloudfront.net/adlc/board.png"
},
{
"type": "AlexaImage",
"imageSource": "https://d3j5530a0cofat.cloudfront.net/adlc/circle.png",
"imageRoundedCorner": false,
"imageScale": "best-fill",
"imageHeight": "19vh",
"imageAspectRatio": "square",
"imageBlurredBackground": false
}
]
}
]
}
}
Try modifying the AlexaImage properties in the APL authoring tool and add values for padding to place the AlexaImage in different positions of the Tic-Tac-Toe board.
Are the vh and vw dimensions responsive?
No. A dimension with vw or vh as the unit is an absolute dimension that works as a shortcut for the viewport.width or viewport.height properties. For example, on an Echo Show, the dimension "100vw" resolves to "1024dp." The dimension "50vw" resolves to "512dp."
The viewport.width and viewport.height properties are constants that stay the same after the document is displayed unless you run the Reinflate command. This means that on a device that can change its screen size during the skill session, such as a tablet, using the vw and vh dimensions creates an experience that resizes poorly when the user rotates the device (if you use the default resizing option). To avoid this poor experience, use relative dimensions whenever possible.
The following example illustrates a parent container with dimensions "width": "100%" and "height": "100%". The container has a child AlexaImage responsive component. The percentage dimension for imageHeight is interpreted as a percentage of the containing component bounding box.
{
"type": "APL",
"version": "1.7",
"settings": {},
"theme": "dark",
"import": [
{
"name": "alexa-layouts",
"version": "1.4.0"
}
],
"mainTemplate": {
"parameters": [],
"items": [
{
"type": "Container",
"width": "100%",
"height": "100%",
"items": [
{
"type": "AlexaBackground",
"backgroundImageSource": "https://d3j5530a0cofat.cloudfront.net/adlc/board.png"
},
{
"type": "AlexaImage",
"imageSource": "https://d3j5530a0cofat.cloudfront.net/adlc/circle.png",
"imageRoundedCorner": false,
"imageHeight": "20%",
"imageAspectRatio": "square",
"imageBlurredBackground": false
}
]
}
]
}
}
Additional properties of containers
Apart from items, containers have three additional properties that you must use to display all the markers on the Tic-Tac-Toe board.
| Property | Type | Default | Description |
|---|---|---|---|
data |
Array | Data to bind into this container | |
direction |
column | row | column | The direction that children are laid out |
justifyContent |
start | end | center | spaceBetween | spaceAround | start | How to distribute free space when there is room on the main axis |
The direction and justifyContent properties will help you design the board in terms of rows and columns. Although not fully complete, the following example is the basis of the strategy that handles three markers per row, with each row being justified at the center of the viewport.
{
"type": "APL",
"version": "1.7",
"settings": {},
"theme": "dark",
"import": [
{
"name": "alexa-layouts",
"version": "1.4.0"
}
],
"mainTemplate": {
"parameters": [
"test"
],
"items": [
{
"type": "Container",
"direction": "row",
"justifyContent": "center",
"items": [
{
"type": "AlexaBackground",
"backgroundImageSource": "https://d3j5530a0cofat.cloudfront.net/adlc/board.png"
},
{ "when": "${@viewportProfile != @hubRoundSmall}",
"type": "AlexaImage",
"paddingTop": "5vh",
"imageSource": "https://d3j5530a0cofat.cloudfront.net/adlc/circle.png",
"imageRoundedCorner": false,
"imageHeight": "20%",
"imageAspectRatio": "square",
"imageBlurredBackground": false
},
{ "when": "${@viewportProfile == @hubRoundSmall}",
"type": "AlexaImage",
"paddingTop": "15vh",
"imageSource": "https://d3j5530a0cofat.cloudfront.net/adlc/circle.png",
"imageRoundedCorner": false,
"imageHeight": "30%",
"imageAspectRatio": "square",
"imageBlurredBackground": false
}
]
}
]
}
}
Although it might be tempting to assign absolute positions to each marker, such a strategy can't scale across all Alexa-enabled devices.
Test this APL document in the APL authoring tool by picking different devices. Because of the differences you observe, your APL document must identify the device it renders on.