Shadowbox.js Media Viewer

Home // Support // Usage // API // Download // FAQ

API

The following table contains the complete Shadowbox application programming interface (API) for your reference.

Method	Description
`init( [options] )`	Initializes the Shadowbox environment. Appends Shadowbox' HTML to the document and sets up several listeners. The optional `options` parameter may be used here to set the default universal set of options. This function may not be called twice.
`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. Please note that because HTML 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 `Shadowbox.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 `Shadowbox.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: `fla`—Adobe Flash Player `qt`—QuickTime Player `wmp`—Windows Media Player `f4m`—Flip4Mac QuickTime Player
`getOptions()`	Gets the current options object in use.
`getCurrent()`	Gets the current gallery object.
`getVersion()`	Gets the current version number of Shadowbox.

Options

The following table contains a list of options that may be used to configure Shadowbox.

Option	Description
animate	Set this `false` to disable all fancy animations (except fades). This can improve the overall effect on computers with poor performance. Defaults to `true`.
animateFade	Set this `false` to disable all fading animations. Defaults to `true`.
animSequence	The animation sequence to use when resizing Shadowbox. May be either `"wh"` (width first, then height), `"hw"` (height first, then width), or `"sync"` (both simultaneously). Defaults to `"wh"`.
flvPlayer	The URL of the flash video player. Only needed when displaying Flash video content. Defaults to `"flvplayer.swf"`.
modal	Set this `false` to disable listening for mouse clicks on the overlay that will close Shadowbox. Defaults to `true`.
overlayColor	The color to use for the modal overlay (in hex). Defaults to `"#000"`.
overlayOpacity	The opacity to use for the modal overlay. Defaults to `0.8`.
flashBgColor	The default background color to use for Flash movies. Defaults to `"#000000"`.
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`.
slideshowDelay	A delay (in seconds) to use for slideshows. If set to anything other than 0, this value determines an interval at which Shadowbox will automatically proceed to the next piece in the gallery. Defaults to `0`.
resizeDuration	The duration (in seconds) of the resizing animations. Defaults to `0.55`.
fadeDuration	The duration (in seconds) of the fade animations. 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". Defaults to `false`.
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"`.
counterLimit	Limits the number of counter links that will be displayed in a "skip" style counter. If the actual number of gallery elements is greater than this value, the counter will be restrained to the elements immediately preceding and following the current element. Defaults to `10`.
viewportPadding	The amount of padding (in pixels) to maintain around the edge of the browser window. Defaults to `20`.
handleOversize	The mode to use for handling content that is too large for the viewport. May be one of `"none"`, `"resize"`, or `"drag"` (for images). The `"none"` setting will not alter the image dimensions, though clipping may occur. Setting this to `"resize"` enables on-the-fly resizing of large content. In this mode, the height and width of large, resizable content will be adjusted so that it may still be viewed in its entirety while maintaining its original aspect ratio. The `"drag"` mode will display an oversized image at its original resolution, but will allow the user to drag it 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"`.
handleException	A function to use for handling exceptions. This function will be passed the error message (string) as its only argument. If this value is left `null`, exceptions will not be caught. Defaults to `null`.
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"`.
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`.
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.
skipSetup	Set this `true` to skip automatically calling `Shadowbox.setup` when Shadowbox initializes. Defaults to `true`. Note: This option may only be used in `Shadowbox.init`.
errors	An object containing the names and URL's of plugins and their respective download pages.
ext	A map of players to their supported extensions. See the source for further details. Note: This option may only be used in `Shadowbox.init`.

Unless otherwise noted, any of these options may be passed to 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">

$(window).load(function(){

    var options = {
        handleOversize:     'drag',
        displayNav:         false,
        handleUnsupported:  'remove',
        autoplayMovies:     false
    };

    Shadowbox.init(options);

});

</script>

If options are passed to Shadowbox.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 on this page.