Progress Bar

The following examples of the ProgressBar show several of its features. The values set in the floating box to the left will affect all of the bars below. All bars have the properties minValue and maxValue left in its default of 0 and 100. Values outside of this range will be ignored.

This bar was created by the following statements:

The argument to the render method is the id of the container where the bar will render.

The shape and colors are the result of style definitions. That is why I provided a className attribute to be assigned to the ProgressBar, so that I can qualify the CSS selectors to have them applied to this instance.

In the first one I'm changing the default height, leaving the width to the internal default (200px). The CSS selector .plain.yui-pb is redundant, .plain would be enough.

The second definition sets the image that provides the rounded corners to contain the bar, the mask. The image needs to be in a format that supports transparency, either GIF or PNG. The image is layered over the bar so it needs to be transparent wherever the bar is to show through.

The mask can be stretched and shrunk as needed. The actual mask.gif image is 400*32px but here it is shown in 200*25px, the ProgressBar handles the scaling. The third definition provides the image to be used for the bar. It will be tiled to fit the space needed so it needs to be designed with a repeating tileable pattern.

You have access to the actual HTML elements that make up the ProgressBar so you can do some limited styling via code:

Size attributes can be given as strings with explicit units or numbers which will be interpreted as pixel sizes. Once the ProgressBar is rendered, the individual elements can be styled. We set the background color of the bar element to green. The whole ProgressBar is an instance of YAHOO.util.Element so, for the overall container of the widget, we can set the style by using Element's own methods like setStyle

The ProgressBar is not limited to show only progress of an operation, it can show anything a bar can show. It can be tricked to show discontinuous values such as this example of song rankings, where the bar is actually a set of discreet stars which can show values in half a star increments.

Song	Artist	Ranking
Carolan's Frolic	Richard Searles
Jeux d'enfants	Cirque Du Soleil
Foliada dos Aires da Terra	Carlos Núñez

The code for the first cell is:

and the bar background image has been set to an image with a single star which is tiled as needed.

Progress bars don't need to be static either. They certainly cannot replace the Chart utility but you can do some decent graphics with them, even animated ones.

Here we draw a set of several Progress Bars moving from bottom to top, with the background image for the bar set to an image of the bar fully extended, which will be uncovered depending on the value of the bar. We are using the Bezier utility to make neighboring bars move in a more coordinated way than just assigning them random values. We calculate 4 random control points for the bars, no matter how many bars there are. The Bezier function will interpolate intermediate values for the bars. On completion of one animation, we set new control points at random, calculate the new values and get them moving again.

The bar itself is always a rectangle. To give it different shapes and borders, a mask is used. The mask should be a GIF or PNG file with transparency where you want the bar to show through. The mask can be opaque in the corners and transparent in the center, as in previous examples or you can also play with transparency and opaqueness anywhere in the graphics like the bar above.

The ProgressBar does not scale the mask via the width and height attributes of the img tag. For very fine detail, like thin lines, edges, grids and borders, this scaling gives poor results. Instead, it cuts the given mask vertically and horizontally right through the center of it and uses each corner separately. These four sectors slide to and from the center lines. If the mask has a repeating pattern, as this one has, you have to make sure that the width and height given are integer multiples of the basic pattern, otherwise it will not tile correctly. In this example, I have made the width and height one pixel wider and higher than it should have been. If you look at the center, you will see that the holes in the grid on the vertical and horizontal lines coming out from it are different in size from the others

By the way, hopefully you might have noticed this bar grows from right to left

This bar uses a mask that is not symmetrical in any way. It cannot be scaled. If you try to make it any different width, the ruler at the bottom will either have no 5 or have two of them if you shrink it further the 4 and 6 will disappear and so on. The bar, which looks like a wedge, is actually rectangular as it always is. The mask has a wedge-shaped opaque area in the upper-left corner, which is the same color as the page background. The bar is not tiling. The bar is a single image, the bar shows whatever needs of it. Here you have them both over a light gray background with blue borders around the two images:

The ProgressBar has been further suplemented with the current value. The ProgressBar always generates the caption, but the container assigned to hold it is normally hidden. To make it show, you just have to un-hide it and possibly assign a suitable font:

