Media Album: Theme HOWTO

This guide is to help Media Album users develop themes to customize the look and feel of Media Album shared albums and the browsing experience.
For more information on XSLT, check out http://www.w3.org/TR/xslt.
Media Album uses XML and XSLT to render pages into HTML. This approach makes it possible to also render into other XML formats, such as WML for cell phones or XML for web services, but this guide will focus on rendering to HTML. Writing a theme from scratch can be quite overwhelming if you are unfamiliar with XSLT, but you can always start with an existing theme and make tweaks to see how everything works.
  1. Album slideshow XML
  2. Browse XML
  3. Media Album schema
  4. Theme XSL
    1. XSL parameters
    2. XSL predefined variables
  5. Media Server
  6. XSL predefined templates

Album XML

The XML for an album slideshow is used to display the slideshow mode for viewing an album. The slideshow mode is used when you visit a shared album's URL or by clicking the Slideshow link for an album while browsing a media collection. The XML looks similar to the following (note the XML namespaces are not shown):
<?xml version="1.0" encoding="UTF-8"?> <media-album-data admin="false" displayAlbum="1"> <user anonymousKey="0/8MudyVj7OphxpoiXyfvnWoalk" singleCompress="normal" singleSize="normal" thumbCompress="normal" thumbSize="normal" userId="7"> <username>test</username> <name>Test User</name> <email>test@msqr.us</email> <password>{SHA}qUqP5cyxm6YcTAhz05Hph5gvu9M=</password> <permissions assignCreateUser="false" assignSuperUser="false" createUser="false" permId="7" superUser="false"/> </user> <settings mediaServer="internal"> <thumbnail compress="normal" height="90" size="normal" width="120"/> <single compress="normal" height="480" size="normal" width="640"/> </settings> <theme author="Test User" authorEmail="test@msqr.us" creationDate="2004-03-13T09:28:03.605" global="true" owner="7" themeId="2"> <name>Kewl Theme</name> <comment>This is my kewl theme, dude.</comment> <base-dir>user/7/1079198883605/</base-dir> <icon>thumbnail.png</icon> <preview>preview.png</preview> <xsl>album.xsl</xsl> <css>album.css</css> </theme> <collection collectionId="1" owner="7"> <path>test/1079127525550/</path> <name>Default</name> <scandate>2004-03-12T14:15:39.581</scandate> </collection> <album albumDate="2004-03-12T00:00:00.000" albumId="1" allowAnonymous="false" allowOriginal="false" anonymousKey="Plua194dSHckPeCzpMNTU454mGgY0" creationDate="2004-03-12T14:15:50.812" modificationDate="2004-03-13T16:40:25.970" owner="7" posterId="1" sortMode="0" themeId="2"> <name>My Album</name> <comment>This is an album, dude.</comment> <item creationDate="2002-12-11T21:18:54.000" displayOrder="1" fileSize="740951" collection="1" height="1600" hits="1" itemId="1" tzName="GMT-08:00" width="1200"> <path>IMG_0900.jpg</path> <mime>image/jpeg</mime> <name>Yee haw</name> <meta>|aCanon|bCanon PowerShot S330|c6|d6|e2|f89</meta> </item> <item creationDate="2004-03-12T14:15:39.000" displayOrder="2" fileSize="86238" collection="1" height="513" hits="1" itemId="2" tzName="GMT-08:00" width="720"> <path>ShowLetter.jpg</path> <mime>image/jpeg</mime> <name>Woa</name> </item> </album> </media-album-data>
Example album source XML.

Browse XML

