rich:progressBar progressBar

Component identification parameters

Name | Value
--- | ---
component-type | org.richfaces.ProgressBar
component-class | org.richfaces.component.html.HtmlProgressBar
component-family | org.richfaces.ProgressBar
renderer-type | org.richfaces.renderkit.ProgressBarRenderer
tag-class | org.richfaces.taglib.ProgressBarTag

## Creating the Component with a Page Tag

Here is a simple example of how the component can be used on a page:

Example:

    ...
    <rich:progressBar value="#{bean.incValue1}"/>
    ...

## Creating the Component Dynamically Using Java

Example:

    import org.richfaces.component.html.progressBar;
    ...
    HtmlProgressBar myProgressBar = new progressBar();
    ...

## Details of Usage

As it was mentioned above, the <rich:progressBar> component displays the status of the ongoing process.

Status of the process is calculated basing on values of the following attributes:

- "value" attribute sets the current value of the process

- "minValue" (default value is "0") sets minimal value for the <rich:progressBar> to start rendering

- "maxValue" (default value is "100") sets maximum value for the <rich:progressBar> to finish rendering

Example:

    ...
    <rich:progressBar value="#{bean.incValue}"  minValue="50"  maxValue="400"/>
    ...

There are two ways to display information on a progress bar:

- Using "label" attribute

  Example:

      ...
      <rich:progressBar value="#{bean.incValue}" id="progrs" label="bean.incValue1"/>
      ...

- Using <h:outputText />

  Example:

      ...
      <rich:progressBar value="#{bean.incValue1}">
          <h:outputText value="#{bean.incValue1}"/>
      </rich:progressBar>
      ...

The "progressVar" attribute defines request scoped variable that could be used for substitution purpose. This variable contains the data taken from "value" attribute. Please, study carefully the following example.

Example:

    ...
    <rich:progressBar value="#{bean.incValue1}" enabled="#{bean.enabled1}" id="progrs1" progressVar="progress">
        <h:outputText value="{progress}%"/>
    </rich:progressBar>
    ...

In the shown example "progressVar" attribute defines a variable "progress" with the value taken from "value" attribute of the <rich:progressBar> component. The "progress" variable performs substitution passing the current value of a progress to the "value" attribute of the <h:outputText>. This is how the current value of a progress appears on the label of <rich:progressBar>.

The <rich:progressBar> component provides 3 predefined macrosubstitution parameters:

- {value} contains the current value

- {minValue} contains min value

- {maxValue} contains max value

You can use them as follows:

Example:

    ...
    <rich:progressBar value="#{bean.incValue1}" minValue="400" maxValue="900">
            <h:outputText value="Min value is {minValue}, current value is {value}, max value is {maxValue}"/>
    </rich:progressBar>
    ...

This is the result:

Macrosubstitution

The "parameters" is also a special attribute that defines parameters for substitution in the label. All you need is to define a value of your own parameter (e.g parameters="param:'#{bean.incValue1}'") and you can use it to pass the data.

Example:

    ...
    <progressBar:progressBar value="#{bean.incValue1}" parameters="param:'#{bean.incValue1}'">
        <h:outputText value="{param}%"/>
    </progressBar:progressBar>
    ...

The "interval" attribute defines the frequency of status polling.

Polling is active while the "enabled" attribute is "true".

Example:

    ...
    <rich:progressBar value="#{bean.incValue}" id="progrs" interval="900" enabled="true"/>
    ...

With the help of "timeout" attribute you can define the waiting time on a particular request. If a response is not received during this time the request is aborted.

The component can also employ "initial" and "complete" facets to display the states of the process: "initial" facet is displayed when the progress value is less or equal to "minValue" , and the "complete" facet is shown when the value is greater or equal to "maxValue". Please see an example below.

Example:

    ...
    <rich:progressBar value="#{bean.incValue1}">
        <f:facet name="initial">
            <h:outputText value="Process not started"/>
        </f:facet>
        <f:facet name="complete">
            <h:outputText value="Process completed"/>
        </f:facet>
    </rich:progressBar>
     ...

