| |||||||
FRAMES NO FRAMES |
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:
Determinate -- An animated horizontal bar used to show the percentage of the task that has been completed.
Indeterminate -- An animated horizontal bar used to show
that a task is progressing, when it is not possible to determine the
task completion
percentage.
Busy -- A smaller animation used to indicate activity for events
that cannot be synchronized to the backend process, and where space is
constrained.
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.
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:
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) |
webuijsf:progressBar
tagBy 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:
progress
attribute value can be bound to
data that updates as the task progresses, and should resolve to an
integer value that indicates the percentage of task completion. The status
attribute can be bound to data
that updates as the task progresses, and should reflect the current
status; for example, the status could be a string used to indicate the
percent completed or time remaining.
taskState
attribute is used to specify the
state of the task. For example, if the task fails, the taskState
would be set to failed
. The taskState
attribute supports several values, which are listed in the attribute
descriptions later in this document. Note that in the Examples section, the taskState
value is used in the backing bean to determine the value of the status
attribute, but is not used as a tag attribute in the webuijsf:progressBar
tag. refreshRate
attribute is used to specify the
number of milliseconds between updates of the animation through
Ajax. The
default rate is 3000 milliseconds.overlayAnimation
attribute is used to render
the percentage completion text on a
determinate progress bar, instead of on a line below the progress
bar.
This technique is useful in tables, for example, or other
locations where space is limited. The progressImageUrl
attribute is used to specify
a different animated image to be used for the progress bar. This
image must be an animated GIF.
ajaxify
attribute is true by default, to enable
the asynchronous JavaScript capabilities of the component, which are
responsible for implementing its dynamic behavior. When the default
Ajax functionality is added to the page, it will automatically
subscribe to a Dojo event that is published according to the specified refreshRate.
When the Dojo event is received, an Ajax request is generated using the
DynaFaces JavaScript library. This same implementation will also listen
for the Ajax response. When the response is returned, the progress bar
is updated as needed.
Set ajaxify
to false if you want to provide your own
implementation of Ajax behavior. 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. |
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.
|
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:
|
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. |
When the component is manipulated on the client side, some functions might
publish event topics for custom AJAX implementations to listen for.
Using the Dojo event system, you can instruct Ajax to listen for the refresh event topic by using:
<webuijsf:script>
var processEvents =
{
update: function(props) {
//
Do something...
}
}
// Subscribe to refresh event.
dojo.subscribe(webui.suntheme.widget.progressBar.event.<eventname>.endTopic,
processEvents, "update");
</webuijsf:script>
The following events are supported.
Event | Description |
webui.suntheme.widget.progressBar.event.refresh.beginTopic | Event topic published before asynchronously refreshing the
component. Supported properties include:
|
webui.suntheme.widget.progressBar.event.refresh.endTopic | Event topic published after asynchronously refreshing the
component. Supported properties include: setProps() function.
|
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.resume()
,
pause()
, stop()
, cancel()
.
For example, the Resume button calls: document.getElementById(component
id).resume();
return 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.<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>
<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>
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>
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>
ProgressBean.java
backing bean is used the examples
above./*
* 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";
}
}
<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>
<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.<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 Class | com.sun.webui.jsf.component.ProgressBarTag |
TagExtraInfo Class | None |
Body Content | JSP |
Display Name | None |
Attributes | ||||
Name | Required | Request-time | Type | Description |
binding | false | false | java.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. |
toolTip | false | false | java.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. |
failedStateText | false | false | java.lang.String | Text to be displayed along with an icon when the task fails. |
width | false | false | java.lang.String | Number of pixels for the width of the progress bar animation. The default is 184. |
type | false | false | java.lang.String | Type of progress bar. Value must be one of the following: |
refreshRate | false | false | java.lang.String | The number of milliseconds between updates to the progress bar. |
rendered | false | false | java.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. |
status | false | false | java.lang.String | Text to be displayed at the bottom of the progress bar, for the status of the operation. |
progress | false | false | java.lang.String | An integer that indicates the completion percentage of the task. |
id | false | true | java.lang.String | No Description |
progressImageUrl | false | false | java.lang.String | URL to an image to use instead of the default image for the progress indicator. |
htmlTemplate | false | false | java.lang.String | Alternative HTML template to be used by this component. |
styleClass | false | false | java.lang.String | CSS style class or classes to be applied to the outermost HTML element when this component is rendered. |
height | false | false | java.lang.String | Number of pixels for the height of the progress bar animation. The default is 14. |
logMessage | false | false | java.lang.String | Text to be displayed in a text area at the bottom of the progress bar component. |
overlayAnimation | false | false | java.lang.String | Set to true to display the operation progress text superimposed on the progress bar animation. |
description | false | false | java.lang.String | Text to describe the operation that is monitored by the progress bar. |
visible | false | false | java.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. |
style | false | false | java.lang.String | CSS style or styles to be applied to the outermost HTML element when this component is rendered. |
tabIndex | false | false | java.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. |
taskState | false | false | java.lang.String | A string representing the state of the task associated with this progress bar.
Valid values are: |
Variables | No Variables Defined. |
| |||||||
FRAMES NO FRAMES |