Shadowbox.js by Michael J. I. Jackson

Version: 1.0β

Overview

Shadowbox is a cross-browser, cross-platform, cleanly-coded and fully-documented media viewer application written entirely in JavaScript. Using Shadowbox, website authors can display pictures and movies in all major browsers without navigating away from the linking page. The default distribution of Shadowbox includes the full source code and a sample gallery (this file) that demonstrates how it is to be used.

Motivation

I know what you're thinking—this has been done before. What makes Shadowbox so different?

	Standards	Shadowbox uses HTML markup that validates. It doesn't depend on phony HTML attributes in your anchor tags to make it work. The web has enough problems with standards compliance as it is, and I believe we should try to not perpetuate them.
	Adapters	It's easy to make Shadowbox adapt to whatever platform you choose. This means that you're not tied to a particular framework if you don't want to be.
	Skins	Customizing the appearance of Shadowbox is easy because it was built with designers in mind. As such, most of its styles can be altered using the only language that's really designed for such a task, CSS. A sample skin is included that demonstrates how the default appearance may be modified to suit your site.
	Formats	Shadowbox supports all of the most popular web media formats including images, QuickTime, Windows Media Player, Flash, Flash video, and even external web pages. This makes it easy to display your content without converting it to some other format.
	Help	Shadowbox employs a smart plugin detection mechanism that can prevent your users from being confronted with uninformative torn image or puzzle piece icons when they don't have the plugins they need. Instead, Shadowbox displays a helpful link to a page where your users can download the software they need to view your content properly.
	Options	Shadowbox supports a host of options that make it highly configurable. If you don't like the way something works, chances are very good that you can change it without digging through the code.

Support

Browsers

Shadowbox supports the following browsers:

Adapters

It's easy to use Shadowbox with your JavaScript library of choice for a given project. This is accomplished using adapters. An adapter is a small file that tells Shadowbox which methods to call on the underlying framework to achieve some common purpose such as querying the DOM or handling events. Shadowbox comes bundled with adapters for the following JavaScript frameworks:

In order to use Shadowbox, you must include shadowbox.css, your choice of underlying framework, the appropriate adapter, and of course shadowbox.js. For example, to use Shadowbox in combination with the Yahoo! User Interface (YUI) library, you would do the following:

<head>
<link rel="stylesheet" type="text/css" href="shadowbox.css" />
<script type="text/javascript" src="yui-utilities.js"></script>
<script type="text/javascript" src="shadowbox-yui.js"></script>
<script type="text/javascript" src="shadowbox.js"></script>
</head>

To use Shadowbox with the Prototype library, you must also include the Scriptaculous effects engine.

<head>
<link rel="stylesheet" type="text/css" href="shadowbox.css" />
<script type="text/javascript" src="prototype.js"></script>
<script type="text/javascript" src="scriptaculous.js?load=effects"></script>
<script type="text/javascript" src="shadowbox-prototype.js"></script>
<script type="text/javascript" src="shadowbox.js"></script>
</head>

To use Shadowbox with Ext, you must include at least ext-core.js.

<head>
<script type="text/javascript" src="/js/ext-2.0/adapter/ext/ext-base.js"></script>
<script type="text/javascript" src="/js/ext-2.0/ext-core.js"></script>
<script type="text/javascript" src="src/js/adapter/shadowbox-ext.js"></script>
<script type="text/javascript" src="shadowbox.js"></script>
</head>

Adapters may be found in the js/adapter/ directory, and additional adapters may be created easily by implementing the same interface. If there is currently no adapter for your favorite library, and you'd like to contribute to the project, please feel free to create your own and send it to me for inclusion in a future release.

Media

Shadowbox supports many different media formats via the Flash, QuickTime, and Windows Media Player browser plugins. Windows media files are supported on the Mac via the Flip4Mac QuickTime plugin.

Flash video is supported via Jeroen Wijering's JW FLV Player. Although Shadowbox supports many types of video, it is recommended that all video be displayed in this (FLV) format because it will have the most uniform result across different platforms. QuickTime and Windows Media Player each have their bugs and quirks that are difficult to iron out.

