Converter objects

JSF Converters convert JSF-formatted string values to/from JavaScriptâ„¢ typed values. For example, the number converter converts the string "$ 1,000.00" (which might be the value of an input field) to a JavaScript number.

Using a converter

In essence, the JSF Converters are JavaScript implementations of the Javaâ„¢ NumberFormat and DateFormat classes (as well as an implementation of a MaskFormat). They convert strings formatted using one of these classes to/from JavaScript typed values.

JSF Converters are used by other JWL componentry when performing field validation, input assist and managing client-side data. Developers writing their own client-side validation may find them useful as well (e.g., if comparing the values of two "numeric" fields, they may use them to convert the values to be JavaScript numbers).

Before you can convert a value, you need to create the converter. For example, create a converter for a datetime using an Islamic calendar, with the format year, month, day, epoch:
<script>
     hX_5.addConverter("2", new hX_5.DateTimeConverter("strict:1", "icu4j", "epoch:i", "format:yyyy/MM/dd G"));
</script>
Use the converter to convert the value of an input field to a JavaScript datetime object:
<script>
	var c = hX_5.getConverterById("2");
	var v = document.getElementById("TestField");
	if (c!=null && v!= null) {
		var dt = c.stringToValue(v.value);
		if (dt!=null) {
			alert ("JavaScript object: " + dt);
		} else {
			alert ("Failed: " + c.lastError());
		}
	}
</script>
In a page where converters are generated by a JSF tag, you can access a converter by retrieving it from the behavior that created it. For example, assume the following JSF tag was put in a page:
<h:inputText styleClass="inputText" id="text1"
size="6" value="#{myBean.myBigDecimal01}">
     <f:convertNumber pattern="##0.0"/>
     <hx:inputHelperSpinner delta="0.1"/>
     <hx:inputHelperAssist validation="true" errorClass="inputText_Error"/>
     <f:validateDoubleRange minimum="-100.0" maximum="100.0"></f:validateDoubleRange>
</h:inputText>
You can retrieve the converter emitted by the JSF-generated behavior by finding the behavior and retrieving the converter-id from the behavior.
<script>
     var cID = hX_5.getBehaviorById("form1:text1", "validate", "onblur").getAttribute("converter");
     var cvt = hX_5.getConverterById(cID);
</script>

hx calls to create and find a converter

Each converter is constructed using a JavaScript constructor and added to the page via an addConverter call.

hX_5.addConverter("id", new hX_5.NameConverter(attributes)); where

id

The ID to be assigned to this converter. The ID must be unique across all created converters within the page (or portal). Any string value may be used as the ID.

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 get a converter object:

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

id

The ID to be assigned to this converter. The ID must be unique across all created converters within the page (or portal). Any string value may be used as the ID.

Common API calls on a converter

To convert a string to a JavaScript object:

var x = cvt.stringToValue("string"); where

cvt

A converter object

string

The string to convert

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 convert a JavaScript object to a string:

var x = cvt.valueToString(value); where

cvt

A converter object

value

A JavaScript object of the type of the converter (Number, Date/Time or String)

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 retrieve information about why the last conversion failed:

var x = cvt.lastError(); where

cvt

A converter object

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 change an attribute of a converter:

cvt.setAttribute("arg"); where

cvt

A converter object

arg

A JSF attribute/value string.

To get an attribute of a converter:

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

cvt

A converter 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.

Table 1. Converter objects

Converter

Description

NumberConverter Convert a string containing a Java-formatted number to/from a JavaScript number object
DateTimeConverter Convert a string containing a Java-formatted date/time to/from a JavaScript date object
MaskConverter Convert a string containing a Java-formatted masked string to/from a JavaScript string object
Related concepts
JSF Widget Library (JWL)
Related tasks
Adding input components to a Faces JSP page

Feedback