The ICEfaces Tutorial
Table of Contents


Lesson: Using the outputProgress component

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 statistic 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 extend. 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.

outputProgress component in Component Showcase application

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.

The rest of this tutorial will discuss the following topics:

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 backend 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}" partialSubmit="true"
                        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:

Progress Bar Mode Example

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

Download the demo:

The progress bar shown was simple and focused on available modes. 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. While the percentage has not completed yet 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 components and selectOneMenu 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:

Progress Bar Label Example

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

Download the demo:

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:

Progress Bar Style Example

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.

Download the demo:

The next tutorial approaches the progress bar from a different mindset. Instead of using it just for updating the user about a long running task, the progress bar is instead 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 using the outputProgress component to demonstrate a simple CPU monitor, something which is normally not considered for the progress bar.

The backing beans were changed to allow for multiple progress bars by breaking up 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 main 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 present. 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:

Multiple Progress Bar Example

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.

Download the demo:

Examples Using Progress Bars

Example Source Notes
Component Showcase Available in release bundles Progress Bar example which includes mode setting and label customization.
Webmail Available on the demo site Used to display the completed percentage of user created tasks.
outputProgress-mode outputProgress-mode source code Allows the switching of determinate and indeterminate mode in a simple progress bar.
outputProgress-label outputProgress-label source code Example showing the customization of progress bar label text and position.
outputProgress-style outputProgress-style source code Demonstration of how easily and fully an outputProgress can be styled with custom CSS.
outputProgress-multiple outputProgress-multiple source code This example shows how multiple progress bars can be displayed on the same page.

The ICEfaces Tutorial
Table of Contents

Copyright 2007 ICEsoft Technologies Inc. All rights reserved.