webuijsf
Tag progressBar


Use the webuijsf:progressBar to render a progress indicator that provides user feedback about a task or job in progress. 

The Progress Bar component supports the following types of progress indicators:

The progress bars can include details such as a description and status of the operation, and controls such as Pause, Resume, and Cancel buttons for controlling the running of the task. 

HTML Elements and Layout

In the rendered HTML page, the progress bar is created with <div> elements and JavaScript functions.

The progress bar component consists of  the dynamic graphical progress animation, and the following optional areas:

The following diagram shows the location of each area of the progressBar component, and the attributes and facets that can be used for each area.

Description (description attribute or progressTextTop facet)
Progress animation (type attribute)
Controls (progressControlRight facet)
Status message (status attribute or progressTextBottom facet)
Controls (progressControlBottom facet)
Log message (logMessage attribute)

Configuring the webuijsf:progressBar tag

By default, the webuijsf:progressBar renders a determinate type progress bar with a refresh rate of 3 seconds. You can use the type attribute to specify one of the indicators DETERMINATE, INDETERMINATE, or BUSY to determine the kind of progress indicator to render.  You can add elements to the basic progress indicator by using the attributes and facets shown in the diagram, and customize other aspects of the components behavior with a few other attributes (described later in this document). 

The component doesn't display any buttons by default. To include buttons, you must use the progressControlRight or progressControlBottom facet. The progressBar component provides JavaScript functions for the control elements that you can call to control the underlying task on the back end.

You can further customize the component with some additional attributes:

Facets

The webuijsf:progressBar tag supports the following facets, which can be used to define the specified areas.

Facet Name
Area of Progress Bar
progressTextTop Descriptive text displayed at the top of the progress bar.
progressTextBottom Status text displayed at the bottom of the progress bar.
progressControlRight Control elements displayed to the right side of the progress bar.
progressControlBottom Control elements displayed at the bottom of the progress bar.

Client Side Javascript Functions

When the progressBar component is rendered, a DOM object corresponding to the progressBar component is created. To manipulate the progressBar component on the client side, you may call functions on the DOM object. With reference to the DOM ID, to disable the component, call document.getElementById(id).setProps({disabled: true}).

JavaScript Function Description
cancel() Handles the Cancel button event.
getProps() Use this function to get widget properties. Please see setProps() function for a list of supported properties.
isBottomControlVisible() Tests the controls area on the bottom, if it was hidden.
isFailedStateMessageVisible() Tests the area for the icon and message indicating a failed state, if it was hidden.
isLogMsgVisible() Tests the log message area, if it was hidden.
isOperationTextVisible() Tests the description of the operation that is being monitored.
isProgressBarContainerVisible() Tests if the progress bar container if it was hidden.
isProgressBarVisible() Tests if the progress bar if it was hidden.
isRightControlVisible() Tests the controls area on the right side, if it was hidden.
isStatusTextVisible() Tests the status message area, if it was hidden.
pause() Handles the Pause button event.
refresh(execute)
Use this function to asynchronously refresh the component.
  • [optional] execute: Comma separated string containing a list of client IDs against which the execute portion of the request processing lifecycle must be run. If omitted, no other components are executed.
resume() Handles the Resume button event.
setOnCancel() Invokes a developer-defined function for the Cancel button event.
setOnComplete() Invokes a developer-defined function that handles the event for task completion.
setOnFail() Invokes a developer-defined function that handles the event for task failure.
setBottomControlVisible() Displays the controls area that displays on the bottom of the component.
setFailedStateMessageVisible() Displays the area that displays the icon and message indicating a failed state.
setLogMsgVisible() Displays the log message area.
setOperationTextVisible() Displays the description of the operation that is being monitored.
setProgressBarContainerVisible() Displays the progress bar container.
setProgressBarVisible() Hides the progress bar.
setProps(props) Use this function to change any of the following supported properties:
  • accesskey
  • align
  • className
  • dir
  • disabled
  • escape
  • id
  • icon
  • lang
  • mini
  • onBlur
  • onChange
  • onClick
  • onDblClick
  • onFocus
  • onKeyDown
  • onKeyPress
  • onKeyUp
  • onMouseDown
  • onMouseMove
  • onMouseOut
  • onMouseOver
  • onMouseUp
  • primary
  • src
  • style
  • tabIndex
  • title
  • value
  • visible
