busyProcess: a visual indicator for long JavaScript tasks

Some time ago I wrote an article to demonstrate a simple method of displaying a processing/loading indicator for Ajax requests using prototype. That works great for Ajax requests, but let's assume you have some CPU intensive task that will be processed on the client side in JavaScript. This task will take several seconds to complete and you want to add some sort of visual indicator to the page while it's working so the user knows something is happening. enter the busyProcess function. You could code your particular JavaScript task to display a processing indicator itself and remove it when it's done, however there are two problems you'll encounter. First, you'll probably never see the processing indicator since your task will immediately do its thing and not give control back to the browser in order to display the indicator before the task finishes and your code removed the indicator. Second, you'll end up adding the same code over and over around each function that may take a while to complete (DRY - Do not Repeat Yourself!). busyProcess handles both of these situations. It is a flexible wrapper for any function passed in to it so that it can be used for any task, and it defers the execution of the function in order to allow the browser to render the visual indicator. Example Click this to be busy for 3 seconds. Get to the code already!

/**
 * busyProcess
 * 
 * Add a busy indicator over an element while running the function it invokes
 * @param {Object} element clicked on to invoke the task
 * @param {Function} function to invoke after adding visual indicator
 */       
function busyProcess(element, func) {
   var busyIndicator = new Element("div", {id: "busy"});
   busyIndicator.setStyle({zIndex: "100",
                           position: "absolute",
                           fontWeight:"bold",
                           height: "16px"});
   Position.clone($(element), busyIndicator, {setWidth: false, setHeight: false});
   busyIndicator.innerHTML = '<img src="images/wait.gif" style="width:16px;height:16px;" /> Processing...';
   document.body.appendChild(busyIndicator);           

   // function needs to be deferred in order for the browser to render the
   // busy indicator, but we need to wrap it in order to remove the busy indicator
   // when it's done
   func = func.wrap(
      function(proceed) {
         proceed();
         busyIndicator.remove();
      });
   func.defer();
}

Ok, so how does it work? The function takes in two arguments. The first is the element clicked on. This is used as the location of the popup processing indicator as the item clicked on is what invoked the action for the user. Since the prototype $() function is used, this can be an element id as well. The second argument is the function to invoke. busyProcess starts by building the processing indicator. This can be customized to your preferences. Just be sure the indicator has a z-index greater than anything other layers on the screen, and that is has absolute positioning. I then utilize the prototype Position.clone to position the indicator over the element clicked on. Now we get to the more interesting part. The indicator needs to go away when the task is done. But how do we know when it's done? You could make the task issue a custom event and register an event listener here to catch it in order to remove the processing indicator. However, then any function you use busyProcess with will need to issue that event when it's done. That could get messy, and easy to forget. So, instead we wrap the original function to have it remove the processing indicator when it's done. So, how do you use this? For a simple example, let's assume we want to sort some large table by different columns when the user clicks on little triangle icons indicating ascending or descending. For simplicity I'm just going to add the code inline on an onclick attribute in the HTML. As a general practice I usually try to register event handlers in my JavaScript code so that the HTML has no JavaScript in it.

<td id="zipcode">Zip Code
<img src="images/sort-asc.gif" alt="ascending sort icon" 
     onclick="busyProcess(this, function() {sortTableBy(this.up('td').identify());}.bind(this));" />
</td>

I intentionally made that a little more complicated than it had to be just to demonstrate that you can use inline anonymous functions as well. Optional (but useful) addition In order to give a more obvious indication that work is being done and to prevent the user from clicking on anything else until it's done you may want to either darken or lighten the rest of the page. To do this, add another layer at the beginning of the busyProcess function like:

   var lightenScreen = new Element("div", {id: "lightenScreen",
                                          'class': "lightenBackground"});
   document.body.appendChild(lightenScreen);           

where the lightenBackground class is defined in CSS as:

.lightenBackground {
    background-color: white;
    opacity: 0.5; /* Safari, Opera */
    -moz-opacity: 0.50; /* FireFox */
    filter: alpha(opacity = 50); /* IE */
    z-index: 20;
    height: 100%;
    width: 100%;
    background-repeat: repeat;
    position: fixed;
    top: 0px;
    left: 0px;
    cursor: wait;
}

or the corresponding darkening version:

.darkenBackground {
 background-color: black;
 opacity: 0.2; /* Safari, Opera */
 -moz-opacity: 0.20; /* FireFox */
 filter: alpha(opacity = 20); /* IE */
 z-index: 20;
 height: 100%;
 width: 100%;
 background-repeat: repeat;
 position: fixed;
 top: 0px;
 left: 0px;
 cursor: wait;
}

Just be sure to remove this layer as part of the wrap by adding the line: lightenScreen.remove();