Component objects

A JavaServer Face (JSF) component extends an HTML DOM object providing it with additional input and output functionality and visualization.

Using a JSF component object

Components preserve as much of the original tags functionality as possible. They provide a new type of a tag. For example, the date picker can be thought of as an <input type="datepicker"> tag where the resulting object maintains the input tag size, CSS attributes, display within a line, tab-order, z-order, language characteristics, and events.

In general, components either extend an input tag and/or a div. A few of the components are used to build other components (for example a menu item).

Most components add a visual element to the page. For example, the calendar component draws a calendar on the page. The visual element of the component is controlled via a set of CSS classes that define the look of the component in general and the look of specific elements within the component.

To use a JSF component object:
  1. Style the object by adding a CSS to the page. For example:
    <style>
    .button1, .button1_moused {
        width:100px;
        height:21px;
    }
    .button1_Label, .button1_Label_moused {
        font-family:sans-serif;
        color:black;
        font-size:14px;
        text-align:left;
        margin-left: 24px;
    }
    </style>
  2. Add the tag the behavior applies to in the page. For example:
    <input type="submit" class="MenuBar_button2b" id="form1:button2" alt="New" title="New" value="New" />
  3. Attach the component to the DOM object. For example:
    <script>
        hX.addComponent("form1:button2", new hX.JSFImage("normal:img/search-button.gif", 
        "moused:img/search-button-moused.gif", "label:New"));
    </script>
In this example the input tag is modified by the image component. It displays an image with text and its display changes on mouse action.

hx calls to create/find a component

Each component is constructed using a Javascript constructor and added to the page via an addComponent call.

hX_5.addComponent ("id", new hX_5.JSFName(attributes)); where

id

The ID of the HTML tag to which the component is attached.

name

The name of the JSF Component.

attributes

Comma separated list of attributes where each attribute is a quoted string consisting of the attribute name and value separated by a colon, for example "label:MyLabel".

Note: Only one component can be attached to a DOM object.

Some components (for example the menu bar) contain subcomponents. To construct a subcomponent:

hX_5.addSubComponent ("parent-id", "id", new hX_5.JSFName(attributes), position);

parent-id

ID of the JSF Component that is the parent of this subcomponent.

id

The ID of the HTML tag to which the component is attached.

name

The name of the JSF Component.

attributes

Comma separated list of attributes where each attribute is a quoted string consisting of the attribute name and value separated by a colon, for example "label:MyLabel".

position

Position of this subcomponent relative to other subcomponents with the same parent. If omitted, the subcomponent is appended.

Subcomponents can also be added collectively with the following syntax:

hX_5.addSubComponent ("parent-id", [ new hX_5.JSFName(attributes), ... ]); where

parent-id

ID of the JSF Component that is the parent of this subcomponent.

name

The name of the JSF Component.

attributes

Comma separated list of attributes where each attribute is a quoted string consisting of the attribute name and value separated by a colon, for example "label:MyLabel".

To remove a subcomponent:

var x = hX_5.removeSubComponent("parent-id", "id"); where

parent-id

ID of the JSF Component that is the parent of this subcomponent.

id

The ID of the HTML tag to which the component is attached.

To get a specific component object:

var o = hX_5.getComponentById("id"); where

id

The ID of the HTML tag to which the component is attached.

returns

A JavaScriptâ„¢ object of the type of the converter (Number, DateTime or String). If the conversion cannot be done, null is returned and lastError is set.

To get all components within a DOM object (e.g., all components attached to any tags within a div):

var a = hX_5.getComponentsInId("id"); where

id

The ID of the HTML tag to which the component is attached.

returns

A JavaScript object of the type of the converter (Number, DateTime or String). If the conversion cannot be done, null is returned and lastError is set.

To get a subcomponent object:

var o = hX_5.getSubComponentById("id"); where

id

The ID of the HTML tag to which the component is attached.

returns

