Matte: Extending with Browse Mode Plugins

Matte supports Browse Mode Plugins for extending how it can display a user's shared albums. Read the general Extending with Plugins documentation before reading this document.

The default brose mode in the default Woosh theme looks like this:

Woosh default Browse Mode view.

Here, when you click on the Alternate Views link, it reveals all available browse modes which were registered with Matte when it started up:

Woosh alternate Browse Mode selection view.

Matte comes with 3 built-in browse mode plugins:

Albums by date: the default browse mode for a user's shared albums ordered by date.
Popularity: virtual albums created from the number of times individual items have been viewed.
Average rating: virtual albums created from the average user rating of individual items.

You can think of browse modes as different search queries that Matte will perform in order to generate the browse user interface. The result of the search is a set of albums, each album populated with the media items that fall into that album's grouping.

Browse Mode Plugin API

There is one main API to implement for browse mode plugins: BrowseModePlugin.

Browse mode keys

Each browse mode is defined by a mode key, which must be unique across all browse modes registered with Matte. A single BrowseModePlugin can support more than one mode. The mode keys it supports are returned by the getSupportedModes() method. In addition, the supportsMode() method returns true or false if it supports a given mode key. These mode keys are passed to the Matte UI, so the UI can allow the user to select different browse modes.

The find() method

The find() method is what performs the browse mode search and returns a SearchResults instance. It is passed a BrowseAlbumsCommand instance, which will be populated with the requested browse mode key, the anonymous user key of the owner of the items being browsed, and optionally a section key that represents a specific subset within the browse search results.

Browse search results

For browsing, it is expected the SearchResults object returned by the find() method contain a collection of AlbumSearchResult objects. The plugin can support sections by returning a PaginationIndex object within the SearchResults that specifies all available sections.

For each AlbumSearchResult, the anonymous key must be generated with some value that can later be passed back to the plugin as a PaginationCriteria.indexKey value. That means the album anonymous keys need to be encoded in such a way they are recognizable from normal browseing section keys.

Let's look at an example of how the PopularityBrowseModePlugin works within the default Woosh theme in Matte:

The popularity browse mode in Woosh theme.

Sections - the plugin breaks up popularity into range groups of 20 different values. In this example there are two sections: 20-39 and 0-19. It is up to the plugin to determin how (and if) sections are supported. Since a user can have any number of shared items, sections are a good way to break up the results into smaller parts that are easier to view. In this case, when a user clicks on a section link, that value will be passed back to the plugin as the PaginationCriteria.indexKey value.
Album search result names - the names of the albums returned by the plugin are set to the section name and an offset within the section. This plugin limits the size of each album to 25, so within each section there can be any number of albums.
Anonymous key - the anonymous keys for each album are encoded as a combination of the section key and the offset within the section. In this example, the anonymous key for the album is encoded as "0 - 19:0". In this way, when a user clicks on the album the 0 - 19:0 value will be passed as the PaginationCriteria.indexKey value, which the plugin can decode as the 0 - 19 section, with the 0 offset album.

The XML model for this example looks like this:

Virtual albums

Each browse mode plugin should support viewing the virtual albums that it returns in the browse search results by way of the ViewAlbumController. That means for each AlbumSearchResult returned while browsing, the anonymousKey should be set to some value that the plugin can understand later as a specific album to find and return. In this case, the returned album should have MediaItemSearchResult objects populated for each item within the virtual album.

For example, the XML model for a virtual album would look like this: