Grid List (1.4.0 - 1.5.0)
The Alexa grid list template (AlexaGridList
) displays a list of images and text in a grid. AlexaGridList
is a full-screen template that optionally displays a header 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.
AlexaGridList
requires APL 1.4 or later. Provide an alternate experience for devices running older versions of APL.Import the alexa-layouts package
To use AlexaGridList
, import the alexa-layouts package.
The latest version of the alexa-layouts
package is 1.7.0. AlexaGridList
was introduced in version 1.2.0.
AlexaGridList parameters
All parameters except type
are optional.
Name | Type | Default | Description | Version added |
---|---|---|---|---|
|
String |
|
Image/video alignment to apply to background image/video. |
1.2.0 |
|
Boolean |
|
When |
1.2.0 |
|
— |
Color to use as a background color. Used when neither |
1.2.0 | |
|
Boolean |
|
When |
1.2.0 |
|
String |
— |
URL for the background image source. Used when |
1.2.0 |
|
Boolean |
|
When |
1.2.0 |
|
String |
|
Image or video scaling to apply to background image or video. |
1.2.0 |
|
— |
The background video source. Provide a source in the same format shown for the |
1.2.0 | |
|
Any |
— |
The name of a custom layout to use for each list item. Leave this unset to use the |
1.2.0 |
|
String |
— |
URL for a default image to use for any list items that don't have an |
1.2.0 |
|
Array |
— |
Array of entity data to bind to this template. |
1.2.0 |
|
String |
— |
URL for attribution image source. Shown when |
1.2.0 |
|
Number |
|
The opacity of the attribution text and attribution image. |
1.3.0 |
|
Boolean |
|
When |
1.2.0 |
|
String |
— |
Attribution text to render in the header. Shown when |
1.2.0 |
|
Boolean |
|
When |
1.2.0 |
|
String |
— |
An accessibility label to describe the back button to customers who use a screen reader. |
1.2.0 |
|
|
Command to run when the user selects the back button. |
1.2.0 | |
|
String |
|
Optional color value to use as the background color for the header. |
1.2.0 |
|
Boolean |
|
When |
1.2.0 |
|
String |
— |
Secondary text to render in header. |
1.2.0 |
|
String |
— |
Primary text to render in the header. |
1.2.0 |
|
Boolean |
|
When |
1.2.0 |
|
String |
|
Sets a default for the |
1.2.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.2.0 |
|
Boolean |
|
Sets a default for the |
1.2.0 |
|
Boolean |
|
Sets a default for the |
1.2.0 |
|
Boolean |
|
When |
1.2.0 |
|
Boolean |
|
Sets a default for the |
1.2.0 |
|
String |
|
Sets a default for the |
1.2.0 |
|
Boolean |
|
Sets a default for the |
1.3.0 |
|
Boolean |
|
When |
1.2.0 |
|
String |
|
Specifies the layout direction for the content. Set this property to either |
1.4.0 |
|
Any |
— |
Array of entity data bind to GridSequence. |
1.5.0 |
|
String |
— |
An identifier to assign to the |
1.2.0 |
|
Dimension |
Calculated based on size of data to display. |
The height for the list items. |
1.2.0 |
|
Number |
0 |
The number of list items to display in a single row. Setting this property a larger value might truncate your images. Leave this unset to use a default optimized the |
1.2.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.2.0 |
|
— |
Sets a default for the |
1.2.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.2.0 |
|
String |
|
Audio track to play on when playing the video. Can be |
1.2.0 |
|
Boolean |
|
When |
1.2.0 |
Horizontal list density (listItemHorizontalCount
)
The AlexaGridList
doesn't scroll horizontally. The template displays a fixed number of items in multiple rows. You can set the number of list items to display in a single row with the listItemHorizontalCount
property. By default, AlexaGridList
sets listItemHorizontalCount
to a number based on the imageAspectRatio
and the viewport size. This default ensures that the full list items display and aren't truncated.
The following table summarizes the defaults for the standard viewport profiles and image aspect ratios.
Image aspect ratio | Hub round | Hub landscape small | Hub landscape medium | Hub landscape | TV fullscreen |
---|---|---|---|---|---|
Square | 1 | 3 | 3 | 3 | 4 |
Round | 1 | 3 | 3 | 3 | 4 |
Standard landscape | 1 | 3 | 3 | 3 | 4 |
Standard portrait | 2 | 4 | 4 | 4 | 5 |
Poster landscape | 1 | 3 | 3 | 3 | 4 |
Poster portrait | 2 | 4 | 4 | 4 | 5 |
Widescreen | 1 | 2 | 2 | 3 | 4 |
To use these responsive defaults, leave listItemHorizontalCount
not set. If you do change listItemHorizontalCount
, note that AlexaGridList
truncates your list items as needed to fit the specified number of items into a row.
Provide the list items
The AlexaGridList
template expects an array of items in the listItems
property. Use one of the following options to structure your list items:
- Provide an array of objects, each with the same properties as those defined in the
AlexaImageListItem
responsive component. - Define a custom layout for your list items, and then pass an array of objects that correspond to your custom items.
Use AlexaImageListItem for the list items
The following example illustrates an array of items in a data source called gridListData
.
{
"gridListData": {
"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 ${gridListData.listItemsToShow}
.
{
"type": "AlexaGridList",
"headerTitle": "Header Title",
"headerAttributionImage": "https://s3.amazonaws.com/ask-skills-assets/apl-layout-assets/attribution_dark_hub_prime.png",
"backgroundImageSource": "https://d2o906d8ln7ui1.cloudfront.net/images/BT6_Background.png",
"listItems": "${gridListData.listItemsToShow}",
"imageShowProgressBar": true
}
Use a custom layout for the list items
You can use a custom layout to define the list items displayed in AlexaGridList
. Use this option when the AlexaImageListItem
format doesn't meet your needs.
For more details about building your own layouts, see APL Layout.
To use a custom layout for the list items
-
Create an array of list items to display. Each item in the array is an object with a set of properties. The following example illustrates a list item object with two properties:
listItemText
andimageUrl
.{ "listItemText": "First list item", "imageUrl": "https://d2o906d8ln7ui1.cloudfront.net/images/md_gruyere.png" }
-
In the
layouts
section of your APL document, create a custom layout to display a single list item. Use thedata
property to access the data for an individual item.For example, if each list item in your array has an
listItemText
property with the list item text to display, usedata.listItemText
to refer to that property in the layout.AlexaGridList
passes thelistItems
you provide to thedata
property for the list. For more details about how thedata
property works, see data array inflation.This example illustrates a
Text
component within a custom layout that displays thelistItemText
property for an item in the data array.{ "type": "Text", "height": "100dp", "style": "textStyleBody", "text": "${data.listItemText}" }
-
In
AlexaGridList
, set thecustomLayoutName
property to the name of your custom layout and bind your array of list items to thelistItems
property.{ "type": "AlexaGridList", "listItems": "${gridListData.listItemsToShow}", "customLayoutName": "MyListItem" }
The following example illustrates an AlexaGridList
that uses a custom layout for the list items. The document defines a custom layout called MyListItem
that displays two properties: imageUrl
and listItemText
. The data source example illustrates the structure of the array passed to listItems
.
AlexaGridList
template passes several properties to AlexaImageListItem
to set defaults. For example, you can set defaultImageSource
one time to specify an image to use when a given list item does not have an image. When you use a custom layout, your custom layout doesn't have access to these defaults.Set defaults for the list items
The AlexaGridList
template includes properties that correspond to properties in AlexaImageListItem
. Use these to set default values for those properties. AlexaGridList
ignores these defaults when you use a custom layout for your list items.
There are two types of defaults:
-
Defaults you can set or override for an individual item –
AlexaGridList
uses the value provided on the individual item when available, and uses the value provided onAlexaGridList
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 –
AlexaGridList
always uses the value provided onAlexaGridList
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 |
imageShadow |
Yes |
primaryAction |
Yes |
For details about each of these properties, see AlexaImageListItem
.
Specify the action for each list item
AlexaGridList
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 AlexaGridList
component, AlexaGridList
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}"
]
}
}
AlexaGridList example
In this example, selecting a list item sends your skill a UserEvent
with "ListItemSelected" and the number of the list item.
Related topics
Last updated: Nov 28, 2023