The mask for this bar has some fancy caps at both top and bottom ends, those blue rounded things at each side. The bar cannot go from edge to edge of the ProgressBar container because it would hide behind the areas taken by those caps at the ends. To reserve space for them, we use the margin CSS attribute given along the image to be used for the bar, in this case, we are leaving 10 pixels at the left and right ends of the bar:

The bottom of the empty area of the bar is the same silver background as the rest of the area around it, it simply looks deeper than the rest because of the inset shading of the mask.

ProgressBars can grow in any direction, as set by the direction attribute, which can take values 'ltr' (left to right, the default), 'rtl', 'ttb' (top to bottom) or 'btt', as in this sample.

If the Animation utility is available, the anim attribute can be set to true to enable it. The instance of Animation in use is available in the anim attribute. You can set the attributes of the animation like duration or method.

The caption for the bar can be shown anywhere, not just overlapping the bar. Any suitable container can hold the caption, which needs to be assigned to property captionEl, like right here: . Change the value of the bar in the box in the left-top box and see it change.

The text shown on the caption can also be altered by setting the textTemplate configuration attribute. This attribute will be processed via YAHOO.lang.substitute. The ProgressBar makes the values of minValue, maxValue and value available for replacement.

This is the code for this bar:

These settings make the bar grow from bottom to top, to last 3 seconds to make any changes and use the bounceBoth easing method.

The space left blank by the bar is not transparent as in the previous examples. I have set a further background which shows in the 'empty' area. This was set through the following style:

The Progress Bar also fires some events when it changes values and also while it changes. Below, you can see the value of the bar above, updated while it is being changed.

This is done with the following code:

We could have almost achieved the same simply by using the caption container and text template. We did it this way just to make some visible changes to reflect the events. An obvious target of these events might be the color of the ProgressBar elements themselves, such as the bar, as has been shown in a previous example, according to the value.

So, in the end, we have four layered levels in the ProgressBar, the CSS selectors for each of the layers, from bottom up, are:

.yui-pb /* The area within the transparent section of the mask not covered by the bar */
.yui-pb-bar /* The bar itself */
.yui-pb-mask div /* The mask that will let the bar be seen through its transparencies */
.yui-pb-caption /* The container for the textual representation of the value */

There is a further selector to set the image of the bar while it is moving (provided the Animation utility is loaded) which is selected via the selector:

.yui-pb .yui-pb-anim

The composite selector is to give it higher priority over the normal .yui-pb-bar selector for the bar. The !important declaration can be used instead.

WAI-ARIA support

The ProgressBar supports WAI-ARIA as specified for the "progressbar" role, see: W3C spec. The ProgressBar container has tabIndex="0" and has role and role-specific settings as described in the document.

Since the ProgressBar cannot know what concept the value corresponds to, it cannot, on its own, provide a meaningful aria-valuetext text. The textTemplate setting allows the implementer to set a text to be used for that setting, the same one used for the caption. Unlike the caption, which changes while the bar is animated, the aria-valuetext is only changed upon completion of the change, otherwise, the continuous changes might overwhelm the screen reader.

API

The ProgressBar has no public properties, all settings are handled through methods get and set

Configuration Attributes

