Create grids

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:

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:

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:

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:

The recommended display type also specifies the lines to display using a stringId and a token attribute:

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.

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:

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.

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.

Sonos Controller user interface – root

The getMetadata response populates the user interface as shown below.

Root browse

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.

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.

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.

listenNow DisplayType

The second mediaCollection sub-element uses the newRelease display type. This uses the lines configured in the newRelease DisplayType in the presentation map.