How to Use the ICEfaces Output Progress Component

The outputProgress component can be used to inform the user of the current status of a long running task. For example, retrieving new emails from a web based client, or uploading a large data set, or performing a statistical computation on some fields.

The mode of the progress bar can be set to display either determinate mode (if the percentage complete is known to the developer), or an indeterminate mode for tasks where the time frame is unknown or cannot be calculated. In addition, the look and feel of the progress bar can be customized to a great extent. Not only can CSS classes be overridden as needed, but the text and position of various labels can be modified. The following screenshot is of the ice:outputProgress component demo in component-showcase.

The progress bar requires the management of the completed percentage at a backing bean level. How the percentage is updated depends on the developer's application. In some cases it is inside a separate thread, in others it is set from a loop in the business logic. In the case of this tutorial, each demo will use a threaded backing bean to track the percentage and any other attributes of the progress bar.

Setting Progress Bar Modes

Customizing the mode of the progress bar is done by setting the boolean attribute indeterminate to true or false. Indeterminate mode will not display a percentage complete on the progress bar, and should be used for tasks without an estimated time frame. Determinate mode is the default, and will display the percentage progress.

In this demo we create a simple progress bar that uses a timed back end task to simulate a long running process. Controls have been added to allow the user to start and stop the progress bar.

To set the mode used, a selectOneRadio component has been used, as shown below.

<ice:selectOneRadio value="#{mode.isIndeterminate}"
                    valueChangeListener="#{mode.modeChanged}">
    <f:selectItems value="#{mode.availableModes}"/>
</ice:selectOneRadio>

The determinate or indeterminate mode is reflected in the progress bar component's attribute as shown below.

<ice:outputProgress value="#{mode.percent}" indeterminate="#{mode.isIndeterminatePrimitive}"/>

The percent value is managed in the backing bean by a thread. The thread will slowly increase the percent value, and can be stopped and restarted based on the user's actions.

With the mode selector, progress bar, and controls in place, this example looks similar to:

The creation of this selectable progress bar was very simple, as the modeOutputProgress.jspx page shows.

In the next tutorial the ability to customize in-progress and completed labels will be demonstrated.

Customizing Progress Bar Labels

The progress bar has two label types; a working and completed label. When the percentage has not completed and the progress bar is still active, the working label is used, specified as the component attribute label. When the progress bar is finished, the completed label will be displayed until further action is undertaken on the progress bar. This label is set through the labelComplete component attribute.

Finally, the position of the labels (both working and completed) can be changed through the labelPosition component attribute, to any of the 8 available positions. The positions are listed below, with embed being the default.

right, top, topcenter, topright, bottom, bottomcenter, bottomright, embed

In the case of this tutorial, a combination of inputText and selectOneMenu components are used to allow the user to choose their own labels and position. The above attributes are then applied to the progress bar in a way similar to the following:

<ice:outputProgress value="#{label.percent}"
                    label="#{label.label}"
                    labelComplete="#{label.labelComplete}"
                    labelPosition="#{label.labelPosition}"/>

The backing for this application is similar to the mode tutorial above, as we use a threaded approach to simulate a long running process. By default, the completed page with label selectors and example progress bar looks similar to:

Notice that by default, a simple percentage label will be displayed, and no completed label is used.

The appearance of these two examples is rather generic and may not suit your application. The next section will demonstrate how to customize the CSS for the outputProgress component.

Customizing Progress Bar Styles

The progressBar styles can be customized by overriding the default CSS values. The first step is to create a new stylesheet and link to it in styleOutputProgress.jspx page, as shown in the line below:

<link href="override.css" rel="stylesheet" type="text/css"/>

Next the default progress bar styles should be copied into the override sheet, and changed as desired. The names of each overriding class are listed below:

.iceOutProg
.iceOutProgBg
.iceOutProgFill
.iceOutProgTxt

After this is done, you can begin customizing the styles. This demonstration changes the colors and borders of the progress bar, to give it a brighter sunken appearance. The result is similar to the following:

For example, to achieve the color change of the outputProgress bar, the following CSS changes were used:

.iceOutProgFill {
    background-color: #FF0202;
    background-position: top left;
    background-repeat: repeat-x;
    height: 25px;
    display: block;
}

Other CSS changes were done to help display the possibilities, and since all the relevant classes are accessible to the developer the outputProgress style can be completely changed.

The next tutorial approaches the progress bar from a different mindset. Instead of using it to display updates on a long running task, the progress bar will be used as a status message. In addition, the next tutorial will look at multiple progress bars on the same page.

Creating Multiple Progress Bars

This tutorial will look at multiple progress bars on a single page, and use the outputProgress component to demonstrate a simple CPU monitor, something which is normally not considered for the progress bar.

The backing beans have been changed to allow for multiple progress bars by breaking the threaded progress bar bean into a creatable instance, and maintaining a list of them. This list is iterated through by a simple dataTable component at the page level, with one progress bar being displayed for each value.

This is a fairly passive demonstration, with no user input available. As a result, the relevant part of the code is the dataTable, which is similar to:

<ice:dataTable value="#{multiple.progressBarList}" var="progress">
    <ice:column>
        <f:facet name="header">
            <ice:outputText value="Server Location"/>
        </f:facet>
        <ice:outputText value="#{progress.name}"/>
    </ice:column>
    <ice:column>
        <f:facet name="header">
            <ice:outputText value="CPU Load"/>
        </f:facet>
        <ice:outputProgress value="#{progress.percent}"/>
    </ice:column>
</ice:dataTable>

As you can see, this is a fairly standard dataTable with two columns. By constantly updating the percentage values of the simulated CPU load, we can demonstrate how a server monitoring suite could implement multiple progress bars. The finished result is similar to the following:

Once the list of progress bars has been created by the backing bean, a thread is started to randomly update the percent value of each simulated server. These updates are then pushed to the page, and give the illusion of actual data changing.

Tutorial Source Code Downloads