A common technique for displaying photos is to use what has come to be called a "lightbox," which is a pop-up window that displays a larger image when the visitor clicks on a thumbnail image. This is much more satisfying than linking directly to the full-size image, which would display the image in the browser but without any of the site's navigation or visual wrapper.

Because all of the hard work has been done by jQuery plugin authors, creating this effect is simple. There are many such plugins available; for this example, we've used Leandro Vieira Pinho's jQuery Lightbox.

Creating the HTML

First, here's a minimalist example of the HTML code:

<div id="photos">
  <w:assets:each tag="gallery">             
    <a href="<w:path rendition='medium' />">
      <img src="<w:path rendition='thumb' />" />
    </a>
  </w:assets:each>
</div>

This code first creates a div with an ID that we'll use in a moment to trigger the lightbox JavaScript code. Inside that div we want an img tag for each of the images, each linked to the large image. Without the lightbox plugin, this would display the large image in a bare browser window, but when the plugin does its magic it will trigger the display of the lightbox pop-up.

In this example, we've used the WebvantaScript w:assets:each iterator to loop through all of the images with the tag "gallery". You could use a category just as well to specify which images to load. And if you are in the context of a database item that has related assets, you could access the images associated with that item.

Note that we've specified a rendition size of "medium" for the large image. You could eliminate the rendition specification entirely here if you wanted to load the original file, but by using a rendition you gain control over the size of the large image. Now the site editors can simply upload an image of any size, as long as it is large enough, and you'll get a sensible display and reasonable download times.

Setting up the JavaScript

Next, you need to load the jQuery library (which you are probably loading already, so we've not included it in the code below), and then load the plugin code. Finally, in a "document ready" block (so the code is not executed until the HTML document has loaded), just call the lightBox function on the element that contains the photos.

<script type="text/javascript" src="/js/jquery.lightbox-0.5.min.js"></script>
<script type="text/javascript">
  $(document).ready(function(){  
    $('#photos a').lightBox();
  });
</script>

This code assumes you have created a folder "js" and uploaded to it the lightbox JavaScript file (which you can download here).

This code should go in the head section of your page.

Note: if the element that contains your image links has an ID other that "photos", be sure to change "#photos" in the jQuery code above to match.

And Finally, the CSS

Now you just need to provide some CSS for styling. Start with the CSS code you'll get in the download referenced above. Copy the contents of the file jquery.lightbox-0.5.css to your system clipboard, and then go to Structure > CSS and create a new css file called lightbox.css and paste in the CSS code. (Or you can simply upload the CSS file via Content > Images & Files, but that makes it harder to edit.)

Finally, add a link to the CSS file in the head section of your page:

<link rel="stylesheet" type="text/css" href="/lightbox.css" />

If you are using the default Webvanta starter site code, you'll need to change the z-index settings in several places in the CSS file. Our drop-down menu code has high z-index values to ensure that it sits on top of any site content, and you'll need the lightbox elements to have even higher values so the lightbox overlays the menu. A simple approach is to add 10000 to all of the z-index values in the lightbox CSS code.

You should now be all set.