OverviewSince 3.2 The ace:submitMonitor component is used to display the status of the browser's connection with the server, whether it is currently idle, actively processing a submission, experiencing a network or server error, or if the session has expired. When a long duration submission is underway, the submitMonitor may block configurable portions of the user interface, to prevent users from further interacting with the page until the results of their submission have been returned, and the user interface has been updated. This can be used to enforce a consistent state. For each connection status that the submitMonitor can display, it's representation is customisable. By default an image is shown, and a label property can be specified as well, or, alternatively, a facet may be used to completely customise the representation. All of which can be styled with CSS. Multiple submitMonitor components may exist on the page, each listening to submissions from components in different regions of the page. This way, each submitMonitor may be customised to best inform the user of the submission status of the particular component(s).
Getting StartedTo use the ace:submitMonitor component, first the ACE Components tag-lib name-space has to be added in your page. <html ... xmlns:ace="http://www.icefaces.org/icefaces/components">
<ace:submitMonitor/>
Attributes
For all the values of blockUI that employ the overlay, that is, every value except @none, autoCenter will default to true, and show the ace:submitMonitor in a popup centered over the page. It may be set to false, to continue showing it where it has been placed in the page without a popup. It can be advantageous to place the ace:submitMonitor itself outside of any portion of the page that will receive updates, and then use blockUI to have it be shown over the area that is being submitted. <ace:submitMonitor blockUI=":myform"/> <h:form id="myform> ... </h:form> idleLabel, activeLabel, serverErrorLabel, networkErrorLabel and sessionExpiredLabel are used to specify the various text labels, for each state that the ace:submitMonitor can be in. Each of these is shown along with a corresponding image. Alternatively, the idle, active, serverError, networkError and sessionExpired facets can be specified to fully customise the view of each state. <ace:submitMonitor idleLabel="Not currently submitting" activeLabel="Busy submitting to server..."> <f:facet name="serverError"> <h:panelGroup> ... </h:panelGroup> </f:facet> </ace:submitMonitor> for property is specified similarly to any other typical for property, except that it can take a space delimited list of component search strings, not just a single one. These describe the regions of the page that this ace:submitMonitor will monitor for submits, where each component and every component within it will be monitored. If this property is not specified, then the default is for the whole page to be monitored. <h:form id="myform"> <h:inputText id="firstName" value="#{bean.firstName}"> <f:ajax/> </h:inputText> <ace:submitMonitor for="firstName" activeLabel="Submitting the user's first name"/> <br/> <h:inputText id="lastName" value="#{bean.lastName}"> <f:ajax/> </h:inputText> <ace:submitMonitor for="lastName" activeLabel="Submitting the user's last name"/> </h:form> styleClass property is for giving a specific ace:submitMonitor a customised styling. This can be used to override the images, text colouring and general appearance used for each state. The CSS example below will show how to change the styling of all ace:submitMonitor components on the page, as well as how to change the styling of specific ones, using the styleClass property. <ace:submitMonitor id="anySubmitMonitor"/> <ace:submitMonitor id="specificSubmitMonitor" styleClass="applicationClass" /> /* Changing the icon and text coloring for the active state of any submitMonitor on the page */ .ice-sub-mon > .ice-sub-mon-mid.active > .ice-sub-mon-img { background-image:url("/application/javax.faces.resource/active_icon_flashing.gif.jsf"); background-repeat:no-repeat; width: 16px; height: 16px; } .ice-sub-mon > .ice-sub-mon-mid.active > .ice-sub-mon-txt { color: green; } /* Changing the icon and text coloring for the active state of specific submitMonitor(s) that have that styleClass */ .ice-sub-mon.applicationClass > .ice-sub-mon-mid.active > .ice-sub-mon-img { background-image:url("/application/javax.faces.resource/active_icon_spinning.gif.jsf"); background-repeat:no-repeat; width: 20px; height: 20px; } .ice-sub-mon.applicationClass > .ice-sub-mon-mid.active > .ice-sub-mon-txt { color: blue; } preload property, by default, causes the state images to be preloaded, so that there will be no lag in displaying them on a state change, and ensure they're already available in the browser for when showing a state of a server or network error, when it would no longer be possible to retrieve them from the server. This is only used when a facet is not provided. Client Behavior EventsNot applicable. Keyboard SupportNot applicable. Javascript APIICEfaces 3.xThe client side component object is exposed through the global variable name specified in the widgetVar attribute. 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. var widget = ice.ace.instance('frm:componentId);
CSS ClassesThe following markup represents the basic HTML structure of the component and the CSS classes it uses. <div> <div class="ice-sub-mon ui-widget [user defined classes]"> <!-- Idle state --> <div class="ice-sub-mon-mid idle"> <span class="ice-sub-mon-img"></span> <span class="ice-sub-mon-txt">Idle</span> </div> <!-- Active state --> <div class="ice-sub-mon-mid active"> <span class="ice-sub-mon-img"></span> <span class="ice-sub-mon-txt">Submitting...</span> </div> <!-- ServerError state --> <div class="ice-sub-mon-mid serverError ui-state-error"> <span class="ice-sub-mon-img ui-icon ui-icon-alert"></span> <span class="ice-sub-mon-txt ui-state-error-text">Server error</span> </div> <!-- NetworkError state --> <div class="ice-sub-mon-mid networkError ui-state-error"> <span class="ice-sub-mon-img ui-icon ui-icon-alert"></span> <span class="ice-sub-mon-txt ui-state-error-text">Network error</span> </div> <!-- SessionExpired state --> <div class="ice-sub-mon-mid sessionExpired ui-state-error"> <span class="ice-sub-mon-img ui-icon ui-icon-clock"></span> <span class="ice-sub-mon-txt ui-state-error-text">Session expired</span> </div> </div> </div> Known IssuesNone. |
SubmitMonitor
© Copyright 2021 ICEsoft Technologies Canada Corp.