jQuery Tools / Overlay - Overlay your HTML with eye candy

Demo. Click on the image

Demo title

Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas.

Class aptent taciti sociosqu ad litora torquent per conubia nostra, per inceptos himenaeos. Donec lorem ligula, elementum vitae, imperdiet a, posuere nec, ante. Quisque mattis massa id metus.

Proin eu libero non urna pretium mollis. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nam in ante sed elit sollicitudin tincidunt. Vestibulum eu ipsum.

The story

This product aims to be the best library for implementing overlays on the web. Period. You have probably encountered other overlaying solutions, and perhaps you even liked some of them, but the reality is that each one of them falls down in one or more of the following areas:

Usability

You want to be in control and need to know how things work. This tool uses standards-based syntax that feels completely natural. There is no clutter and there are no surprises. There is no "hidden" HTML/CSS logic that messes things up. This tool does only what it is supposed to and nothing else. If you want to overlay an image slideshow, use another tool to render the slideshow and use this one for the overlaying. That is how great programs are architected.

Eye candy

Overlaying is done in a visually appealing way by growing a background image from 0 to the desired size. This differs from "regular" overlaying solutions that do overlaying only based on static DIVs. And it's no secret: our visual behaviour has been "borrowed" from Apple's website.

Customization

The visual appearance can be controlled using CSS (what else?!?). If you are experienced with CSS, you will be able to create a variety of interesting-looking overlays. For scripters, we have a range of callback functions and a high quality scripting API, so that you have all the tools you need to customize the library's behaviour to your own specific requirements. There are also a large number of more standard configuration options.

This tool uses a simple and natural syntax and has an advanced programming API. You can extend it with callback methods or with your own plugins. This tool has a similar structure and feel as the other tools. Learn to use this tool and you will know how to use the rest.

This tool is a mature project and is actively maintained. The source code is clean, professional and easy to follow. It passes Douglas Crockford's JavaScript Verifier and it it doesn't assign any global variables. Active forums keep this tool alive and you can expect to see new releases coming out in the future.

Our overlay tool is now a significant part of the JavaScript/Web 2.0 landscape. Don't rely on other, half-baked solutions.

Usage

You can study the workings of overlay in the following examples. Each contains documented source code, along with a standalone page to allow you to easily transfer the examples to your own site. The most important example is the first one, "Minimal setup for overlay". It teaches you the basics of using the library.

Combining overlay with Flowplayer

These demos provide some examples of how to use overlay and Flowplayer together.

The Flowplayer home page. Open the scripting tab and press "Show me"
The basics of overlaying videos
Custom fullscreen action in overlays
E-mail and embed features in overlays

overlay Graphics

You can use our graphics as the basis for your design. You can freely change the design as you see fit. Click the image on the right to download a zip file. Before using the graphics, you should consult the User's Guide on how graphics can be used when designing the look and feel of the tools.

Here are a few examples of what is included in the zip file:

Configuration

There are many other ways of using this tool than can be illustrated in the demos provided here. It is important to realize that elements being overlayed can contain any HTML: text, images, forms, Flash objects, or any combination of the above.

Choosing a background image

overlay always uses a background image, which is expanded from nothing to the desired size. The background image you choose has a dramatic impact on the look and feel of your overlays. Here are few sample backgrounds used in our demos. You may use them freely on your own site.

gray, petrol, white

You can use any browser-renderable background image with overlay. However, using PNG images allows you to have neat drop shadows in your overlays, since PNG supports alpha transparency, while GIF and JPG images do not. You can use the same background image at different sizes without experiencing significant quality degradation.

Installation

The general way to setup overlay is as follows:

// select one or more elements to be overlay triggers
$("JQUERY SELECTOR").overlay({

	// one configuration property
	color: '#ccc',

	// another property
	start:  {
		top: 300
	},

	// ... the rest of the configuration properties
});

Here is a list of all available configuration options.

Property	Default value	Description
start (`Object`)	`{ top: 'center', left: 'center', width: 0, absolute: false }`	The starting position and dimensions of the animated image. By default, the starting position is the position of the element that triggers the overlay and the starting size is zero. When triggering is done programmatically, the default starting position is the centre of the screen. You can override these defaults using the following properties: `top` specifies how far from the top edge of the screen the growing animation should start. `left` specifies how far from the left-hand edge of the screen the growing animation should start. `width` specifies the width of the background image when the animation starts. The height is auto-calculated to preserve the aspect ratio of the image. `absolute` If set to `true`, the starting position is measured from the top left-hand corner of the browser window and the scrolling position has no impact. By default, the scrolling position is added.
finish (`Object`)	`{ top: 100, left: 'center', absolute: false }`	The final position of the overlay after the growing animation finishes. Again, you can override this default using the following properties: `top` specifies how far from the top edge of the screen the overlay should be placed when the animation finishes. `left` specifies how far from the left-hand edge of the screen the overlay should be placed when the animation finishes. `absolute` If set to `true`, the final position is measured from the top left-hand corner of the browser window and the scrolling position has no impact. By default, the scrolling position is added. The final size is defined using CSS for the overlayed element.

