Progress bar

Used to provide a visual cue to indicate some task is being preformed or to indicate the amount done or left to be done in a task.

JSF tags that emit the component

<hx:progressBar>

Base HTML

<div id="id" title="something" style="display:block;"></div

JavaScript constructor

hX_5.addComponent("id", new hX_5.JSFProgressBar(attributes)); where

id	The ID of the HTML tag to which the component is attached.
attributes	Comma separated list of attributes where each attribute is a quoted string consisting of the attribute name and value separated by a colon, for example "label:MyLabel".

Attributes

Table 1. Progress bar attributes
Attribute name	Description
css-prefix	The base class of a set of CSS classes that describe the visual appearance.
normal	When set to true, the progress bar displays in progress mode. When set to false, the progress bar displays in percentage mode.
defaultmessage	The message that will appear on the Bar when it is created.
defaultpercent	Interval by which the progress bar incrementally updates. This attribute is used when the progress bar is in progress mode.
itu	Length of the time interval in milliseconds. This attribute is used when the progress bar is in percentage mode.
outward	When set to true, the progress bar expands from centre outwards. When set to false (default), the progress bar expands from end to end. This attribute is used when the progress bar is in progress mode.
startprecent	This is the amount the progress bar will initially display. This attribute is used when the progress bar is in percentage mode. The default value is zero.
numconverterid	This is the ID of the number converter to use to display the visible percentage. Used only for percentage mode. If not set, a simple number converter is created. The pattern is always "##0%"

CSS classes

Table 2. Progress bar CSS classes
CSS class name	Description
progressBar	This is the style that gets applied to the entire progress bar control.
progressBar-Table	This is the style that gets applied to the table that makes up the progress bar.
progressBar-Message	This is the style that gets applied to the area holding the message text and the message text.
progressBar-Bar	This is the style that gets applied to the moving bar.
progressBar-Bar_container	This is the style that gets applied to the area containing both the moving bar and percentage text.
progressBar-Bar_text	This is the style that gets applied to the area containing the percentage text and the percentage text.

API calls

Table 3. Progress bar API calls
API call	Description
redraw()	Redraw the component taking into account any changes made to the attributes/properties of the base tag.
start(string)	Starts the progress bar running and changes the message text to the value of string. If you do not want a message, do not pass a parameter. This API call is used when the progress bar is in progress mode.
stop(string)	Stops the progress bar running and changes the message text to the value of string. If you do not want a message, do not pass a parameter. This API call is used when the progress bar is in progress mode.
reset()	Resets the bar displayed values to zero.
upDatePercentage(integer)	Update the progress bar to the value of integer. Integer value must be 0 and 100, values outside this range are rounded up and down respectively. This API call is used when the progress bar is in percentage mode.
UpdateMessage(string)	Used to change the message that is displayed. If you want to clear the message, leave this parameter blank.

Accessibility

There is no need for keyboard accessibility as it is not that type of component. The progress bar shows up in high contrast settings and displays information in grayscale. It is also possible to style this to make it more accessible. It is accessible by screen readers.

Limitations

Hiding the progress bar does not reset it.
Once a progress bar is created, it remains in the mode in which it was created.
Calling the start function on a progress bar, in progress mode, multiple times will cause it to malfunction, normally the speed of update increases.
Calling the start function on a progress bar, in percentage mode, has no effect and calling the upDatePercentage function on a progress bar, in progress mode, has no effect.
If you reset a progress bar when it is in progress mode, it resets to zero and continues straight away.
Reset must be called between stop and (re)start in progress mode, otherwise it will not restart.

Example code

This is an example of a progress bar in progress mode. It uses the progressBar css class. The bar expands from end to end. The initial message displayed says hello. The bar increases in size by 10 percent every second when started.

