Control.ProgressBar

Introduction

Control.ProgressBar is a percentage based progress bar that can be set to grow in one of three ways: on a timed interval, when events in your application tell it to, or it can be set to poll a given URL. The mechanism for action is simple, just create a div with relative or absolute positioning, attach the JavaScript, and this control will set the width of the inner element as necessary.

Example

The buttons below demonstrate one way of programatically controlling the progress bar.

HTML

	<div id="progress_bar"></div>
	<div style="margin-top:10px;">
		<input type="button" value="Start" id="progress_bar_start"/>
		<input type="button" value="Stop" id="progress_bar_stop"/>
		<input type="button" value="Reset" id="progress_bar_reset"/>
		<input type="button" value="+ 5%" id="progress_bar_step_5"/>
		<input type="button" value="+ 25%" id="progress_bar_step_25"/>
	</div>

JavaScript

	var progress_bar = new Control.ProgressBar('progress_bar',{
	    interval: 0.15
	});
	$('progress_bar_stop').observe('click',progress_bar.stop.bind(progress_bar));
	$('progress_bar_start').observe('click',progress_bar.start.bind(progress_bar));
	$('progress_bar_reset').observe('click',progress_bar.reset.bind(progress_bar));
	$('progress_bar_step_5').observe('click',progress_bar.step.bind(progress_bar,5));
	$('progress_bar_step_25').observe('click',progress_bar.step.bind(progress_bar,25));

CSS

	#progress_bar {
		width:102px;
		height:7px;
		border:1px solid #ccc;
		padding:0;
		margin:0;
		position:relative;
		background-image:url("/stylesheets/progress_bar.gif");
		background-repeat:repeat-x;
	}

	#progress_bar div {
		background-color:#fff;
	}

Style Notes

The container (in this case #progress_bar) must be absolutely or relatively positioned. The inner div is automatically created for you, and should be assigned a background color or image (in this case white). Do not assign a position, height, width, margin, padding or border to the inner element.

Instance

Return	Name	Description
Control.ProgressBar	initialize(Element container [,Hash options])
null	poll(string url [,number interval,Hash ajax_options])	Begin polling a given url at an interval (default 3000ms). URL should return an int between the 0 and 100 to set the progress percentage.
null	reset()	Also calls stop()
null	setProgress(number value)
null	start()	Start drawing the progress bar at the interval and step in the options hash.
null	step(number value)	Increment the progress bar by a given amount.
null	stop()
bool	active
Element	container
number	progress

Options

Type	Name	Default	Description
function	afterChange	function(){}
Hash	classNames	{active: 'progress_bar_active', inactive: 'progress_bar_inactive'}	The class names that get added and removed from the container depending on state.
number	interval	0.25	Default time in seconds between step() calls when start() is called.
number	max	100	Maximum width in pixels.
number	min	0	Minimum width in pixels.
number	step	1	Default step amount when start() is called.

Events

Name	Description
afterChange(number progress, bool active)	Called whenever the progress bar changes.