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:

1. No coding required. When using some rendering technologies, such as JSP, PHP, etc. you must be comfortable with writing code in that particular language, which can be overwhelming to some, powerful to others, and generally messy. XSLT, on the other hand, is a relatively simple language designed exactly for this type of job: transforming XML into other markup languages (e.g. XHTML, HTML, WML, other XML, etc). We will concentrate here on transforming into XHTML, as this is the language used for normal web pages and most themes will focus in this area.

2. Less-known language. Of course you might say that XSLT is, in fact, coding. That is true. The language is very high-level and focused on the specific task at hand, turning XML into XHTML. The only major down side of XSLT is that not a lot of web-heads are familiar with XSLT, at least not as many as familiar with JSP, PHP, etc.

3. Guaranteed well-formed XML results. Using XSLT to generate XHTML ensures you will generate well-formed results. It will not be possible to generate an un-closed <br> tag, for example.

   You can, in fact, generate HTML results with XSLT that are not valid XML documents, by setting the output method to html (or text. When the output method is set to xml, however, you are guaranteed to generate well-formed XML results.

4. Isolated code. By using XSLT for the rendering language, the themes are nicely isolated from the main Matte Java code, and generally don't have access to Matte, or Java, internals. This helps keep themes clean, focused, and provides some relief to administers of Matte systems that themes are not going to run off and do something naughty.

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:

1. Browse: a view of all of a single user's shared albums, generally designed to display each album as a link to that album's slide show (see Album next).

   

   The built-in Woosh browse view.

2. Album: a single shared album, generally designed to display all the media items contained in the album as a slide show.

   

   The built-in Woosh album view.

3. Item detail: information about a single media item, generally designed to display all available information about that item, such as metadata, comments, ratings, etc. This is usually used in album themes to dynamically show this information when viewing a specific media item. The built-in Woosh theme uses AJAX to display this information, for example.

   

   The built-in Woosh item detail view.

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:

1. An album view XSLT file, named theme.xsl. This is required.
2. A browse view XSLT file, named browse.xsl. This is required if the theme is to be used for album browsing.
3. A detail view XSLT file, named info.xsl. This is optional and can be used by the theme for dynamically displaying detailed information about selected media items.
4. The theme thumbnail PNG image, named thumbnail.png. This is optional, but recommended. This thumbnail should be designed as a small icon for the theme, sized to about 160x120 pixels.
5. The theme preview PNG image, named preview.png. This is optional, but recommended. This preview shold be designed as a showcase for what the theme features are, sized to about 1024x768 pixels.
6. The theme metadata properties file, named theme.properties. This is optional, but recommended. It allows the ThemePak to define the following properties:

   theme.name

   The name of the theme.

   theme.author

   The name of the theme's author(s).

   theme.authoremail

   The email address of the theme's author(s).

   theme.created

   The creation date of the theme, in the format yyyy-mm-dd (eg. 2006-09-26).

7. The theme messages resource bundle, named theme-messages[_lang].properties. These are optional. They can be used to provide localized messages to make the theme work in different languages. One of the bundles can omit the _lang portion of the file name to be used as the default message bundle.
8. Any other resources required by the theme, such as CSS files, images, JavaScript, etc.

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.

The Matte administration screen, showing the built-in Woosh theme.

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.

The built-in Woosh theme is thus a good place to start. Follow these steps:

1. Start up Matte and log in as an administrator (Matte creates an administrator for you the first time it runs, the login is matte-admin and the password is password). Then use the Setup Wizard to update the XSLT cache property to No. The SetupWizard can be loaded by typing in the URL /matte/setupWizard.do (leaving your server name, etc.).

   Also note the value of your Themes directory path, on the Filesystem setup page. This is where your uploaded themes will go later on.

2. Restart Matte for the XSLT setting to take effect.
3. Log back into Matte as an administrator, and from the Admin screen in Matte, click on the "Woosh" theme from the list on the left. Then choose the "Download theme" action to download the entire Theme as a Matte ThemePak.
4. Unzip the ThemePak and create a new theme.properties file (as described previously) to give this theme a new name, author, etc.
5. Zip up all the theme contents (not the theme's top-level folder, but just all the files/folders inside that) into a new ThemePak.
6. Use the Matte Admin screen to upload the new ThemePak as a new theme. Now you have copied the Woosh theme into a new theme. The new theme's files will be located in your theme directory that you specified in the Setup Wizard. Inside the theme directory there will be another directory named themes and inside that will be a directory of the Matte-assigned unique ID for your new theme. For example if your theme directory is /var/matte/themes and Matte assigns your new theme an ID of 382 then the theme resources will be located in /var/matte/themes/themes/382. Note the duplicate "themes" directory, this is not a mistake.
7. The Woosh theme makes use of an XSLT templates file called theme-util.xsl. This file exists in the Matte WAR at /WEB-INF/themes/theme-util.xsl. In order for the new custom theme to make use of this file, copy it to the root of your custom theme directory (the one specified in the Setup Wizard). This XSLT templates file provide handy and oft-used functionality required by themes.
8. Go back to the Home screen now, and create a test album. Add some items into the album and then share the album using the new theme (go to Actions > Album Sharing, choosing your new theme from the Theme menu.

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:

<x:x-data>

The root XML element.

<x:x-context>

Some specialized information about the web request, which will include:

<x:x-server-name>

The name of the server hosting Matte. This is usually only needed when constructing full URLs, such as when constructing the URL for the Atom RSS link from the browse view.

<x:server-port>

The port the server hosting Matte is running on.

<x:user-agent>

The browser client requesting the page. This can be used for browser-sniffing style code in the XSLT where you want to return different content based on the browser making the request.

<x:user-locale>

The browser client's locale settings, for internationalization support.

<x:web-context>

The URL path to the Matte web application. By default this is /matte but can be changed to anything.

<x:path>

The URL path, after the web context, of the current request.

<x:x-session>

A list of <x:x-param> elements, one for each item in the current user's web session. The Matte session will contain information like the currently logged in user details.

<x:x-request>

A list of <x:param> elements, one for each request parameter provided on the current request.

<x:x-request-headers>

A list of <x:param> elements, one for each HTTP header provided on the current request. These are not usually needed in Matte themes, but can be handy in some situations.

<x:x-model>

This element will hold the Matte data model XML tree, such as the selected album, item, etc.

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

The elements in more detail are listed here:

<m:album>

<m:item>

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:

resource

The path of your theme resource, relative to the root of your theme's directory. For example my-javascript.js.

theme

The ID of the currently running theme. This is available via the /x:x-data/x:x-model[1]/m:model[1]/m:theme[1] XPath, or you can use the pre-defined helper variable $theme.

web-context

Matte's servlet context path, normally /matte. This is also pre-defined as the helper variable $web-context.

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:

item

A <m:item> XML element.

album-key

The @anonymous-key attribute of the <m:album> element that the item is shared with.

size

One of the predefined Matte size constants, defined as one of the following:

• BIGGEST (1600x1200)
• BIGGER (1024x768)
• BIG (800x600)
• NORMAL (640x480)
• SMALL (480x320)
• TINY (320x240)
• THUMB_BIGGER (240x180)
• THUMB_BIG (180x135)
• THUMB_NORMAL (120x90)
• THUMB_SMALL (64x48)

These pixel dimenstions listed here are the defaults provided by Matte, but the sizes are configurable by the system administrator so may be different than what is listed here. When in doubt, choose NORMAL for full-size viewing and THUMB_NORMAL for thumbnails.

Generally you will not want to hard-code the values for full-size images into your theme, however, since users visiting your shared albums will be given the opportunity to specify the desired image size themeselves. You would thus want to allow for your theme to be able to display any of these sizes.

quality

One of the predefined Matte quality constants, which represent how much Matte will attempt to compress images to achieve smaller file sizes at the expense of image quality. The constants are defined as one of the following:

• HIGHEST (little or no compression)
• HIGH (small amount of compression)
• GOOD (decent amount of compression, suitable for online viewing
• AVERAGE (fairly high amount of compression, visibly lower image quality but much smaller file size)
• LOW (very high amount of compression, very poor image quality, but very small file sizes, suiteable for very slow internet connections or thumbnail images)

When in doubt, use GOOD for full-size viewing, and either GOOD or AVERAGE for thumbnails.

Generally you will not want to hard-code the value for full-size images into your theme, however, since users visiting your shared albums will be given the opportunity to specify the desired image quality themeselves.

web-context

Matte's servlet context path, normally /matte. This is also pre-defined as the helper variable $web-context.

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):

Next: Browse View

Continue next with details on the Browse View.