jQuery Tools / Overlay - A generic tool for overlaying needs

For promotional purposes

Berlin Gustavohouse

The Gustavo House in Storkower Strasse. It was built in 1978 and reconstructed in 1998 by the Spanish artist Gustavo.

Berlin Alexanderplatz Station

Berlin Alexanderplatz is a railway station in the Berlin city centre and is one of the city's most important interchange points for local public transport.

For image galleries

prev next

For user interactions

Yes or no? User input

This is a modal dialog

You can only interact with elements that are inside this dialog. To close it click a button or use the ESC key.

Yes No

This is a modal dialog

You can only interact with elements that are inside this dialog. To close it click a button or use the ESC key.

OK Cancel

For every overlaying need

Overlaying HTML on top of the main document is one of the most common features in today's websites. You need different kinds of overlays for different situations such as:

1. Great looking overlays for displaying your products.
2. Simple and snappy overlays for showing info or warning boxes.
3. Modal dialogs for prompting and alerting users.
4. "lighbox" style image galleries.

This tool handles all these different situations by offering a flexible effect framework. You can use the effect that is most suitable for the situation at hand.

The overlay can contain any HTML and the whole thing can be styled with CSS. There is no clutter and there are no surprises. This overlay tool is now a significant part of the JavaScript/Web 2.0 landscape. Don't rely on other, half-baked solutions.

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.

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.

• Minimal setup for overlay
• The Apple effect for overlay
• Creating modal dialogs with overlay
• Opening overlays programmatically
• Overlays with different styles
• Loading external pages into overlay
• Multiple overlays on a same page
• Creating a customized Overlay effect
• Using the gallery plugin

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

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
	top: 50

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

Here is a list of all available configuration options.

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(event) {
		this.getTrigger().hide();
	}
});

See the Using Callback Functions section in the User's Guide for more detailed dscription about this important topic.

Defining custom close elements

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 easily add more closing elements inside the overlay simply by assignin the CSS class name "close" to them. These elements can be styled and positioned any way you like inside the overlay.

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 programatically with this API call
api.load();

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

Here is a list of all available API methods:

Making custom effects

If you want to make custom effects you should use the $.tools.overlay.addEffect method. This method is "static", meaning that you don't have to have the the overlay API (or instance) already loaded. You can add effects before any overlays are initialized.

This method accepts three arguments. The first argument is the effect name, the second argument is the function that performs the required functionality for loading the overlay and the third argument is a function that closes the overlay. You can use this method to modify existing effects or add new ones. Here is the official default effect taken directly from the source code of the overlay tool:

// adds an effect called "myEffect" to the overlay
$.tools.overlay.addEffect("myEffect",

	// load function
	function(done) {

		/*
			- the 'this' variable is a reference to the overlay API
			- here we use jQuery's fadeIn() method to perform the effect
		*/
		this.getOverlay().fadeIn(this.getConf().speed, done);
	},

	// close function
	function(done) {

		// fade out the overlay
		this.getOverlay().fadeOut(this.getConf().closeSpeed, done);
	}
);

As you can see it is fairly easy to implement effects. Inside the functions the this variable is a pointer to the scripting API. This gives you access to various parts of the overlay elements. The functions are fed with one argument which is a reference to a function that must be called after you have performed you effect. The reason for this is that many times those effects perform animations that have a certain duration. We must know when these animations are finished so that the onLoad and onHide events are really called after the overlay is completely shown or hidden.

Note that if you are using jQuery's animate, fadeIn or fadeOut methods the done function can simply be given to this method as the last argument. jQuery will take care of it after the animation finishes. Otherwise you must call done.call().

Here is one custom overlay effect demo.

Effects

Apple Effect

The Apple effect looks and behaves like you might have seen on apple.com. Click here to see an example:

Overlaying is done in a visually appealing way by growing a background image from 0 to the desired size. If you choose to use this effect you are tied to the dimensions of the image. You can change the width but the height changes accordingly so that the aspect ratio remains the same.

Usage

The best way to learn is to study the full documentation for the example above. Here you can see the JavaScript setup for this effect:

$(function() {
	$("#apple img[rel]").overlay({effect: 'apple'});
});

It's important to note that this effect is not included in the standard distribution of jQuery Tools. You need to include it yourself on the download page.

You may want to configure this effect as a default effect so that you don't have to define the effect property on every call. This can be achieved with global configuration.

Configuration

Here is a full list of available configuration options for this effect. These options are added to the default configuration options.

Using the Apple effect upon page load

Due to a major bug in jQuery you should not load overlays with the Apple effect upon document.ready() event when using external stylesheets. This causes unpredictable behaviour in Safari 3+ and Chrome (webkit-based browsers). There are two workarounds for handling this:

• Use $(window).load() instead. This will definitely be executed after the stylesheets have been loaded.
• Define your overlay style directly on the page or inline for the element. Here is a demo about this method.

Plugins

Gallery plugin for Overlay

Click on any of the following thumbnails and you will realize that you don't need any other overlaying solution anymore.

Highlights

• Every bit of the system can be skinned and configured.
• Standards-based syntax. Works even on browsers without JavaScript enabled.
• Navigation with keyboard arrow keys.
• Styling of the thumbnail images. Try the demo and navigate through the gallery.
• Automatic preloading of the images.
• Auto-hiding functionality for next/prev links and for the image description element.
• Small file size: only about 2kb of minified code. uncomparable

Usage

The best way to learn is to study the full documentation for the example above. For the impatient here is the HTML setup. Notice the standards based syntax.

<!-- list of thumbnails -->
<div id="thumbs">

	<a href="path/to/big-picture1.jpg" title="Image description #1">
		<img src="path/to/thumbnail1.jpg" /></a>

	<a href="path/to/big-picture2.jpg" title="Image description #2">
		<img src="path/to/thumbnail2.jpg" /></a>

	<a href="path/to/big-picture3.jpg" title="Image description #3">
		<img src="path/to/thumbnail3.jpg" /></a>

	<!-- and so on ... -->
</div>

JavaScript setup

// select the thumbnails and make them trigger our overlay
$("#thumbnails a").overlay({

	// each trigger uses the same overlay with the id "gallery"
	target: '#gallery',

	// optional exposing effect
	expose: '#f1f1f1'

// let the gallery plugin do its magic!
}).gallery({

	// the plugin accepts its own set of configuration options
	speed: 800
});

Configuration

Here is a full list of available configuration options. You can also see these options by running the command console.dir($.tools.overlay.plugins.gallery.conf); from the console of the Firebug plugin in Firefox. These options are given for the gallery plugin and not for the overlay itself.

'<strong>${title}</strong> <span>Image ${index} of ${total}</span>'

Release Notes

  follow jQuery Tools on