Home > Articles > Open Source > Ajax & JavaScript

  • Print
  • + Share This
  • 💬 Discuss
Global AJAX Events

Global AJAX Events

The low-level $.ajax() function supports the well-known set of callback functions available with most AJAX libraries:

  • beforeSend is called before the request is sent. It could be used to display a request-specific loading indicator, or to set additional HTTP request headers in the XMLHttpRequest object.
  • error is executed when the web server returns an error status (HTTP status code >= 400).
  • success is executed when the web server returns a success status.
  • complete is executed after the completion of the AJAX request.

The beforeSend and complete functions are always executed (and can be used to indicate that an AJAX call is in progress/has been completed). Only one of the error and success functions is executed; you can use them to display error messages or format/insert the response data into the web page.

Aside from the callback functions, the jQuery library defines a number of browser-independent events that can be triggered before, during, or after AJAX calls. You can bind these events to any DOM element (they have a global scope anyway), and you should use the body element for consistency unless you have good reasons to decide otherwise.

The AJAX events ajaxComplete, ajaxError, ajaxSend and ajaxSuccess closely match the callback functions. The ajaxStart and ajaxStop events add interesting new functionality when you're executing multiple parallel AJAX requests: jQuery triggers ajaxStart event when the first AJAX request starts and ajaxStop event when the last event completes. This pair of events is thus ideal if you want to display page-wide loading indicators.

We'll use the ajaxStart, ajaxStop, and ajaxError events in the FAQ application to display visual cues to the user:

  • The ajaxStart event displays an opaque layer covering the whole web page and a dialog box with the loading indicator.
  • The ajaxError event changes the formatting of the dialog box and its message. It also triggers an automatic close of the box in three seconds. (To keep the sample code simple, I've decided to omit the OK/Cancel buttons.)
  • The ajaxStop event hides the opaque layer and the dialog box. As it's executed after the ajaxError event, it has to check the dialog box status to ensure that the error indication remains visible.

The code for all three events is included below:

function startAjax() {
  var canvas = $("#modalCanvas");
  var msg = $("#loadingMessage");
  if (msg.attr("initial")) msg.text(msg.attr("initial"));
  if (!canvas.length) {
    canvas = $("<div id='modalCanvas'>").appendTo("body");
  }
  canvas.show();
  $("#loading").show();
}

function stopAjax() {
  var loading = $("#loading");
  if (!loading.is(".errorDialog")) loadingCompleted();
}

function failedAjax() {
  $("#loading").addClass("errorDialog");
  var msg = $("#loadingMessage");
  msg.attr("initial",msg.text());
  msg.text("Server request has failed");
  setTimeout(loadingCompleted,3000);
}

function loadingCompleted() {
  $("#loading").hide().removeClass("errorDialog");
  $("#modalCanvas").hide();
}

The AJAX events are bound to the document in an anonymous initialization function, which supersedes the call to loadCategories function we've used previously:

$(function() {
  $("body").ajaxStart(startAjax)
           .ajaxStop(stopAjax)
           .ajaxError(failedAjax)
  loadCategories();
});
  • + Share This
  • 🔖 Save To Your Account

Discussions

comments powered by Disqus