creates an overlay on the selected object(s) by selector. useful for long-waiting requests

util.helper.wait.js

/**
 * @author Christian Noel Reyes <[email protected]>
 * tested working with: >= jquery1.4.2
 * usage: 
 *   util.wait('.selectorClass'); // or #selectorID
 *   util.unwait('.selectorClass');
 */
var util = {
  wait: function(selector, options){
    var defaultOptions = {
      "message"          : "working...",
      "showLoadingImage" : true,
      "animate"          : false, // if true, requires the latest version of jquery and jqueryUI
      "animation"        : "fade",
      "speed"            : "slow"
    };

    var options = $.extend(defaultOptions, options);

    var objSet = $(selector);

    var success = 0;

    if(objSet.length == 0)
      return "no objects selected";
    else if(objSet.length == 1){
      success = util._waitApplyToObject(objSet, options);
    }else{
      for (var i = 0; i < objSet.length; i++) {
        success += util._waitApplyToObject(objSet[i], options);
      };
    }

    return success + " objects waiting.";
  },
  _waitApplyToObject: function(object, options){
    var object = $(object);

    if(object.data("waiterOverlay") != null){
      return 0;
    }

    var overlayHTML = 
      "<div class='waiterOverlay'>\
        <span></span>\
      </div>";

    var overlay = $(overlayHTML).css({
      "width"             : object.outerWidth(),
      "height"            : object.outerHeight(),
      "left"              : object.position().left,
      "top"               : object.position().top,
      "z-index"           : object.css("z-index") == "auto" ? 1 : object.css("z-index")+1,
      "position"          : "absolute",
      "text-align"        : "center",
      "background-color"  : "#D7EBF9"
    });

    if(options.animate){
      overlay.hide();
    }

    overlay.find("span")
      .text(options.message)
      .css({
        "line-height" : object.outerHeight() + "px"
      });

    if(options.showLoadingImage){
      var loaderImage = $("<img>");
      loaderImage.attr("src", "/images/ajax-loader-text.gif")
        .attr("alt", "loader")
        .css({
          "vertical-align" : "middle",
          "padding-right"  : "5px"
        });
      overlay.find("span").prepend(loaderImage);
    }

    object.data("waiterOverlay", overlay);
    object.after(overlay);

    if(options.animate){
      overlay.effect(options.animation, options.speed);
    }

    return 1;
  },
  unwait: function(selector, options){
    var defaultOptions = {
      "animate" : false,
      "animation" : "fade",
      "speed" : "slow"
    };

    var options = $.extend(defaultOptions, options);

    var objSet = $(selector);

    var objCounter = objSet.length;
    var objSuccess = 0;

    for (var i = 0; i < objSet.length; i++) {
      var obj = $(objSet[i]);

      var overlay = obj.data("waiterOverlay");

      if(overlay != null){
        if(options.animate){
          overlay.finish().effect(options.animation, options.speed, function(){
            this.remove();
          });
        }else{
          overlay.remove();
        }
        objSuccess += 1;
        obj.data("waiterOverlay", null);
      }
    };

    return objCounter + " found, " + objSuccess + " instances removed.";
  }
};