Shadowbox uses a smart plugin detection mechanism that automatically detects whether or not the client is capable of displaying linked content. For movies that can be played using either QuickTime or Windows Media Player, Shadowbox will automatically detect which one is installed and use it. In the case of a missing plugin, Shadowbox can either display a useful error message with a link to the appropriate plugin download page (the default behavior), or it can ignore the gallery piece altogether. See the handleUnsupported option in the options section below for more details on how to customize this behavior.

Demos

Single Image (Flickr) Single Large Image (without resizing) Single Large Image (with resizing) Image Gallery image image

Single SWF SWF Gallery Single Movie (flv) Single Movie (mov) Single Movie (mpeg-4, controller disabled) Single Movie (avi, autoplay disabled) Single Movie (wmv) Apple.com Trailer YouTube Google Video Movie Gallery External Website This page Mixed Content Gallery

Usage

Shadowbox must be initialized before it can be used. To initialize the Shadowbox environment, call Shadowbox.init() as soon as the DOM loads. For example, if I were using the YUI library, I would do the following:

<script type="text/javascript">

YAHOO.util.Event.onDOMReady(Shadowbox.init);

</script>

The following options may be used to customize Shadowbox:

loadingImage	The URL of an image to use as a loading indicator while loading content. Defaults to "images/loading.gif". Note: This option may only be set on init() and may not be changed on a per-link basis.
animate	Set this false to disable all fancy dimension and opacity animations. This can improve the overall effect on computers with poor performance. Defaults to true.
flvPlayer	The URL of the flash video player. Defaults to "flvplayer.swf".
overlayColor	The color to use for the overlay. Defaults to "#000".
overlayOpacity	The transparency of the overlay. Defaults to 0.85.
overlayBgImage	The URL of a pre-made image to use for browsers (such as FF Mac) that don't support playing movies over backgrounds that are not 100% opaque. Defaults to "images/overlay-85.png".
autoplayMovies	Set this false to disable automatically playing movies when they are loaded. Defaults to true.
showMovieControls	Set this false to disable displaying QuickTime and Windows Media player movie control bars. Defaults to true.
resizeDuration	The duration (in seconds) of the resizing animations. Defaults to 0.35.
fadeDuration	The duration (in seconds) of the overlay fade animation. Defaults to 0.35.
displayNav	Set this false to hide the gallery navigation controls. Defaults to true.
continuous	Set this true to enable "continuous" galleries. By default, the galleries will not let a user go before the first image or after the last. Enabling this feature will let the user go directly to the first image in a gallery from the last one by selecting "Next".
displayCounter	Set this false to hide the gallery counter. Counters are never displayed on elements that are not part of a gallery. Defaults to true.
counterType	The mode to use for the gallery counter. May be either 'default' or 'skip'. The default counter is a simple '1 of 5' message. The skip counter displays a separate link to each piece in the gallery, enabling quick navigation in large galleries. Defaults to "default".
viewportPadding	The amount of padding (in pixels) to maintain around the edge of the browser window. Defaults to 20.
resizeLgImages	Set this true to enable on-the-fly resizing of large images. If an image is too large for Shadowbox, enabling this feature will set the height and width of that image so that it may still be viewed in its entirety while maintaining its original aspect ratio. This option will only work on images. Defaults to false.
initialHeight	The height of Shadowbox (in pixels) when it first appears on the screen. Defaults to 160.
initialWidth	The width of Shadowbox (in pixels) when it first appears on the screen. Defaults to 320.
enableKeys	Set this false to disable keyboard navigation of galleries. Defaults to true.
keysClose	An array of the keys (or key codes) that a user may use to close Shadowbox. Defaults to ['c', 'q', 27] (c, q, or esc).
keysPrev	An array of the keys (or key codes) that a user may use to skip to the previous piece in the gallery. Defaults to ['p', 37] (p or left arrow).
keysNext	An array of the keys (or key codes) that a user may use to skip to the next piece in the gallery. Defaults to ['n', 39] (n or right arrow).
onOpen	A hook function that will be fired when Shadowbox opens. The single parameter of this function will be the link (DOM) element that was clicked.
onClose	A hook function that will be fired when Shadowbox closes. The single parameter of this function will be the link (DOM) element for the piece that was last displayed.
handleUnsupported	The mode to use for handling unsupported media. May be either 'link' or 'remove'. Media are unsupported when the browser plugin required to display the media properly is not installed. The link option will display a user-friendly error message with a link to a page where the needed plugin can be downloaded. The remove option will simply remove any unsupported gallery elements from the gallery before displaying it. With this option, if the element is not part of a gallery, the link will simply be followed. Defaults to "link".
skin	An option for advanced users, this allows the user to change the actual HTML markup of Shadowbox.

