Building a photo album with the Spry framework

Additional Requirements

To complete this tutorial you will need to install the following software and files:

Spry framework for Ajax

• Download Spry

Optional: Dreamweaver

• Try
• Buy

This tutorial describes how to incorporate the Spry framework into a static HTML page in order to create a dynamically generated web photo album. The Spry framework allows users to dynamically load and incorporate XML data into an HTML page with a minimal amount of markup. After developing the functionality of the photo album, CSS is used to create a variety of different layouts for the same basic HTML page.

In this project, the index page of the photo album will display both the thumbnails and the first large image. When the user clicks on a thumbnail image on the index page, the corresponding larger version of that image will display in place of the first image. Traditional web photo albums usually consist of several static web pages, (usually one page per image in the album) along with the images themselves. These pages are usually identical with the exception of their URL, which changes depending on the current large image being viewed. In a traditional photo album, when the user clicks on a thumbnail, (or clicks the next or previous button) on one of the album pages, a completely new HTML page is fetched and loaded into the browser to display the next image. This tutorial uses a different convention—rather than updating the whole page, only the new larger image is reloaded via Ajax. This approach provides a faster display of the images and results in a smoother user experience when reviewing the photos. The Spry framework is very helpful in this situation, because it makes it possible to create a very flexible page that dynamically displays images using only a few lines of code.

If you haven’t already, download the source files for this tutorial and uncompress the zip file. The sample file folder contains the following:

• Spry data framework and xpath.js files
• XML file containing image information: photos.xml
• Sample photos listed in the XML file, including thumbnails
• Completed version of the photo gallery: gallery_finished.htm

The Spry framework

The Spry framework is a JavaScript library that contains all the functions needed for using XML data on the photo album page.

Here’s a list of terms that will be used in this tutorial:

• Data set: A JavaScript object that contains a flattened table-like representation of XML data.
• Dynamic region: A region of a web page that is bound to one or more data sets and has the ability to regenerate itself as the data in the data sets is loaded or changed.
• Data reference: A reference to data from a specific data set inside a dynamic region. As the dynamic region regenerates itself, these data references are replaced with actual data from the data set. Data references are denoted in dynamic regions with curly braces of the form like this: {dataSetName::columnName}. If a dynamic region is bound to only one data set, data references can use the short hand notation instead: {columnName}

It is important that you are familiar with these terms and concepts to follow along with this tutorial. Now let’s start the project.

We’ll begin by creating the basic structure of the photo album page. Our HTML page will consist of a <div> that contains the thumbnails and another <div> that contains the main image. If you haven’t already, now is a good time to review the finished version of the project (open gallery_finished.htm from the sample file folder) to get a better understanding of how this will work.

Note: The steps outlined in this tutorial assume you are working with Dreamweaver 8. If you are using another editor, make sure that the code you write looks similar to the sample code provided below. If you create your version of the photo album page and save it into the sample file folder, the provided CSS file will give your page a basic layout. Follow the steps below to create the HTML page for the photo album:

1. Download the sample files. Uncompress the folder to access the files.
2. Launch Dreamweaver. Create and save a new HTML page, taking care to save the file into the same folder that contains the sample files. Name your file 'gallery.htm'. Use the Split View setting (select View > Code and Design), so that you can refer to both the code and design windows as you follow along with these instructions.
3. Choose Window > Insert to access the Insert panel. It is displayed at the top of the program. From the drop-down menu on the far left, choose Layout, instead of the default setting (Common).
4. Next, click the Draw Layer button (the third button to the right of the drop-down menu).
5. In the Design window, click and drag to draw a layer on the left half of the page. This is the <div> that will hold the thumbnail images. The layer you draw should take up most of the left half of the page. Don’t worry about the exact proportions now, because the layer can be resized later as needed. Select the layer by clicking on its "handle" on the upper left corner.
6. While the layer is selected, access the Property inspector. (If it is not already displayed, select Window > Properties). Select the text in the field that says "Layer1" and type in the new Layer ID name: thumbContainer
7. Click on the Draw Layer button again and draw another layer on the right side of the page. This is the <div> that will hold the larger image. Click the "handle" of the layer to select it, then, in the Property inspector, set this Layer’s ID name to: main
8. In the Title field at the top of the page, type the page title: Ajax Album Demo

