The JavaServerTM Faces implementation provides a set of Converter implementations that you can use to convert component data.
The standard Converter implementations, located in the javax.faces.convert package, are as follows:
A standard error message associated with each of these converters. If you have registered one of these converters onto a component on your page, and the converter is not able to convert the component’s value, the converter’s error message will display on the page. For example, the error message that displays if BigIntegerConverter fails to convert a value is:
{0} must be a number consisting of one or more digits |
In this case, the {0} substitution parameter will be replaced with the name of the input component on which the converter is registered.
Two of the standard converters (DateTimeConverter and NumberConverter) have their own tags, which allow you to configure the format of the component data using the tag attributes. For more information about using DateTimeConverter, see Using DateTimeConverter. For more information about using NumberConverter, see Using NumberConverter. The following section explains how to convert a component’s value, including how to register other standard converters with a component.
To use a particular converter to convert a component’s value, you need to register the converter onto the component. You can register any of the standard converters in one of the following four ways:
Nest one of the standard converter tags inside the component’s tag. These tags are convertDateTime and convertNumber, which are described in Using DateTimeConverterand Using NumberConverter, respectively.
Bind the value of the component to a backing bean property of the same type as the converter.
Refer to the converter from the component tag’s converter attribute.
Nest a converter tag inside of the component tag and use either the converter tag’s converterId attribute or its binding attribute to refer to the converter.
As an example of the second way, if you want a component’s data to be converted to an Integer, you can simply bind the component’s value to a backing bean property. Here is an example:
Integer age = 0; public Integer getAge(){ return age;} public void setAge(Integer age) {this.age = age;}
If the component is not bound to a bean property, you can employ the third method by using the converter attribute directly on the component tag:
<h:inputText converter="javax.faces.convert.IntegerConverter" />
This example shows the converter attribute referring to the fully-qualified class name of the converter. The converter attribute can also take the ID of the component.
The data from inputText tag in the this example will be converted to a java.lang.Integer. The Integer type is already a supported type of the NumberConverter. If you don’t need to specify any formatting instructions using the convertNumber tag attributes, and if one of the standard converters will suffice, you can simply reference that converter by using the component tag’s converter attribute.
Finally, you can nest a converter tag within the component tag and use either the converter tag’s converterId attribute or its binding attribute to reference the converter.
The converterId attribute must reference the converter’s ID. Here is an example:
<h:inputText value="#{LoginBean.Age}" /> <f:converter converterId="Integer" /> </h:inputText>
Instead of using the converterId attribute, the converter tag can use the binding attribute. The binding attribute must resolve to a bean property that accepts and returns an appropriate Converter instance.
Custom converters and using binding attribute are advanced topics covered in Java EE 6 Tutorial, Volume II: Advanced Topics.
You can convert a component’s data to a java.util.Date by nesting the convertDateTime tag inside the component tag. The convertDateTime tag has several attributes that allow you to specify the format and type of the data. Table 8–1 lists the attributes.
Here is a simple example of a convertDateTime tag:
<h:outputText id= "shipDate" value="#{cashier.shipDate}"> <f:convertDateTime dateStyle="full" /> </h:outputText>
When binding the DateTime converter to a component, ensure that the backing bean property to which the component is bound is of type java.util.Date. In the preceding example, cashier.shipDate must be of type java.util.Date.
The example tag can display the following output:
Saturday, September 26, 2009 |
You can also display the same date and time by using the following tag where date format is specified:
<h:outputText value="#{cashier.shipDate}"> <f:convertDateTime pattern="EEEEEEEE, MMM dd, yyyy" /> </h:outputText>
If you want to display the example date in Spanish, you can use the locale attribute:
<h:inputText value="#{cashier.shipDate}"> <f:convertDateTime dateStyle="full" locale="Locale.SPAIN" timeStyle="long" type="both" /> </h:inputText>
This tag would display the following output:
sabado 26 de septiembre de 2009 |
Refer to the Customizing Formats lesson of the Java Tutorial at http://java.sun.com/docs/books/tutorial/i18n/format/simpleDateFormat.html for more information on how to format the output using the pattern attribute of the convertDateTime tag.
Table 8–1 convertDateTime Tag Attributes
You can convert a component’s data to a java.lang.Number by nesting the convertNumber tag inside the component tag. The convertNumber tag has several attributes that allow you to specify the format and type of the data. Table 8–2 lists the attributes.
The following example uses a convertNumber tag to display the total prices of the books in the shopping cart:
<h:outputText value="#{cart.total}" > <f:convertNumber type="currency"/> </h:outputText>
When binding the Number converter to a component, ensure that the backing bean property to which the component is bound is of primitive type or has a type of java.lang.Number. In the case of the preceding example, cart.total is of type java.lang.Number.
Here is an example of a number that this tag can display:
$934 |
This result can also be displayed using the following tag where currency pattern is specified:
<h:outputText id="cartTotal" value="#{cart.Total}" > <f:convertNumber pattern=" $####" /> </h:outputText>
See the Customizing Formats lesson of the Java Tutorial at http://java.sun.com/docs/books/tutorial/i18n/format/decimalFormat.html for more information on how to format the output using the pattern attribute of the convertNumber tag.
Table 8–2 convertNumber Attributes
Attribute |
Type |
Description |
---|---|---|
binding |
NumberConverter |
Used to bind a converter to a backing bean property. |
currencyCode |
String |
ISO 4217 currency code, used only when formatting currencies. |
currencySymbol |
String |
Currency symbol, applied only when formatting currencies. |
groupingUsed |
boolean |
Specifies whether formatted output contains grouping separators. |
integerOnly |
boolean |
Specifies whether only the integer part of the value will be parsed. |
locale |
String or Locale |
Locale whose number styles are used to format or parse data. |
maxFractionDigits |
int |
Maximum number of digits formatted in the fractional part of the output. |
maxIntegerDigits |
int |
Maximum number of digits formatted in the integer part of the output. |
minFractionDigits |
int |
Minimum number of digits formatted in the fractional part of the output. |
minIntegerDigits |
int |
Minimum number of digits formatted in the integer part of the output. |
pattern |
String |
Custom formatting pattern that determines how the number string is formatted and parsed. |
type |
String |
Specifies whether the string value is parsed and formatted as a number, currency, or percentage. If not specified, number is used. |
for |
String |
Used with composite components. Refers to one of the objects within the composite component inside which this tag is nestled. |