Shadowbox.js Media Viewer

Shadowbox was designed with both the web hobbyist and the experienced programmer in mind. As such, it can easily be added to any web page with very little time and effort using the default settings. At the same time, Shadowbox offers a great deal of flexibility for those users who need to fine-tune the details of its appearance and operation for a given project.

This page contains detailed instructions on how to set up and run Shadowbox from both perspectives.

Installation

After you download the code, decompress the archive (unzip it) and upload the entire folder to your web server. The exact location is not important since Shadowbox will automatically detect where it is installed when it runs. However, it is important that you keep all of the files together. After you have uploaded the code to your server, simply link to the JavaScript and CSS files as described below.

Setup

The simplest way to set up Shadowbox is to include the JavaScript and CSS files in the <head> of your document (web page) and then call Shadowbox.init, like this:

<link rel="stylesheet" type="text/css" href="shadowbox.css">
<script type="text/javascript" src="shadowbox.js"></script>
<script type="text/javascript">
Shadowbox.init();
</script>

If you already have another JavaScript library included on your page, such as jQuery or MooTools, Shadowbox will automatically detect it and include the correct adapter for working with that library. All you need to do is make sure you include that library before you include your Shadowbox code. For example, if I were using the popular Prototype library with Shadowbox, I would do the following:

<link rel="stylesheet" type="text/css" href="shadowbox.css">
<script type="text/javascript" src="prototype.js"></script>
<script type="text/javascript" src="shadowbox.js"></script>
<script type="text/javascript">
Shadowbox.init();
</script>

NOTE: By default, only the image player is loaded. If you need to play other types of content, use the players option to specify which players you'd like to load.

The following example is a bit more complex and uses some options to customize the Shadowbox setup in order to show you how this is to be done. In this example, the Italian language file is used and the QuickTime player is loaded for viewing QuickTime videos.

<link rel="stylesheet" type="text/css" href="shadowbox.css">
<script type="text/javascript" src="shadowbox.js"></script>
<script type="text/javascript">
Shadowbox.init({
    language:   "it",
    players:    ["qt"]
});
</script>

Markup

Secondly, you need to tell Shadowbox which links you want it to open. The simplest way to do this is through your HTML markup. If you're going to take this route, at the very least you must add a rel="shadowbox" attribute to each link. 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>

That's it! Clicking on this link should now open up the image in Shadowbox.

NOTE: The word lightbox will also work here. This feature was added for compatibility with the original Lightbox script. Also note that because HTML area tags do not support the rel attribute, you cannot use this method to set them up for use with Shadowbox. Instead, use Shadowbox.setup as described below.

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. To specify a movie's height and width (in pixels), use the height and width parameters.

<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.

<a href="myimage.jpg" rel="shadowbox;options={animate: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. 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 demonstrates how various media can be combined into a single gallery.

<a rel="shadowbox[Mixed];" href="vanquish.jpg">jpg</a>
<a rel="shadowbox[Mixed];width=520;height=390" href="caveman.swf">swf</a>
<a rel="shadowbox[Mixed];width=292;height=218" href="kayak.mp4">movie</a>
<a rel="shadowbox[Mixed]" href="index.html">iframe</a>

Advanced

If you don't want to add to your markup, you don't have to. Shadowbox may be manipulated with pure JavaScript. This use is slightly more complex, but it has several benefits including the fact that your HTML markup will be cleaner and you can more easily integrate Shadowbox into an existing project.

If you were paying attention in the section about markup, you'll notice that there are several parameters that commonly accompany Shadowbox content. These parameters are listed in the table below.

Parameter	Description
content	The actual content to display (e.g. URL, HTML code, etc.)
player	The player that should be used for the content (optional, can be automatically determined in most cases)
title	The title to use for the content (optional)
height	The content's height (in pixels, optional for images)
width	The content's width (in pixels, optional for images)
gallery	The gallery name to use for the content (optional)

When using the markup method, each of these options may be present in one form or another. A link's gallery name, height, and width may all be configured within the link's rel attribute. Similarly, its title is contained in the title attribute and the content value defaults to the link's href. The content type is then derived from the extension on the linked file.

So, now that you know what's really going on behind the scenes, you can just pass objects that contain these pieces of information to Shadowbox.open as in the following example.

<link rel="stylesheet" type="text/css" href="shadowbox.css">
<script type="text/javascript" src="shadowbox.js"></script>
<script type="text/javascript">
Shadowbox.init({
    // let's skip the automatic setup because we don't have any
    // properly configured link elements on the page
    skipSetup: true,
    // include the html player because we want to display some html content
    players: ["html"]
});

window.onload = function(){

    // open a welcome message as soon as the window loads
    Shadowbox.open({
        content:    '<div id="welcome-msg">Welcome to my website!</div>',
        player:     "html",
        title:      "Welcome",
        height:     350,
        width:      350
    });

};
</script>

You can also use Shadowbox.setup to manually set up link elements for use with Shadowbox. This can be useful, for example, if you have a page that is updated via Ajax with links being created and destroyed dynamically.

<link rel="stylesheet" type="text/css" href="shadowbox.css">
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="shadowbox.js"></script>
<script type="text/javascript">
Shadowbox.init({
    // skip the automatic setup, we'll do this later manually
    skipSetup: true,
    // include the quicktime and windows media player players for playing
    // movies (assuming we have some movies we want to show in either of
    // those formats)
    players: ["qt", "wmp"]
});

window.onload = function(){

    // set up all anchor elements with a "movie" class to work with Shadowbox
    Shadowbox.setup("a.movie", {
        gallery:            "My Movies",
        autoplayMovies:     true
    });

};
</script>

When using this method to set up links with Shadowbox, you may mix in the link parameters with the options argument as the second parameter. However, the same parameters will apply to all links set up in the same call, so you may want to make separate calls to Shadowbox.setup for each link.

NOTE: The first parameter to Shadowbox.setup may be a single link element, an array of elements, a CSS selector, or an array in which the first item is a CSS selector and the second item is the context element under which the selection should take place. Also, any options found in a link's HTML markup automatically trump those passed in via setup().

Shadowbox.js - A more powerful and versatile Lightbox

by Michael J. I. Jackson

Installation

Setup

Markup

Advanced