Web Applications
ColorBox
A light-weight, customizable lightbox plugin for jQuery 1.3 and 1.4
Why you should be using ColorBox
- Supports photos, grouping, slideshow, ajax, inline, and iframed content.
- Lightweight: less than 9KB of JavaScript.
- Appearance is controlled through CSS so users can restyle the box.
- Behavior settings can be over-written without altering the ColorBox javascript file.
- Can be extended with callbacks & event-hooks without altering the source files.
- Completely unobtrusive, options are set in the JS and require no changes to existing HTML.
- Preloads background images and can preload upcoming images in a photo group.
- Written in jQuery plugin format and can be chained with other jQuery commands.
- Generates W3C valid XHTML and adds no JS global variables & passes JSLint.
- Released under the MIT License.
Tested In: Firefox 3+, Safari 3+, Opera 9+, Chrome, Internet Explorer 6, 7, 8.
Goals of ColorBox
Allow users to create a customized lightbox that is unique to their project.
Promote accessibility, W3C standards, and best practices.
Instructions
The colorbox method takes a key/value object and an optional callback.
Format: $('selector').colorbox({key:value, key:value, key:value}, callback);
Example: $('a#login').colorbox({transition:'fade', speed:500});
Example: $('a.gallery').colorbox();
Example: $('button').colorbox({href:"thankyou.html"});
And it can be called directly, without assignment to an element
Example: $.colorbox({href:"thankyou.html"});
ColorBox can accept a function in place of a static value:
$("a[rel='example']").colorbox({title: function(){
var url = $(this).attr('href');
return '<a href="'+url+'" target="_blank">Open In New Window</a>';
}});
Follow the source code on the demonstration pages for plenty of examples.
| Key | Default | Description |
|---|---|---|
| transition | "elastic" | The transition type. Can be set to "elastic", "fade", or "none". |
| speed | 350 | Sets the speed of the fade and elastic transitions, in milliseconds. |
| href | false | This can be used as an alternative anchor URL or to associate a URL for non-anchor elements such as images or form buttons. Example: $('h1').colorbox({href:"welcome.html"}) |
| title | false | This can be used as an anchor title alternative for ColorBox. |
| rel | false | This can be used as an anchor rel alternative for ColorBox. This allows the user to group any combination of elements together for a gallery, or to override an existing rel so elements are not grouped together. Example: $('#example a').colorbox({rel:'group1'}) Note: The value can also be set to 'nofollow' to disable grouping. |
| width | false | Set a fixed total width. This includes borders and buttons. Example: "100%", "500px", or 500 |
| height | false | Set a fixed total height. This includes borders and buttons. Example: "100%", "500px", or 500 |
| innerWidth | false | This is an alternative to 'width' used to set a fixed inner width. This excludes borders and buttons. Example: "50%", "500px", or 500 |
| innerHeight | false | This is an alternative to 'height' used to set a fixed inner height. This excludes borders and buttons. Example: "50%", "500px", or 500 |
| initialWidth | 300 | Set the initial width, prior to any content being loaded. |
| initialHeight | 100 | Set the initial height, prior to any content being loaded. |
| maxWidth | false | Set a maximum width for loaded content. Example: "100%", 500, "500px" |
| maxHeight | false | Set a maximum height for loaded content. Example: "100%", 500, "500px" |
| scalePhotos | true | If 'true' and if maxWidth, maxHeight, innerWidth, innerHeight, width, or height have been defined, ColorBox will scale photos to fit within the those values. |
| scrolling | true | If 'false' ColorBox will hide scrollbars for overflowing content. This could be used on conjunction with the resize method (see below) for a smoother transition if you are appending content to an already open instance of ColorBox. |
| iframe | false | If 'true' specifies that content should be displayed in an iFrame. |
| inline | false | If 'true' a jQuery selector can be used to display content from the current page. Example: $("#inline").colorbox({inline:true, href:"#myForm"}); |
| html | false | This allows an HTML string to be used directly instead of pulling content from another source (ajax, inline, or iframe). Example: $.colorbox({html:'<p>Hello</p>'}); |
| photo | false | If true, this setting forces ColorBox to display a link as a photo. Use this when automatic photo detection fails (such as using a url like 'photo.php' instead of 'photo.jpg', 'photo.jpg#1', or 'photo.jpg?pic=1') |
| opacity | 0.85 | The overlay opacity level. Range: 0 to 1. |
| open | false | If true, the lightbox will automatically open with no input from the visitor. |
| preloading | true | Allows for preloading of 'Next' and 'Previous' content in a shared relation group (same values for the 'rel' attribute), after the current content has finished loading. Set to 'false' to disable. |
| overlayClose | true | If false, disables closing ColorBox by clicking on the background overlay. |
| escKey | true | If false, will disable closing colorbox on esc key press. |
| arrowKey | true | If false, will disable the left and right arrow keys from navigating between the items in a group. |
| loop | true | If false, will disable the ability to loop back to the beginning of the group when on the last element. |
| slideshow | false | If true, adds an automatic slideshow to a content group / gallery. |
| slideshowSpeed | 2500 | Sets the speed of the slideshow, in milliseconds. |
| slideshowAuto | true | If true, the slideshow will automatically start to play. |
| slideshowStart | "start slideshow" | Text for the slideshow start button. |
| slideshowStop | "stop slideshow" | Text for the slideshow stop button |
| current | "{current} of {total}" | Text format for the content group / gallery count. {current} and {total} are detected and replaced with actual numbers while ColorBox runs. |
| previous | "previous" | Text for the previous button in a shared relation group (same values for 'rel' attribute). |
| next | "next" | Text for the next button in a shared relation group (same values for 'rel' attribute). |
| close | "close" | Text for the close button. The 'Esc' key will also close ColorBox. |
| onOpen | false | Callback that fires right before ColorBox begins to open. |
| onLoad | false | Callback that fires right before attempting to load the target content. |
| onComplete | false | Callback that fires right after loaded content is displayed. |
| onCleanup | false | Callback that fires at the start of the close process. |
| onClosed | false | Callback that fires once ColorBox is closed. |
Extending
Public methods and event hooks are provided for developers who want to extend or modify the plugin's functionality without having to rewrite the source files.
Example of using an event listener and public method to build a primitive slideshow:
$(document).bind('cbox_complete', function(){
setTimeout($.colorbox.next, 1500);
});
Public Methods
$.colorbox()
This method allows you to call ColorBox without having to assign it to an element.
Example: $.colorbox({href:'login.php'});
$.colorbox.next() and $.colorbox.prev()
These methods moves to the next and previous items in a group and are the same as pressing the 'next' or 'previous' buttons.
$.colorbox.close()
This method initiates the close sequence, which does not immediately complete. The lightbox will be completely closed only when the 'cbox_closed' event is fired.
$.colorbox.element()
This method is used to fetch the current HTML element that ColorBox is associated with. Returns a jQuery object containing the element.
Example: var $element = $.colorbox.element();
$.colorbox.resize({settings_object})
This allows ColorBox to be resized based on it's own auto-calculations, or to a specific size.
This must be called manually after ColorBox's content has loaded.
The optional parameters object can accept 'width' or 'innerWidth' and 'height' or 'innerHeight'.
Without specifying a width or height, ColorBox will attempt to recalculate the height of it's current content.
$.colorbox.init()
This runs silently when the DOM is first loaded and is used to initialize the lightbox (adds necessary HTML to the DOM, preloads the interface graphics, initializes variables, etc). If ColorBox were completely removed from the DOM, to load in a new stylesheet for example, this would be needed to re-initialize it.
$.colorbox.remove()
Removes all traces of ColorBox from the document. Not the same as $.colorbox.close(), which tucks colorbox away for future use.
Event Hooks
ColorBox triggers four different events during it's use. The event hooks fire at the same time as their corresponding callbacks (ie. cbox_complete & onComplete), but can be used to make a universal change to ColorBox, while callbacks are more for targeting changes on a specific instance of the modal.
'cbox_open' triggers when ColorBox is first opened, but after a few key variable assignments take place.
'cbox_load' triggers at the start of the phase where content type is determined and loaded.
'cbox_complete' triggers when the transition has completed and the newly loaded content has been revealed.
'cbox_cleanup' triggers as the close method begins.
'cbox_closed' triggers as the close method ends.
Author
Hi, I'm Jack and I'm the designer/developer for this project and this website. You can follow me on twitter if you are interested in updates to this or my other work.
I created ColorBox because I needed a lightbox that could easily be customized to compliment the style of the website it was being integrated with.
If you are interested in contracting Color Powered to assist with a project, jQuery or otherwise, contact Alex or myself.
Help
Visit the ColorBox Google Group if you have any questions or problems. Always post a link demonstration your problem! See below for solutions to common problems.
Flash appears over ColorBox:
This is not a ColorBox specific problem, by default Flash will overlay any HTML content. This can be prevented by setting the 'wmode' param and embed attribute to 'transparent'.
For more information from Adobe Support
ColorBox is positioned incorrectly or behaving strangely in Internet Explorer:
This is likely a doctype issue. ColorBox requires a valid doctype and rendering in quirks mode is not supported. Make sure you are using the full doctype declaration to insure rendering in standards mode.
This abbreviated doctype renders the document in quirks mode for Internet Explorer:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
The doctype with URI renders in standards mode for all browsers:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
For more information, see A List Apart's primer on doctypes.
ColorBox is positioned incorrectly or behaving strangely:
This could be a source order problem. Both jQuery and colorbox.css need to be loaded prior to jquery.colorbox.js. ColorBox should be called or assigned to elements inside of jQuery's ready method, which should be declared after jquery.colorbox.js.
ColorBox broken or displaying incorrectly when loading documents:
Often this is due to not using an iframe when an iframe would be required. The default method, ajax, is only for elements that can exist within a <body> element.
If you are loading a complete HTML document with <html>, <head>, and <body> elements, then using an iframe is required. While nesting these elements may appear to display correctly in some browsers, it is still invalid HTML and should not be depended on. Remember to set the width and height values for ColorBox when using an iframe, it has no way of knowing the dimensions of elements that exist within the iframe.
ColorBox leverages jQuery's load method for handling ajax. If you are loading a document from the same domain as your current document, you can use a selector pull out just the portion of the document that is needed.
Example:
$('#example').colorbox({href:"document.html div#content"});
ColorBox's borders do not display in Internet Explorer:
Some of the example styles provided make use of transparent .PNG files. Alpha transparencies aren't supported by default in IE6, and can cause an undesirable 'black halo' effect in IE7 and IE8 when changing their opacity. ColorBox resolves this by using one of IE's CSS filters. You can see these at the bottom of colorbox.css. The filter src paths are relative to the HTML document (just like an IMG element), while CSS background image paths are relative to the CSS document. In the examples I provide the relative path is the same, but users often change the directory structure once they move the files over to their own host. The filter src path needs to reflect this change with the appropriate relative path or an absolute path. Here is an example that assumes the 'images' folder is in the root directory:
Original CSS with incorrect relative path:
.AlphaImageLoader(src=images/internet_explorer/borderTopLeft.png
Corrected relative path:
.AlphaImageLoader(src=/images/internet_explorer/borderTopLeft.png
Corrected absolute path:
.AlphaImageLoader(src=http://your_domain.com/images/internet_explorer/borderTopLeft.png
Trying to load an external page results in "Request unsuccessful"
This could be due to an invalid URL or trying to load ajax content from a different domain. Ajax will only work with documents that are on the same domain as your current document due to browser restrictions. Ajax has to be run from a server to function (e.g., ajax content is not going to work from your desktop unless you are running a web server such as Apache for local development).
How to disable grouping by rel attribute
Set ColorBox's value for rel to 'nofollow'. Example:
$('a[rel="examples"]').colorbox({rel:'nofollow'});
JavaScript/jQuery is not working inside of ColorBox.
This is often due to trying to access an element before it has been loaded into the document and can be resolved by moving the JavaScript into ColorBox's onComplete callback.
Example (using jQuery Forms plugin):
$('#login_window').colorbox({onComplete:function(){
$('form#login').ajaxForm();
}});
Opening ColorBox outside of an iframe
Anything loaded within an iframe is going to be confined to that iframe. The only way not to be confined by the iframe is to move ColorBox to the parent document. From the iframe you can reach back to the parent document to call ColorBox.
Example:
<a href='login.php' onclick='parent.$.colorbox({href:"login.php"}); return false;'>Open from parent</a>
Note that grouping will not work with this format since the parent document can not access the content of the iframe to see if any of those elements share a rel attribute value.