Create a Dojo Lightbox with dojox.image.Lightbox

One of the reasons I love the Dojo Toolkit is that it seems to have everything.  No scouring for a plugin from this site and then another plugin from that site to build my application.  Buried within the expansive dojox namespace of Dojo is dojox.image.  dojox.image is host to many common UI plugins, the most popular being dojox.image.Lightbox, a great solution if you're looking to create a reliable, elegant Lightbox with Dojo.  Let me show you how use dojox.image.Lightbox in your next web application!

dojox.image.Lightbox and dojox.image.LightboxDialog Features

The dojox.image.Lightbox resource has many cool features:

• Integrated theming and images
• Keyboard accessible
• Resizes when the viewport changes
• Flexible with numerous options
• Declarative or Programmatic instance creation
• Works with Dojo data stores

Let me show you just how easy it is to use Dojo's Lightbox solution!

The CSS

dojox.image.Lightbox doesn't require any of the Dijit themes but does require its own CSS file:

<style type="text/css">
	/* bring in the lightbox CSS */
	@import "http://ajax.googleapis.com/ajax/libs/dojo/1.6/dojox/image/resources/Lightbox.css";
</style>

All of the imagery required comes via the CSS file -- no need to add your own styles.

The HTML and JavaScript

The first step in using any Dojo resources is adding a SCRIPT tag with a path to Dojo within the page and requiring the desired Dojo Toolkit resources:

<script src="http://ajax.googleapis.com/ajax/libs/dojo/1.6/dojo/dojo.xd.js"></script>
<script type="text/javascript">
	// Request dependencies
	dojo.require("dojox.image.Lightbox");
</script>

The dojox.image.Lightbox resource can be used declaratively (with HTML) or programmatically (with JavaScript).  If you plan to use declarative widget creation, you'll need to set the djConfig object's parseOnLoad property to true before loading Dojo:

// Parse the page upon load
djConfig = { parseOnLoad: true };

With parseOnLoad in place, you can add links to the page with the data-dojo-type attribute set to dojox.image.Lightbox and instance-specific options within the data-dojo-props attribute.  Here's a sample:

<div id="imageHolder">
	<a href="slideshow/cricci1.jpg" data-dojo-type="dojox.image.Lightbox" data-dojo-props="group:'GoddessPics',title:'Christina Ricci',href:'slideshow/cricci1.jpg'"><img src="slideshow/cricci1.jpg" alt="Christina Ricci" /></a>
	<a href="slideshow/cricci2.jpg" data-dojo-type="dojox.image.Lightbox" data-dojo-props="group:'GoddessPics',title:'Christina Ricci',href:'slideshow/cricci2.jpg'"><img src="slideshow/cricci2.jpg" alt="Christina Ricci" /></a>
	<a href="slideshow/cricci3.jpg" data-dojo-type="dojox.image.Lightbox" data-dojo-props="group:'GoddessPics',title:'Christina Ricci',href:'slideshow/cricci3.jpg'"><img src="slideshow/cricci3.jpg" alt="Christina Ricci" /></a>
	<a href="slideshow/cricci4.jpg" data-dojo-type="dojox.image.Lightbox" data-dojo-props="group:'GoddessPics',title:'Christina Ricci',href:'slideshow/cricci4.jpg'"><img src="slideshow/cricci4.jpg" alt="Christina Ricci" /></a>
	<a href="slideshow/cricci5.jpg" data-dojo-type="dojox.image.Lightbox" data-dojo-props="group:'GoddessPics',title:'Christina Ricci',href:'slideshow/cricci5.jpg'"><img src="slideshow/cricci5.jpg" alt="Christina Ricci" /></a>
</div>

Groups allow you to have images available within...groups... with next and previous buttons.  The title property provides a ...title... and the href property provides the content which should load within the lightbox. You may have any number of groups on the page.  That's all that's needed to create a simple Dojo Lightbox declaratively!

If you're looking to create your Lightbox programmatically, no problem -- that's easy too!  Add your images to the page the same way you did above, minus the data-dojo-type and data-dojo-props attributes, and instead use the following JavaScript code:

// When the DOM is ready and resources are loaded...
dojo.ready(function() {
	// Create an instance
	var lightbox = new dojox.image.Lightbox({ title:"Christina Ricci", group:"GoddessPics", href:"slideshow/cricci1.jpg" });
	// Start it up!
	lightbox.startup();
})

With your instance created, start adding more images:

// Add another image by using the lightbox's _attachedDialog method...
lightbox._attachedDialog.addImage({
	title:"Christina Ricci 2", 
	group:"GoddessPics",  // Can be same group or different!
	href:"slideshow/cricci2.jpg"
});

Regardless of declarative or programmatic implementation, you can show or hide the lightbox with the respective methods:

// Show the lightbox
lightbox.show();
// Hide the lightbox!
lightbox.hide();

As you'd expect with any Dojo Toolkit resource, dojox.image.Lightbox provides the usual onShow, onHide, and other utility methods that are helpful in customizing the Lightbox usage.

dojox.image.Lightbox and dojox.image.LightboxDialog are great resources available within Dojo's "treasure chest", DojoX. Other classes within the dojox.image namespace include Gallery, Slideshow, and Magnifier. Look forward to tutorials about those soon!