I've spent thousands of hours developing Album Shaper. If you enjoy using Album Shaper, please send in a donation to show your support!
|
|
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:
- 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:
/usr/local/share/albumshaper/themes/Nifty On Windows this
will likely be: C:\Program Files\Album Shaper\themes\Nifty
- 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.
- 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:
<html><body>
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.
</body></html>
|
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">.
- 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.
- 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!
- 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')}">
<html>
<head>
<meta name="generator" content="Album Shaper (c.) Will Stokes"/>
<title><xsl:value-of select="name"/></title>
</head>
<body>
|
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">
Collection:<br>
<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"/>
</a>
</xsl:for-each>
</xsl:for-each>
|
Finally, we must complete our theme by ending the body and html tags, as
well as the document as a whole.
</body>
</html>
</xsl:document>
</xsl:template>
</xsl:stylesheet>
|
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!
|
