A JQuery Progress Bar Plugin

While working on the imGoogleMaps upgrade, I realized that I had to add a progress bar. Rather than creating the progress bar functionality in imGoogleMaps, I decided to create a separate JQuery plugin – imProgressBar. It was simple to develop and easy to use – and I even took the time to create over 20 bar graphics.

Styling the Progress Bar

The imProgessBar has three containers that need to be styled: the progress bar container id , the progress bar back class, and the progress bar class. Each of these can be styled to your liking (width, height, border, etc).

#imProgBarCntnr {
  	float:left;
  	width:200px;
  	height:20px;
}
.imBarBack {
	float:left;
	width:150px;
	height:18px;
	background-color:#d8d8d8;
}
.imProgBar {
	float:left;
	height:18px;
	background: url(improgressbar/images/bar_sky_blue.jpg) repeat-x;
}

imProgBarCntnr is the parent container for the progress bar. This must be an id.

imBarBack holds the actual progress bar. It should be visible so the user knows the end point of the progress bar (the 100% mark). This must be a class.

imProgBar is the actual progress bar. I’m using an image in the example above, but you can use any styling (such as background-color). The plugin comes bundled with 21 different bar graphics, so it can match the color scheme of a variety of websites.

imProgressBar Display Options

The imProgressBar plugin has two display options: inline and popup.

When setting a display of inline, you must add an insert_type option. The values for insert_type are:

  • prepend – insert inside parent element before the first element
  • append – insert inside parent element after the last element
  • after – insert after a named element – can be either id or class (‘#id’, ‘.class’)
  • before – insert before a named element – can be either id or class (‘#id’, ‘.class’)

The popup option will automatically create a popup that is horizontally centered on the screen. You don’t have to worry about a popup blocker, because I’m actually just setting the z-Index of the main container to 99. When using the popup option, you can also specify the top value (the default is 20px).

When styling the main container for a popup progress bar, you don’t have to set the positioning style as this is done by the plugin:

#imProgBarCntnr {
  	width:200px;
  	height:20px;
        background-color:#000000;
}

Progress Bar Animation

Each increment of the progress bar is animated. You can set the animation duration and animation easing values. The default animation duration is 100 (.01 seconds). Depending upon the duration of the process, you may want to increase this value. The animation easing can be either ‘linear’ (the default) or ‘swing’.

Enabling the imProgressBar

To enable the plugin:

?View Code JAVASCRIPT
$(document).ready(function(){
	$('#mapInfo').imProgressBar({
		progress_bar: {'container': 'imProgBarCntnr', 'bar_back_class' : 'imBarBack', 'bar_class': 'imProgBar'},
		display: {'type': 'inline', 'insert_type': 'prepend'},
		animate_duration: 1500
	});
});

In this example, I using the plugin with the inline prepend option. The main container will be inserted before the first element in the mapInfo id container.

Initializing the Progress Bar

To start the progress bar, you must supply the plugin with the total (total records, etc). The plugin uses this information to determine how much to increment the progress bar. You send this information to the plugin using JQuery’s trigger method. The event for the trigger is ‘startProgress’. The progress bar will appear on the screen once this event is triggered.

?View Code JAVASCRIPT
$(window).trigger('startProgress', [ total_recs ]);

So you will trigger the event in your code once you know the total amount of records that need to be processed (and right before you begin processing).

Updating Progress

To update the progress (increment the progress bar), you also use JQuery’s trigger method, but this time the event is ‘updateProgress’.

?View Code JAVASCRIPT
$("div").each(function (i) {
     if (this.style.color != "blue") {
          this.style.color = "blue";
     } else {
          this.style.color = "";
    }
    $(window).trigger('updateProgress');
});

So first you tell the plugin how many records need to be processed, then after each iteration, you tell the plugin to update the progress bar. When the process is complete, the progress bar will automatically disappear from the screen.

Example

In the following example, I’m using setTimeout, to delay processing of a function.

?View Code JAVASCRIPT
$(document).ready(function(){
	var theCount = 0;
	var t_cnt = 0;
	var adrTime = null;
 
	$('#mapInfo').imProgressBar({
		progress_bar: {'container': 'imProgBarCntnr', 'bar_back_class' : 'imBarBack', 'bar_class': 'imProgBar'},
		display: {'type': 'inline', 'insert_type': 'prepend'},
		animate_duration: 1500
	});
	loadAddress();
	function loadAddress() {
		var total_recs = 5;
		t_cnt = 5; 
		//initialize progress bar
		$(window).trigger('startProgress', [ total_recs ]);
		getAdrLocation();
	}
 
	function getAdrLocation() {
		theCount++;
		//update progress bar
		$(window).trigger('updateProgress');
		if (theCount < t_cnt) {
			adrTime = setTimeout (function(){
				getAdrLocation();
			}, 5000);
		} else {
			clearTimeout(adrTime);
			//mapAddress();
		}
	}		
});

First I enable the plugin. The I get the total number of records and trigger the ‘startProgress’ to display the progress bar on the page. Then I update the progress bar with each iteration.

The imProgressBar can be downloaded from the JQuery Plugin site or Google Code. You can view demos of the plugin here.

Be Sociable, Share!

Checkout My New Site - T-shirts For Geeks