Create lists

This tutorial guides you through creating a display type that displays your albums as a list in the Sonos app.

Some default container itemType objects are already available that display contents in lists. You may want to look at these to see if they suit your needs before customizing display types.

Create a presentation map

Your presentation map determines how certain elements in your service appear in the Sonos app. You should have one presentation map for your service. This tutorial assumes that you have not created a presentation map for your service. See Customize display for details about presentation maps.

Your presentation map always starts with the open <Presentation> tag and ends with the close </Presentation> tag:

The ellipsis (…) in the example above indicate other content that exists within the tags.

Create a display type using the “DisplayType” attribute in your presentation map:

Enter a name for your display type using the “id” parameter of the <DisplayType> sub-element and enter “LIST” as the content of the <DisplayMode> sub-element:

The XML above indicates that the listOfAlbums display type will be a list.

Configure lines and strings

Unlike the example in the Grid tutorial, this example uses the default album title and artist as the two lines next to the album art, so you do not need to specify lines.

Respond to getMetadata requests

This section goes over the getMetadata requests and responses and how they appear in Sonos apps.

getMetadata request – root

When a user browses into your service, the Sonos app sends a getMetadata request to show the root container.

getMetadata response – root

You should send back a getMetadata response that includes all top-level containers. The response below only shows the relevant container, the “Listen Now” container using the mediaCollection sub-element for browse:albums_v2, which uses the listOfAlbums display type we created in the presentation map above.

Sonos app user interface – root

The getMetadata response populates the user interface as shown below.

Root browse

getMetadata request – album as list

When the user clicks the “Album as List” container, the app sends a getMetadata request to your service to display its contents.

getMetadata response – album as list

Your service should send a getMetadata response with the contents of this container. The sample below returned a large number of results, but only a few are shown, for brevity.

Sonos app user interface – album as list

These contents are displayed using the listOfAlbums display type, in this case, as a list.

Album list

List display mode without images

If desired, your service can choose not to return any artwork for non-playable browse nodes in a list display mode. To do this, set the ItemThumbnails source attribute to “none” in your presentation map.

Album list no thumbnails

The Sonos app will only display a list without an image on a iOS or Android device. The Sonos app on a Mac or PC will use default Sonos browse icons. As noted above, this will only work with non-playable items, such as a list of genres. Anything that a listener can play will still need artwork.