value: Numeric, default: 0, the value that will be represented by the bar
minValue: Numeric, default: 0, the minimum value for the bar. Settings of value below this will be ignored
maxValue: Numeric, default: 100, the maximum value for the bar. Settings of value above this will be ignored
width and height: Any valid CSS width specification, defaults 200px wide, 20px high, a string including standard CSS units or any numeric value (which will be interpreted as pixel sizes
direction: Either 'ltr' (default), 'rtl', 'ttb', 'btt', sets in which direction the bar will grow from (left, right, top or bottom) in which direction. Once set it cannot be changed
anim: Setting it to true will enable animation. The YUI Animation utility is required. It will return the instance of YAHOO.util.Anim that this ProgressBar uses. Alternatively, it will also take an instance of YAHOO.util.Anim set by the user. The duration and method properties are the most important to use.
element, barEl and maskEl: Read only. They contain references to the actual elements making up the ProgressBar. element is the overall container.
captionEl: Contains a reference to the container of the caption text. It defaults to the built-in container which overlaps the ProgressBar, but can be set to any other container anywhere on the page
textTemplate: A formatting string to provide a meaningful text for caption and the WAI-ARIA aria-valuetext attribute. It is processed by YAHOO.lang.substitute and has the values of minValue, maxValue and value available for replacement

YUI's Element utility will apply any other attribute setting directly to the HTML element which contains the ProgressBar. We have used the className attribute in the examples above to select different styles for each bar. This functionality is inherited from Element, any other attributes can be set likewise.

Methods

Constructor: Takes an optional object literal with settings for the attributes listed above. Returns an instance of ProgressBar
render(el, before): Draws the ProgressBar appending it to the element given in el (either the string id or a reference to the HTML element), optionally locating it right before the element given in before
redraw(): Redraws the ProgressBar with the current settings. It takes no arguments, it doesn't return anything
destroy(): Deletes the HTML code created and removes any event listeners attached to them

ProgressBar inherits from YAHOO.util.Element and inherits other methods from it, such as get, set, getStyle and setStyle.

CSS styles

To make it easy to draw the most basic ProgressBar a few settings relating to presentation are provided. However, the code and presentation of the widget have been kept separate as much as possible. The programmer can write the code independently of the graphics designer. Once a ProgressBar instance is created, the programmer just needs to set the value, all other aspects of the presentation (except direction) can be handled through CSS styles

Selector	Attribute	Description
.yui-pb	width height	overall size of the ProgressBar. Can be set via the `width` and `height` configuration settings
.yui-pb	background	background to be used on the area the bar is not covering
.yui-pb-bar	background-image background-color	Image or color to use for the bar
.yui-pb-bar	margin	offset from the edge of the ProgressBar to where the mask transparency starts. If the bar goes into this area, it would be hidden behind the mask. This setting makes the bar use only the inner, transparent part of the mask.
.yui-pb .yui-pb-anim	background-image background-color	Image or color to use for the bar while it is changing.
.yui-pb-mask div	background-image	mask with transparencies to allow the bar to show through
.yui-pb-caption	display	the caption is normally hidden, it needs to be shown by setting `display:inline`
.yui-pb-caption	font and others	the caption is normally shown centered in the normal font, which is unlikely to be satisfying

How it works

The diagram to the left shows the layers of the ProgressBar. The layer that holds the caption and is on top of all the others has been omitted for clarity.

The green rectangle is the container which is the base for the whole control. It has the className yui-pb.

The red rectangle is the bar itself, which occupies just part of the container and has className yui-pb-bar.

The blue area is the mask which has a transparent hole that allows the lower layers to be seen and has className yui-pb-mask.

The red bar does not start at the very edge of the container, because it would otherwise be hidden under the borders of the mask. The black vertical lines in between the top and bottom layers show these two do match while the red bar is offset by as much as set in its margin.

The blue mask is not a continuous image but it is made of four sections shown cut by the yellow lines.

This set of diagrams show how the mask image is used. The blue sections enclosed in red at the top two images show a couple of masks of very different sizes, both made of the very same base image, which is shown below.

The red line outlines the table used to hold the mask which is of the same size as the overall ProgressBar. The table is divided in four cells of 50% width and height, marked by the yellow lines.

The same mask image is set as the background for each of the four individual cells but instead of letting it tile normally, we use the background-position CSS attribute so each is aligned to its own corner. The blue area shows the corner section of the mask image that is visible in each cell, enclosed in between the table edge in red and the cell dividers in yellow, the light blue areas are the parts of the same image that fall outside of the cells and are invisible.

If the top ProgressBar were to be stretched a little more, the now invisible edges opposite each visible corner would start to show. On the other hand, if the lower ProgressBar were to be reduced, the yellow lines would start eating into the rounded inner corners and the inner contour would not blend but meet at an angle.

If we call A the length of the straight section of each edge and B the length of the section from the edge until the rounded inner corner meets the straight section so that the width of the original mask is A + 2 * B, we can use that image as a mask for any ProgressBar that is at least 2 * B on the side (no straight section visible) to 2 * A + 2 * B (the straight sections are seen twice, once in each contiguous cell).

Placing the mask in a regular <img> tag would allow for unbound stretching and shrinking by using the width and height attributes. The problem with this approach is that the definition and general appearance of the base image might be altered drastically. Lines 1px wide might become too wide or completely disappear, rounded corners will turn elliptical if stretched unevenly and generally, the image will loose resolution and become distorted.