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.
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:
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.
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.
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.
text. When the output method is set to
xml, however, you are guaranteed to generate well-formed XML results.
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.
In Matte there are three main user interfaces that are theme-able. Think of these as unique URLs which are accessible by users:
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).
Album: a single shared album, generally designed to display all the media items contained in the album as a slide show.
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.
Going forward we will refer to these UIs as unique views, e.g. "browse view", "album view", and "detail view".
Themes are installed and managed in the form of ThemePaks, which are zip archives following certain conventions:
_langportion of the file name to be used as the default message bundle.
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.
The built-in Woosh theme is thus a good place to start. Follow these steps:
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
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.
theme.propertiesfile (as described previously) to give this theme a new name, author, etc.
/var/matte/themesand Matte assigns your new theme an ID of
382then the theme resources will be located in
/var/matte/themes/themes/382. Note the duplicate "themes" directory, this is not a mistake.
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.
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!
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
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:
Some specialized information about the web request, which will include:
/mattebut can be changed to anything.
<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:param>elements, one for each request parameter provided on the current request.
<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.
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.
<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: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
To view the XML source used for this page, you can add
the URL, like this:
The elements in more detail are listed here:
This element represents an album, which is a collection of items. In themes, the following components of this element are especially important:
@creation-dateattribute can be used, which is the date the album was created.
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. 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.
@creation-dateof 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.
In order to generate links to theme resources, such as HTML <link> tags for
get-resource-url XSLT template. This template takes the following
/x:x-data/x:x-model/m:model/m:themeXPath, or you can use the pre-defined helper variable
/matte. This is also pre-defined as the helper variable
behaviour.js theme resource:
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:
@anonymous-keyattribute of the
<m:album>element that the item is shared with.
One of the predefined Matte size constants, defined as one of the following:
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.
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:
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.
/matte. This is also pre-defined as the helper variable
For example, here's how you would generate an HTML <img> tag for a thumbnail
$display-image is a variable holding a
$display-album is a variable holding a
Continue next with details on the Browse View.