The browse XML is used to display the browse mode for viewing a media collection. The XML looks similar to the following (note the XML namespaces are not shown):
<?xml version="1.0" encoding="UTF-8"?> <browse-data admin="false" browseName="Browse By Date" displayItem="1" displayPage="0" key="0/8MudyVj7OphxpoiXyfvnWoalk" pageSize="5" totalAlbums="4" totalItems="2" totalPages="1"> <user anonymousKey="0/8MudyVj7OphxpoiXyfvnWoalk" singleCompress="normal" singleSize="normal" thumbCompress="normal" thumbSize="normal" userId="7"> <username>test</username> <name>Test User</name> <email>test@msqr.us</email> <password>{SHA}qUqP5cyxm6YcTAhz05Hph5gvu9M=</password> <permissions assignCreateUser="false" assignSuperUser="false" createUser="false" permId="7" superUser="false"/> </user> <settings mediaServer="internal"> <thumbnail compress="normal" height="90" size="normal" width="120"/> <single compress="normal" height="480" size="normal" width="640"/> </settings> <theme author="Matt Magoffin" authorEmail="spamsqr@msqr.us" creationDate="2004-03-12T12:57:16.161" global="true" owner="0" themeId="-1"> <name>Default Theme</name> <comment>This is the default theme.</comment> <base-dir>inc/standard/default/</base-dir> <icon>thumbnail.png</icon> <preview>preview.png</preview> <xsl>album.xsl</xsl> <css>album.css</css> </theme> <album-crumb album="2002" page="0"> <name>2002</name> </album-crumb> <album-crumb album="200211" page="0"> <name>December</name> </album-crumb> <album albumId="200211" allowAnonymous="false" allowOriginal="false" owner="7" parentId="2002" posterId="1" sortMode="0"> <name>December</name> <item creationDate="2002-12-11T21:18:54.000" fileSize="740951" collection="1" height="1600" hits="1" itemId="1" tzName="GMT-08:00" width="1200"> <path>IMG_0900.jpg</path> <mime>image/jpeg</mime> <name>Yee haw</name> <meta>|aCanon|bCanon PowerShot S330|c6|d6|e2|f89</meta> </item> </album> </browse-data>
Example browse source XML

Media Album schema

The XML used by Media Album is defined by a set of XML Schema definitions. Check out the Media Album XML Schema Reference for detailed information about the XML objects used by the applicaiton. You can also browse the schema files (both the .xsd source and .html syntax-colored versions) to look at all the objects defined.

Theme XSL

The album XSL's job is generally to take album and browse XML objects and transform them into some representation of HTML so a person viewing the album or browsing the media collection can see the contents of it.

Header and footer theme XSL

For themes, some XSL is prepended and appended automatically by the Media Album application. This takes care of setting up the XSL stylesheet so that your theme only needs to define the XSL templates necessary to render the HTML.
<?xml version="1.0" encoding="utf-8" <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0" xmlns:ma = "http://msqr.us/xsd/MediaAlbum" xmlns:date="http://exslt.org/dates-and-times"> <xsl:import href="../../../theme-util-to-html.xsl"/> <xsl:import href="../../../../exslt/date.format-date.template.xsl"/> <xsl:output method="html" indent="yes" doctype-public="-//W3C//DTD HTML 4.01 Transitional//EN"/> <xsl:param name="user-agent"/> <xsl:param name="web-context"/> <xsl:param name="url-path"/> <xsl:param name="album-mode"/> <xsl:variable name="thumbCompress" select="/*/ma:settings/ma:thumbnail/@compress"/> <xsl:variable name="singleCompress" select="/*/ma:settings/ma:single/@compress"/> <xsl:variable name="thumbSize">t<xsl:value-of select="/*/ma:settings/ma:thumbnail/@size"/></xsl:variable> <xsl:variable name="singleSize" select="/*/ma:settings/ma:single/@size"/> <xsl:variable name="thumbMaxWidth" select="number(/*/ma:settings/ma:thumbnail/@width)"/> <xsl:variable name="thumbMaxHeight" select="number(/*/ma:settings/ma:thumbnail/@height)"/> <xsl:variable name="thumbMaxRatio" select="$thumbMaxHeight div $thumbMaxWidth"/> <xsl:variable name="rootAlbum" select="/*/ma:album[1]"/> <xsl:variable name="displayAlbumId" select="/*/@displayAlbum"/> <xsl:variable name="displayAlbum" select="//ma:album[@albumId = $displayAlbumId]"/> <xsl:variable name="item" select="//ma:item[1]"/> <xsl:variable name="user" select="/*/ma:user[1]"/> <xsl:variable name="ua-type"> <xsl:call-template name="get-browser-type"> <xsl:with-param name="ua" select="$user-agent"/> </xsl:call-template> </xsl:variable> <xsl:variable name="ua-platform"> <xsl:call-template name="get-browser-platform"> <xsl:with-param name="ua" select="$user-agent"/> </xsl:call-template> </xsl:variable> <xsl:variable name="ua-version"> <xsl:call-template name="get-browser-version"> <xsl:with-param name="ua" select="$user-agent"/> </xsl:call-template> </xsl:variable>
Theme XSL header, prepended to theme XSL
The custom album theme XSL will be inserted after this, and then the XSL will be automatically closed with the following XSL snippet:
</xsl:stylesheet>
Theme XSL footer, appended to theme XSL