setRightControlVisible() Displays the controls area that displays on the right side of the component.
setStatusTextVisible() Displays the status message area.
stop() Handles the Stop button event.
subscribe(topic, obj, func) Use this function to subscribe to an event topic.
  • topic: The event topic to subscribe to.
  • obj: The object in which a function will be invoked, or null for default scope.
  • func The name of a function in context, or a function reference to invoke when topic is published.

Client-Side JavaScript Events

When the component is manipulated on the client side, some functions might publish event topics for custom AJAX implementations to listen for. For example, you can listen for the refresh event topic by using:

<webuijsf:script>
    var processEvents = {                       
        update: function(props) {
            // Do something...
        }
    }

    // Subscribe to refresh event.
    domNode.subscribe(domNode.event.refresh.endTopic, processEvents, "update");


</webuijsf:script>

The following events are supported.

Event Description
<Node>.event.refresh.beginTopic Event topic published before asynchronously refreshing the component. Supported properties include:
  • [optional] execute - list of the components to be executed along with this component
  • id - The client ID to process the event for
<Node>.event.refresh.endTopic Event topic published after asynchronously refreshing the component. Supported properties include: setProps() function.
  • props - JSON object containing properties of the component. See setProps() function for details on properties and their usage

Examples

Example 1:  Simple Determinate Progress Bar with Control Buttons and Log Message

This example creates a determinate type progress bar with Pause, Resume, and Cancel buttons, which are defined with the progressControlBottom facet, at the bottom of the progress bar. The component also displays a text area for log messages because the logMessage attribute is specified.

The buttons are set up to call various JavaScript functions of the progressBar component when clicked:  resume(), pause() , stop(), cancel(). For example, the Resume button calls: document.getElementById(component id).resume(); 

Notereturn false; is called on all control elements in order to prevent page submission when the controls are clicked.  Also, notice that the Pause and Resume buttons are enabled and disabled through JavaScript when the buttons are clicked.

See also the ProgressBean.java backing bean used with this example.

<webuijsf:progressBar type="DETERMINATE" id="pb1" progress="#{ProgressBean.progressRate}"
                      refreshRate="2000"
                      description="Progress Bar 1 with Log Message"
                      status="#{ProgressBean.status}"
                      logMessage="#{ProgressBean.logMsg}!!"> 

                      <f:facet name="progressControlBottom">
                              <webuijsf:panelGroup id="statusPanel" separator="">
                                <webuijsf:button mini="true" id="pauseButton" text="Pause"
                                   onClick="document.getElementById('form1:statusPanel:resumeButton').disabled=false;
                                   this.disabled=true;document.getElementById('form1:pb1').pause();return false;"  />
                                <webuijsf:button mini="true" id="resumeButton" text="Resume"
                                   onClick="document.getElementById('form1:statusPanel:pauseButton').disabled=false;
                                   this.disabled=true;document.getElementById('form1:pb1').resume();return false;"  />
                              <webuijsf:button mini="true" id="cancelButton" text="Cancel"
                                   onClick="document.getElementById('form1:pb1').cancel();return false;" />
                             </webuijsf:panelGroup>
                     </f:facet>
 
</webuijsf:progressBar>


Example 2:   Indeterminate Progress Bar

This example shows how to create a simple indeterminate progress bar, an animated horizontal bar without a completion percentage.  The example shows a description and the buttons Pause, Resume, and Cancel.

<webuijsf:progressBar type="INDETERMINATE" id="pb2"
                      refreshRate="3000"
                      description="Indeterminate Type ProgressBar" >
                     
                     <f:facet name="progressControlRight">
                         <webuijsf:panelGroup id="statusPanel" separator="">
                             <webuijsf:button mini="true" id="pauseButton" text="Pause"
                                      onClick="document.getElementById('form1:statusPanel:resumeButton').disabled=false;
                                      this.disabled=true;document.getElementById('form1:pb2').pause();return false;"  />
                             <webuijsf:button mini="true" id="resumeButton" text="Resume"
                                      onClick="document.getElementById('form1:statusPanel:pauseButton').disabled=false;
                                      this.disabled=true;document.getElementById('form1:pb2').resume();return false;"  /> 
                             <webuijsf:button mini="true" id="cancelButton" text="Cancel"
                                      onClick="document.getElementById('form1:pb2').cancel();return false;" />
                         </webuijsf:panelGroup>
                    </f:facet>
</webuijsf:progressBar>

 

Example 3: Busy Progress Bar

