Create your first skin

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

Before you get started it's recommended that you learn the basics of jAlbum skin development by checking out the skin introduction tutorial.

InstallMyFirstSkin.jpg
Installing the "MyFirstSkin" skin in the jAlbum application

When creating a new skin for jAlbum you usually never start from scratch, instead you take an existing skin and base your new skin on that. The jAlbum application has a built in feature that let's you create a new skin based on the "Minimal" skin. To find this feature select "Tools", "Skin developer" and "Create new skin" from the menu.

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

EditSkinFiles.jpg
Launching the jAlbum Skin editor from the "Tools" menu

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.

You can also use the keyboard shortcut Ctrl+Shift+E (or Cmd+Shift+E if you're on a Mac) to launch the Skin editor.


Add rows and columns

MyFirstSkinAddTable.png
Adding a table of images using <ja:rowiterator> and <ja:coliterator>

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 two of jAlbum's special "iterator tags" <ja:rowiterator> and <ja:coliterator>. These tags repeat their content for each row or column that is to be created.

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

<table>
    <ja:rowiterator>
      <tr>
      <ja:coliterator>
        <td>
          <a href="${closeupPath}">
              <img src="${thumbPath}" style="width:${thumbWidth}px; height:${thumbHeight}px;"/>
          </a>
        </td>
      </ja:coliterator>
      </tr>
    </ja:rowiterator>
</table>


The iterator tags will create a HTML table with all the thumbnails in neat rows and columns.

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 style attribute uses two variables, ${thumbWidth} and ${thumbHeight}. These variables will be replaced by the actual size of the image.

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 containing the image tag.

${variableName} is the naming convention for all jAlbum variables.


Take it for a test drive

MyFirstSkin.jpg
Previewing the very first album built with your new skin

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.

Try to change the Columns and Rows settings on the Pages tab of the jAlbum settings window, and then hit Make Album again. Notice how the layout of the album changes? This is the <ja:rowiterator> and <ja:coliterator> in action!


Add an album title

MyFirstSkinAddTitle.jpg
Giving your album a new 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 table 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.

Did you notice that the skin were already using the ${title} variable inside the title tag in the templates head section? This means that the title you entered also will be used as the web browsers window title.

What about image titles and captions?

MyFirstSkinTitleOnSlides.png
Making image titles visible on the slides page

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 and add the following line of code above inside 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).

Learn more about the ${title} variable and rest of the variables available here. You can also list all jAlbum variables and their explanation in the editor by pressing Ctrl+Space. If you've already started typing a variable name, pressing Ctrl+Space will complete the name.

MyFirstSkinComments.png
Adding an image caption below the main image

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.

You can learn more about the <ja:if> tag and the rest of the tags here.

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

Adding navigation

MyFirstSkinAddNav.png
Adding navigation buttons to the slide page

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).

To explore the content of a skin select "Tools", "Open directories" and "Open skin directory" from the menu, or use the keyboard shortcut Ctrl+Alt+S (or Cmd+Alt+S if you are a Mac person).

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.

The full content of a skin's "res" folder is copied to the generated album.

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.

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!

sample album 4.jpg

Done! What's next?

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

Firstskin error.png

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].

If you ever get stuck during skin development don't forget that we have a friendly forum filled with experienced skin developers that are happy to help out. The system console provides a place to test code and get full error messages (click the small black warning triangle to open the system console).