However, the usage of these facets is optional. If you omit them nothing will be displayed.

The <rich:progressBar> component can be used in two modes: Ajax (default) and Client. In order to define the mode you need to use "mode" attribute.

- Ajax - polling is activated when the component is enabled to check its value.

- Client - component updates after its value changed through JavaScript API.

## JavaScript API

JavaScript API

Function | Description
--- | ---
enable() | Begins polling for ajax mode
disable() | Stops polling for ajax mode
setValue(value) | Updates the progress of the process
setLabel(label) | Update the label for the process

## Look-and-Feel Customization

For skinnability implementation, the components use a style class redefinition method. Default style classes are mapped on skin parameters.

There are two ways to redefine the appearance of all <rich:progressBar> components at once:

- Redefine the corresponding skin parameters
- Add to your style sheets style classes used by a <rich:progressBar> component

## Skin Parameters Redefinition

Skin parameters redefinition for the progressBar without a label

Skin parameters | CSS properties
--- | ---
controlBackgroundColor | background-color
panelBorderColor | border-color

Skin parameters redefinition for the completed progress area of the progressBar without a label

Skin parameters | CSS properties
--- | ---
selectControlColor | background-color

Skin parameters redefinition for the progressBar with a label

Skin parameters | CSS properties
--- | ---
panelBorderColor | border-color
generalFamilyFont | font-family
generalSizeFont | font-size
controlTextColor | color

Skin parameters redefinition for the label of the progressBar

Skin parameters | CSS properties
--- | ---
panelBorderColor | border-color

Skin parameters redefinition for the completed progress area of the progressBar with a label

Skin parameters | CSS properties
--- | ---
selectControlColor | background-color
controlBackgroundColor | color

Skin parameters redefinition for the remained progress area of the progressBar with a label

Skin parameters | CSS properties
--- | ---
controlBackgroundColor | background-color
controlTextColor | color

## Definition of Custom Style Classes

On the screenshot there are classes names that define styles for component elements.

Classes names

Classes names for the progressBar without a label

Class name | Description
--- | ---
rich-progress-bar-shell | Defines styles for a wrapper <div> element of a progressBar
rich-progress-bar-uploaded | Defines styles for the completed progress area
rich-progress-bar-height | Defines height for a progressBar
rich-progress-bar-width | Defines width for a progressBar

Classes names for the progressBar with a label

Class name | Description
--- | ---
rich-progress-bar-shell-dig | Defines styles for a wrapper <div> element of a progressBar
rich-progress-bar-uploaded-dig | Defines styles for the label
rich-progress-bar-remained | Defines styles for the remained progress area
rich-progress-bar-completed | Defines styles for the completed progress area
rich-progress-bar-height-dig | Defines height for a progressBar
rich-progress-bar-width | Defines width for a progressBar

Note:

It's necessary to define width of the component in pixels only.

In order to redefine styles for all <rich:progressBar> components on a page using CSS, it's enough to create classes with the same names (possible classes could be found in the tables above) and define necessary properties in them.

Example:

    ...
    .rich-progress-bar-remained{
        background-color: #ebf3fd;
    }
    ...

This is the result:

Redefinition styles with predefined classes

In the example above background color of the remained part of progress area was changed.

It's aslo possible to change styles of a particular <rich:progressBar> component. In this case you should create own style classes and use them in corresponding <rich:progressBar> styleClass attributes. An example is placed below:

Example:

    ...
    .myClass{
    background-color: #ebf3fd;
    }
    ...

The "remainClass" attribute for <rich:progressBar> is defined as it’s shown in the example below:

Example:

    <rich:progressBar value="#{bean.incValue1}" styleClass="remainClass"/>

This is the result:

Modificaton of a look and feel with own classes and styleClass attributes

As it could be seen on the picture above, background color of the remained part of progress area was changed.

## Relevant Resources Links

Here you can see the example of <rich:progressBar> usage and sources for the given example.