changes.
| h2. Overview |
| _Since 3.0_ |
| |
| Progress bar is a progress indicator that can work on the client side by itself or gets its progress update from the server using ajax. |
| |
| {tip}See the ICEfaces Showcase [Live Demo|http://icefaces-showcase.icesoft.org/showcase.jsf?grp=aceMenu&exp=progressBarBean] of this component, complete with source code.{tip} |
| |
| |
| h2. Getting Started |
| |
| Client side only: |
| {panel} |
| {code:xml|borderStyle=dashed} <script type="text/javascript"> |
| function begin() |
| { |
| this.progressInterval = setInterval ( |
| function() |
| { |
| clientSideBar.setValue(clientSideBar.getValue() + 10); |
| } |
| , 2000); |
| } |
| |
| function stop() |
| { |
| clearInterval(this.progressInterval); |
| clientSideBar.setValue(0); |
| } |
| </script> |
| ... |
| <ace:panel> |
| <ace:progressBar widgetVar="clientSideBar" /> |
| </ace:panel> |
| ... |
| <h:commandButton onclick="begin();" ... /> |
| <h:commandButton onclick="stop();" ... /> |
| {code} |
| {panel}Client polling server: |
| {panel} |
| {code:xml|borderStyle=dashed} <ace:progressBar widgetVar="#{upload.widgetVarName}" usePolling="true" pollingInterval="2000" value="#{upload.progressValue}" ... /> |
| ... |
| <h:commandButton onclick="#{upload.widgetVarName}.start();" ... /> |
| {code} |
| {panel} |
| h2. Attributes |
| {tip:title=TagLib Documentation}This section covers attributes involved in the typical use-cases for this component. For reference, the complete taglib documentation for this component is available [here|http://www.icefaces.org/docs/v4_latest/ace/tld/ace/progressBar.html].{tip} |
| {panel} |
| *usePolling* specifies the mode of progressBar, in polling mode progress value is retrieved periodically from a backing bean. |
| {panel} |
| {panel} |
| *cancelListener*, *changeListener*, *completeListener* are the listeners for the different stages of the progress. In the change event you can get the value and percentage of the progress bar. |
| {panel} |
| {panel} |
| *pollingInterval* is time between polls to the server in milliseconds. |
| {panel} |
| h2. Event Listeners |
| |
| | changeListener | Listener to be invoked when the value of the progressbar changes. | |
| | completeListener | Listener to be invoked when the value of the progressbar reaches the maximum value. | |
| | cancelListener | Listener to be invoked when the progress process is cancelled by calling cancel(). | |
| |
| h2. Client Behavior Events |
| |
| | complete | Fired when the value of the progressbar reaches the maximum value (default event). | |
| | cancel | Fired when the progress process is cancelled by calling cancel(). | |
| | change | Fired when the value of the progressbar changes. | |
| |
| h2. JavaScript API |
| |
| | The client side progress bar object is exposed through the global variable named by the *widgetVar* attribute. You can use the *getValue()* and *setValue()* methods to read and change the value. Use the *start()* and *cancel()* methods for polling. See Getting Started above for examples. |
| | h4. ICEfaces 3.x |
| |
| | The client side progress bar object is exposed through the global variable name specified in the *widgetVar* attribute. You can use the *getValue()* and *setValue()* methods to read and change the value. Use the *start()* and *cancel()* methods for starting/cancelling the progress: |
| |
| | {panel} |
| {code:xml|borderStyle=dashed} |
| <ace:progressBar widgetVar="sampleProgeessBar" value="#{bean.value}" /> |
| <h:commandButton value="Start" onclick="sampleProgeessBar.start();" ... /> |
| <h:commandButton value="Cancel" onclick="sampleProgeessBar.cancel();" ... /> |
| {code} |
| {panel} |
| |
| | h4. ICEfaces 4+ |
| |
| The "widgetVar" attribute on the ACE components has been removed in ICEfaces 4 and in its place a new "ice.ace.instance()" client JavaScript object lookup API has been introduced. The reason for this change is to enable lazy-initialization of the ACE component JavaScript objects to improve runtime performance and reduce browser memory use. You can use the *getValue()*, *setValue()*, *start()* and *cancel()* methods as described above. |
| |
| {code}widget = ice.ace.instance('frm:myProgressBar');{code} |
| |
| To illustrate this change, see the before and after code example below. |
| |
| h5. Before (ICEfaces 3 API) |
| |
| {panel} |
| {code:xml|borderStyle=dashed} |
| <ace:progressBar widgetVar="sampleProgeessBar" value="#{bean.value}" /> |
| <h:commandButton value="Start" onclick="sampleProgeessBar.start();" ... /> |
| <h:commandButton value="Cancel" onclick="sampleProgeessBar.cancel();" ... /> |
| {code}{panel} |
| |
| h5. After (ICEfaces 4 API) |
| {panel}{code:xml|borderStyle=dashed} |
| <ace:progressBar id="myProgressBar" value="#{bean.value}" /> |
| <h:commandButton value="Start" onclick="ice.ace.instance('frm:myProgressBar').start();" ... /> |
| <h:commandButton value="Cancel" onclick="ice.ace.instance('frm:myProgressBar').cancel();" ... /> |
| {code}{panel} |
| |
| {tip}The _ice.ace.instance_ function requires the _full_ client id of the component to be specified, such as "j_idt77:componentId" instead of just "componentId". To reduce the complexity of working with complete IDs with this function it may be preferable in some cases to use {{prependId="false"}} in the enclosing form (e.g. _<h:form prependId="false">_).{tip} |
| |
| h2. Keyboard and ARIA Support |
| |
| The following ARIA roles are supported: progressbar. |
| |
| h2. CSS Classes |
| |
| The following markup represents the basic HTML structure of the component and the CSS classes it uses. |
| |
| {code:xml} |
| <div class="[user defined classes] ui-progressbar ui-widget ui-widget-content ui-corner-all" style="[user defined styles]"> |
| <div class="ui-progressbar-value ui-widget-header ui-corner-left"></div> |
| </div> |
| {code} |
| h2. Known Issues |
| |
| None. |
| |
| h2. Additional Resources |