type: widget

release: 1.6 (Note: for the 1.6 release, we will only be building the determinate progressbars with and without internal labels (O1 and O2)

status: in planning

documentation: http://docs.jquery.com/UI/Progressbar

demo: http://jqueryui.com/demos/progressbar

 

 

 

---

 

1 - Description:

 

Progress indicators are meant to give a user feedback about the status of an operation that may not be instantaneous (completed in less than 500ms). Progress indicators can be placed in a wide range of UI contexts -- dialog box, page, menu or even within a form element. There are two basic types of progress indicators: determinate and indeterminate.

 

Determinate indicators provide specific feedback on where in the process the system is at any given time. These are usually shown as a horizontal bar that fills from left to right as the process heads towards completion and should fill completely when the process is complete. Variations of this indicator can range from a simple bar with or without labels (O1) to a bar with embedded text with the value complete (O2) or a segmented bar (O3) if the feedback is not continuous. A small circle that fills with a color can also be used as a determinate indicator (O7). A determinate progressbar should never cycle from empty to full to empty again on a timer - if the status of a process cannot be accurately tracked, an indeterminate progress indicator should be used.

 

Indeterminate indicators are used to provide feedback that a process is underway but that the current status cannot be tracked accurately enough to provide specific feedback on the current level of completeness. This can be displayed either as an animated bar with diagonal movement (O4) or a AJAX-style circular spinner (O5-6, O8).

 

In situations where multiple processes need to be completed sequentially, multiple progressbars can be used together. In the situation where a user is uploading multiple files, you could provide one progressbar for the total % complete and a second progressbar for the file currently being uploaded. In applications where multiple processes could happen in parallel, it's also possible to have a progressbar for each file.

 

The small, circular indicators are particularly useful for cases where you want to display the status of multiple steps in a sequence (like a wizard) in a list format where there may be a long name and there isn't room (or the need) for a full progressbar for each step. One advantage of this indicator is that it's also possible to mix and match indeterminate and determinate circular indicators if some steps have status feedback (like installing or downloading files) and other don't (saving data back to a web server) because these have both have the same size footprint. 

 

For a detailed explanation of progress indicators and best practices, please review Apple's human interface guidelines for progress indicators or Microsoft Vista UI guidelines for progressbars.

 

Official jQuery UI determinate progressbar widget:

(To be re-factored as part of this re-design)

http://docs.jquery.com/UI/Progressbar

 

Progress bar in the wild that uses only CSS3:

http://dipperstove.com/design/css3-progress-bars.html

 

Cross Browser HTML5 Progress Bars in depth:

http://www.useragentman.com/blog/2012/01/03/cross-browser-html5-progress-bars-in-depth/

 

---

 

2 - Visual design:

 

 

 

 

 

Design examples of 1.6 rc3 determinate progressbar options:

 

 

---

 

3 - Functional Specifications/Requirements:

This is a read-only widget for communicating status so there is no user interaction of any form with this widget. If the developer wants to allow a user to pause or cancel a process with an progress indicator, a separate button or link should be added for this purpose. The progressbar should be pretty "dumb" and just display the current % complete it's passed. The developer can write the logic to say once callback A is complete, then set progress to X% and that's it.

 

For the 1.6rc3 release, we are only building a determinate progressbar with no label.

 

Options:

- value (0.0-100.0) - type float, default 0, force a min of 0 and max of 100, no rounding for 1.6 release

 

Callbacks:

- change - occurs when value is changed

 

Methods:

- value - gets/sets value, equivalent of .progressbar('option', 'value', [x])

 

Notes for class toggling:

- When progress reaches 100 (or maybe 99), toggle the class on div.ui-progressbar-value from .ui-corner-left into .ui-corner-all. This will allow the right side of the progress fill to be rounded (which shouldn't happen until it fills to the edge of the bar).

 

 

---

 

4 - Markup & Style:

 

4.1 Initial markup examples

 

JavaScript:

 

HTML:

 

4.2 Recommended transformed HTML markup demo with html and css (live view of svn):

 

 

View demo page: http://jquery-ui.googlecode.com/svn/trunk/tests/static/progressbar/progressbar.html

4.3 Markup & style browser QA status

 

As of 12/12/08, static markup for this widget renders correctly in the following browsers.  (Correct rendering = true to design, with only small differences across browsers owing to differences in support of rounded corners, and native OS form element and font rendering.)

 

Please update this list as more browsers / platforms are tested.

 

	XP	Vista	Mac 10.5
IE 6
IE 7
IE 8 beta
Firefox 2.0.0.18
Firefox 3.0.4
Safari 3.2
Opera 9.1
Opera 9.62
Chrome 1.0

 

 

 

 

 

 

 

 

 

 

 

 

 

 

4.4 Accessibility recommendation

 

Progress indicators must have an ARIA role of progressbar.  Determinate progress indicators will also have aria-valuemin, aria-valuemax, aria-valuenow attributes.  The absense of aria-valuenow indicates that the progress indicator is indeterminate.

 

Labelledby or describedby attributes can be used as well to provide information about what action the progress indicator is reporting on.  This can reduce confusion if multiple progress indicators are being updated at the same time.

 

Progressbars should not use live regions.  See the free ARIA discussion about this.

 

4.5 CSS & Theme

 

The coded example above uses the new Themeroller framework classes. We use the Content Area bg and border for the unfilled progressbar and the Default state color, texture and border (at a % transparency) for the filled part of the progressbar. For the progressbar example with the embedded label (O2), it's important to use the proper text color classes that match the background it will sit over -- Content Area for unfilled, Default for filled -- or there may be serious legibility issues.

 

Both the animated inderminate progressbar and spinner graphics will not be easily ThemeRoller-ized because creation of animated gifs or flash movies is not currently supported. In the case of a gif, we woudl also need to know the background color to anti-alias the spinner against for transparency which gets fairly complex. The bar could always be a fairly neutral gray color as seen in the mockup (O4) but the spinner graphic is more of a challenge. Ideally, we could tie into an existing web service like AjaxLoad which already has this all figured out. 

 

 

---

 

6 - Open issues being discussed

 

None.

 

---

 

7 - Related jQuery Plugin:

 

http://plugins.jquery.com/project/jQueryProgressBar

http://digitalbush.com/projects/progress-bar-plugin/

http://mattberseth.com/blog/2008/07/jqueryui_progressbar_widget.html

http://beckelman.net/post/2008/10/05/jQuery-Progress-Indicators.aspx

http://plugins.jquery.com/project/progession

 

 

 

Closed issues 

• Adding an option to animate the background for a Mac-style progressbar. It would need to animate up, then down by 10-20px on a smooth loop. Some TR background will look better than others here, but I think it's a good idea. Do we have a standard way to animate background position in UI so this isn't baked into the progressbar? I can see that being nice for rollover states and other things. [Richard]: Animate could be tricky, so I'm not sure how I feel about it as a default.

  What if you update it while it's animating? Should it jump? If it doesn't, then it'll be behind. [Todd]: Ideally, it could just continue to animate to the newest position, maybe at a faster rate. Maybe we should create a new utility page for aniamte backgroud image to start hashing this out? [Todd]:After seeing Apple's doc, I think it's better to leave out animation and let the dev deal with smoothly incrementing if they want. 

• What are the options and defaults for the plug-in? Please fill out section 3 based on the discussions in dev. [Todd]: I editied down this section with the proposed info. Added value as an option because this wasn't included.

•  Which of the design mockups are in scope for the next release? Sounds like O1 and O2 at the moment, but there is the open quuestion of whether the secondary label in O2 is in scope. [Todd]: I created a new set ofmockups for each of the options in section 3. Please review and confirm these look right.

• It would be nice if our visualization utility could be tapped for some of these progress indicators. Particularly those that don't really map to divs very well, like the circular progress indicators could use a visualization utility similar to what we'd use to make a pie chart. When non-CSS skinning would need to occur, style options could be passed to the plugin, to be translated into canvas. [Todd]: This is out of scope for 1.6 rc3 but will be needed for the next iteration of this when we add spinners and circular indicators.

• Labels were removed because they were too complex.

 

---