Adding JSF client side support to an HTML page

The hxclient JavaScript library implements the client-side support for JSF Widget Library (JWL) components in an HTML page. The library currently implements most but not all of the client-side support. Some components are implemented in a second set of libraries, the Odyssey Browser Framework (OBF) libraries.

Using the hxclient library

When creating a page, the hxclient library can be used in one of two ways:

In a Faces JSP page, use of the library is transparent. JSF tags automatically initialize, manage and use the library in the emitted HTML. Special coding is not required to use the library.
In a JSP page or an HTML page, the library needs to be initialized. Components, behaviors, and supporting components (such as converters and validators) are created by explicit JavaScript calls.

Once a page is running in the browser, JavaScript is used, typically in an event handler, to modify the page DOM and/or to modify JWL components. For example:

JavaScript can modify the attributes and CSS properties of DOM objects that are managed by the hxclient library. For example, JavaScript is used to hide or show an <input> tag that the hxclient library has turned into a color picker. In most cases, special coding is not required. The hxclient library monitors DOM nodes. Changes to the DOM are automatically managed by the library. There are a few cases where browsers do not correctly monitor changes (for example when dealing with the disabling of DOM objects). Explicit calls to the hxclient library need to be coded in these cases.
Explicit JavaScript calls are used to modify the behavior of the library (for example to add or remove elements from a menu bar). Explicit JavaScript calls are also used by facilities of the library (for example to convert a string formatted as a date to a JavaScript datetime object).

Structure of the hxclient Library API - the hx object

The hxclient library installs itself as a single global JavaScript object in a page. All API calls are made on this single object or on objects returned by this object.

In a non-portlet page, hxclient object is always named hX. The base API calls are all functions attached to this object. For example, the hX.redraw(); call forces all hxclient objects on the page to redraw themselves.

In a portlet page, it is possible that different JWL pages use different version of the library. Instances of the library are version stamped. A page can contain multiple version of the library. When this occurs an instance of the library is instantiated and a variation of the hx object is created with the version number included in the name.

The hX object supports two kinds of functions:

access functions
utility functions

Each supported component, behavior, converter, validator, and assist is defined by an hxclient object. The hxclient object can be thought of as a peer of a DOM object that gives the DOM object additional capabilities. For example, given an <input> DOM object (representing an <input> tag in the page), if the tag is used as a date picker, there is a parallel hxclient object called a JSFDatePicker object. To access the DOM object you call:

var obj = document.getElementById("form1:text1");

To access the parallel hxclient object, you make use an accessor function of the hX object:

var obj = hX.getComponentById("form1:text1");

Just as there is a well defined API for manipulating a DOM object once it has been accessed, there is a well defined API for manipulating a hxclient object once it has been accessed.

In addition to accessor functions, the hX object supports a set of utility functions. These functions primarily provide a browser neutral way of performing DOM manipulations. For example, there are calls that can set focus on an object, that works regardless of the browser type, and calls that manage the addition and removal of event handlers from an object.

Page structure

In a Faces JSP page, the hxclient library is installed and managed for you. The JSF tags ensure that the library is installed in the page and that appropriate calls are made to initialize and use the library.

In a non-JSF page, the page must be structured to include the library, its supporting libraries and stylesheets, the library initialization, and calls made to instantiate components and behaviors in the page.

Note: The structure of the page is changing as JWL 3.0 is being developed (for example libraries will be refactored). If you are hand coding the page to use JWL, you will need to modify at least the includes used as the hxclient code base is changed.

<HEAD>
...
    <!-- Include a stylesheet that styles the JWL components -->
    <LINK rel="stylesheet" type="text/css" href="theme/stylesheet.css" title="Style">
...    
<HEAD>

<BODY>
...html...
    <!-- Include the hxclient library -->
    <script type="text/JavaScript" language="JavaScript" src="/project/.ibmjsfres/hxclient_v3_0.js"></script>
    <!-- (Optional) Include a localized string library -->
    <script charset="ISO-8859-1" type="text/JavaScript" language="JavaScript" src="/project/.ibmjsfres/hxclient_v3_0.js"></script>
    <!-- (Optional, required for portlet) Identify the Resource Server -->
    <script type="text/javascript">
        if (hX_5) hX_5.setResourceServer("/project/.ibmjsfres");
    </script>

... html ...

    <!-- Declare an appropriate HTML tag -->
    <input type="submit" value="submit" id="form1:button1" />
    <input id="form1:text1" type="text" value="03/14/2006" />
    <!-- Specify what is to be done to the tag -->
    <script type="text/javascript">
        hX_5.addBehavior("form1:button1", "onclick", new hX.JSFBehaviorGeneric("action:confirm", "target:Do you want to submit this form?"));
        hX_5.addComponent("form1:text1", new hX.JSFDatePicker());
    </script>

... html ...

    <!-- Initialize the page -->
    <script type="text/javascript">
        if (hX_5) hX_5.onPageLoad();
    </script>
</BODY>

Feedback