Image List (1.6.0)

Note: Learn how to improve your skills with APL with Build visually rich experiences using APL at the Alexa Learning Lab.

(This is not the most recent version of AlexaImageList. Use the Other Versions option to see the documentation for the most recent version of AlexaImageList)

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.

Compatibility

AlexaImageList is designed to work with all standard viewport profiles in the alexa-viewport-profiles package:

All hub round profiles
All hub landscape profiles
All hub portrait profiles
All mobile profiles
All TV profiles

If you use AlexaImageList on an unsupported viewport, you might have unexpected results. For details about viewport profiles, see Viewport Profiles.

Import the alexa-layouts package

To use AlexaImageList, import the alexa-layouts package.

The latest version of the alexa-layouts package is 1.7.0. AlexaImageList was introduced in version 1.1.0.

AlexaImageList parameters

All parameters except type are optional.

Name	Type	Default	Description	Widget support	Version added
`backgroundAlign`	String	`center`	Image/video alignment to apply to background image/video.	Not supported	1.1.0
`backgroundBlur`	Boolean	`false`	When `true`, display the provided background image with a blur effect. Applies when `backgroundImageSource` contains a value.	Not supported	1.1.0
`backgroundColor`	Color	—	Color to use as a background color. Used when neither `backgroundImageSource` or `backgroundVideoSource` contain values.	Not supported	1.1.0
`backgroundColorOverlay`	Boolean	`false`	When `true`, apply a scrim to the background to make it easier to read the text displayed over the image or video.	Not supported	1.1.0
`backgroundImageSource`	String	—	URL for the background image source. Used when `backgroundVideoSource` isn't provided.	Not supported	1.1.0
`backgroundOverlayGradient`	Boolean	`false`	When `true`, apply a gradient to the background.	Not supported	1.1.0
`backgroundScale`	String	`best-fill`	Image or video scaling to apply to background image or video.	Not supported	1.1.0
`backgroundVideoSource`	Video source	—	The background video source. Provide a source in the same format shown for the `source` property of the Video component.	Not supported	1.1.0
`defaultImageSource`	String		URL for a default image to use for any list items that don't have an `imageSource` defined. Provide a `defaultImageSource` to make sure that image containers are never empty. The same `defaultImageSource` is used for all list items that are missing `imageSource`.	Not supported	1.1.0
`entities`	Array	—	Array of entity data to bind to this template.	Not supported	1.2.0
`headerAttributionImage`	String	—	URL for attribution image source. Displays when `headerAttributionPrimacy` is `true`, or on a device that shows Title/Subtitle and Attribution.	Not supported	1.1.0
`headerAttributionOpacity`	Number	`0.8`	The opacity of the attribution text and attribution image in the header. Set to a number between 0 and 1.	Not supported	1.3.0
`headerAttributionPrimacy`	Boolean	`true`	When `true`, display the `headerAttributionImage` on devices that display a single element due to screen size. When `false`, display the `headerTitle` and `headerSubtitle`.	Not supported	1.1.0
`headerAttributionText`	String	—	Attribution text to render in the header. Shown only when no `headerAttributionImage` is provided and `headerAttributionPrimacy` is `true`, or on a device that shows both Title/Subtitle and Attribution.	Not supported	1.1.0
`headerBackButton`	Boolean	`false`	When `true`, displays a back button in the header. Set the `headerBackButtonCommand` property to specify a command to run when the user clicks this button.	Not supported	1.1.0
`headerBackButtonAccessibilityLabel`	String	`Back`	An accessibility label to describe the back button to customers who use a screen reader.	Not supported	1.1.0
`headerBackButtonCommand`	Command	`{"type":"SendEvent","arguments":["goBack"]}`	Command to run when the user selects the back button.	Not supported	1.1.0
`headerBackgroundColor`	String	`transparent`	Optional color value to use as the background color for the Header.	Not supported	1.1.0
`headerDivider`	Boolean	`false`	When `true`, display a divider below the header to help separate it from the content. .	Not supported	1.1.0
`headerTitle`	String	—	Primary text to render in header.	Not supported	1.1.0
`hideDivider`	Boolean	`true`	Toggle to hide the divider that appears at the bottom/right of each 'Horizontal Item Lockup' item to help separate it from the next content.	Not supported	1.6.0
`hideOrdinal`	Boolean	`false`	When `true`, don't display the number next to each list item.	Not supported	1.1.0
`hintText`	String	—	Hint text to display in the footer. Use `textToHint` to add the correct wake word to the hint. Not shown on small devices unless `imageMetadataPrimacy` is `false`.	Not supported	1.1.0
`imageAlignment`	String	`center`	Sets a default for the `imageAlignment` option for the items in `listItems`. See the `imageAlignment` property in `AlexaImageListItem`.	Not supported	1.1.0
`imageAspectRatio`	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 `imageAspectRatio` property for the `AlexaImage` responsive component except that the height and width of the bounding box are pre-defined based on the aspect ratio and can't be changed. All list items always use the same aspect ratio.	Not supported	1.1.0
`imageBlurredBackground`	Boolean	`false`	Sets a default for the `imageBlurredBackground` option for the items in `listItems`. See the `imageBlurredBackground` property in `AlexaImageListItem`.	Not supported	1.1.0
`imageHeight`	Dimension	—	Sets a default for the `imageHeight` option for the items in `listItems`. Each image in the list scales to fit within this height using the `imageScale` setting.	Not supported	1.4.0
`imageHideScrim`	Boolean	`false`	Sets a default for the `imageHideScrim` option for the items in `listItems`. See the `imageHideScrim` property in `AlexaImageListItem`.	Not supported	1.1.0
`imageMetadataPrimacy`	Boolean	`true`	When `true`, hide the `hintText` on small devices and display the `secondaryText` and `tertiaryText`. Set this property to `false` to hide the `secondaryText` and `tertiaryText` and display the `hintText` instead. This property is ignored on larger devices that have room to display both the text items and the `hintText`.	Not supported	1.1.0
`imageRoundedCorner`	Boolean	`true`	Sets a default for the `imageRoundedCorner` option for the items in `listItems`. See the `imageRoundedCorner` property in `AlexaImageListItem`.	Not supported	1.1.0
`imageScale`	String	`best-fit`	Sets a default for the `imageScale` option for the items in `listItems`. See the `imageScale` property in `AlexaImageListItem`.	Not supported	1.1.0
`imageShadow`	Boolean	`true`	Sets a default for the `imageShadow` option for the items in `listItems`. When `true`, display a drop shadow behind the image for each list item.	Not supported	1.3.0
`lang`	String	`${environment.lang}`	The language for the text displayed in the template. This language determines the default font used for the text. For example, when set to `ar-SA`, the component uses Arabic fonts when available on the device. Set to a BCP-47 string. For more details about language-specific fonts for responsive components, see Language-specific fonts in the components and templates.	Not supported	1.4.0
`layoutDirection`	String	`${environment.layoutDirection}`	Specifies the layout direction for the content. Set this property to either `LTR` (left-to-right) or `RTL` (right-to-left). This property doesn't inherit the `layoutDirection` from the component's parent container. Therefore, explicitly set this property when needed. For more details about support for right-to-left languages in the responsive components, see Support for Right-to-left Languages.	Not supported	1.4.0
`listId`	String	—	An identifier to assign to the `Sequence` component used for the list. Set `listId` to a value to enable voice-based scrolling with the built-in intents. Also set this parameter to an ID if you need to target the list for commands, such as the `SpeakList` command.	Not supported	1.2.0
`listItems`	Array of `AlexaImageListItem`		An array of items to display in the list. Each item is an object with the same properties as defined in `AlexaImageListItem`. See Provide the list items.	Not supported	1.1.0
`primaryAction`	Command	—	Sets a default for the `primaryAction` option for the items in `listItems`. Set this property to the command to trigger when the user selects an item from the list. See the `primaryAction` property in `AlexaImageListItem`.	Not supported	1.1.0
`speechItems`	Any	—	An array of speech items. The `AlexaImageList` template assigns each item in this array to the `speech` property of the corresponding list item. Use this property when you want to use the `SpeakList` command to speak the list items. For details, see Use the SpeakList command with AlexaImageList.	Not supported	1.2.0
`theme`	String	`dark`	Set the dark or light color theme. The selected theme controls the colors used for the template.	Not supported	1.1.0
`type`	String	—	Always set to `AlexaImageList`.	Not supported	1.1.0
`videoAudioTrack`	String	`foreground`	Audio track to play on when playing the video. Can be `foreground` \| `background` \| `none`.	Not supported	1.1.0
`videoAutoPlay`	Boolean	`false`	When `true`, the video begins playing automatically when the document renders on the device. Applies when `backgroundVideoSource` contains a value.	Not supported	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 on AlexaImageList otherwise.

