Version: 1.0
The Shadowbox environment must be initialized before it can be used. To initialize Shadowbox, 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>
If the library you're using doesn't support the DOM ready event, or you don't know what that means (read this article), you can always simply use the following code to achieve the same effect.
<script type="text/javascript"> window.onload = Shadowbox.init; </script>
Shadowbox is highly configurable, but can also be used with little to no configuration at all. The following table contains a list of options that may be used to configure Shadowbox.
| Option | Description |
|---|---|
| assetURL | A base URL that will be prepended to the loadingImage, flvPlayer, and overlayBgImage options to save on typing. Defaults to "". |
| loadingImage | The URL of an image to use as a loading indicator while loading content. Defaults to "images/loading.gif". |
| 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. |
| animSequence | The animation sequence to use when resizing Shadowbox. May be either "wh" (width then height), "hw" (height then width), or "sync" (both simultaneously). Defaults to "wh". |
| 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". |
| listenOverlay | Set this false to disable listening for mouse clicks on the overlay that will close Shadowbox. Defaults to true. |
| 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. |
| handleLgImages | The mode to use for handling images that are too large for the viewport. May be one of "none", "resize", or "drag". The "none" setting will not alter the image dimensions, though clipping will occur. Setting this to "resize" enables on-the-fly resizing of large images. In this mode, the height and width of large images will be adjusted so that they may still be viewed in their entirety while maintaining the original aspect ratio. The "drag" mode will display the image at its original resolution, but will allow the user to drag the image within the view to see portions that may be clipped. See the demo for a demonstration of all three modes of operation. Defaults to "resize". |
| 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 argument of this function will be the current gallery element. |
| onFinish | A hook function that will fire when Shadowbox finishes loading the current gallery piece (after all animations are complete). The single argument of this function will be the current gallery element. |
| onChange | A hook function that will be fired when Shadowbox changes from one gallery element to another. The single argument of this function will be the gallery element that is about to be displayed. |
| onClose | A hook function that will be fired when Shadowbox closes. The single argument of this function will be the gallery element 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". |
The following options are provided for advanced users.
| Option | Description |
|---|---|
| skipSetup | Set this true to skip automatically calling setup() after init(). Defaults to true. Note: This option may only be used in init() and still requires setup() to be called manually later. |
| text | An object containing the textual messages displayed by Shadowbox. Provided for i18n support. |
| errors | An object containing the names and URL's of plugins and their respective download pages. |
| skin | An object containing the actual HTML markup of Shadowbox. |
| ext | A map of file types to extensions. Note: This option may only be used in init(). |
Any of these options may be passed into Shadowbox.init() in a JavaScript object (hash) once the page loads. The following example uses jQuery syntax to demonstrate how this is to be done.
<script type="text/javascript">
$(document).ready(function(){
var options = {
resizeLgImages: true,
displayNav: false,
handleUnsupported: 'remove',
keysClose: ['c', 27], // c or esc
autoplayMovies: false
};
Shadowbox.init(options);
});
</script>
If options are passed into init(), they will be applied as the default for all instances of Shadowbox on a page. However, options may also be used on a per-link basis as described below.
The simplest way to use Shadowbox is through your HTML markup. 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>
Note: The word "lightbox" will also work here. This feature was added for compatibility with the original Lightbox script. Please 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 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, use the height and width parameters. Note: 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 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>
If you don't want to add to your markup, you don't have to. Shadowbox may be controlled manually through the use of 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 link elements. These parameters are listed in the table below.
| Parameter | Description |
|---|---|
| title | The title to use for the gallery element. |
| type | The type of element. May be "img", "swf", "flv", "qt" (QuickTime), "wmp" (Windows Media Player), "iframe", or "html". |
| 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. |
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 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({
title: 'Welcome',
type: 'html',
content: 'Welcome to my website!',
height: 350,
width: 350
});
};
</script>
Note: The open() method may also accept a second argument that contains some options to apply.
You can also use the setup() method 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 on the fly.
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 setup() for each link.
It is important to note that any options found in a link's HTML markup automatically trump those passed in via setup().
The following table contains the Shadowbox API for your reference.
| Method | Description |
|---|---|
init( [options] ) |
Initializes the Shadowbox environment. Appends Shadowbox' HTML to the document and sets up listeners on the window and overlay element. The optional options parameter may be used here to set the default universal set of options. |
setup( links [, options] ) |
Sets up listeners on the given links that will trigger Shadowbox. If no links are given, this method will set up every anchor element on the page with the appropriate rel attribute. Note: Because AREA elements do not support the rel attribute, they must be explicitly passed to this method. The optional options parameter specifies a set of options that will be applied to all links in this set by default. |
applyOptions( options ) |
Applies the given set of options to those currently in use. Note: Options will be reset on open() so this function is only useful after it has already been called (while Shadowbox is open). |
revertOptions() |
Reverts Shadowbox' options to the last default set in use before applyOptions() was called. |
open( obj [, options] ) |
Opens the specified object in Shadowbox. The optional options parameter may be used here to specify the set of options to apply on this call only. |
change( n ) |
Jumps to the piece in the current gallery with index n. |
next() |
Jumps to the next piece in the gallery. |
previous() |
Jumps to the previous piece in the gallery. |
close() |
Deactivates Shadowbox. |
clearCache() |
Clears Shadowbox' cache and removes listeners and expandos from all cached link elements. May be used to completely reset Shadowbox in case links on a page change. |
getPlugins() |
Gets an object that lists which plugins are supported by the client. The keys of this object will be:
|
getOptions() |
Gets the current options object in use. |
getCurrent() |
Gets the current gallery object. |
getVersion() |
Gets the current version number of Shadowbox. |