Image List
The Alexa image list template (AlexaImageList
) displays a scrolling list of images and text. AlexaImageList
is a full-screen template that optionally displays a header, footer, and background. You provide a set of image-based items to display in the list and configure the appearance of the list, such as including dividers and whether to number the items. You can also provide the command to run when a user selects an item from the list.
- Import the alexa-layouts package
- AlexaImageList parameters
- Provide the list items
- Set defaults for the list items
- Specify the action for each list item
- AlexaImageList and dynamicIndexList data sources
- AlexaImageList example
- Related topics
Import the alexa-layouts package
To use AlexaImageList
, import the alexa-layouts package.
The latest version of the alexa-layouts
package is 1.2.0
. AlexaImageList
was introduced in version 1.1.0
.
AlexaImageList parameters
All parameters except type
are optional.
Name | Type | Default | Description | Version added/updated |
---|---|---|---|---|
|
String |
|
Image/video alignment to apply to background image/video. |
1.1.0 |
|
Boolean |
|
When true, display the provided background image with a blur effect. Applies when |
1.1.0 |
|
None |
Color to use as a background color. Used when neither |
1.1.0 |
|
|
Boolean |
|
When true, apply a scrim to the background to make it easier to read the text displayed over the image or video. |
1.1.0 |
|
String |
None |
URL for the background image source. Used when |
1.1.0 |
|
Boolean |
|
When true, apply a gradient to the background. |
1.1.0 |
|
String |
|
Image or video scaling to apply to background image or video. |
1.1.0 |
|
None |
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 |
|
|
Array |
[] |
Array of entity data to bind to this template. |
1.2.0 |
|
String |
None |
URL for attribution image source. Displays when |
1.1.0 |
|
Boolean |
true |
When true, display the |
1.1.0 |
|
String |
None |
Attribution text to render in the header. Shown only when no |
1.1.0 |
|
Boolean |
|
When true, displays a back button in the header. Set the |
1.1.0 |
|
String |
None |
An accessibility label to describe the back button to customers who use a screen reader. |
1.1.0 |
|
|
Command to execute 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 true, display a divider below the header to help separate it from the content. |
1.1.0 |
|
String |
None |
Secondary text to render in header. |
1.1.0 |
|
String |
None |
Primary text to render in header. |
1.1.0 |
|
String |
None |
Hint text to display in the footer. Use |
1.1.0 |
|
String |
center |
Sets a default for the |
1.1.0 |
|
String |
square |
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 |
false |
Sets a default for the |
1.1.0 |
|
Boolean |
false |
Sets a default for the |
1.1.0 |
|
Boolean |
true |
When true, hide the |
1.1.0 |
|
Boolean |
true |
Sets a default for the |
1.1.0 |
|
String |
best-fit |
Sets a default for the |
1.1.0 |
|
Array of |
An array of items to display in the list. Each item is an object with the same properties as defined in |
1.1.0 |
|
|
none |
Sets a default for the |
1.1.0 |
|
|
String |
dark |
Set the dark or light color theme. The selected theme controls the colors used for the template. |
1.1.0 |
|
String |
None |
Always set to |
1.1.0 |
|
String |
|
Audio track to play on when playing the video. Can be |
1.1.0 |
|
Boolean |
|
When true, the video begins playing automatically when the document renders on the device. Applies when |
1.1.0 |
Provide the list items
The AlexaImageList
template expects an array of items in the listItems
property. Each item is an object with the same properties as those defined in the AlexaImageListItem
responsive component.
The following example illustrates an array of items in a data source called imageListData
.
{
"imageListData": {
"listItemsToShow": [
{
"primaryText": "First list item",
"secondaryText": "Secondary text",
"imageSource": "https://d2o906d8ln7ui1.cloudfront.net/images/md_gruyere.png",
"imageProgressBarPercentage": 90,
"imageShowProgressBar": false,
"ratingSlotMode": "multiple",
"ratingNumber": 2.87,
"ratingText": "(206 ratings)"
},
{
"primaryText": "Second list item",
"secondaryText": "Secondary Text",
"tertiaryText": "Tertiary text",
"imageSource": "https://d2o906d8ln7ui1.cloudfront.net/images/md_gorgonzola.png",
"providerText": "Provider Text",
"imageProgressBarPercentage": 50,
"ratingSlotMode": "multiple",
"ratingNumber": 4.5,
"ratingText": "(500 ratings)"
},
{
"primaryText": "No image, use the default",
"secondaryText": "Secondary text",
"ratingSlotMode": "multiple",
"ratingNumber": 2,
"ratingText": "(50 ratings)"
},
{
"primaryText": "Fourth list item",
"secondaryText": "No progress bar",
"imageSource": "https://d2o906d8ln7ui1.cloudfront.net/images/tl_brie.png",
"ratingSlotMode": "multiple",
"ratingNumber": 5,
"ratingText": "(452 ratings)"
},
{
"primaryText": "Fifth list item",
"secondaryText": "With background blur",
"imageSource": "https://d2o906d8ln7ui1.cloudfront.net/images/MollyforBT7.png",
"ratingSlotMode": "multiple",
"ratingNumber": 0,
"ratingText": "(206 ratings)"
},
{
"primaryText": "Sixth list item (long text that wraps)",
"secondaryText": "Longer secondary text that truncates",
"imageSource": "https://d2o906d8ln7ui1.cloudfront.net/images/sm_blue.png",
"ratingSlotMode": "multiple",
"ratingNumber": 0,
"ratingText": "(206 ratings)"
}
]
}
}
Then, bind this array to the listItems
property with the expression ${imageListData.listItemsToShow}
.
{
"type": "AlexaImageList",
"listItems": "${imageListData.listItemsToShow}",
"defaultImageSource": "https://d2o906d8ln7ui1.cloudfront.net/images/BT7_Background.png",
"imageBlurredBackground": true,
"primaryAction": {
"type": "SendEvent",
"arguments": [
"ListItemSelected",
"${ordinal}"
]
}
}
The specific list item parameters available depend on the version of AlexaImageListItem
. For example, the properties to display a rating require the 1.2.0 or later version of the alexa-layouts
package. For the full set of properties, see AlexaImageListItem
.
Set defaults for the list items
The AlexaImageList
template includes properties that correspond to properties in AlexaImageListItem
. Use these to set default values for those properties.
There are two types of defaults:
-
Defaults you can set or override for an individual item –
AlexaImageList
uses the value provided on the individual item when available, and uses the value provided onAlexaImageList
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 –
AlexaImageList
always uses the value provided onAlexaImageList
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 |
imageHideScrim |
Yes |
ImageMetadataPrimacy |
No |
imageRoundedCorner |
Yes |
imageScale |
Yes |
primaryAction |
Yes |
For details about each of these properties, see AlexaImageListItem
.
Specify the action for each list item
AlexaImageList
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 AlexaImageList
component, AlexaImageList
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}"
]
}
}
AlexaImageList and dynamicIndexList data sources
The AlexaImageList
template uses a Sequence
. This means you can use a dynamicIndexList
data source. With a dynamicIndexList
data source, you can do the following:
- Display large lists progressively as the user scrolls through the content (lazy loading).
- Update the items the data source after it is already displayed, so you can change the values on the screen without sending an entirely new document.
To use a dynamicIndexList data source with AlexaImageList
- Follow the
dynamicIndexList
structure shown in dynamicIndexList data source. Don't include any other properties not defined in this structure. - Put your list item objects in the
items
array in the data source. - Bind the data source to the
listItems
property ofAlexaImageList
. This binding is equivalent to binding the data source to thedata
property of aSequence
in a custom layout.
The following examples show a document with an AlexaImageList
that uses a dynamicIndexList
data source.
For details about defining a dynamicIndexList
data source, see dynamicIndexList data source.
For details about the directives and requests you use to manage the data source, see Alexa.Presentation.APL Interface Reference.
AlexaImageList example
In this example, selecting a list item sends your skill a UserEvent
with "ListItemSelected" and the number of the list item.