For example, you might set imageScale to best-fit for the whole list, but then override it to best-fill for one item on the list.
Defaults that always apply to all the items in the list – AlexaImageList always uses the value provided on AlexaImageList 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 for imageAspectRatio 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

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}"
    ]
  }
}

Use the SpeakList command with AlexaImageList

Use the speechItems parameter on AlexaImageList when you want to use the SpeakList command to read the list of items. Set the speechItems property to an array of items.

The SpeakList command requires a speech property on each list item to speak. The speech property must be set to the output of either the ssmlToSpeech or textToSpeech transformer. Therefore, you need to do the following to use SpeakList with AlexaImageList:

Use an object type data source for the array of items to speak. Within this data source, configure either the ssmlToSpeech or textToSpeech transformer to process the array of items to speak.
Bind the speechItems property of the AlexaImageList to list of items to speak.
Invoke the SpeakList command for the list.

Configure a data source for list speech items

Create an object type data source to use with your document.

In the data source, add an array of items to speak to a property within the properties object in the data source.

The following example shows an object data source that contains an array called listItemsToShow. Note that the array of items is within the properties object.

 {
   "imageListData": {
     "type": "object",
     "objectId": "imageListDataId",
     "properties": {
       "listItemsToShow": [
         {
           "primaryText": "First list item",
           "imageSource": "https://d2o906d8ln7ui1.cloudfront.net/images/md_gruyere.png"
         },
         {
           "primaryText": "Second list item",
           "imageSource": "https://d2o906d8ln7ui1.cloudfront.net/images/md_gorgonzola.png"
         }
       ]
     }
   }
 }

