Matte: Theme HOWTO: Overview

The look and feel of shared albums can be completely customized in Matte by way of themes. This document describes how web-heads can write customized themes for Matte.

XSLT

In Matte themes are rendered by transforming XML with XSLT 1.0. Therefore you must be comfortable with the XSLT language in order to write a Matte theme. There are good and not-so-good consequences for using XSLT:

For help getting started with XSLT, check out the XSLT article Wikipedia which contains many links at the bottom to tutorials and more information on XSLT.

Theme-able UIs

In Matte there are three main user interfaces that are theme-able. Think of these as unique URLs which are accessible by users:

Going forward we will refer to these UIs as unique views, e.g. "browse view", "album view", and "detail view".

ThemePak

Themes are installed and managed in the form of ThemePaks, which are zip archives following certain conventions:

Starting a new theme

Administrators of Matte systems can manage themes by going to the Admin page after logging into Matte. From there you can view, install, update, and remove themes.

A great way to get started on a new theme is to modify an existing theme. You can copy an existing theme, create a test album and share it using the new theme, configure Matte to reload the theme XSLT on each request, and then interactively make changes to the XSLT to work on changes.

You should now be able to view your shared album using your new copy of the Woosh theme by clicking on the link provided after you save the album's sharing settings. You are now ready to start modifying your new theme however you see fit!

XWeb XML Data Model

Matte uses an XML data model based on a view platform called XWeb. XWeb provides an XML data model that includes web elements that web-heads will be familiar with. Here is a sample XWeb XML document with all Matte-specific XML removed:

Note the use of the XWeb namespace http://msqr.us/xsd/jaxb-web, mapped to the x prefix. These elements provide you with all the data elements needed to be able to see what was requested by the person's browser, what parameters were provided, the person's language settings, etc. The elements you see are:

If you are familiar with Java servlets, these data elements will be very familiar to you. The formal definition of XWeb is in the form of an XML Schema, located here.

Matte XML Data Model

Inside the <x:x-model> XWeb element (listed above) Matte will generate a Matte-specific XML tree in the form of a <m:model> element. Note the namespace for Matte XML elements: http://msqr.us/xsd/matte. Internally Matte uses the m namespace prefix for this namespace, which we'll use in this document as well. This element is a container for <m:album> and <m:item> elements. Here is an example Matte XML model document, this one from a detail view request:

This provides a good example of the Matte XML elements you'll work with in a theme.

By default you can view the source XML document for any Matte URL by passing an xml=true parameter with the request. For example a Browse View URL might look like http://myserver.com/matte/browse.do?user=XYZ. To view the XML source used for this page, you can add &xml=true to the URL, like this: http://myserver.com/matte/browse.do?user=XYZ&xml=true

<m:album>

This element represents an album, which is a collection of items. In themes, the following components of this element are especially important:

@album-date: The date assigned to the album. This date is optional, and if not provided the @creation-date attribute can be used, which is the date the album was created.
@anonymous-key: This key is used in the URL for the album view to display the album.
@modify-date: The date the album was last modified. This will not be present if the album has never been modified after its initial creation.
@name: The name of the album.
<m:comment>: A description or comment about the album.
<m:item> (list): Any number of of these elements can appear in an album, and represent the items in the album.
<m:owner>: The user that created this album.
<m:poster>: An optional "poster" item to be used as the album's thumbnail.
<m:theme>: The theme assigned to this album. This is needed in the album and detail views in order to render links to theme resources such as images, JavaScript, etc.

<m:item>

This element represents a media item, such as a photo, audio file, video file, etc. In themes, the following components of this element are especially important:

@creation-date: The date the item was created. This may be the date the item was added to Matte, or for some media types the date the item was originally created. For example JPEG photos taken with digital cameras come with the date the photo was taken embedded in the image file, and Matte will extract that date and use that for the item's creation date. Note that the time zone associated here is generally the time zone that Matte is running in, not the time zone of the media item. See the <m:tz> and <m:tz-display> elements below.
@file-size: The size of the original media item's file, in bytes.
@height: For media types with a height, such as photos or videos, the original height of the media, in pixels.
@hits: The number of times this media item has been viewed (not as a thumbnail).
@item-id: The unique ID of this item, required when rendering the URLs to link to the item.
@mime: The MIME type of this media item.
@name: The name of the item, defined by the user. For some media types Matte will extract the name embedded in the file, such as the song title from MP3 files. For all others this is set initially to the name of the media item's file. Users can replace this with anything they like, however.
@path: A file path for the original media item in Matte. This path is always relative from the user's collection directory.
@width: For media types with a width, such as photos or videos, the original width of the media, in pixels.
<m:metadata> (list): Any number of these elements can be associated with an item. They represent metadata extracted from the item's file. For example for digital photos this list will be populated with EXIF data. They key names are fairly self-explainatory, and the element's content will contain the associated metadata value.
<m:tz>: The time zone of the media item's @creation-date. This is mostly useful for photos from digital cameras, which do not store a time zone with the dates they add to the photos. Generally you set a time zone on the camera, and then it uses that time zone for the dates and times it embedds in the photos you take.
<m:tz-display>: A time zone to display the @creation-date of this item in. This is used in conjunction with the <m:tz> value to translate the time zone of the item into a different time zone. Again this is mostly useful for photos from digital cameras, where the camera's time zone is set to a different time zone than the location the photo was taken. This time zone represents the time zone the photo was taken in, or the "local time" of the photo, and can be used to display the local time of the photo rather than the time zone that the camera is set to.

Linking to theme resources

In order to generate links to theme resources, such as HTML <link> tags for your theme's CSS, or HTML <script> tags for your theme's JavaScript, you should call the get-resource-url XSLT template. This template takes the following parameters:

For example, here's how you would generate an HTML JavaScript <script> tag for the behaviour.js theme resource:

Linking to media images

In order to link to thumbnail images or full-size images, for example to generate an HTML <img> tag, call the render-media-server-url XSLT template. This template takes the following parameters:

For example, here's how you would generate an HTML <img> tag for a thumbnail image (where $display-image is a variable holding a <m:item> element and $display-album is a variable holding a <m:album> element):