After completing these steps, review the tags in the Code window. Your HTML should look similar to the code below:

You may see some slight differences in your code, primarily due to the exact positioning of your two <div> layers and settings you’ve selected in your Dreamweaver preferences. It is not imperative that your code looks identical to the example shown above.

Note: If you wish to use the exact HTML code from this tutorial, simply copy the code example above, then select all the code in the Code window of Dreamweaver and paste the tutorial code over it.

Now that we’ve created the HTML page, it is time to set up the dynamic functionality using the functions available in the library of the Ajax framework.

After building the HTML page, the next step is to add the Ajax script to the project. We’ll start by adding the XML data set. But before we’re ready to do that, let’s take a look at the XML data and get a feel for how it is used.

Open the photos.xml file in the source files folder using Dreamweaver. If you study one node of the XML file, you will see the following tag:

Notice that the 'photo' XML node contains all the basic information needed for an HTML <img> tag. You will use this data to dynamically build a series of HTML <img> tags that will display in the album.

Defining the data set

The first thing we need to do is link the sprydata.js and xpath.js files to the gallery.htm file you’ve created.

1. Type the following code into the <head> section of your HTML in the Code window:

Note: If you've moved the xpath.js and sprydata.js files into a subfolder within the sample files folder, make sure that the src path matches your project's folder structure.

Now we are ready to create the data set. This is accomplished using a JavaScript call to the sprydata.js file. Follow the steps below:

2. In the <head> section of your HTML page, add a <script> tag. Type the code below to add the JavaScript call that will create the data set.

If you haven't already, now is a good time to save your file.

Check your progress so far by taking a look at your Code window and comparing the code with the entire HTML page example below:

The code we've just added between the <script> tags creates a variable called 'dsGallery', which is the name of the data set. "Spry.Data.XMLdataset" is the function that creates the data set. The file "photos.xml" is the name of the XML file that contains the photo data. The part "gallery/photos/photo" describes the path within the XML where the actual data starts. This data set section of the code represents the first three tags in the sample XML node we reviewed. This means that the data for the data set begins within the <photo> node in the photos.xml document.

Surprisingly, that is all the script we need to add to define the data set!

Adding data bindings

Now that we have defined the data set, we can add data bindings to the HTML page. We'll start by adding the thumbnail images to the 'thumbcontainer' <div> we created earlier.

3. Insert an image tag within the thumbcontainer DIV, by typing the following between the <div> tags: <img src="">
4. Next, add the data reference for the image URL to the src attribute, as follows:

The 'src' field points to the thumbnails folder and then pulls in the XML value of the 'thumbpath' attribute in the XML file. This will complete the path to the thumbnail image. The @ symbol is used before the name because the value is an attribute of the image tag. For example, to link to an image file called "foo.jpg" from <image thumbpath="foo.jpg">, use this syntax: {@thumbpath}. This is different than typing a value of a tag, which would be: <thumbpath>foo.jpg</thumbpath>. This would be written as {thumbpath} without the "@".

The thumbnail image is now set. Now we'll set the images to repeat by adding a 'spry:repeat' attribute to the thumbnail image tag. This will cause the image tag to repeat over the entire data set.

5. Inside the thumbnail <img> tag, add the following 'spry:repeat' attribute:

6. Locate the 'thumbContainer' <div> tag, and add the following 'spry:region' attribute:

7. Next, find the 'main' <div> tag and add a 'spry:detailregion' attribute:

At this point, your code should look like the example below:

In the two <div> tags, the 'spry:region' attribute tells the Ajax framework that each <div> layer contains dynamic data.

The 'spry:repeat' attribute in the <img> tag tells the dynamic region that it should create an image for each row in the dsGallery data set. This results in the page generating an image for every thumbnail in the data set.

Now, when you choose File > Preview in Browser, all the thumbnail images are displayed in the page.

Setting up the main image display

This next part will look very familiar, because it is very similar to the step we just completed.

8. In the 'main' <div> tag, add an image tag. Also add code to display the image name underneath the main image, as shown below:

