Progress API

Creating a Progress bar

To instantiate a new Progress component on your page:


var myProgressBar = fluid.progress(container, options);

Returns: The Progress component object.

Note: the initial state of a progress element is assumed to be hidden with the minimum amount of progress.

Parameters

container: a CSS-based selector, single-element jQuery object, or DOM element that identifies the root DOM node of the Progress markup.

options: an optional data structure that configures the Progress component, as described in the fluid:Options section of this page.

Supported Events

The Progress component fires the following events (for more information about events in the Fluid Framework, see Events for Component Users):

Event	Type	Description	Parameters	Parameter Description

Event	Type	Description	Parameters	Parameter Description
New in v1.3: `onProgressBegin`	default	This event fires once the progress display has appeared. Note that this is not a 'preventable' event.	none
New in v1.3: `afterProgressHidden`	default	This event fires once the progress display has been removed after progress is complete.	none

To add listeners to the firers one can use two approaches:
1) Using the listeners option to the component creator function (see #Options below for more information):


//onProgressBegin:
var myProgress = fluid.progress("#progress-container", {
    listeners: {
        onProgressBegin: myProgressShow //callback function
    }              
}); 
//afterProgressHidden:
var myProgress = fluid.progress("#progress-container", {
    listeners: {
        afterProgressHidden: myProgressHide //callback function
    }              
});

2) Programmatically:


//onProgressBegin:
myProgress.events.onProgressBegin.addListener(myProgressShow); 
//afterProgressHidden:
myProgress.events.afterProgressHidden.addListener(myProgressHide);

Methods

Method	Description	Parameters

Method	Description	Parameters
`show(animation)`	Shows the element defined by the displayElement selector using either the default showAnimation object parameters or an animation passed in.	`animation`: see below the description of animate object used in the showAnimation option.
`hide(delay, animation)`	Hides the element defined by the displayElement selector using either the default hideAnimation object parameters or an animation passed in	`delay:` see below the description of the delay option `animation`: see below the description of animate object used in the hideAnimation option
`update(percentage, labelValue, animationForShow)`	Updates the indicator element with a new percentage complete, updates the visible label, and ariaElement, shows the displayElement if it is currently hidden using either the default showAnimation object parameters or an animation passed in.	`percentage`: an integer value between 0 and 100 indicating the current progress (numbers greater than 100 are interpreted as 100) `labelValue`: a string to display in the label element `animationForShow`: see below the description of animate object used in the fluid:showAnimation option.
`refreshView()`	Resets the position and size of the indicator element based on the current size and position of the progressBar element. Useful for liquid layouts or events that change the location or size of the progressBar.	none

Options

Name	Description	Values	Default

Name	Description	Values	Default
`selectors`	Javascript object containing selectors for various fragments of the Progress markup	The object must contain a subset of the following keys: `displayElement` `progressBar` `indicator` `label` `ariaElement` See fluid:selectors below for requirement details	`selectors: { displayElement: ".flc-progress", progressBar: ".flc-progress-bar", indicator: ".flc-progress-indicator", label: ".flc-progress-label", ariaElement: ".flc-progress-bar" }` See #Selectors below for requirement details
`strings` New in v1.3	The strings that will be used by the component. This is where localization is handled `ariaBusyText` String to inject into the ariaElement during update() while the percentage is less than 100%. The %percentComplete token is replaced with a number indicating the current percent complete. New in v1.3 If `ariaBusyText` is provided, the `aria-valuetext` attribute will be updated using this test. Otherwise, the value of the `aria-valuenow` attribute will be used for `aria-valuetext`. `ariaDoneText` String to inject into the ariaElement during update() when the percentage complete is 100%.	The object must contain a subset of the following keys: `ariaBusyText` `ariaDoneText`	`strings: { ariaBusyText: "Progress is %percentComplete percent complete", ariaDoneText: "Progress is complete." }`
`showAnimation`	JavaScript object that defines the default animation for displaying the Progress displayElement. The default `showAnimation` can be overridden at run-time by passing an animation object in with the `progress.show()` or `progress.update()` methods.	The structure of the object mirrors and gets mapped to the parameters of jQuery's animate method. NOTE: The `callback` property is deprecated in v1.3	`showAnimation: { params: { opacity: "show" }, duration: "slow", callback: null }, // equivalent of $().fadeIn("slow")`
`hideAnimation`	JavaScript object that defines the default animation for hiding the Progress displayElement. The default `hideAnimation` can be overridden at run-time by passing an animation object in with the `progress.hide()` method.	The structure of the object mirrors and gets mapped to the parameters of jQuery's animate method. NOTE: The `callback` property is deprecated in v1.3	`hideAnimation: { params: { opacity: "hide" }, duration: "slow", callback: null }, // equivalent of $().fadeOut("slow")`
`listeners` New in v1.3	JavaScript object containing listeners to be attached to the supported events.	Keys in the object are event names, values are functions or arrays of functions.	See #Supported Events for more information.