Configure the ssmlToSpeech or textToSpeech transformer with the following settings:
- inputPath – The array of items to speak. The transformer expects the path you provide to be within the properties object, so you don't need to include properties in the path. When the items in your array are objects, specify the specific field within the object that contains the text or SSML.
- outputName – Set to the string "speech". The AlexaImageList template includes "speech" when handling the list of items, so you must use this exact string.
- transformer – Either ssmlToSpeech or textToSpeech, depending on the format of the items in the array
The following example configures the textToSpeech transformer to process the primaryText field for each item in the listItemsToShow array.
```
 {
   "transformers": [
     {
       "inputPath": "listItemsToShow[*].primaryText",
       "outputName": "speech",
       "transformer": "textToSpeech"
     }
   ]
 }
```

Bind the speechItems property to the list of items to speak

In your APL document, use a data-binding expression to bind the speechItems property of AlexaImageList to your list of items to speak.

Continuing the previous example, the expression is ${imageListData.properties.listItemsToShow}. This example uses the same primaryText both for display and for speech.

{
  "type": "AlexaImageList",
  "listItems": "${imageListData.properties.listItemsToShow}",
  "speechItems": "${imageListData.properties.listItemsToShow}"
}

Run the SpeakList command for the list

Run the SpeakList command when you want Alexa to read the items provided in speechItems. For example, you might run the command from the onMount handler to read the items after the device displays the document.

Assign the listId parameter on AlexaImageList to an ID unique to your document. You must provide this ID to run SpeakList.

 {
   "type": "AlexaImageList",
   "listId": "myImageListWithItemsToSpeak",
   "listItems": "${imageListData.properties.listItemsToShow}",
   "speechItems": "${imageListData.properties.listItemsToShow}"
 }

Set the componentId property for the SpeakList command to the ID you provided for listId.

The following example invokes the command in the onMount handler. Alexa speaks the items after the device displays the document.

 {
   "onMount": [
     {
       "type": "SpeakList",
       "delay": 5000,
       "componentId": "myImageListWithItemsToSpeak",
       "start": 0,
       "count": "${imageListData.properties.listItemsToShow.length}",
       "minimumDwellTime": 1000,
       "align": "center"
     }
   ]
 }

The following examples show the complete document and data source. After the device displays the document, Alexa reads the primary text for each of the six items in the list. The SpeakList command includes the five second delay to allow Alexa to speak the normal speech output for the skill response before reading the list items.

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 of AlexaImageList. This binding is equivalent to binding the data source to the data property of a Sequence in a custom layout.

The following examples show a document with an AlexaImageList that uses a dynamicIndexList data source.

Copied to clipboard.

To learn how to test APL examples in the authoring tool, see Experiment with APL Examples in the Authoring Tool.

This datasource object defines two data sources:

imageListData is a dynamicIndexList that contains the list items.
staticData is an untyped data source that defines text strings for other elements on the screen.

{
  "imageListData": {
    "type": "dynamicIndexList",
    "listId": "datasourceForImageList",
    "startIndex": 0,
    "minimumInclusiveIndex": 0,
    "maximumExclusiveIndex": 100,
    "items": [
      {
        "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"
      }
    ]
  },
  "staticData": {
    "headerTitle": "Header title for a dynamic list",
    "headerSubtitle": "These static text items are in a different data source",
    "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",
    "defaultImageSource": "https://d2o906d8ln7ui1.cloudfront.net/images/BT7_Background.png",
    "hintText": "Footer text"
  }
}

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.