A JavaScript object of the type of the converter (Number, DateTime or String). If the conversion cannot be done, null is returned and lastError is set.

To get the parent of a subcomponent:

var x = hX_5.getParentComponentById("id"); where

id

The ID of the HTML tag to which the component is attached.

returns

A JavaScript object of the type of the converter (Number, DateTime or String). If the conversion cannot be done, null is returned and lastError is set.

Common API calls on a component

To change an attribute of a component or subcomponent:

c.setAttribute("arg"); where

c

A component object.

arg

A JSF attribute/value string.

To get an attribute of a component or subcomponent:

var x = c.getAttribute("argname"); where

c

A component object.

argname

A string containing the name of the attribute.

returns

A JavaScript object of the type of the converter (Number, DateTime or String). If the conversion cannot be done, null is returned and lastError is set.

To redraw a component taking into account any changes made to the attributes or properties of the base tag. This is used when an attribute or property is changed:

var x = c.redraw(); where

c

A component object.

To release any active UI elements in a component (for example deselect any buttons in the component):

var x = c.uirelease(); where

c

A component object.

To set the value of a component. For components based on an input tag, this is equivalent to setting the value attribute of the input tag except it also ensures the value provided is valid (that is it will convert and validate it).

var x = c.setValue("string"); where

c

A component object.

string

The string to convert

To get the value of a component. For components based on an input tag, this is equivalent to getting the value attribute of the input tag except the value can be cast to something other than a string.

var x = c.getValue(boolean); where

c

A component object.

boolean

Cast the return value to a JS object of the appropriate type.

returns

A JavaScript object of the type of the converter (Number, DateTime or String). If the conversion cannot be done, null is returned and lastError is set.

Responding to Changes in the Underlying Object

Components modify a base HTML DOM object, for example, a date picker modifies an input tag. When a change is programmatically made to the base tag, for example the tag is disabled, the component should pick up the change and reflect the change.

For example, if you disable the base tag, the component should disable. Due to browser limitations and component implementation limitations changes may not be picked up and reflected. When a base tag is changed, if the component does not pick up the change, you need to notify the component that a change has been made. This is done by calling the component redraw function:
// Get an html tag and disable it
var obj = document.getElementById("form1:text1");
obj.disabled = true;
// Force the component to acknowledge the change
var c = hX_5.getComponentById("form1:text1");
c.redraw();

Note that changes made to a base object style either directly (by setting a style property) or indirectly (by changing a CSS rule), are not picked up and you must call redraw in these cases.

In some cases it is not possible to modify a specific attribute or property of a base object. These limitations are rare and are noted in the documentation of the components. In general, these limitations are value specific, for example you cannot change a component from being proportionally sized to being absolutely sized.

Table 1. Component objects

Component

Description

JSFCalendar Modify an input field to be a small calendar that can be used to choose a date.
JSFColorPicker Modify an input field to be a combo-box used to pick a color.
JSFDataTable Manages the client-side interactions for advanced JSF DataTable functions such as vertical scrolling, selection, etc.
JSFDatePicker Modify an input field to include a button that pops up a small calendar that can be used to select a date.
JSFDialog Modify a div into a modal or modeless dialog box.
JSFImage Modify a button or an image to contain multiple images or text and/or to have multiple states (normal, mouse-overed, depressed, disabled).
JSFMenu Modify a div to be a menu or a tree of menus (a menu bar).
JSFMenuItem (sub component) An element within a menu.
JSFProgressBar Modify a div to be a progress bar.
JSFSection Modify a div to be a collapsible or expandable section.
JSFSlider Modify an input field to include a button that pops up a slider that can be used to select a value for the field.
JSFSpinner Modify an input field to include a pair of spinner buttons that can be used to increment or decrement the field value by a specified interval.
JSFTwistie Provides bind function or action to any HTML event handler.
Related concepts
JSF Widget Library (JWL)

Feedback