If you've been reading the blog, you've probably ready fatgeorge's implementation of the lightbox. Well, I decided DNNDev.com needed a good lightbox demo to showcase how easy it is to use XMod 5.0 with other solutions. In other words, I'm happy to say I didn't write all the lightbox code. Instead, I leveraged XMod's built-in abilities to easily integrate third party libraries. This saved me a TON of time trying to figure out how to build a lightbox. All I had to do is plug-in my XMod data and I was done. This worked great on Firefox and, predictably, not so well on IE. After many hours of head-scratching, I discovered an IE-specific bug and was able to implement a workaround. So, it should now look good on IE as well.

What is a Lightbox?

The term derives from photography. It is used by photographers, generally for viewing and sorting slides. In modern computer programming parlance, the lightbox is a program that provides a nice slideshow for images. Typically, you click on a thumbnail image and the screen darkens while the image is displayed in its full glory in the center. There are numerous scripts out there for lightboxes. For our demo, I chose Cody Lindley's "Thickbox". It is free and open-source and, beneficially for us, it uses the "jQuery" Javascript library as its foundation. Why is this beneficial? If you've installed XMod 5.0, you already have jQuery installed. The files needed by Thickbox will be provided for you at the end of the blog.

The Form

Since I already had a form setup that provides data to most of the demos on the site, I decided to use that. It's very simple and basic. You'll probably want to add an upload control or two (the fatgeorge control would be a good choice) to the form. I had already uploaded my images to the site via FTP, so no upload control was necessary. The focus of this exercise is not the form, but here it is for your use:

<form>
  <controls>
    <input ref="FlowerName"><label>Flower</label></input>
    <textarea ref="Description"><label>Description</label></textarea>
    <input ref="ImageName"><label>Image File Name</label></input>
  </controls>
</form>

The Template

For most solutions involving third party libraries, you'll probably want to use a repeater template type. This provides you with the most control over the HTML this is output to the browser. Many times, you'll need that flexibility to generate HTML the library can effectively work with. For Thickbox, all we need is a series of images, surrounded by hyperlinks. The hyperlink contains the path to the full-sized image while the image tag shows the thumbnail image.

<a href="path/to/fullimage/image.jpg">
  <img src="path/to/thumbnail/image.jpg">
</a>

Thickbox needs some way to identify which images on a page are intended to be displayed in the gallery. To help it out, you need to add a CSS class and also a rel attribute like so:

<a href="path/to/fullimage/image.jpg" class="thickbox" rel="gallery-plants">
  <img src="path/to/thumbnail/image.jpg">
</a>

All images you want to include must include those two attributes. The value of rel can be anything you want, but all images in a gallery must share the same rel value. Now that we have the basic requirements, let's start building the template. If you haven't already done so, create a new Repeater type template. We'll be working in the Plain Text editor.

We start by including the supporting files in the page. Thickbox requires us to include a stylesheed (thickbox.css), the base jQuery library (jquery.js), and its own small Javascript file (thickbox.js). XMod makes this easy with the scriptblock tag. It allows us to include Javascript files and even CSS files. These files should be included in the HEAD section of the page, so we specify a blocktype of HeadScript. We also give the script a unique ID and tell XMod it should only be included once in the page.

<xmod:scriptblock blocktype="HeadScript" scriptid="ThickBox" registeronce="true">
  <link href="/path/to/css/file/thickbox.css" rel="stylesheet" type="text/css" />
  <script type="text/javascript" src="/DesktopModules/XMod/scripts/jquery.js"></script>
  <script type="text/javascript" src="path/to/js/file/thickbox.js"></script>
</xmod:scriptblock>

Inside the script block tag are standard HTML tags for including a stylesheet (<link>) and Javascript files (<script>). The href and src paths you specify for thickbox.css and thickbox.js will depend on where you place those files in your website. The path to the jquery.js file, though, can remain the same, since that is where XMod 5 has installed the file.

With the preliminaries out of the way, we can get to the meat of the template.

<xmod:repeaterviewstyle showpager="false"/>

<itemtemplate>
  <a href="/path/to/fullimage/<xmod:field name="ImageName"/>" 
    class="thickbox" rel="gallery-plants" title="<xmod:field name="FlowerName"/>">
  <img src="/path/to/thumbnail/<xmod:field name="ImageName"/>" 
    alt="<xmod:field name='FlowerName'/>"/></a>
</itemtemplate>

First, we've added <xmod:repeaterviewstyle>. This is required for repeater templates. We've set showpager to false because we won't be using paging. Next, we have the <itemtemplate> tag. This tag's contents will be repeated for each record that is displayed. Since the form only stores the filename of the image (ImageName), we can store our thumbnails in one folder and full-sized images in another, but keep the same filename.

So, in the hyperlink, I've provided a path to my full-sized image folder and added the <xmod:field> tag to append the image filename. I've also added the title attribute and given it the value of the FlowerName field. Finally, I supplied the <img> tag with the path to the thumbnails and appended the image name. If you're following along at home, you'll want to supply paths that are appropriate for your website.

For your reference, here's the complete template. As you can see, there's not a lot to it, but you get a lot out of it. You can copy and paste this into the plain text editor, upload the supporting files, change the paths to point to the appropriate files and locations on your website and you're ready to roll.

<xmod:scriptblock blocktype="HeadScript" scriptid="ThickBox" registeronce="true">
  <link href="/path/to/css/file/thickbox.css" rel="stylesheet" type="text/css" />
  <script type="text/javascript" src="/DesktopModules/XMod/scripts/jquery.js"></script>
  <script type="text/javascript" src="path/to/js/file/thickbox.js"></script>
</xmod:scriptblock>

<xmod:repeaterviewstyle showpager="false"/>

<itemtemplate>
  <a href="/path/to/fullimage/<xmod:field name="ImageName"/>" 
    class="thickbox" rel="gallery-plants" title="<xmod:field name="FlowerName"/>">
  <img src="/path/to/thumbnail/<xmod:field name="ImageName"/>" 
    alt="<xmod:field name='FlowerName'/>"/></a>
</itemtemplate>

One Minor Tweak

To get the nifty loading... animated image to appear you need to make one little change to thickbox.js. Near the top of the file, locate the following line:

var tb_pathToImage = "/demos/xmod/thickbox/loadingAnimation.gif";

Change that path to point to the loadingAnimation.gif file on your website.

DNN Adds Some Complications

Many Javascript libraries (script.aculo.us, jQuery, and others) use the "$" as a short-hand for calling functions in that library. DNN also uses this short-hand. This causes conflicts when multiple libraries are used together. One nice feature of jQuery, and the reason we chose it, is its ability to switch from using "$" to using "jQuery". Some libraries written to use jQuery also provide a mechanism that prevents them from conflicting in the first place. If you are using a library and it doesn't seem to work, this should be one of the first things you focus on. Thickbox was not written to avoid conflicts. So, I edited the code to use "jQuery" instead of "$". I've supplied the modified version so you don't have to do the editng.