Writing Themes

Creating Translations



I've spent thousands of hours developing Album Shaper. If you enjoy using Album Shaper, please send in a donation to show your support!

SourceForge.net Logo

Writing Themes

Themes allow you to cusotomize how albums look. They are completly configurable. Themes dictate what files are created, the layouts each page will have, what information is presented, and can optionally include various resource files such as button images, icons, and background images. In order to write your first theme, follow the instructions below:
  1. The first step when creating a theme is to create a new folder in the proper location for Album Shaper to find it. You should create such a folder using the name of the theme and place it in the themes folder. For example, if I wanted to create a new Nifty theme on Linux this would mean creating a folder:


    On Windows this will likely be:

    C:\Program Files\Album Shaper\themes\Nifty

  2. If you fire up Album Shaper at this point and try to save an album, you'll notice your new theme does not come up in the Save As dialog. That is because we havn't included a theme.xsl file in this new folder, and Album Shaper is clever enough to realize it wouldn't have a clue how to apply this theme.

  3. Clearly the next step is to start populating this new folder with various files. Themes need only one file to work, theme.xsl, but several other files can supplement this one and further enhance your theme. It's strongly suggested you include a desription.html file. This file is used to provide a short descrition of your theme in the Save-As dialog, and should include the theme's name and version number, followed by the author name and his/her contact info, followed by a short description of the theme. For example:


    Nifty v1.1<br>
    Joe Smith, jsmith@gmail.com<br>

    This theme is perfect for creating nifty collections of photos to share with friends and family. Limited photo information and web optimizied slideshows make viewing photos easy.


    The Save-As dialog also provides a theme author the ability to show off his/her themes in a variable number of preview images. If you want to include preview images with your theme place these images in the theme folder and name them preview1.png, preview2.png, etc. These images need to be in the png format, and 400x250 in resolution. You can have as many as you want, but they must start with preview1.png and not skip numbers.

    Finally, if you wish to include resource files with your theme you can create a resources folder in your theme folder and put any such miscellanious files in there. When using your theme to export an album, a copy of the resources foler will be exported with the album, thus all image links should be relative links to this folder, for example <img src="resources/button.png">.

  4. If you try to use your theme as this point, you will be able to select it, read its description, flip though its preview images, but when you hit save an error will occur. That's because you've included a theme.xsl file, but it's blank. This generates an error because we obviously havn't included enough information as to how to write out the files we wish to generate. When exporting an album, Album Shaper first saves out the images and album XMl file, and thus if something goes wrong you'll never lose your work, you may just not have any HTML files to show just yet.

  5. Before we begin writing our theme, it might help to have a bit of background on what we are doing. Album Shaper themes are written in a language called XSLT. XSLT is a language for translating XML documents into other documents. It is often useful to translate from one XML schema to another, and in fact Album Shaper does that in order to update older albums prevous to version 1.0a3. Anyways, let's get back on track. XSLT is an interpretated language, and just so happens to be written in XML format itself. If you want to learn more about XSLT I suggest you pick up a copy of XSLT Programmer's Reference by Michael Kay. It's not too expensive and has a slew of information in there. It's how I learned XSLT, and while I can't say I've read it cover to cover, it certainly proved very useful while learning XSLT and coding up the first themes for Album Shaper. Since XSLT is a large and complicated language, I don't think I'll attempt, and fail, to explain it all here. Instead I'll let you pick up a book or read online from the numerous resources availble. In order to get you up to speed on XSLT though, I'll walk you though a simple example of using it in a Nifty theme, after which you're on your own!

  6. Let's being our theme. Open up theme.xsl in a text editor and begin the file with:

    <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">

    We have now declared that what follows is a stylesheet. At this point I think we'll need a bit more background again. XSLT works by applying stylesheets to XML input files. In our case the XML input file is the Album.xml file Album Shaper writes out with your album. This file contains all annotation and organization information for your album, and we can write xslt code to match against these various files in order to print out html as we see fit. To begin, let's match against the album node of the XML file.

    <xsl:template match="album">

    Since the input XML file has only one album node, the following code will be run only once, and at this point we no have access to all the children nodes of the album root node. Before we continue we should now create a HTML file. You can name your files whatever you want, although it's customary to make your top level HTML file Album.html, and so we will do that here.

    <xsl:document method="html" indent="yes" href="{concat($outputPath, '/Album.html')}">
    <meta name="generator" content="Album Shaper (c.) Will Stokes"/>
    <title><xsl:value-of select="name"/></title>

    The first line there created a new Album.html file in the output directory. You'll notice we do this by contating the input variable outputPath with the filename to get the full path. We also began the HTML file and included a reference to Album Shaper as the generator with a meta tag. If you would like your theme to be include on the Album Shaper web site including this meta tag is a requirement. Next we set the title of the page to the name of the album. You'll recall that I said we now had access to the various subnodes of the album root node once we matched it in the beginning. The name of the album is stored in a name subnode of the album node, and we reference it using the xslt command <xsl:value-of>. Finally we began the body element of the HTML file, and thus we'll now continue with including the body of the page. In this simple example, we'll create a HTML file that is simply a series of slideshow sized images with subalbum names and descriptions separating photos from each subalum.

    <xsl:for-each select="subalbum">
    <xsl:value-of select="name"/><br>
    <xsl:value-of select="description"/><br>
    <xsl:variable name="subalbumNumber" select="position()"/>
    <xsl:for-each select="photo">
    <xsl:variable name="photoDescription" select="description"/>
    <a href="img/{$subalbumNumber}/{position()}.jpg">
    <img src="img/{$subalbumNumber}/{position()}_thumb.jpg" alt="$photoDescription"/>

    Finally, we must complete our theme by ending the body and html tags, as well as the document as a whole.


That's it! That is your first theme. Very trivial, but it makes use of most of the information provided in the album. To see how you can do more take a look at the Slick theme. It makes use of most of the information stored in an album's XML file, creates multiple documents, and splits up the work over multiple xsl files. This documentation is my first run through. If you have questions send me an email, I'll get back to you and post all such questions and answers online for all to see. Good luck!

Copyright © 2003-2005 Will Stokes