XSL parameters

The header XSL defines several XSL parameters. They are as follows:
XSL param Description
album-mode
A constant representing an alternate view mode. If unspecified then the normal album slideshow mode is desired, otherwise this is used to show alternate modes like item metadata (in a slideshow). Supported values are:
browse
For browse mode (not really necessary since the root XML object is different for browsing than for slideshow).
item-meta
For displaying the metadata for a single item.
url-path The URL path used during browse mode for the current request. This is required to construct browse URLs within the same browse mode context (i.e. browse by date, browse by popularity, etc).
user-agent The complete HTTP user-agent header value. This (along with the ua-type, ua-platform, and ua-version shortcut variables listed below) is useful for rendering different HTML based on the browser platform of the user.
web-context The configured root web context used by Media Album. This is necessary to construct links to Media Album URLs.

XSL variables

The XSL also defines several XSL variables for convenience.
XSL VariableXSL TypeDescription
thumbCompress String
The compression setting to use for thumbnail images. The compression setting is passed to the Media Server to vary the compression of the thumbnails, and could be one of the following:
  1. none
  2. normal
  3. medium
  4. high
singleCompress String The compression setting used for single images. Single images are the "full size" images, usually viewed one at a time, for example by clicking on a thumbnail image. See the compression values for thumbCompress.
thumbSize String
The size setting use for thumbnail images. The size setting is passed to the Media Server to vary the size of the thumbnails, and could be one of the following:
  1. tsmall (80x60)
  2. tnormal (120x90)
  3. tbig (160x120)
singleSize String
The size setting use for single images. The size setting is passed to the Media Server to vary the size of the images, and could be one of the following:
  1. small (320x240)
  2. normal (640x480)
  3. medium (800x600)
  4. big (1024x768)
  5. huge (1600x1200)
thumbMaxWidth Number The maximum width in pixels thumbnail images are allowed to be. Used to help calculate appropriate thumbnail image widths and heights.
thumbMaxHeight Number The maximum height in pixels thumbnail images are allowed to be. Used to help calculate appropriate thumbnail image widths and heights.
thumbMaxRatio Number The ratio of thumbMaxHeight to thumbMaxWidth. Used to help calculate appropriate thumbnail image widths and heights.
rootAlbum Node The root album node. Since albums can be nested, this will always be the top-most album. This node could be used to construct a list of nested albums (if available).
displayAlbumId Number The ID if the album that should be shown. Since more than one album can be present in the XML, this is the ID of the album that should be shown to the user.
displayAlbum Node The album node that should be shown. This is the album node that will contain the <item> objects to display to the user.
item Node The first item node, which usually means the item that should be displayed.
user Node The current user node. The user node will only be present for logged in users.
ua-type String
A coded shorthand for the current user agent. Currently this will be one of the following:
  • ie (Microsoft Internet Explorer)
  • moz (Any Gecko-based browser: Mozilla, Netscape 6+)
  • unknown (Anything else)
ua-platform String
A coded shorthand for the current user agent's platform. Currently this will be one of the following:
  • win (Microsoft Windows)
  • mac (Apple Macintosh)
  • unknown (Anything else)
ua-version String A coded shorthand for the user agent's version. Currently this only works if the ua-type is ie or moz.

Media Server

The Media Server is the servlet that servers media items to client browsers. When you generate your HTML, you'll generate HTML <img> tags, for example, that have src attributes that point to Media Server URLs.
<img height="86" width="120" src="/ma/MediaServer?id=2&s=normal&c=normal" alt="Woa">
Example HTML Media Server <img> tag
You don't need to know how to generate these URLs, you smiply call the appropriate XSLT template (e.g. render-image-tag to render an <img> tag).

XSL predefined templates

Many templates are available for your theme which take care of rendering links to CSS or JavaScript objects, links to Media Server items (e.g. images), and many more. Visit the Media Album XSL Template Reference pages for more information.
$Id: theme-howto.html,v 1.1 2007/01/08 04:39:03 matt Exp $