This tutorial will teach you how to create your very own jAlbum skin, but you will also learn how to:

• understand the basics of jAlbum code syntax for variables and tags
• layout images in a table on the index page
• add titles and captions to index and slide pages
• work with "next" and "previous" buttons

Getting started

When creating a new skin for jAlbum you can start from scratch or base your new skin on an existing skin. The jAlbum application has a built in feature that let's you create a new skin based on one of the installed skins. To find this feature select "Tools", "Skin developer" and "Create new skin" from the menu. Then give your skin a name and select the skin you want it based on, your new skin is installed and ready for editing.

In this tutorial we will however not use this feature. Instead we will base our new skin on a sample skin called "MyFirstSkin". Click this link to download the skin and choose to open the file (do not choose to "Save on computer"). jAlbum will then notify you that it will install the skin.

Launch the jAlbum Skin editor

In the skin introduction tutorial you learned how to edit an existing skin, but in case you forgot, this is how you start the jAlbum Skin editor:

Make sure that you have select "MyFirstSkin" in the skin selection box. Then from the menu, select "Tools", "Skin developer" and "Edit skin files". This will open the relevant skin files for editing.

• index.htt is the template file for index pages
• slide.htt is the template file for slide pages

Remember that these files are basically HTML files containing some special jAlbum variables and tags. You are about to learn how to use some of these available variables and tags in a skin.

Add thumbnails

Start by selecting the window showing the "index.htt" file. As you can see this template is rather empty, so let's fill it up with some images!

It's time to get aquainted with one of jAlbum's special "iterator tags" <ja:fileiterator>. This tag repeatedly processes the code within it, once for each object in your project.

Now, let's write some code! In the body section of the index template insert the following snippet:

<ja:fileiterator start="0">
  <a href="${closeupPath}">
    <img src="${thumbPath}" width="${thumbWidth}" height=${thumbHeight}" alt="${thumbPath}">
  </a>
</ja:fileiterator>

The iterator tags will create a HTML table with all the thumbnails lined up one after the other, wrapping if the screen width is too small to fit them all on one line.

The thumbnail image tag has a couple of attributes that we're going to take a closer look at.

• The src attribute uses a variable called ${thumbPath}. When the album is generated this variable will be replaced with the path to the generated thumbnail image.
• The width and height of the thumbnails uses two variables, ${thumbWidth} and ${thumbHeight}. These variables will be replaced by the actual size of the image.

There is also an 'alt' tag which provides alternative information should the image not be display or if the visitor is using a screen reader. It uses the thumbPath variable, but you can use any of the appropriate jAlbum variables for an alt tag.

In the code snippet above we also link the thumbnail images to the corresponding slide page. This is done using another jAlbum variable, ${closeupPath}, in the href attribute of the anchor tag that contains the image tag.

Your index.htt code should now look like the below image

Take it for a test drive

Save your changes and close the editing windows. It's time to make your first album with your new skin!

Make sure that you have added some images to the jAlbum application and that "MyFirstSkin" is still selected in the skin selector box. Now hit the "Make jAlbum" and sit back as jAlbum lets your skin work its magic. When the album has been built, hit "Preview". The result should look something like the example to the right.

Add an album title

In the quick introduction tutorial we added a title to the index page. Now we are going doing to do the same thing in this skin, but this time, instead of just writing the full title inside the template file we are going to make the title customizable using a variable.

Once again open up the jAlbum Skin editor and select the "index.htt" editing window. Enter a new line above the fileiterator code we previously added and insert the following line of code:

<h1>${title}</h1>

When you are done save your changes and go back to jAlbums main interface by clicking the main window (this way you can leave the editing windows open in the background if you want to). Open up the General tab of your album's settings window and give your album a nice title.

When you are done, press Make Album again and notice your new title appearing above the photos on the index page.

Your index.htt code should now look like the below image

What about image titles and captions?

So far we have concentrated our efforts to the index page, but now it's time to touch up the slides pages as well. From jAlbum's editing interface you can add titles and captions to your images, wouldn't it be nice if those texts appeared in your album? Open up the "slide.htt" editing window, it should look like this:

