The announcement from Microsoft regarding its contribution to the jQuery project led many developers and project managers to welcome jQuery into large corporate projects. All of a sudden, dozens of jQuery plug-ins started being perceived under a different and much more positive perspective. In this article, I examine a jQuery plug-in that is incredibly useful to block the user interface until a given operation -- typically, a background server operation -- is terminated. You can find the BlockUI plug-in here.

The need for such a plugin can be traced back to the advent of the AJAX paradigm. Whenever you start an AJAX operation -- regardless of it being your own plain script or the script injected by some ASP.NET controls -- you often want to prevent the user from taking certain actions that are in conflict with the one going on. More often than not, you don't want to block the entire user interface, but just a section of it such as a DIV or a smaller element. The expected behavior is easy to formalize; it is much less easy to implement in a fully reusable way. All you want is, disabling clickable elements, providing visual clues of disablement, optionally display a "Work in progress" message. Finally, you want everything to return to the initial state as soon as the AJAX operation terminates. Years of trial-and-error demonstrated that the best way of achieving this is by overlaying the section of the page to disable with a (semi)transparent HTML block that is removed at the end of the operation or when some other script is run. BlockUI simply makes blocking segments of the user interface of Web page a breeze. Let's see how. Needless to say, first you make sure you reference the library, as shown below:

<script type="text/javascript" src="jquery.blockui.js" />

Updated in the Spring of 2010, the latest version of blockUI supports jQuery 1.4.2. The plug-in has two main working modes: it can block the entire page or a DOM sub-tree.

To block the entire page you use the $.blockUI and $.unblockUI functions. Here's some sample code that blocks the page when you click on a button named btnStart. The code also unblocks the user interface as you click anywhere on the blocked page:

$(document).ready(function() { 
    $("#btnStart").click(function() { 
        $.blockUI(); 
        $(".blockOverlay").click($.unblockUI); 
    }); 
});

The .blockOverlay string is an internal name to refer to the DIV displayed to cover the page. When you call $.blockUI without further parameters it grays out the browser's client area and centers a "Please wait" message in the screen. You can change overlay effects and message by adding parameters to $.blockUI. Alternately, you can define new default settings for the $.blockUI function to use when called in a parameterless way. Here's how to specify parameters in an individual call:

$.blockUI( { message: "Loading"} );

And here's how to set new default settings for the message attribute:

$.blockUI.defaults.message = "Loading...";

When you choose to disable the entire page, then most of the time you want the success callback of the asynchronous operation to unblock the page. The full list of properties supported by blockUI can be found here.

To block only an element within the page, you resort to a slightly different API: block and unblock. The following code shows how to block the content of a DIV tag.

$("#myForm").block({ message: "Processing…" });

To unblock, you need the following:

$("#myForm").unblock();

In this case, the trigger of the unblocking code will likely be the click handler of another link or button around the page or perhaps a timer.