jsProgressBarHandler (Dynamic Unobtrusive Javascript Progress/Percentage Bar)

Overview



What is jsProgressBarHandler ?

jsProgressBarHandler is a Javascript based Percentage Bar / Progress Bar, inspired upon JS-code by WebAppers and CSS-code by Bare Naked App. Next to a structural rewrite of the WebAppers code, this javascript progress bar can easily be extended and tweaked just by setting a few parameters.

jsProgressBarHandler

jsProgressBarHandler has been tested and verified working in IE6, IE7, FireFox 2 and Safari 3.0.3. Other browsers should work fine too (untested though).

top



Demo

jsProgressBarHandler Demo

top



Download

Please download the latest version below:

Latest Version

Archived Versions

jsProgressBarHandler 0.3.2 was never released so you won't find it here ;)

Don't forget to read the License & usage and Installation/Configuration blocks on this page! ;)

top



Version History

Version 0.3.3 - 2008.11.10

  • UPD: fixed IE compatibility issue (thanks Kevin - Sep 19 2008 / 6pm)
  • UPD: setPercentage now parses the targetPercentage to an Integer to avoid infinite loop (thanks Jack - Sep 07 2008 / 9pm)
  • UPD: Moved from Event.Observe(window, 'load', fn) to document.observe('dom:loaded', fn) in order to force people to use an up to date Prototype release.
  • UPD: setPercentage now takes an overrideQueue param. If set the current queue is cleared.
  • ADD: Added onTick callback event which gets called when the percentage is updated.
  • ADD: Added stable (as in "non-crashing") versions of the additions which first surfaced in the (unreleased) 0.3.2 release
    Preloading support partially implemented in IE as all versions (IE6,7&8) are quite hard to tame (one time they work, the next reload they don't anymore)

Version 0.3.2 - 2008.04.09 (*UNRELEASED*)

  • ADD: implemented preloading of images to avoid slight flicker when switching images (BUGGY!)
  • ADD: percentage image now has class percentImage and percentage Text now has class percentText; This allows you to style the output easily.

Version 0.3.1 - 2008.02.20

  • UPD: fixed queue bug when animate was set to false (thanks Jamie Chong)
  • UPD: updatedPrototype to version 1.6.0.2

Version 0.3.0 - 2008.02.01

  • ADD: animation queue, prevents from the progressbar getting stuck when multiple calls are made during an animation
  • UPD: multiple barImages now work properly in Safari

Version 0.2.1 - 2007.12.21

  • ADD: option: set boxImage
  • ADD: option: set barImage (one or more)
  • ADD: option: showText

Version 0.2 - 2007.12.13

  • SYS: Total rewrite of jsProgressBarHandler, now comes in two classes
  • ADD: Configuration Options (animate, width, height)

Version 0.1 - 2007.08.02 - * INITIAL RELEASE *

  • Basic rewrite of the webappers.com version

top


License & usage

The script is now released under a creative commons Attribution-ShareAlike 2.5 license. Should you use the script within a commercial context please think about clicking the PayPal donate button.

top


Installation/Configuration

Working with Ruby on Rails? Then check out Progress Bar Helper, written by Thomas Gendulphe

Progressbars can either be manually created, or automatically.

Automatic Creation of Progress Bars

  1. Include the needed javascript (2 files) in your HTML document (included in download)

    HTML:
    1. <!-- jsProgressBarHandler prerequisites : prototype.js -->
    2.     <script type="text/javascript" src="js/prototype/prototype.js"></script>
    3.  
    4.     <!-- jsProgressBarHandler core -->
    5.  
    6.     <script type="text/javascript" src="js/bramus/jsProgressBarHandler.js"></script>
  2. The elements you want to change with a dynamic progressBar must be scripted as this:

    HTML:
    1. <span class="progressBar" id="myElementId">15%</span>

    • Yes, it must be a span element
    • progressBar is the className that will trigger jsProgressBarHandler to change it with a progress bar
    • the id (myElementId in the example) must be unique (as per HTML specification) and is required for jsProgressBarHandler to work properly
    • the innerHTML of the element must be the percentage (either with or without the &proc; character)
  3. You might want to edit the first few lines (#28-35) of js/bramus/jsProgressBarHandler.js to change some settings like width, height, animation and the images to use
  4. That's it, you're done!

Manual Creation of Progress Bars

  1. Include the needed javascript (2 files) in your HTML document (included in download)

    HTML:
    1. <!-- jsProgressBarHandler prerequisites : prototype.js -->
    2.     <script type="text/javascript" src="js/prototype/prototype.js"></script>
    3.  
    4.     <!-- jsProgressBarHandler core -->
    5.  
    6.     <script type="text/javascript" src="js/bramus/jsProgressBarHandler.js"></script>
  2. Create a container (viz. a regular HTML element like a paragraph or a span) in your HTML file to hold the progressbar. Make sure it has an id set.

    HTML:
    1. <div class="percentImage1" id="hereComesMyFirstProgressBar">[ Loading Progress Bar ]</div>
  3. If you're using the default markup used (with span elements which has progressBar as className), then edit js/bramus/jsProgressBarHandler.js and set the var autoHook to false (line #25)
  4. Create a new JS_BRAMUS.jsProgressBar instance by adding this javascript to your HTML page (the code will be executed when the DOM is done loading):

    JavaScript:
    1. Event.observe(window, 'load', function() {
    2.     firstManualPB = new JS_BRAMUS.jsProgressBar($('hereComesMyFirstProgressBar'), 50, {animate: false, width: 240, height: 24});
    3.     secondManualPB = new JS_BRAMUS.jsProgressBar($('hereComesMySecondProgressBar'), 10, {animate: true, showText: false});
    4. }, false);

    • The first param is the element to create the progressbar in
    • The second param is the (intial) percentage the progressbar should hold
    • The third param is optional and holds a specific configuration for that instance. Parts of this object can be omitted (and parts of the default options will be used instead), or the param can even be dropped (the full default options will be used)
  5. You might want to edit the first few lines (#28-35) of lib/jsProgressBarHandler.js to change the default settings for width, height, animation and the images to use
  6. To configure an onTick callback function, please read the post introducing jsProgressBarHandler 0.3.3 ;)
  7. That's it, you're done!

top


FAQ

Coming soon:

  • How can I implement my own images?
  • How can I create a multi-colored progress bar? (tip: options.barImage)
  • How can I invoke a certain action when a certain percentage is reached? (tip: options.onTick - see this page for now.)

top


Feedback/Support

One can always leave a comment in case any questions should arise or if a bug were to be found; and one can always support me by donating me a tidbit to my paypal ;)

top


Make a donation

It certainly is no obligation but it would most certainly put a smile on my face ;) Alternatively you can support me by clicking one of the ads below.

Advertisements

Spread the word!

  • del.icio.us
  • digg
  • Ma.gnolia

About this Page

Best of Bram.us