SubmitMonitor

Added by Mark Collette, last edited by Arturo Zambrano on Dec 11, 2014  (view change)
Table of Contents

Overview

Since 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).

See the ICEfaces Showcase Live Demo of this component, complete with source code.

Getting Started

To 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">
Now you ready to use ace:submitMonitor component, here is the basic example:

<ace:submitMonitor/>

Attributes

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.
blockUI and autoCenter together control what portion of the page will be covered with a translucent overlay and have events blocked, while a submit is in progress, as well where the ace:submitMonitor will display itself during that time. Valid values for blockUI are:

  • component search string, as would be given in a typical for property. This can be used to block a form or other such large section of a page
  • @all : (default) the whole document body
  • @source : only over the component that originated the request
  • @none : do not present an overlay, and instead have the submitMonitor always be present where it has been placed in the page

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 Events

Not applicable.

Keyboard Support

Not applicable.

Javascript API

ICEfaces 3.x

The 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);
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">).
This component doesn't have a client-side API made specifically to be used by application developers. However, the component's internal methods and variables can be accessed in this way, including the underlying jQuery object and objects from underlying Javascript libraries (if applicable), and can be used for whatever purpose a developer might have in mind.

CSS Classes

The 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 Issues

None.
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.

© Copyright 2021 ICEsoft Technologies Canada Corp.