ICEfaces : JavaScript Client API

JavaScript Client API

ICEfaces 2 provides a client-side JavaScript API that allows developers access to various features like form submission, event callbacks, and Ajax Push connection monitoring.

Namespace

The namespace used for the ICEfaces client API is 'ice'. It is defined in the bridge.js file, a link to which is automatically rendered out to each page that uses ICEfaces.

Form Submission API

The functions here allow developers access to the specialized types of form submission (e.g. partial, full, single) provided by ICEfaces.

ice.submit(event, element) or ice.s(event, element)

This is the full submit function that behaves much like a traditional form submission where all form items are posted to the request.

Usage:

ice.submit(myEvent, theSubmittingElement);

Parameters:

  • event

The event captured by the event handler.

  • element

The element owning the event handler.

ice.se(event, element) and ice.ser(event, element)

These functions submit a single element rather than all the elements of the form. This kind of submission reduces the elements serialization overhead and also increases the communication efficiency with the server.

Usage:

ice.se sends javax.faces.partial.execute=@this and javax.faces.partial.render=@all along with the serialized element and event.

ice.se(myEvent, theSubmittingElement);

ice.ser sends javax.faces.partial.execute=@this and javax.faces.partial.render=@this along with the serialized element and event.

ice.ser(myEvent, theSubmittingElement);

Parameters:

  • event

The event captured by the event handler.

  • element

The element owning the event handler.

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.

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:

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

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.onBeforeUpdate(callback)

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

Usage:

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

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

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

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:

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

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:

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

Parameters:

  • statusCode

    The HTTP status code.

  • errorDescription

    The description of the network error.

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:

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

Parameters:

  • source

    The element that triggered the form submission.

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:

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

Parameters:

  • elementID

    The ID of the element to be monitored for removal.

  • callback

    The callback function invoked when the identified element is 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.

Usage:

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

Parameters:

  • callback

    The callback function invoked when the document has been loaded.

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.

Usage:

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

Parameters:

  • callback

    The callback function invoked when the document has been unloaded.

Focus Retention API

The functions here allow developers access to ICEfaces' focus retention mechanism.

ice.setFocus(id) or ice.sf(id)

Accepts an element ID. By calling this function the client will send the ID to the server next time a form submit is invoked. The focus is not moved on the specified element.

Usage:

ice.setFocus(id);

Parameters:

  • id

    The ID of the element.

ice.applyFocus(id) or ice.af(id)

Accepts an element ID. By calling this function the client will move the focus on the specified element and also call ice.setFocus so that the server will be informed about the focus change.

Usage:

ice.applyFocus(id);

Parameters:

  • id

    The ID of the element.

Push Specific API

The following functions are available and valid only when ICEpush is enabled for the application.

ice.onBlockingConnectionUnstable(callback)

Accepts a reference to a callback function. The callback function will be invoked when the client bridge's hearbeat detects that the server isn't responding in a timely fashion.

Usage:

ice.onBlockingConnectionUnstable(connectionUnstableHandler);
...
var connectionUnstableHandler = function() {
...
};

Parameters:

  • none

ice.onBlockingConnectionLost(callback)

Accepts a reference to a callback function. The callback function will be invoked when the blocking connection to the server has been lost and is considered unrecoverable.

Usage:

ice.onBlockingConnectionLost(connectionLostHandler);
...
var connectionLostHandler = function(reconnectionAttempts) {
...
};

Parameters:

  • reconnectionAttempts

    The number of reconnect attempts made by the bridge to re-establish the connection before considering the connection unrecoverable.

ice.onBlockingConnectionServerError(callback)

Accepts a reference to a callback function. The callback function will be invoked when a server error is received by the browser on the blocking connection.

Usage:

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

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.

Configuration API

The following parameters are used to configure certain functional parts of the client.

ice.disableDefaultErrorPopups

This parameter can be used to disable the popups rendered by default when a network error, session expiry or server error occurs. The parameter is usually set when an application or component developer wants to have rendered only the defined custom indicators.

Usage:

ice.disableDefaultErrorPopups = true;

Logging API

ice.log.debug(logger, message, exception)

Logs a DEBUG level message to the console or log window.

ice.log.info(logger, message, exception)

Logs a INFO level message to the console or log window.

ice.log.warn(logger, message, exception)

Logs a WARN level message to the console or log window.

ice.log.error(logger, message, exception)

Logs a ERROR level message to the console or log window.

Usage:

ice.log.debug(ice.log, 'Debug message');

ice.log.info(ice.log, 'Info message');

ice.log.warn(ice.log, 'Warning message');

try {
  ...
} catch (e) {
  ice.log.error(ice.log, 'Error occurred', e);
}

Parameters:

  • logger

    The logger.

  • message

    The message to be logged.

  • responseDOM

    The captured exception. This is an optional parameter.

ice.log.childLogger(parentLogger, categoryName)

Creates an new child logger that logs its messages into the defined category.

Usage:

var a = ice.log.childLogger(ice.log, 'A');
ice.log.debug(a, 'message in category A');
//outputs -- [window.A] debug: message in category A

var aa = ice.log.childLogger(a, 'AA');
ice.log.warn(aa, 'message in category AA');

//outputs -- [window.A.AA] warning: message in category AA

Parameters:

  • logger

    The parent logger.

  • categoryName

    The name of the category.
Copyright © 2012 ICEsoft Technologies, Canada Corp.