Description
This jQuery plugin provides access to the onprogress event of the XMLHttpRequest
object available
in modern browsers.
This allows you to get the information needed to visually show download progress when your web application is making a large AJAX request.
The code has been tested in recent versions of Chrome/Chromium and in Firefox 4.
Dependencies
This plugin requires jQuery 1.5 or higher.
How to use
Add the script to the page's list of <script>
tags after the jQuery reference.
In your page code, check the value of jQuery.support.ajaxProgress
. If this value is false, then the browser doesn't
support the onprogress
event, so you'll have to write fallback code (for example, showing a generic progress spinner
instead of a percentage).
The onprogress
event passes to its handlers a native object conforming to the
ProgressEvent interface:
The ProgressEvent object
The interface has the following fields
{Boolean} lengthComputable
- true if the size of the response is known. This is usually known if the server sends aContent-Length
header.{Number} loaded
- the number of bytes loaded so far{Number} total
- the total number of bytes in the response.
The plugin exposes the onprogress
event in two ways:
Global AJAX Event
As a global AJAX event that you can subscribe to. You can set a handler on any jQuery selection in the DOM, and it will get triggered for all AJAX requests.
$("#loading").bind("ajaxProgress", function(jqEvent, progressEvent, jqXHR) {
if (progressEvent.lengthComputable) {
$(this).text("Loaded " + (Math.round(progressEvent.loaded / progressEvent.total * 100)) + "%");
} else {
$(this).text("Loading...");
}
});
The handler signature is function ( jqEvent, progressEvent, jqXHR )
, where jqEvent
is the the event object created by
jQuery, progressEvent
is the native ProgressEvent object described above, and jqXHR
is the original
wrapper around the XMLHttpRequest object.
Local AJAX Event
You can also provide a handler for a specific jQuery.ajax()
call by including a progress
field in the options
object you pass to jQuery.ajax()
.
$.ajax("/myfile", {progress: function(jqXHR, progressEvent) {
if (progressEvent.lengthComputable) {
console.log("Loaded " + (Math.round(progressEvent.loaded / progressEvent.total * 100)) + "%");
} else {
console.log("Loading...");
}
}});