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. Unlike 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.
To activate BootsFaces BlockUI, add a context parameter to your
application's
web.xml
:
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 accidental 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.
Setting the parameter < f:param name="blockui.disabled" value="true"/>/f:param>
of a commandbutton deactivates BlockUI for this particular button. You can observe this in the next
demo if you open the web developer tools of your browser. Both requests take five seconds.
The first button triggers a standard AJAX request without BlockUI. The second button triggers the
same request with BlockUI. It shows a waitcursor, it grays the background, and it blocks input
until the request has been finished.
If blockUI is active, every AJAX request triggers
mouseOutEvent on the client.
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.
Use
$.blockUI.defaults
to configure BootsFaces BlockUI, as decribed here. For
instance, the code snippet below deactivates the gray-out-effect replaces it with 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.
BootsFaces doesn't trigger BlockUI on PrimeFaces components. You'll
have to use the
<p:blockUI />
component of PrimeFaces if you're using both frameworks in the same project.