This example creates a simple Busy progress indicator.  Although this example does not show it, you can specify a description, status message, log message in a Busy progress indicator. 

<webuijsf:progressBar type="BUSY" id="pb3"
                      refreshRate="3000"
</webuijsf:progressBar>

Example 4: Overlay Animation Progress Bar 

This example creates a determinate progress bar with overlay animation, in which the percentage complete is displayed within the progress bar.  This technique is often used in tight spaces, where the size of the indicator must be kept to a minimum. However, you can also use the overlay animation when you use a more expansive progress bar with a description, status, log message, and control buttons.
See also the ProgressBean.java backing bean.

<webuijsf:progressBar type="DETERMINATE" id="pb5" 
progress="#{ProgressBean.progressRate}"
refreshRate="2000"
overlayAnimation="true" >
</webuijsf:progressBar>

Backing Bean for Examples

The ProgressBean.java backing bean is used the examples above.

ProgressBean.java

This backing bean is used in Example 1 and Example 4

/*
 * ProgressBean.java
 */

package progressbar;

import com.sun.webui.jsf.component.ProgressBar;
import javax.faces.component.UIComponent;
import javax.faces.context.FacesContext;


public class ProgressBean2 {
    
    private int progressRate = 0;
    
    private String status = "0% complete";
    
    /** Creates a new instance of ProgressBean */
    public ProgressBean2() {
        
    }
    
    public int getProgressRate() {
        
        String task = "";
        if (getComponentInstance() != null)
            task = getComponentInstance().getTaskState();
        
        if(task != null) {
            if (task.equals(ProgressBar.TASK_PAUSED)) {
                status = "Task Paused ...";
                return progressRate;
                
            }
            if (task.equals(ProgressBar.TASK_CANCELED)) {
                status = "Task Canceled ..";
                return progressRate;
            }
        }
        
        progressRate = progressRate + 3;
        status = progressRate + "% complete";
        
        if (progressRate > 99) {
            progressRate = 100;
        }
        
        if (progressRate == 100) {
            
            getComponentInstance().setTaskState(ProgressBar.TASK_COMPLETED);
            status = "Task Completed successfully ..";
        }
        
        return progressRate;
    }
    
    
    public String getStatus() {
        
        return status;
    }
    
    public ProgressBar getComponentInstance() {
        FacesContext context = FacesContext.getCurrentInstance();
        UIComponent comp = context.getViewRoot().findComponent("form1:pb2");
        ProgressBar pb = (ProgressBar) comp;
        
        return pb;
    }
    
    public String action() {
        getComponentInstance().setTaskState(ProgressBar.TASK_NOT_STARTED);
        progressRate = 0;
        status = "";
        return "progressbar";
    }   
}

Example 5: Update Client-Side ProgressBar Properties Using the getProps and setProps functions

This example shows how to toggle the visible state of a progress bar client side using the getProps and setProps functions. When the user clicks the button, the progress bar is either shown or hidden.

<webuijsf:progressBar type="BUSY" id="pb1"/>
<webuijsf:button id="button1" text="Hide Progress Bar" onClick="hideProgressBar()"/>

<script type="text/javascript">
    function hideProgressBar() {
        var domNode = document.getElementById("pb1");
        var props = domNode.getProps();
        if (domNode != null) {
            domNode.setProps({"visible":!props.visible});
        }
    }
</script>

Example 6: Asynchronously Update ProgressBar Using refresh function

This example shows how to asynchronously update an anchor using the refresh function. When the user clicks on the button, the progress bar is asynchronously updated with new data.
<webuijsf:progressBar type="BUSY" id="pb1" description="#{MyBean.text}"/>
<webuijsf:button id="button1" text="#{MyBean.text}" onClick="refreshProgressBar();return false;"/>
<webuijsf:script>
    function refreshProgressBar() {
        var domNode = document.getElementById("form1:pb1"); // Get progress bar
        return domNode.refresh(); // Asynchronously refresh progress bar
    }
</webuijsf:script>

Note that the refresh function can optionally take a list of elements to execute. Thus, a comma-separated list of ids can be provided to update components server-side: refresh("form1:id1,form2:id2,..."). When no parameter is given, the refresh function acts as a reset. That is, the component will be redrawn using values set server-side, but not updated.

Example 7: Asynchronously Update ProgressBar Using refresh function

