Documentation in development
Some concepts covered in this chapter may refer to the previous version of Richfaces, version 3.3.3. This chapter is scheduled for review to ensure all information is up to date.
Read this chapter for details on components that display messages and other feedback to the user.
The <rich:progressBar> component displays a progress bar to indicate the status of a process to the user. It can update either through Ajax or on the client side, and the look and feel can be fully customized.
Basic usage of the <rich:progressBar> component requires only the value attribute, which points to the method that provides the current progress.
By default, the minimum value of the progress bar is 0 and the maximum value of the progress bar is 100. These values can be customized using the minValue and maxValue attributes respectively.
The progress bar can be labeled in one of two ways:
- Using the
labelattribute The content of the
labelattribute is displayed over the progress bar.Example 12.2. Using the
labelattribute<rich:progressBar value="#{bean.incValue}" id="progrs" label="#{bean.incValue}"/>
- Using nested child components
Child components, such as the JSF
<h:outputText>component, can be nested in the<rich:progressBar>component to display over the progress bar.Example 12.3. Using nested child components
<rich:progressBar value="#{bean.incValue}">
<h:outputText value="#{bean.incValue} %"/>
</rich:progressBar>
Macro-substitution
The following section details the use of macro-substitution paramaters in labeling. Macro-substitution may be revised and altered in future versions of RichFaces. Be aware of this when using macro-substitution in your applications.
For labeling, the <rich:progressBar> component recognizes three macro-substitution parameters:
{value}The current progress value.
{minValue}The minimum value for the progress bar.
{maxValue}The maximum value for the progress bar.
Example 12.4. Using macro-substitution for labeling
<rich:progressBar value="#{bean.incValue1}" minValue="400" maxValue="900">
<h:outputText value="Minimum value is {minValue}, current value is {value}, maximum value is {maxValue}"/>
</rich:progressBar>
Additionally, you can use the {param} parameter to specify any custom parameters you require. Define the parameters in the bean for the progress method, then reference it with the <rich:progressBar> component's parameters attribute, as shown in Example 12.5, “Using the param parameter”.
Example 12.5. Using the param parameter
<rich:progressBar value="#{bean.incValue}" parameters="param:'#{bean.dwnlSpeed}'">
<h:outputText value="download speed {param} KB/s"/>
</rich:progressBar>
To define customized initial and complete states for the progress bar, use the initial and complete facets. The initial facet displays when the progress value is less than or equal to the minimum value, and the complete facet displays when the progress value is greater than or equal to the maximum value.
Example 12.6. Initial and complete states
<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>
The <rich:progressBar> component can be set to constantly poll for updates at a constant interval. Use the interval component to set the interval in milliseconds. The progress bar is updated whenever the polled value changes. Polling is only active when the enabled attribute is set to true.
Example 12.7. Using set intervals
<rich:progressBar value="#{bean.incValue1}" id="progress" interval="900" enabled="#{bean.enabled1}"/>
The mode for updating the progress bar is determined by the mode attribute, which can have one of the following values:
ajaxThe progress bar updates in the same way as the
<a4j:poll>component. The<rich:progressBar>component repeatedly polls the server for the current progress value.clientThe progress bar updates on the client side, set using the JavaScript API.