<div id="pb1" title="this is a progress bar"
style="display:block;"></div>
<input type="button" value="start" onclick="start1();"/>
<input type="button" value="stop" onclick="end1();"/>
<script>
hX_5.addComponent("pb1", new hX_5.JSFProgressBar("normal:true","css-prefix:progressBar","outward:false", "itu:1000", "defaultmessage:hello", "defaultpercent:10"));

function start1()
{
var obj = hX_5.getComponentById("pb1");
obj.start();
}

function end1()
{
var obj = hX_5.getComponentById("pb1");
obj.stop();
}
</script>

This is an example of a progress bar in progress mode. It uses the progressBar css class. The bar expands from middle outwards. The initial message displayed says hello. The bar increases in size by 5 percent every 4 second when started.

<div id="pb2" title="this is a progress bar"
style="display:block;"></div>
<input type="button" value="start" onclick="start2();"/>
<input type="button" value="stop" onclick="end2();"/>
<input type="button" value="change message" onclick="change2();"/>
<input type="button" value="reset" onclick="reset2();"/>
<script>
hX_5.addComponent("pb2", new hX_5.JSFProgressBar("normal:true","css-prefix:progressBar","outward:true", "itu:4000", "defaultmessage:<b
>hello</b>", "defaultpercent:5"));
</script>

function start2()
{
var obj = hX_5.getComponentById("pb2");
obj.start("starting");
}

function end2()
{
var obj = hX_5.getComponentById("pb2");
obj.stop("finished");
}

function reset2()
{
var obj = hX_5.getComponentById("pb2");
obj.reset();
obj.redraw();
}

function change2()
{
var obj = hX_5.getComponentById("pb2");
obj.upDateMessage("process is still on going");
obj.redraw();
}

This is an example of a progress bar in percentage mode. It uses the progressBar css class. The bar expands from end to end always. The percentage is displayed over the bar. The initial message displayed says hello. The bar increases in size to the amount set in upDatePercentage and the message change to that specified in upDateMessage.

<div id="pb3" title="this is a progress bar"
style="display:block;"></div>
<input type="button" value="set to 20%" onclick="move1();"/>
<input type="button" value="set to 72%" onclick="move2();"/>
<script>
hX_5.addConverter("0", new hX_5.NumberConverter("strict:1", "pattern:##0%", "locale:,.%\u2030-\u20ac"));
hX_5.addComponent("pb3", new hX_5.JSFProgressBar("normal:false","css-prefix:progressBar", "defaultmessage:hello", "numberconverterid:0"));

function move1()
{
var obj = hX_5.getComponentById("pb3");
obj.upDatePercentage(20);
obj.redraw();
}

function move2()
{
var obj = hX_5.getComponentById("pb3");
obj.upDatePercentage(72);
obj.upDateMessage("value is now set to 72 %");
obj.redraw();
}
</script>

This is an example of a progress bar in percentage mode and sets the initial display percentage to 15%, using the startpercent parameter. It uses the progressBar css class. The bar expands from end to end always. The percentage is displayed over the bar. The initial message displayed says hello. The bar increases in size to the amount set in upDatePercentage and the message change to that specified in upDateMessage.

<div id="pb3" title="this is a progress bar"
style="display:block;"></div>
<input type="button" value="set to 20%" onclick="move1();"/>
<input type="button" value="set to 72%" onclick="move2();"/>
<script>
hX_5.addConverter("0", new hX_5.NumberConverter("strict:1", "pattern:##0%", "locale:,.%\u2030-\u20ac"));
hX_5.addComponent("pb3", new hX_5.JSFProgressBar("normal:false","css-prefix:progressBar", "defaultmessage:hello", "startprecent:15", "numberconverterid:0"));

function move1()
{
var obj = hX_5.getComponentById("pb3");
obj.upDatePercentage(20);
obj.redraw();
}

function move2()
{
var obj = hX_5.getComponentById("pb3");
obj.upDatePercentage(72);
obj.upDateMessage("<i>value is now set to 72 %</i>");
obj.redraw();
}
</script>

Feedback