Lists (1.5.0)
(This is not the most recent version of AlexaLists
. Use the Other Versions option to see the documentation for the most recent version of AlexaLists
)
The Alexa lists template (AlexaLists
) displays a list of items. AlexaLists
is a full-screen template that optionally displays a header, footer, and background. You specify whether the template presents text-based list items or image-based items. For text items, the template uses AlexaTextList
. For image-based items, the template uses AlexaImageList
on most viewports, and AlexaPaginatedList
on small, round hubs.
Import the alexa-layouts package
To use AlexaLists
, import the alexa-layouts package.
The latest version of the alexa-layouts
package is 1.7.0. AlexaLists
was introduced in version 1.1.0.
AlexaLists parameters
All parameters except type
are optional.
Name | Type | Default | Description | Version added |
---|---|---|---|---|
|
String |
|
Image/video alignment to apply to background image/video. |
1.1.0 |
|
Boolean |
|
When |
1.1.0 |
|
— |
Color to use as a background color. Used when neither |
1.1.0 | |
|
Boolean |
|
When |
1.1.0 |
|
String |
— |
URL for the background image source. Used when |
1.1.0 |
|
Boolean |
|
When |
1.1.0 |
|
String |
|
Image or video scaling to apply to background image or video. |
1.1.0 |
|
String |
|
Audio track to play on when playing the video. Can be |
1.1.0 |
|
Boolean |
|
When |
1.1.0 |
|
— |
The background video source. Provide a source in the same format shown for the |
1.1.0 | |
|
String |
— |
URL for a default image to use for any list items that don't have an |
1.1.0 |
|
String |
— |
Primary text to display in up to two lines when the list has no items. Text is truncated to fit to two lines. |
1.1.0 |
|
String |
— |
Secondary text to display in a single line when the list has no items. Displayed below the primary text. Text is truncated to display on a single line. |
1.1.0 |
|
Array |
— |
Array of entity data to bind to this template. |
1.2.0 |
|
String |
— |
Hint text to display in the footer. Use |
1.1.0 |
|
String |
— |
URL for attribution image source. Displays when |
1.1.0 |
|
Number |
|
The opacity of the attribution text and attribution image in the header. Set to a number between 0 and 1. |
1.3.0 |
|
Boolean |
|
When |
1.1.0 |
|
String |
— |
Attribution text to render in the header. Shown only when no |
1.1.0 |
|
Boolean |
|
When |
1.1.0 |
|
String |
— |
An accessibility label to describe the back button to customers who use a screen reader. |
1.1.0 |
|
|
Command to run when the user selects the back button. |
1.1.0 | |
|
String |
|
Optional color value to use as the background color for the Header. |
1.1.0 |
|
Boolean |
|
When |
1.1.0 |
|
String |
— |
Secondary text to render in header. |
1.1.0 |
|
String |
— |
Primary text to render in header. |
1.1.0 |
|
Boolean |
|
When |
1.1.0 |
|
String |
|
Sets a default for the |
1.1.0 |
|
String |
|
Aspect ratio to use for the image bounding box for all the items in the list. Options are square, round, standard_landscape, standard_portrait, poster_landscape, poster_portrait, widescreen. This property works the same as the |
1.1.0 |
|
Boolean |
|
Sets a default for the |
1.1.0 |
|
— |
Sets a default for the |
1.4.0 | |
|
Boolean |
|
Sets a default for the |
1.1.0 |
|
Boolean |
|
When |
1.1.0 |
|
Boolean |
|
Sets a default for the |
1.1.0 |
|
String |
|
Sets a default for the |
1.1.0 |
|
Boolean |
|
Sets a default for the |
1.3.0 |
|
String |
|
The language for the text displayed in the template. This language determines the default font used for the text. For example, when set to |
1.4.0 |
|
String |
|
Specifies the layout direction for the content. Set this property to either |
1.4.0 |
|
String |
— |
An identifier to assign to the |
1.2.0 |
|
Boolean |
|
When |
1.1.0 |
|
Array of listItems |
— |
Array of list items to display. |
1.1.0 |
|
— |
Sets a default for the |
1.1.0 | |
|
Any |
— |
An array of speech items. The |
1.2.0 |
|
String |
|
Set the dark or light color theme. The selected theme controls the colors used for the template. |
1.1.0 |
|
Boolean |
|
When |
1.1.0 |
|
String |
— |
Always set to |
1.1.0 |
Choose the list layout to display (listImagePrimacy)
The listImagePrimacy
parameter determines the list layout.
When listImagePrimacy
is true
, the template displays either an AlexaImageList
or an AlexaPaginatedList
. These layouts show an image and text for each item. The AlexaPaginatedList
displays on small, round hubs, so a single list item is shown on each page.
When listImagePrimacy
is false
, the template displays an AlexaTextList
. This layout displays a scrolling list of text items.
Provide the list items
The AlexaLists
template expects an array of items in the listItems
property. Each item is one of the following:
- An object with the same properties as those defined in the
AlexaImageListItem
responsive component. - An object with the same properties as those defined in the
AlexaTextListItem
responsive component.
The list uses the image properties when listImagePrimacy
is true
and ignores the image properties when listImagePrimacy
is false.
The following example illustrates an array of items in a data source called listData
.
{
"listData": {
"listItemsToShow": [
{
"primaryText": "First list item",
"secondaryText": "Secondary text",
"imageSource": "https://d2o906d8ln7ui1.cloudfront.net/images/md_gruyere.png",
"imageProgressBarPercentage": 90,
"imageShowProgressBar": false
},
{
"primaryText": "Second list item",
"secondaryText": "Secondary Text",
"tertiaryText": "Tertiary text",
"imageSource": "https://d2o906d8ln7ui1.cloudfront.net/images/md_gorgonzola.png",
"providerText": "Provider Text",
"imageProgressBarPercentage": 50
},
{
"primaryText": "No image, use the default",
"secondaryText": "Secondary text"
},
{
"primaryText": "Fourth list item",
"secondaryText": "No progress bar",
"imageSource": "https://d2o906d8ln7ui1.cloudfront.net/images/tl_brie.png"
},
{
"primaryText": "Fifth list item",
"secondaryText": "With background blur",
"imageSource": "https://d2o906d8ln7ui1.cloudfront.net/images/MollyforBT7.png"
},
{
"primaryText": "Sixth list item (long text that wraps)",
"secondaryText": "Longer secondary text that truncates",
"imageSource": "https://d2o906d8ln7ui1.cloudfront.net/images/sm_blue.png"
}
]
}
}
Then, bind this array to the listItems
property with the expression ${listData.listItemsToShow}
. This example displays an AlexaImageList
or AlexaPaginatedList
and shows the provided images.
{
"type": "AlexaLists",
"listItems": "${listData.listItemsToShow}",
"listImagePrimacy": true,
"defaultImageSource": "https://d2o906d8ln7ui1.cloudfront.net/images/BT7_Background.png",
"imageBlurredBackground": true
}
Change listImagePrimacy
to false
to display an AlexaTextList
with the same data. This version ignores the properties that don't apply to AlexaTextList
.
{
"type": "AlexaLists",
"listItems": "${listData.listItemsToShow}",
"listImagePrimacy": false,
"defaultImageSource": "https://d2o906d8ln7ui1.cloudfront.net/images/BT7_Background.png",
"imageBlurredBackground": true
}
Default text for an empty list
Use the emptyPrimaryText
and emptySecondaryText
parameters to define text to display if there are no list items. This displays a short headline of text in the center of the screen.
The following example shows an AlexaLists
with content for emptyPrimaryText
and emptySecondaryText
.
{
"type": "AlexaLists",
"listItems": "${listData.listItemsToShow}",
"emptyPrimaryText": "${listData.emptyPrimaryText}",
"emptySecondaryText": "${listData.emptySecondaryText}",
"imageBlurredBackground": true
}
This example shows the data source that would produce the "empty list" message on the screen.
{
"listData": {
"emptyPrimaryText": "You don't have any list items",
"emptySecondaryText": "To get started, tell me the item to add to the list",
"listItemsToShow": []
}
}
Set defaults for the list items
The AlexaLists
template includes properties that correspond to properties in AlexaImageListItem
. Use these to set default values for those properties. These apply when listImagePrimacy
is true
.
There are two types of defaults:
-
Defaults you can set or override for an individual item –
AlexaLists
uses the value provided on the individual item when available, and uses the value provided onAlexaLists
otherwise.For example, you might set
imageScale
tobest-fit
for the whole list, but then override it tobest-fill
for one item on the list. -
Defaults that always apply to all the items in the list –
AlexaLists
always uses the value provided onAlexaLists
for these properties. Any value in a corresponding property on an individual item is ignored.For example, you must set
imageAspectRatio
on the whole list. You can't have a list in which some items display as squares and some as circles. Any value forimageAspectRatio
on a list item is ignored.
The following table lists the properties you use as defaults.
Property | Can override on an item |
---|---|
defaultImageSource |
No |
imageAlignment |
Yes |
imageAspectRatio |
No |
imageBlurredBackground |
Yes |
imageHeight |
No |
imageHideScrim |
Yes |
ImageMetadataPrimacy |
No |
imageRoundedCorner |
Yes |
imageScale |
Yes |
imageShadow |
Yes |
primaryAction |
Yes |
For details about each of these properties, see AlexaImageListItem
.
Specify the action for each list item
AlexaLists
is interactive. Users can select items on the list. Set the primaryAction
property to the command you want to run when the user selects an item.
When you set primaryAction
on the AlexaLists
component, AlexaLists
passes the command to each item on the list.
To override command for an individual list item, set the primaryAction
property on the list item itself.
The following example shows how you to use the SendEvent
command to send your skill a UserEvent
request. This passes the number representing the selected item as part of the SendEvent.arguments
array.
{
"primaryAction": {
"type": "SendEvent",
"arguments": [
"ListItemSelected",
"${ordinal}"
]
}
}
AlexaLists example
![A simple AlexaLists on a larger hub](https://m.media-amazon.com/images/G/01/mobile-apps/dex/ask-apl/alexa-layouts/alexa-lists-hub._TTH_.png)
![The same AlexaLists template becomes a paginated list on a small hub](https://m.media-amazon.com/images/G/01/mobile-apps/dex/ask-apl/alexa-layouts/alexa-lists-round._TTH_.png)
Related topics
Last updated: Nov 28, 2023