This example shows how to asynchronously update a progress bar using the refresh function. The execute property of the refresh function is used to define the client id which is to be submitted and updated server-side. As the user types in the text field, the input value is updated server-side and the progress bar is updated client-side -- all without a page refresh.
<webuijsf:progressBar type="BUSY" id="pb1" description="#{MyBean.text}"/>
<webuijsf:textField id="field1" text="#{MyBean.text}" label="Change Progress Bar Description"
onKeyPress="setTimeout('refreshProgressBar();', 0);"/> // Field used to asynchronously update text.
<webuijsf:script>
    function refreshProgressBar() {
        var domNode = document.getElementById("form1:pb1"); // Get progress bar

        return domNode.refresh("form1:field1"); // Asynchronously refresh while submitting field value
    }
</webuijsf:script>

Note that the refresh function can optionally take a list of elements to execute. Thus, a comma-separated list of IDs can be provided to update components server-side: refresh("form1:id1,form2:id2,...")



Tag Information
Tag Classcom.sun.webui.jsf.component.ProgressBarTag
TagExtraInfo ClassNone
Body ContentJSP
Display NameNone

Attributes
NameRequiredRequest-timeTypeDescription
bindingfalsefalsejava.lang.String A ValueExpression that resolves to the UIComponent that corresponds to this tag. This attribute allows the Java bean that contains the UIComponent to manipulate the UIComponent, its properties, and its children.
toolTipfalsefalsejava.lang.String

Sets the value of the title attribute for the HTML element. The specified text will display as a tooltip if the mouse cursor hovers over the HTML element.

failedStateTextfalsefalsejava.lang.String

Text to be displayed along with an icon when the task fails.

widthfalsefalsejava.lang.String

Number of pixels for the width of the progress bar animation. The default is 184.

typefalsefalsejava.lang.String

Type of progress bar. Value must be one of the following:
"DETERMINATE" for horizontal bar showing percent complete
"INDETERMINATE" for horizontal bar without percent complete
"BUSY" for simple activity indicator

refreshRatefalsefalsejava.lang.String

The number of milliseconds between updates to the progress bar.

renderedfalsefalsejava.lang.String Use the rendered attribute to indicate whether the HTML code for the component should be included in the rendered HTML page. If set to false, the rendered HTML page does not include the HTML for the component. If the component is not rendered, it is also not processed on any subsequent form submission.
statusfalsefalsejava.lang.String

Text to be displayed at the bottom of the progress bar, for the status of the operation.

progressfalsefalsejava.lang.String

An integer that indicates the completion percentage of the task.

idfalsetruejava.lang.StringNo Description
progressImageUrlfalsefalsejava.lang.String

URL to an image to use instead of the default image for the progress indicator.

htmlTemplatefalsefalsejava.lang.String Alternative HTML template to be used by this component.
styleClassfalsefalsejava.lang.String

CSS style class or classes to be applied to the outermost HTML element when this component is rendered.

heightfalsefalsejava.lang.String

Number of pixels for the height of the progress bar animation. The default is 14.

logMessagefalsefalsejava.lang.String

Text to be displayed in a text area at the bottom of the progress bar component.

overlayAnimationfalsefalsejava.lang.String

Set to true to display the operation progress text superimposed on the progress bar animation.

descriptionfalsefalsejava.lang.String

Text to describe the operation that is monitored by the progress bar.

visiblefalsefalsejava.lang.String

Use the visible attribute to indicate whether the component should be viewable by the user in the rendered HTML page. If set to false, the HTML code for the component is present in the page, but the component is hidden with style attributes. By default, visible is set to true, so HTML for the component HTML is included and visible to the user. If the component is not visible, it can still be processed on subsequent form submissions because the HTML is present.

stylefalsefalsejava.lang.String

CSS style or styles to be applied to the outermost HTML element when this component is rendered.

tabIndexfalsefalsejava.lang.String

Position of this element in the tabbing order of the current document. Tabbing order determines the sequence in which elements receive focus when the tab key is pressed. The value must be an integer between 0 and 32767.

taskStatefalsefalsejava.lang.String

A string representing the state of the task associated with this progress bar. Valid values are:
not_started
running
paused
resumed
stopped
canceled
failed
completed


Variables
No Variables Defined.


Output Generated by Tag Library Documentation Generator. Java, JSP, and JavaServer Pages are trademarks or registered trademarks of Sun Microsystems, Inc. in the US and other countries. Copyright 2002-4 Sun Microsystems, Inc. 4150 Network Circle Santa Clara, CA 95054, U.S.A. All Rights Reserved.