Event Callback API

ice.onAfterUpdate(callback)

Accepts a reference to a callback function. The callback function will be invoked after the updates are applied to the DOM.

Usage:

var postUpdateHandler = function(updates) {
...
};
ice.onAfterUpdate(postUpdateHandler);

Parameters:

• updates

A set of <update> elements as defined in the JSF 2.0 JavaScript API documentation (see jsf.ajax.response in http://java.sun.com/javaee/javaserverfaces/2.0/docs/js-api/symbols/jsf.ajax.html).

ice.onBeforeSessionExpiry(callback)

Accepts a reference to a callback function. The callback function will be invoked before the HTTP session will be expired. How much earlier the callback will be invoked is defined in warnBeforeSessionExpiryInterval context parameter.

Usage:

var beforeSessionExpiryHandler = function() {
...
};
ice.onBeforeSessionExpiry(beforeSessionExpiryHandler);

ice.onBeforeSubmit(callback)

Accepts a reference to a callback function. The callback function will be invoked just before the form submit request is issued.

Usage:

var paramHandler = function(source, userInitiated) {
...
};
ice.onBeforeSubmit(paramHandler);

Parameters:

• source

  The element that triggered the form submission.

• userInitiated

  True if the submit was triggered by user (as opposed to a push notification).

ice.onBeforeUpdate(callback)

Accepts a reference to a callback function. The callback function will be invoked before the updates are applied to the DOM.

Usage:

var preUpdateHandler = function(updates) {
...
};
ice.onBeforeUpdate(preUpdateHandler);

Parameters:

• updates

A set of <update> elements as defined in the JSF 2.0 JavaScript API documentation (see jsf.ajax.response in http://java.sun.com/javaee/javaserverfaces/2.0/docs/js-api/symbols/jsf.ajax.html).

ice.onElementRemove(elementID, callback)

Accepts the ID of the element to be monitored for removal and a reference to a callback function. The callback function will be invoked when the element with the specified ID is removed from the document.

Usage:

var callback = function() {
...
};
ice.onElementRemove(elementID, callback);

Parameters:

• elementID

  The ID of the element to be monitored for removal.

• callback

  The callback function invoked when the identified element is removed.

ice.onElementUpdate(elementID, callback)

Accepts the ID of the element to be monitored for update or removal, and a reference to a callback function. The callback function will be invoked when the element with the specified ID is removed from the document. The callback is invoked before the update is applied so that it has a chance to work with objects that are about to be removed or replaced in the document.

Usage:

var callback = function() {
...
};
ice.onElementUpdate(elementID, callback);

Parameters:

• elementID

  The ID of the element to be monitored for update or removal.

• callback

  The callback function invoked when the identified element is updated or removed.

ice.onLoad(callback)

Accepts a reference to a callback function. The callback function will be invoked when the DOM document finished loading. This registration function allows the registration of multiple callbacks without the danger of callback overwriting (unlike the native windown.onload property).

ICEfaces inserts the JS resource defining the ice.onLoad function right before the 'head' ending tag to make sure the scripts are loaded in a deterministic order. Any inline or referenced Javascript code that uses this function needs to be loaded later, preferably right after the 'body' starting tag.

It should also be noted that before ICEfaces 3.1 release ice.onLoad function is backed by the window.onload property. Overwriting this property without chaining the new callback with the previous one would render ICEfaces bridge non-functional. The preferred method of registering callbacks would be to use window.addEventListener or window.attachEvent (in Internet Explorer) functions instead.

var callback = function() {
...
};
ice.onLoad(callback);

Parameters:

• callback

  The callback function invoked when the document has been loaded.

ice.onNetworkError(callback)

Accepts a reference to a callback function. The callback function will be invoked when a network error is detected by the browser during a request-response.

Usage:

var networkErrorHandler = function(statusCode, errorDescription) {
...
};
ice.onNetworkError(networkErrorHandler);

Parameters:

• statusCode

  The HTTP status code.

• errorDescription

  The description of the network error.

ice.onServerError(callback)

Accepts a reference to a callback function. The callback function will be invoked when a server error is received by the browser from a JSF form submit.

Usage:

var serverErrorHandler = function(statusCode, responseText, responseDOM) {
...
};
ice.onServerError(serverErrorHandler);

Parameters:

• statusCode

  The HTTP status code.

• responseText

  The body of the HTTP response in text format.

• responseDOM

  The parsed body of the HTTP response as XML. This parameter is present only when response is in XML/HTML format.

ice.onSessionExpiry(callback)

Accepts a reference to a callback function. The callback function will be invoked when the HTTP session has been invalidated or expired.

Usage:

var sessionExpiryHandler = function() {
...
};
ice.onSessionExpiry(sessionExpiryHandler);

ice.onUnload(callback)

Accepts a reference to a callback function. The callback function will be invoked when the DOM document is unloaded. This registration function allows the registration of multiple callbacks without the danger of callback overwriting (unlike the native windown.onunload property).

ICEfaces inserts the JS resource defining the ice.onUnload function right before the 'head' ending tag to make sure the scripts are loaded in a deterministic order. Any inline or referenced Javascript code that uses this function needs to be loaded later, preferably right after the 'body' starting tag.

It should also be noted that before ICEfaces 3.1 release ice.onUnload function is backed by the window.onunload property. Overwriting this property without chaining the new callback with the previous one would render ICEfaces bridge non-functional. The preferred method of registering callbacks would be to use window.addEventListener or window.attachEvent (in Internet Explorer) functions instead.

var callback = function() {
...
};
ice.onUnload(callback);

Parameters:

• callback

  The callback function invoked when the document has been unloaded.

ice.onBeforeUnload(callback)

Accepts a reference to a callback function. The callback function will be invoked before the DOM document is unloaded. This registration function allows the registration of multiple callbacks without the danger of callback overwriting (unlike the native windown.onbeforeunload property).

ICEfaces inserts the JS resource defining the ice.onBeforeUnload function right before the 'head' ending tag to make sure the scripts are loaded in a deterministic order. Any inline or referenced Javascript code that uses this function needs to be loaded later, preferably right after the 'body' starting tag.

It should also be noted that before ICEfaces 3.1 release ice.onBeforeUnload function is backed by the window.onbeforeunload property. Overwriting this property without chaining the new callback with the previous one would render ICEfaces bridge non-functional. The preferred method of registering callbacks would be to use window.addEventListener or window.attachEvent (in Internet Explorer) functions instead.

var callback = function() {
...
};
ice.onBeforeUnload(callback);

Parameters:

• callback

  The callback function invoked before the document is unloaded.

ice.onUserInactivity(interval, idleCallback, activeCallback)

(Since ICEfaces 3.4)

Accepts the registration of callbacks that can be used to monitor user's activity within a page. When the user is idle (no keyboard or mouse events triggered) for more than the specified interval the idleCallback will be invoked. In case the user resumes activity after the interval has elapsed the activeCallback will be invoked.

The callbacks can be used for example to render an alert but remove the alert once the user resumes activity

var idleCallback = function() {
...//display alert and/or postback form data
};
var activeCallback = function() {
...//hide alert
};
ice.onUserInactivity(interval, idleCallback, activeCallback);
...//or optionally
var userActiveEvents = ['click', 'keydown'];
ice.onUserInactivity(interval, idleCallback, activeCallback, userActiveEvents);

Parameters:

• interval

  The interval after which the idleCallback will be invoke if the user is idle.

• idleCallback

  The callback function invoked when the specified interval has elapsed.

• activeCallback

  The callback function invoked when the user becomes active again, only when the specified interval has elapsed.

• userActiveEvents (Since ICEfaces 4.1)

  An array of JS event names used for detecting the user activity ('blur' and 'focus' events cannot be used since they do not bubble up).