expose		Overlay is very often used together with the expose tool. Because of this, the support for this feature has been built inside the tool. This configuration accepts the expose tools configuration. This is either a simple string specifying the background color of the mask or a more complex object literal specifying more configuration variables. See an example of an overlay together with expose. By default the `expose` feature is disabled.
speed	`'normal'`	The speed of the growing animation. Valid values are 'slow', 'normal' and 'fast', or you can supply a numerical value (in milliseconds). By setting this property to 0, the overlay will appear immediately without any animation.
fadeInSpeed	`'fast'`	The speed at which the content fades in on top of the background image after the growing animation has completed. Valid values are 'slow', 'normal' and 'fast', or you can supply a numerical value (in milliseconds).
oneInstance	`true`	By default, there can be only one overlay on the page at once. Setting this property to `false` allows you to have many overlay instances.
closeOnClick	`true`	By default, overlays are closed when the mouse is clicked outside the overlay area. Setting this property to `false` suppresses this behaviour.
preload	`true`	By default, the background image is preloaded into the browser's cache, so that, when an overlay is opened, the background image is already loaded, resulting in a smoother animation, even for larger images. Settings this property to `false` suppresses image preloading and reduces download bandwidth in situations where overlays are not opened.
close		A jQuery selector for the close button(s) inside the overlay. If this is not supplied, a close button is auto-generated. You can find more information about this here.
zIndex	`9999`	This is the CSS z-index property for overlayed elements. A z-index specifies the placement of an element on a document's z-axis. The default `zIndex` value is very high, so it is unlikely that you will need to alter it; however, this value must be greater than the z-index of any other element on the page so that the overlay will always be visible when called.
target		The element to be overlayed (if not specified in the `rel` attribute of the triggering element).

onBeforeLoad	None	This callback function is triggered before the growing animation begins. A function which returns `false` will prevent a particular overlay from being loaded.
onLoad	None	This callback function is triggered when the animation has completed and a particular overlay is in place.
onBeforeClose	None	This callback function is triggered before a particular overlay is closed. A function which returns `false` will prevent a particular overlay from being closed.
onClose	None	This callback function is triggered when a particular overlay is closed.
api	`false`	When this tool is initialized (constructed), the return value is a jQuery object associated with the selector. By setting this property to `true` the return value is this tool's JavaScript API instead. If the selector returns multiple elements, the API of the last element will be returned. Read more about accessing the tool API.

Using callback functions

Here is an example of an onLoad callback function. Inside any callback function the this variable is a pointer to the overlay scripting API:

$("button[rel]").overlay({

	// hide trigger when the overlay is opened
	onLoad: function() {
		this.getTrigger().hide();
	}
});

Custom close button

By default, a close button is auto-generated as the first element inside the container. Here is the generated HTML:

<!-- auto- generated close button -->
<div class="close"></div>

You can create one or more custom close buttons inside your overlay and style/position them in any way you like. In order to make them work, you need to activate them with the close property, as follows:

$("a.overlay").overlay({

	// provide a jQuery selector for the element(s) that act as close button(s)
	close: 'img.close'
});

If you supply a value to the close property, the overlay does not auto-generate a close button.

Scripting API

Overlay has a clean and well-designed API for scripters, with which it is possible to enrich the overlay user experience. You can get a handle to the API in numerous ways as described in the Users Manual. Here is an example of how to access the API:

// get handle to the API upon initialization by enabling the "api" variable
var api = $("div.overlay").overlay({oneInstance: false, api: true});

// open the overlay programmatitaclly with this API call
api.load();

// retrieve an existing api
api = $("div.overlay").overlay();

Here is a list of all available API methods:

Method	Return value type	Description
load()	`Overlay`	Opens the overlay.
close()	`Overlay`	Closes the overlay.
isOpened()	`boolean`	Returns `true` if the overlay is opened.
getBackgroundImage()	`jQuery`	Returns the background image as a jQuery object.
getContent()	`jQuery`	Returns the overlayed content as a jQuery object.
getTrigger()	`jQuery`	Returns the triggering element as a jQuery object.
getConf()	`Object`	Returns the configuration for the overlay.
api	`false`	When this tool is initialized (constructed), the return value is a jQuery object associated with the selector. By setting this property to `true` the return value is this tool's JavaScript API instead. If the selector returns multiple elements, the API of the last element will be returned. Read more about accessing the tool API.

onBeforeLoad(fn)	`API`	Registers a new callback function that is triggered before the growing animation begins. The callback is given as the argument. Returning `false` in the callback will prevent the overlaying from taking place. You can assign multiple `onBeforeLoad` listeners with this command. See using callbacks for more information.
onLoad(fn)	`API`	Registers a new callback function that is triggered right after the overlay has been loaded. The callback is given as the argument. You can assign multiple `onLoad` listeners with this command. See using callbacks for more information.
onBeforeClose(fn)	`API`	Registers a new callback function that is triggered before overlay is closed. The callback is given as the argument. Returning `false` in the callback will prevent overlay from closing. You can assign multiple `onBeforeClose` listeners with this command. See using callbacks for more information.
onClose(fn)	`API`	Registers a new callback function that is triggered after the overlay has been closed. The callback is given as the argument. You can assign multiple `onClose` listeners with this command. See using callbacks for more information.