To create display types for containers, you’ll need to:
- Add them to your presentation map.
- Configure lines and strings (this is optional).
- Configure your
getMetadatamediaMetadataandmediaCollectionelements to returndisplayTypeandsummarymetadata for containers that use these elements.
See below for details, or click one of the tutorials to walk through a guided implementation.
Create display types in your presentation map
In the presentation map, create a display type with the DisplayType element. Set an id for the display type to reference the display type in the getMetadata response. For example, the id for the display type below is genreGrid:
|
1 |
<DisplayType id="genreGrid"> |
Next, choose a display mode to define the layout of the object. As shown in the overview, there are four display modes: GRID, LIST, HERO, and EDITORIAL. Continuing with the example above, let’s say you want the genreGrid display type to be a grid with the default amount of lines. In your presentation map, set the display mode to GRID, as shown below:
|
1 2 3 4 5 6 7 |
<PresentationMap type="DisplayType"> ... <DisplayType id="genreGrid"> <DisplayMode>GRID</DisplayMode> </DisplayType> ... </PresentationMap> |
If you provide a DisplayType in the presentation map, it overrides the default presentation mode for the container, except for an album view, as you wouldn’t want tracks in an album to be displayed other than as a list.
Configure lines (optional)
Within the DisplayType in the presentation map, you can set the lines that you want to display for that DisplayType. You can configure lines using token keywords that will be mapped to metadata in the getMetadata response, use stringIds from your strings file, or a combination of both.
Syntax
Configure lines in DisplayType elements in your presentation map using the Lines element with Line elements for each line. Use a token or stringId parameter to specify the contents of the line.
Using Tokens
A token represents text that will be replaced with metadata from the getMetadata response. Use the token parameter to display the following metadata (see getMetadata for details):
- genre – the genre returned in the metadata.
- artist – the artist returned in the metadata.
- album – the album returned in the metadata.
- title – the title returned in the metadata.
- summary – the summary returned in the metadata.
Here’s an example:
|
1 2 3 4 5 6 |
<DisplayType id="newRelease"> <Lines> <Line token="title"/> <Line token="artist"/> </Lines> </DisplayType> |
In this example,
|
1 |
<Line token="title"/> |
displays the title from the metadata response and
|
1 |
<Line token="artist"/> |
displays the artist.
Configuring strings
Use the stringId parameter to display a named string in the strings.xml file. For example:
|
1 2 3 4 5 6 |
<DisplayType id="newRelease"> <Lines> <Line stringId="TITLE_BY_ARTIST"/> <Line stringId="NEW_RELEASE"/> </Lines> </DisplayType> |
In this example:
|
1 |
<Line stringId="TITLE_BY_ARTIST"/> |
displays the string in your strings.xml file with the stringId named “TITLE_BY_ARTIST” and
|
1 |
<Line stringId="NEW_RELEASE"/> |
displays the string in your strings.xml file with the stringId named “NEW_RELEASE”.
Using tokens in strings
You can use tokens in strings to include metadata returned from your getMetadata response. To use a token in a string, enter one of the tokens shown in the bulleted list above surrounded by brackets. For example, you may want to call out a recently added title in an editorial view. To do so, you could add the following stringId in your strings.xml file:
|
1 |
<string stringId="RECENTLY_ADDED_TITLE">{title} recently added</string> |
See Strings and Localization to learn how to configure your strings file.
Configure getMetadata responses
When you want to display items using your new display type, return it in the getMetadata response. For example:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 |
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns="http://www.sonos.com/Services/1.1"> <s:Body> <ns:getMetadataResponse> <ns:getMetadataResult> <ns:index>0</ns:index> <ns:count>10</ns:count> <ns:total>10</ns:total> ... <ns:mediaCollection> <ns:id>browse:genreList</ns:id> <ns:itemType>container</ns:itemType> <ns:displayType>genreGrid</ns:displayType> <ns:title>Genres</ns:title> <ns:canPlay>false</ns:canPlay> <ns:containsFavorite>false</ns:containsFavorite> <ns:albumArtURI /> </ns:mediaCollection> ... </ns:getMetadataResult> </ns:getMetadataResponse> </s:Body> </s:Envelope> |
When you return mediaMetadata or mediaCollection to a getMetadata request, the displayType for the item determines how it is displayed on the controller. For example, Sonos controllers display the mediaCollection shown above as a genreGrid display type when a user browses into it:
The getMetadata response for the container includes the Cooking Playlist:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 |
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns="http://www.sonos.com/Services/1.1"> <s:Body> <ns:getMetadataResponse> <ns:getMetadataResult> <ns:index>0</ns:index> <ns:count>4</ns:count> <ns:total>4</ns:total> ... <ns:mediaCollection> <ns:id>cooking</ns:id> <ns:itemType>container</ns:itemType> <ns:displayType>genreMood</ns:displayType> <ns:title>Cooking Playlist</ns:title> <ns:summary>Enjoy music while preparing food for friends and family.</ns:summary> <ns:canPlay>false</ns:canPlay> <ns:albumArtURI>https://example.com/assets/images/boost.jpg</ns:albumArtURI> </ns:mediaCollection> ... </ns:getMetadataResult> </ns:getMetadataResponse> </s:Body> </s:Envelope> |
Likewise, the display type for the Cooking Playlist is the genreMood display type, which is associated with the HERO display mode in the presentation map:
|
1 2 3 4 5 |
... <DisplayType id="genreMood"> <DisplayMode>HERO</DisplayMode> </DisplayType> ... |
When you browse into the Cooking Playlist container, the controller uses the genreMood display type to display the contents:
Define display type for item type
You can define the default display types for item types. This can help simplify your integration, as well as provide a consistent browse experience for users.
For example, SMAPI is designed so that the parent container defines the display type used to render its children. Because of this, if a user displays a container using a related browse call, the call only provides an ID for the item, and not the parent container, so the user may not see the display type you intended. Instead they’ll see the default display type. You can set the default display type for item types to mitigate this issue.
To set a default display type for an item type, enter the itemType in the type attribute of the DisplayType element in the presentation map:
|
1 2 3 4 5 |
<PresentationMap type="DisplayType"> <DisplayType type="podcast"> <DisplayMode>HERO</DisplayMode> </DisplayType> </PresentationMap> |
This entry in the presentation map means that any podcast that doesn’t already have a valid display type will have the HERO DisplayMode. Note that podcast is a semanticType, an extension of itemType. See SMAPI object types for details about item types and Add podcasts for details about podcasts and semantic types.
Tutorials
See the tutorials for detailed examples: