Event Callback API

Table of Contents

Event Callback API

The functions here allow developers access to the main events that occur in the ICEfaces client-side bridge. This API complements the existing API that's available in JSF 2 that allows the developer to register callbacks for general event and error handling. The ICEfaces API is designed in much the same way as the JSF API. Callback functions are registered that allow the developer to tap into several types of client events that are specific to ICEfaces.

The following Event Callback APIs are available:



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.
Usage:

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.
Usage:

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

Parameters:

  • callback

    The callback function invoked when the document has been 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
Usage:

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


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

© Copyright 2018 ICEsoft Technologies Canada Corp.