Any of these options may be passed into Shadowbox.init() when the page loads. Note: The example below uses jQuery syntax.

<script type="text/javascript">

$(document).ready(function(){

    var options = {
        resizeLgImages:     true,
        displayNav:         false,
        handleUnsupported:  'remove',
        keysClose:          ['c', 27] // c or esc
    };

    Shadowbox.init(options);

});

</script>

Additionally, options may be passed in as parameters on a per-link basis as described below.

Markup

HTML Markup for Shadowbox is simple. At the very least, you must add a rel="shadowbox" attribute to your links. For example, say you have this link to an image on your page:

<a href="myimage.jpg">My Image</a>

In order to set up this link for use with Shadowbox, simply change it to this:

<a href="myimage.jpg" rel="shadowbox">My Image</a>

If you would like to display a title for your image, simply add a title attribute to the link.

<a href="myimage.jpg" rel="shadowbox" title="My Image">My Image</a>

You must explicitly tell Shadowbox the dimensions to use to display content other than images. This is done by adding a few parameters to the end of the rel attribute, separated by semi-colons (like a CSS style declaration). To specify a movie's height and width, use the height and width parameters. Note: unlike in CSS, these values must always be specified in pixels.

<a href="mymovie.swf" rel="shadowbox;height=140;width=120">My Movie</a>

Additionally, you may set Shadowbox options on a per-link basis. To do this, you must include a JSON-formatted parameter called options. An example could be:

<a href="myimage.jpg" rel="shadowbox;options={overlayOpacity: 0.5, resize: false}">My Image</a>

In addition to displaying single images and movies, Shadowbox is also capable of displaying galleries of content. In order to designate a link as part of a gallery, you must add the gallery name to the rel attribute between square brackets immediately following the word "shadowbox". For example, the following markup creates a gallery called "Vacation" with two pictures:

<a href="beach.jpg" rel="shadowbox[Vacation]">The Beach</a>
<a href="pier.jpg" rel="shadowbox[Vacation]">The Pier</a>

Galleries may be composed of content of many different types. The following markup comes directly from the last demo above. It demonstrates how various media can be combined into a single gallery.

<a rel="shadowbox[Mixed];options={counterType:'skip',continuous:true}" class="option" title="JPG" href="gallery/aston_martin/vanquish.jpg">Mixed Content Gallery</a>
<a rel="shadowbox[Mixed];width=520;height=390" class="hidden" title="SWF" href="gallery/caveman.swf">swf</a>
<a rel="shadowbox[Mixed];width=292;height=218" class="hidden" title="MPEG-4" href="gallery/kayak.mp4">movie</a>
<a rel="shadowbox[Mixed]" class="hidden" title="IFRAME" href="index.html">iframe</a>

Download

Click here to download Shadowbox.

Tip Jar

If you use Shadowbox in a commercial product, or you simply like to reward people's hard work, please consider giving a tip via PayPal. All donations are sincerely appreciated. Thanks!

License

Credits

Shadowbox was inspired by Lokesh Dhakar's Lightbox and Kevin Miller's LightWindow. Credit should be given to the authors of those libraries for the basic idea behind Shadowbox.

The default Shadowbox Flash video player is Jeroen Wijering's JW FLV Player. It is distributed under the Creative Commons Attribution-Noncommercial-Share Alike 2.0 Generic license.

All Flash animation pieces in this gallery are original pieces included courtesy of Wyatt Miles.

Compressed versions of the files necessary to run Shadowbox are included in the default distribution in the build directory. The compression was performed with the excellent YUI compressor by Julien Lecomte.