BlockUI since 0.8.1

While supporting the traditional AJAX style of JSF, BootsFaces also implements a new AJAX API that's a little simpler to use. Among other things, this includes a fairly opinionated BlockUI component. Our theory is you want to activate BlockUI with every AJAX request, so you only have to configure it. Other than other frameworks BootsFaces doesn't require you to activate BlockUI on every AJAX requests individually.

Most likely you've already suffered from mysterious errors caused by double-clicks. If you don't take precautions, JSF interprets the double-click as two individual clicks, and sends two requests to the server. Thing is, most users have learned over time that you can do everything with a double-click, and it hardly ever hurts. So they use the double-click even when it's superfluous.

As a solution, you can activate BlockUI. That's a component that prevents user interactions when an AJAX request has been started. The screen is darkened, and BootsFaces also shows a waitcursor by default. When the AJAX request has been completed, the screen is unlocked again.

BlockUI is based on the jQuery blockUI plugin.

Basic usage

To activate BootsFaces BlockUI, add a context parameter to your application's web.xml:

Conditional activation and deactivation

Once you've activated BootsFaces BlockUI, every AJAX request triggered by a BootsFaces component activates the waitcursor and prevents the user from doing further input until the request has been completed. This way, you get a fairly good protection against accidential double-clicks.

If you don't want to activate BlockUI generally, you can control it via an EL expression. Note that this expression is read when the page is rendered, and it's only read on non-AJAX requests.

AJAX, mouse events and BlockUI

If blockUI is active, every AJAX request triggers a mouseOutEvent. When the AJAX request has been processed and the BlockUI overlay pane is hidden, a mouseOverEvent is triggered. Keep this in mind if you need to use the mouse events.

Live demo

Live preview


Use $.blockUI.defaults to configure BootsFaces BlockUI, as decribed here. For instance, these lines deactive the gray-out-effect, and show the waitcursor of BootsFaces.

Hint There's a catch: the path of the image is relative to the URL of the current page. If you use nested folders, it may be difficult to guess the correct path.

PrimeFaces and other third-party-frameworks

BootsFaces doesn't trigger BlockUI on PrimeFaces components. You'll have to use the <p:blockUI /> component of PrimeFaces.