Overview

Shadowbox was designed with both the web hobbyist and the experienced programmer in mind. As such, it can be easily 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.

Setup

There are several ways to set up your Shadowbox environment, depending on the needs of your project. Regardless of the route you choose, you'll need the following four basic components in order to properly run Shadowbox:

• Adapter
• Skin
• Language
• Player(s)

Each of these is explained in greater detail in the sections below.

Adapter

The first thing you'll need to set up in order to use Shadowbox is an adapter. For an explanation of what an adapter is, see this page.

Note: I should clarify at this time that you don't technically need an adapter at all. Shadowbox actually ships with a base "adapter" that can be used if you're not already using some other library and you'd prefer to use Shadowbox in standalone mode.

The adapter must be included before you include your shadowbox.js file. For example, if I were using the popular Prototype library with Shadowbox, I would include the files in the following order:

<script type="text/javascript" src="prototype.js"></script>
<script type="text/javascript" src="shadowbox-prototype.js"></script>
<script type="text/javascript" src="shadowbox.js"></script>

To use Shadowbox in standalone mode, you only need to include the base adapter:

<script type="text/javascript" src="shadowbox-base.js"></script>
<script type="text/javascript" src="shadowbox.js"></script>

Skin

A Shadowbox skin is a directory of files that determine what Shadowbox will look like when it is displayed. The "classic" skin is included with the default distribution, and it is hoped that more skins will become available as third-party developers have some time to explore the Shadowbox code.

Note for Developers: A skin directory contains all of the markup, CSS, and images that Shadowbox will need to display properly. The skinning API is built to give designers maximum flexibility over the appearance of the application. Some nice features are supported, including string formatting and transparent PNG support. See the README for more information.

To use a skin, simply call Shadowbox.loadSkin, as in the following example:

Shadowbox.loadSkin('classic', 'my/skin/dir');

The first parameter is the name of the skin you'd like to use, and the second is the path to the directory where the skin is located. As always, you can view the source of the demo page if you want to see an example of how this is to be done.

Note: Because it is not possible to compile the code for a Shadowbox skin into a static build, you must either use the above mentioned method of loading the skin or manually include both the skin.js and skin.css files for the appropriate skin (using <script> and <link> tags respectively) at the top of your page.

Language

Shadowbox uses textual messages for error display and while hovering over navigation controls. Thanks to the efforts of the Shadowbox community, all messages used in the application have been translated into several different languages. The desired language may either be compiled into the build or loaded at runtime using Shadowbox.loadLanguage. For example, you would use the following code to load the Italian language file:

Shadowbox.loadLanguage('it', 'my/lang/dir');

The first parameter is the two-letter abbreviation for the language you'd like to use (as found in the ISO 639-1 standard), and the second is the path to the directory where the language files are stored. Have a look through the lang directory to see which languages are available.

Player

Shadowbox supports a wide range of media formats. However, you may not need to display all of the supported formats on your page. For this purpose, several media "player" classes have been created that are able to display different types of content. The following table lists the different players and gives a short description of the type of content each is capable of displaying.

Player	Description
img	Used to display various image formats including gif, jpeg, and png. Supports dragging of oversized images via the handleOversize configuration option.
swf	Used to display SWF's. Supports background color setting via the flashBgColor configuration option.
flv	Used to play Flash video files via Jeroen Wijering's JW FLV Player.
qt	Uses the QuickTime browser plugin to play content.
wmp	Uses the Windows Media Player browser plugin to play content.
iframe	Displays content in an HTML Iframe. Useful for playing videos from YouTube and Google video, as well as displaying exterior web sites.
html	Injects some pure HTML code into the Shadowbox display. Useful for displaying inline tables and forms.

Just like language files, players may either be compiled into the build or loaded at runtime using Shadowbox.loadPlayer. For example, if I only need to display images and Flash video, I'd make the following function call:

Shadowbox.loadPlayer(['img', 'flv'], 'my/player/dir');

The first parameter of this function should be an array containing the names of the players you'd like to use, and the second is the path to the directory where the player class files are located.

Sample

Whew! That's a lot of setup, I know. So in conclusion of this section, here is some sample code that should help you get going. As always, don't forget to check out the source of the demo page for yet another example.

<script type="text/javascript" src="shadowbox-base.js"></script>
<script type="text/javascript" src="shadowbox.js"></script>
<script type="text/javascript">

Shadowbox.loadSkin('classic', 'my/skin/dir'); // use the "classic" skin
Shadowbox.loadLanguage('en', 'my/lang/dir'); // use the English language
Shadowbox.loadPlayer(['img', 'qt'], 'my/player/dir'); // use img and qt players

window.onload = Shadowbox.init;

</script>

It should be noted that all paths used in the Shadowbox.load* functions are inserted directly into <script> and <link> tags, so you can use either absolute or relative paths. In fact, if you don't care about the speed of your load time, you can always link to the Shadowbox SVN repository for your skin, language, and player files. However, although Google is generally pretty fast, you'd better be prepared to wait a while! You'll get much faster load times storing everything on your server.

Note: All setup code must be called before the page loads, as in the previous example. Also, keep in mind that you may compile a given language and/or player classes into a static build, thus eliminating the need to use Shadowbox.loadLanguage and/or Shadowbox.loadPlayer entirely.

Basic Usage

In order to use Shadowbox, you must do at least two basic things. First you must initialize the Shadowbox environment. Initialization should only happen once—when the page first loads. Second, you must tell Shadowbox which links you would like it to open. These steps are described in greater detail below.

Initialization

The first step to using Shadowbox is to initialize the Shadowbox environment by calling Shadowbox.init as soon as the page loads. When using any of the Shadowbox.load* methods mentioned above, initialization should happen as soon as the window loads. This allows the external files to load before using them in the initialization process.

<script type="text/javascript">

// calls to Shadowbox.load* here (see above example)

window.onload = Shadowbox.init;

</script>

In the case that you don't like loading external files on the fly, you must link to the skin, language, and player files statically using <script> and <link> tags. If you do this, you may call Shadowbox.init as soon as the DOM loads. For example, if I were using the YUI library, I would do the following:

<link rel="stylesheet" type="text/css" href="path/to/skin.css">
<script type="text/javascript" src="path/to/skin.js">

<script type="text/javascript" src="">

<script type="text/javascript">

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

</script>

Note: Read this article for more information on the DOM ready event.

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 is a compressed version of the last demo. It demonstrates how various media can be combined into a single gallery.

<a rel="shadowbox[Mixed];options={counterType:'skip',continuous:true}" 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 gallery elements. These parameters are listed in the table below.

Parameter	Description
player	The player that should be used for the content. May be "img", "swf", "flv", "qt" (QuickTime), "wmp" (Windows Media Player), "iframe", or "html".
title	The title to use for the gallery element.
height	The content's height (in pixels, not necessary for images).
width	The content's width (in pixels, not necessary for images).
gallery	The gallery name to use for the content (optional).
content	The actual content to display (e.g. URL, HTML code, etc.).

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.

<script type="text/javascript">

window.onload = function(){

    Shadowbox.init({
        // let's skip the automatic setup because we don't have any
        // properly configured link elements on the page
        skipSetup: true
    });

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

};

</script>

Note: Shadowbox.open may also accept a second argument that contains some options to apply.

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 dynamic page with links being created and destroyed dynamically.

The following example uses Prototype 1.6 syntax.

<script type="text/javascript">

document.observe('dom:loaded', function(){

    Shadowbox.init({
        skipSetup: true // skip the automatic setup
    });

    // 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: Any options found in a link's HTML markup automatically trump those passed in via setup().