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.

img

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 imageSource property which specifies the URL of the image.
  • The imageAspectRatio defines the aspect ratio to use for the image bounding box. (This property applies when you provide either imageHeight or imageWidth, but not both.)
  • The ImageScale which applies a best-fill strategy.
  • The imageHeight property 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.