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.
html
(or 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:
yyyy-mm-dd
(eg. 2006-09-26)._lang
portion 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
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.
theme.properties
file (as described previously) to give this
theme a new name, author, etc./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.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 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:
Some specialized information about the web request, which will include:
/matte
but 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.
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:
This element represents an album, which is a collection of items. In themes, the following components of this element are especially important:
@creation-date
attribute 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:
<m:tz>
and <m:tz-display>
elements below.@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-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.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:
my-javascript.js
./x:x-data/x:x-model[1]/m:model[1]/m:theme[1]
XPath, or you
can use the pre-defined helper variable $theme
./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:
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:
<m:item>
XML element.@anonymous-key
attribute 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 $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):
Continue next with details on the Browse View.