Add the line of code below inside of the body section (it's actually identical to the code we used to add the album title):

<h1>${title}</h1>

In this case the ${title} variable will pick up the value added in title field in bottom right corner of the jAlbum application. If no title has been specified the variable will pick up the file name of the image instead (but the file extension, like .jpg will be stripped).

From the editing interface you can also add an image caption (in the field below the main image), so let's add support for that as well! To fetch the image caption we use the ${comment} variable. So if we wanted code that simply added a caption it would look like this:

<p>${comment}</p>

However we only want to add the caption code for images that actually has a caption. So we will have to modify this code slightly, but before doing so it's time to introduce another one of jAlbums special tags, the <ja:if> tag.

This tag is used to test for a certain condition and can be used to make your template produce slightly different results depending on if the condition specified is met or not.

That may sound a bit complicated, but it's actually rather simple, so let's take a look at an example instead:

<ja:if test="true">This text will be included in the album.</ja:if>
<ja:if test="false">This text will NOT be included in the album.</ja:if>

In this example the first tag will see its condition met and the second one will not. Therefore only the content specified within the first tag will end up in the generated album.

Now that you are familiar with <ja:if> tag, it's time to add some captions! First look for a suitable place to put the caption (below or above the image?). Then insert the following code:

<ja:if exists="comment">
    <p>${comment}</p>
</ja:if>

We have now modified the first caption inclusion code to add a <ja:if> tag with a condition that is only met if the ${comment} variable exists. This means that the content inside the tag will only be added to the generated album if a caption has been entered for the specific image being shown.

Before we continue, it's good idea to save your changes and to remake your album to see your changes take effect.

Adding navigation

Your new skin is coming along nicely, but there's still one major flaw that we should deal with. There's no way to navigate between slide pages, and there's also no way to go back to the index page when you are on a slide page! So as a final step of this tutorial, let's add some navigation.

Let's start with a "back to index page" button. To get one we need to add a link back to the index page on the slide page. To reference the index page we use the ${indexPage} variable, like this:

<a href="../${indexPage}">Back to index</a>

That takes care of the actual link, but it would look a lot better if we had some kind of button image to use instead of just a text link. Fortunately the skin that you based your new skin on comes with a couple of buttons that we can use (take a peek inside the skin's "res" folder to see all the resources that's bundled with the skin).

Here's a modified version of the code that produces the link back to the index page:

<a href="../${indexPage}"><img src="${resPath}/home.png" alt="Back to index" title="Back to index" /></a>

Notice that we are referencing the "home.png" in the "res" folder by using the ${resPath} variable. This variable can be used to refence any resources found in a skin's res folder. jAlbum albums can contain subfolders, by using ${resPath} you are ensured to always get a link to the one single res folder.

Now we are almost done! All that's left is to add the "next" and "previous" slide links. It should be fairly easy, but there's two scenarios that we need to consider. The first slide page doesn't have a "previous slide", and the last slide page does of course not have a "next slide", so we need to add some kind of test to handle these scenarios. Again, or old friend the <ja:if> tag comes in handy:

<ja:if exists="previousPage">
    <a href="${previousPage}"><img src="${resPath}/previous.png" alt="Previous image" title="Previous image" /></a>
</ja:if>

<a href="../${indexPage}"><img src="${resPath}/home.png" alt="Back to index" title="Back to index" /></a>

<ja:if exists="nextPage">
    <a href="${nextPage}"><img src="${resPath}/next.png" alt="Next image" title="Next image" /></a>
</ja:if>

This code snipped shows a fully implemented navigation where the "Back to index" has been complemented with "Previous image" and "Next image" buttons. To generate these buttons we use the variables ${previousPage} and ${nextPage}, and we also use <ja:if> tags to make sure that these variables exists before adding the buttons. Put this code within the <div class="navigation"> tag in the slides template.

Your slide.htt code should look like the image above (adding navigation buttons to the slide page).

Now, let's save the changes and remake the album, to be able to see your skin in action and to enjoy the result of all your hard work!

Done! What's next?

Before going further lets introduce an error and see how to debug it!

Open the index.htt file in the editor again and at line ten enter

<ja:if test="true">
This is an error because 
there is no 'end-if' tag

Save the change and then try to make the album again. The result will be an error message as shown, note too the small warning triangle at the bottom right of the main window. Click on the small triangle to the left of 'Error details (click to reveal)' and you will be given details of the error

Stack trace for jAlbum 13.8 using skin MyFirstSkin:
se.datadosen.tags.ElementException: 
Element ja:if has no matching ending tag (index.htt:10)

The error has been identified and the location and line number given, index.htt line ten. Now click on the 'Edit skin' button and the file with the error will be opened with the cursor will be at the start of the line with the error. Remove the lines added to cause the error, save the changes and the album will again make without any errors.

Congratulations you are now a Level 1 jAlbum skin developer :)

Now that you have created your first skin you can either return to the skins section of the Developer Center to look for ways to improve your skin even further, or you can choose to learn how to upload a skin to jalbum.net.