This tutorial guides you through creating a display type that displays your container content as a grid in Sonos controllers. You’ll also create display types to customize the text that appears under the album art in the grid.
Some default container itemType objects are already available that display albums in a grid with two-line display. You may want to look at these to see if they work for you before customizing display types.
Create a presentation map
Your presentation map determines how certain elements in your service appear in the Sonos controller. 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 other elements you can change using your presentation map.
Your presentation map always starts with the open <Presentation> tag and ends with the close </Presentation> tag:
|
1 2 3 |
<Presentation> ... </Presentation> |
Within this file you will add different types of PresentationMap elements. The dots (…) in the example above indicate other content that exists within the tags.
Create a display type using the DisplayType attribute in your presentation map:
|
1 2 3 4 5 6 |
<Presentation> <PresentationMap type="DisplayType"> ... </PresentationMap> ... </Presentation> |
Enter a name for your display type using the id parameter of the DisplayType sub-element and enter “GRID” as the content of the DisplayMode sub-element:
|
1 2 3 4 5 6 7 8 |
<Presentation> <PresentationMap type="DisplayType"> <DisplayType id="listenNow"> <DisplayMode>GRID</DisplayMode> </DisplayType> </PresentationMap> ... </Presentation> |
The XML above indicates that the listenNow display type will be a grid.
Configure lines and strings
Create the newRelease and recommended display types to set how the lines will display under the album art in your grid.
The newRelease display type specifies the lines to display using stringId attributes:
|
1 2 3 4 5 6 7 8 |
... <DisplayType id="newRelease"> <Lines> <Line stringId="TITLE_BY_ARTIST" /> <Line stringId="NEW_RELEASE" /> </Lines> </DisplayType> ... |
The recommended display type also specifies the lines to display using a stringId and a token attribute:
|
1 2 3 4 5 6 7 8 |
... <DisplayType id="recommended"> <Lines> <Line token="title" /> <Line stringId="RECOMMENDED" /> </Lines> </DisplayType> ... |
The “title” token maps to the “title” sub-element of the mediaCollection element. See the Configure lines section of Configure display types for more details on tokens.
The stringId attribute refers to strings in your strings.xml file, as shown below.
|
1 2 3 4 5 6 7 8 9 |
<?xml version="1.0" encoding="utf-8" ?> <stringtables xmlns="http://sonos.com/sonosapi"> <stringtable rev="9" xml:lang="en-US"> ... <string stringId="NEW_RELEASE">Featured {genre}</string> <string stringId="TITLE_BY_ARTIST">{title} / {artist}</string> <string stringId="RECOMMENDED">New by {artist}</string> ... </stringtable> |
String elements with the stringId attribute can also use tokens, surrounded by curly braces ({ }). When the Sonos controller renders the text, the lines are replaced with the text in the string.
Your presentation map should now have the following elements:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 |
<Presentation> ... <PresentationMap type="DisplayType"> <DisplayType id="listenNow"> <DisplayMode>GRID</DisplayMode> </DisplayType> <DisplayType id="newRelease"> <Lines> <Line stringId="TITLE_BY_ARTIST" /> <Line stringId="NEW_RELEASE" /> </Lines> </DisplayType> <DisplayType id="recommended"> <Lines> <Line token="title" /> <Line stringId="RECOMMENDED" /> </Lines> </DisplayType> ... </PresentationMap> </Presentation> |
Respond to getMetadata requests
This section goes over the getMetadata requests and responses and how they appear in Sonos controllers.
getMetadata request – root
When a user browses into your service, the Sonos controller sends a getMetadata request to show the root container.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
<?xml version="1.0" encoding="UTF-8"?> <s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"> <s:Header> ... </s:Header> <s:Body> <getMetadata xmlns="http://www.sonos.com/Services/1.1"> <id>root</id> <index>0</index> <count>100</count> </getMetadata> </s:Body> </s:Envelope> |
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 listenNow, which uses the listenNow display type we created in the presentation map above.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 |
<?xml version="1.0" encoding="UTF-8"?> <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:listenNow</ns:id> <ns:itemType>container</ns:itemType> <ns:displayType>listenNow</ns:displayType> <ns:title>Listen Now</ns:title> <ns:canPlay>false</ns:canPlay> <ns:containsFavorite>false </ns:containsFavorite> <ns:albumArtURI /> </ns:mediaCollection> ... </ns:getMetadataResult> </ns:getMetadataResponse> </s:Body> </s:Envelope> |
Sonos Controller user interface – root
The getMetadata response populates the user interface as shown below.
getMetadata request – Listen Now
When the user clicks the “Listen Now” container, the controller sends a getMetadata request to your service to display its contents.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 |
<?xml version="1.0" encoding="UTF-8"?> <s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"> ... <s:Body> <getMetadata xmlns="http://www.sonos.com/Services/1.1"> <id>browse:listenNow</id> <index>0</index> <count>100</count> </getMetadata> </s:Body> </s:Envelope> |
getMetadata response – Listen Now
Note that the display type for the first mediaCollection sub-element below is “recommended”. This display type determines how the controller displays the lines below the album art.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 |
<?xml version="1.0" encoding="UTF-8"?> <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>5</ns:count> <ns:total>5</ns:total> ... <ns:mediaCollection> <ns:id>al:10</ns:id> <ns:itemType>album</ns:itemType> <ns:displayType>recommended</ns:displayType> <ns:title>Forgiveness & Gratefulness</ns:title> <ns:summary>Forgiveness & Gratefulness</ns:summary> <ns:isFavorite>false</ns:isFavorite> <ns:artist>Saratoga Indiana</ns:artist> <ns:artistId>ar:8</ns:artistId> <ns:canPlay>true</ns:canPlay> <ns:canEnumerate>true</ns:canEnumerate> <ns:canAddToFavorites>true</ns:canAddToFavorites> <ns:albumArtURI> https://CDN/images/album1.jpg</ns:albumArtURI> </ns:mediaCollection> <ns:mediaCollection> <ns:id>al:11</ns:id> <ns:itemType>album</ns:itemType> <ns:displayType>newRelease</ns:displayType> <ns:title>We Have Respect For Them</ns:title> <ns:isFavorite>false</ns:isFavorite> <ns:artist>Bauer</ns:artist> <ns:artistId>ar:9</ns:artistId> <ns:canPlay>true</ns:canPlay> <ns:canEnumerate>true</ns:canEnumerate> <ns:canAddToFavorites>true</ns:canAddToFavorites> <ns:albumArtURI> https://CDN/images/album2.png</ns:albumArtURI> </ns:mediaCollection> ... </ns:getMetadataResult> </ns:getMetadataResponse> </s:Body> </s:Envelope> |
In this case, the first line is the title of the album, and the second line is the stringId “RECOMMENDED”.
Sonos Controller user interface – Listen Now
Your service should send a getMetadata response with the contents of this container. These contents are displayed using the listenNow display type, in this case, as a grid. Only the first two results are shown in the SOAP response above, for brevity.
The second mediaCollection sub-element uses the newRelease display type. This uses the lines configured in the newRelease DisplayType in the presentation map.