Notice that the only difference in this code from the thumbnail code is that we are using {@path} instead of {@thumbpath}. Since these values are identical in the XML files, we could use either one—but for the sake of clarity and best practices, we'll use the correct attribute.

The basic photo album functionality is now set up. Choose File > Preview in Browser again and you will see the page display the first main image and all of the thumbnail images. However, if you click the thumbnail images, nothing happens. Our goal for this next part is to add the functionality that when the user clicks on a thumbnail image, the corresponding larger version of that image will update the main <div> area. To do this, we need to establish a relationship between the thumbnail images and the main image, as shown below:

9. In the Code window, add a 'spry:setrow' attribute to the thumbnail <img> tag:

Here's an example of how your HTML code should look now:

Let’s take a look now, and see what is happening:

When the user clicks on a thumbnail, the spry:setrow attribute tells the browser to set the RowID of the data set as the CurrentRow. The 'spry:detailregion' attribute is updated with this value and that in turn updates the path of the main image with the image name from that node ID in the XML file. The new main image is now displayed.

When you preview your page in a browser, you’ll see that the photo album works quite well now in terms of functionality, but the thumbnail images are displaying in an disorderly fashion along the top of the browser window. Do not worry about the layout of your HTML page, we’ll address that in the next section of this tutorial.

We’ll use some CSS code to restrain the thumbnail images so that they display correctly. We can achieve this by adding a float rule and size rules for the thumbnails, so that the thumbnail images are constrained within the thumbnail container <div> tag.

1. Locate the style tag in the <head> section of the HTML document. Add the following CSS:

The 'float:left;' code forces the images to stay within the thumbnail <div>. The height and width values define the size of the thumbnail image. Feel free to adjust or remove these values for your specific needs, but be aware that specifying a consistent height and width value causes the block of images to display in a pleasingly uniform manner, even though some of the thumbnail images may be slightly stretched.

2. Next, find the thumbnail image tag, and add a class attribute with a value of "thumbs", like this:

Here’s an example of how the code should look now:

Preview your page in a browser and verify that the images are constrained within the <div> areas properly—causing the images in your photo album page (gallery.htm) to display like the completed version of this tutorial (located in the sample files folder). To compare, open a new browser window and choose File > Open File and navigate to the gallery_finished.htm file to view the pages side by side.

After following the steps in this tutorial, you can see how easy it was to create a fully functional and good looking photo album…using only a few lines of code. The beauty of this design is that it is very flexible and can be adapted to suit your project. Try moving and resizing the <div> containers to create different page layouts. Use more CSS to add further styling to enhance the look and feel. If you update your XML file with descriptions or metadata about each image, these captions can be displayed as well. Try adding the height and width data to the page. See what it looks like when you change the height and width of the thumbnails.

When preparing the sample files for this tutorial, I used Photoshop CS2 to generate a Flash style web photo gallery. After exporting the gallery, I copied the "thumbnails" and "images" folders and the photos.xml file and used them for this project. When building your own photo album, you can use Photoshop CS2 to create your own files and use them as shown in this tutorial. If you followed the steps closely, you should be able to simply replace the images and the XML file with the files you created in Photoshop and it will display correctly with your new images. Just make sure that the naming conventions and folder structure is the same when you copy the files, or else update your XML and HTML page to reflect your site’s structure.

Note: The current version of the Safari browser has a known issue regarding renaming nodes that causes the photo album page to display incorrectly unless a workaround is implemented. If you are creating the site for Safari users, it is necessary to update your XML file slightly for the photo album to display correctly. The issue occurs because the Safari browser will convert an XML node named 'image' into an actual <img> tag! If you encounter this issue, update your XML file by changing the <image> XML node to something different, like <photo>. After making this change, your XML file would look similar to this:

For the purposes of this tutorial, I’ve already converted the XML <images> and <image> nodes so that this code will work in all browsers. But keep this renaming issue in mind, if you are seeing an odd display when previewing your future photo albums using the Safari browser.

Taking the project to the next level

