jQuery Tools / Overlay - Overlay your HTML with eye candy
Demo. Click on the image
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.
- Minimal setup for overlay
- Trigger overlay programmatically
- Overlays with different styles
- Multiple overlays on a same page
- Loading external pages into overlay
- Overlay together with expose tool
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.
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) |
{
|
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:
|
finish (Object) |
{
|
The final position of the overlay after the growing animation finishes. Again, you can override this default using the following properties:
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. |