Expose

Start entering text on the input fields below and you'll see the masking effect:

The story

Expose is a JavaScript tool that exposes selected HTML elements on the page so that the surrounding elements will gradually fade out. The exposing effect was first introduced in the overlay tool. Usually the effect is an integral part of the program and cannot be used separately. This tool takes the idea of exposing a little further. It is a separate tool that can be used as a general purpose masking utility. You can use it for overlays, forms, images, videos or Flash objects. You can use CSS to tweak the look of the mask.

Usage

Here are some most common ways of using the mask:

// place a white mask over the page
$(document).mask();
 
// place a custom colored mask over the page
$(document).mask("#789");
 
// place a non-closable mask
$(document).mask{ closeOnEsc: false, closeOnClick: false });
 
// place a mask but let selected elements show through (expose)
$("div.to_be_exposed").expose();
 
// close the mask
$.mask.close();

JavaScript

There are two different calls: mask and expose. The mask method is only available for the document object and you cannot use any other selector. The expose() method can take any jQuery selector and all elements returned by the selector are placed on top of the mask.

The mask is loaded immediately after the expose or mask call. You can supply a different configuration on each call and the latest call is remembered. A subsequent expose call for example will use the previously used configuration if no arguments are given.

You can also use an existing element as a mask. By default the tool uses an element whose id is exposeMask and if it does not exist already exist then it will be created automatically.

Demos

We believe that the best way to learn is through demos. The following demos are fully documented and a standalone page is provided to get mask working on your site. It's really important to study the first demo "Minimal setup for mask" because it teaches you the basics of using the library.

Expose and Flowplayer demos

These demos show how to use a video player together with the mask tool:

These graphics are being used as the mask's background image. JPG versions are smaller, but they have a fixed background color. PNG images are larger, but you can use any background color in them. Here is a cool example where the mask's background image has been changed.

expose 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

Here is a full list of available configuration options:

property	default	description
closeOnClick	`true`	Specifies whether the masking disappears when the mask is clicked. By default, this is set to `true`.
closeOnEsc	`true`	Specifies whether masking disappears when the `ESC` key is pressed from the keyboard. By default, this is set to `true`.
closeSpeed	`'fast'`	How quickly the mask disappears. Possible values are 'slow', 'normal' and 'fast or you can supply the number of milliseconds. For example, a value of 2000 will cause the mask to disappear in 2 seconds. By setting this to zero there is no animation and the mask disappears immediately.
color	`'#fff'`	The background color of the mask. This will dramatically affect how it appears. If you supply a value of `null` here, you can control the background color with CSS. See the `maskId` property below for more information.
loadSpeed	`'slow'`	How quickly the mask will appear. Possible values are 'slow', 'normal' and 'fast or you can supply the number of milliseconds. For example, a value of 2000 will cause the mask to appear in 2 seconds. By setting this to zero there is no animation and the mask appears immediately.
maskId	`'exposeMask'`	The mask is a normal `div` element placed on top of your page and whose size is automatically adjusted to cover the user's screen completely. You can style it normally with CSS just like any other element on the page. By default, the mask's `id` is set to `mask`, but you can change that with tis configuration option. Since version 1.2.0 you can use an existing element as the mask if it's id matches the one given in this configuration option.
opacity	`0.8`	The transparency setting of the mask. A decimal value from 0 to 1. A bigger value means less transparency while a value of 0 is fully transparent (invisible).
startOpacity	`0`	since 1.2.0. The initial transparency level of the mask before it starts fading in to the desired opacity as specified by the `opacity` option. A decimal value from 0 to 1. A bigger value means less transparency while a value of 0 is fully transparent (invisible). For example, you can start with full opacity and gradually fade to a semi-transparent mask.
zIndex	`9998`	This is the z-index CSS property for the mask. The `zIndex` specifies the placement of the element along the z-axis of the document. 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.

onBeforeLoad		This callback function is triggered before the masking effect. Returning `false` or calling `event.preventDefault()` in the callback prevents masking from occurring.
onLoad		This callback function is triggered after masking takes place.
onBeforeClose		This callback function is triggered before mask is closed. Returning `false` or calling `event.preventDefault()` in the callback prevents it from closing.
onClose		This callback function is triggered when mask is closed.

Here is an example of an onBeforeLoad callback function given in configuration. Inside any callback function the this variable is a pointer to the mask scripting API.

  $("#mydiv").expose({
 
  // before masking begins ...
  onBeforeLoad: function(event) {
 
  // grow the exposed elements smoothly by 100 pixels
  this.getExposed().animate({width: '+=100'});
  }
  });

JavaScript

Note: unlike other jQuery Tools you can supply callbacks only from the configuration and you can assign only one callback for the same event.

Scripting API

Unlike other jQuery Tools in this library the mask is a singleton. Only one mask instance can exist at any given time. This singleton can be accessed directly with $.mask or via the this variable inside callback functions.

Method listing

method	return value	description/example
close()	`API`	Closes the mask.
fit()	`API`	Forces the mask to fill the whole document. This is usually not needed since the tool itself does this. You'll need this on occasions when the mask is loaded and your document has grown in size in the meantime.
isLoaded(fully)	`boolean`	Returns `true` if mask is loaded. Since 1.2.4 you can supply a boolean argument that makes sure that the function returns `true` only if the mask is fully visible in it's final position and opacity.
getMask()	`jQuery`	Returns the mask as a jQuery object. You can use jQuery methods such as `css` or `animate` to modify it.
getExposed()	`jQuery`	Returns exposed elements (if any) as a jQuery object.
getConf()	`Object`	Returns the masking configuration.