As it is now, the album is fully functional and will work well for almost users. However, for simplicity's sake, I hard-coded some of the values directly into the HTML page, that could have been handled more flexibly by specifying this information in the XML; specifically, for the purposes of this tutorial, the folder paths to the image files are hard-coded. If you’ve investigated the files, you may have noticed that this folder information is already in the XML file, but stored as tags in the <gallery> node, at the very root level of the XML. For practice, you can try making this code more versatile and reusable by swapping out the hard coded values in the HTML into the nodes of the XML file. There are many other data points in the file that can be used to further polish the album. In order to use this data, you will need to create another data set.

Multiple Data sets

If you stop following along with the tutorial right now, you have a fully functioning photo album that you can update by changing the CSS styles (as needed) and you can create new galleries by generating new images, thumbnails and XML files. If you want to continue with the tutorial, we will add a second dataset and add some of the album information to the top of the page.

I mentioned briefly at the start of this tutorial that multiple data sets can be used in a single page. Creating a second data set for the photos.xml file will give you access to the extra data. Once this is accomplished, you can easily display the data on the page. Notice that in addition to the folder paths, other data points such as font, color, border, photographer name and date are also included in the file by default. The values in the XML file can be edited or changed. The nodes can also be expanded as needed. For instance, a 'description' attribute can be added to each image node to include a caption for each image. After adding this attribute, you could use the description attribute (instead of the image name) to display beneath each main image.

The Photoshop CS2 Web Album feature allows for the setting of other metadata points as well. Let’s take a look at how this works:

1. Create a second data set in the head of the document. This will be similar to the first data set, except the XML folder path will only point to the root of the XML. The name of this new data set is 'dsData'. See the highlighted code below:

After adding this new data set, you are now ready to make use of these new data points in the album. Start by replacing the hard coded image folder paths to the values used in the XML file, as described in the steps below:

2. In the thumbnail 'src' path, remove the 'thumbnails/' and replace it with the XML value. Make sure to remove the forward slash, since that character is already stored in the XML value for the path.
3. Repeat step #2 for the main <img> tag. Remove the 'images/' part of the path from the 'src' field and replace it with the XML value.
4. The next part involves telling the dynamic region that you will be using the data from the new data set. Add the data set name to the spry:region attribute, separated by a space, as shown in the code example below:

To understand how to specify the dynamic data, here’s another example:

Instead of using: {dsData::large/@base}

You could also think of it this way: {dataset::XMLTagName/@XMLTagAttribute}

At this point, we’re ready to add the site information to the top of the page.

5. Draw a new layer <div> on the page. Position the layer as you wish. In the finished version of this project in the sample files, I placed the <div> at the top in the center of the page. Name the new <div> layer 'header'.
6. Designate that the new layer is a spry region by adding the spry:region attribute. Bind the 'dsData' dataset by setting it as the value of the spry:region, as shown in the code below:

Now we can add dynamic values to this region. In the XML file included with the sample files, the following values are available:

• Site Name
• Photographer
• Contact info
• Email
• Date

Add these values to the document so that they display as part of the album. Since there is only one data set bound to this region, the simple {tagname} syntax can be used. The only exception to this is the data, which is an attribute of the <gallery> tag.

7. For each value above, create a new label and enter the dynamic value for that label: Site Name: {sitename}. Remember that attributes of a tag are denoted like this: {@attributeName} Update your code as shown with the highlighted tags below:

Preview your page in a browser and double-check that this new header data is showing up correctly.

For the final step, we’ll make the website and email values real hyperlinks.

8. Wrap the {contactinfo} field in an <a> tag and set the href attribute to: {contactinfo}.
9. Also wrap the {email} text in an <a>. Set the href attribute to: mailto:{email}

   Your final HTML page should look like this:

Preview your page in a browser and verify that the links in the header are working.

Congratulations! You have successfully created a Spry web photo album using only 60 lines of code—primarily CSS!

Using the Spry Framework and some simple markup, you’ve seen how you can create a dynamic photo album. With some slight variations, you can use the same techniques described in this tutorial to create a wide variety of web pages. For example, you could create a page that displays dynamic text instead of images. With just a few more steps, you can loop over a table’s <tr> tag to make a dynamic table. Spry also makes it easy to dynamically populate form elements. Once you give it a try, you’ll find that the Spry Framework provides excellent site functionality with clean markup. By adding Ajax to your site, you can develop pages that are flexible and easily updated. The possibilities are endless and limited only by your imagination.