Control.ProgressBar

CSS based progress bar widget for Prototype.js

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.

Code Sample

<div id="progress_bar"><div></div></div>
<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"/>
<script>
    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));
</script>
<style>
#progress_bar {
    width:102px;
    height:7px;
    border:1px solid #ccc;
    padding:0;
    margin:0;
    position:relative;
    background-image:url("progress_bar.gif");
    background-repeat:repeat-x;
}
#progress_bar div {
    background-color:#fff;
}
</style>

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.

How to Read the API Table

Anything in the method and property lists that ends with "()" is a method, and anything that doesn't is a property. All events are specifiable in the options hash, or via "observe()" if Object.Event has been included on the page before Control.ProgressBar was. In a method signature, each argument is separated by a comma, if the words are lower case it refers to the data type and gives a hint to what it is used for, if there is an upper case word it refers to the class of object that must be used. Arguments with [square brackets] around them are optional.

Class Methods and Properties

ReturnNameDescription
Control.ProgressBarinitialize(mixed container_id [,options Hash])
voidsetProgress(int value)
voidpoll(string url [int interval])Begin polling a given url at an interval (default 3 seconds). URL should return an int between the 0 and 100 to set the progress percentage.
voidstart()Start drawing the progress bar at the interval and step in the options hash.
voidstop()
voidstep(int amount)Increment the progress bar by a given amount.
voidreset()Stop the progress bar and reset it.
Elementcontainer
intprogress
booleanactive

Options

TypeNameDefaultDescription
functionafterChangefunction(){}
intmin0Minimum width in pixels.
intmax100Maximum width in pixels.
floatinterval0.25Default time in seconds between stepping when start() is called.
intstep1Default step amount when start() is called.
HashclassNames{active: 'progress_bar_active', inactive: 'progress_bar_inactive'}The class names that get added and removed from the container depending on state.

Events

All events can be passed in as an option, or if Object.Event has been included, they can be observed by calling Control.Tabs.observe() to observe all instances, or by calling observe() on any particular instance to just observe that one.

NameDescription
afterChange(int progress, boolean active)Called whenever the progress bar changes.

RSS Changelog

Is available at http://livepipe.net/projects/control_progress_bar/changelog.rss

Downloads & SVN

The Control Suite subversion repository is available at: svn://livepipe.net/control_suite/

Other Resources

Have you written a post or article about Control.ProgressBar? Please contact me!