11.1 Using the Standard Converters

11.1.1 Converting a Component's Value

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

• Nest one of the standard converter tags inside the component's tag. These tags are f:convertDateTime and f:convertNumber, which are described in Using DateTimeConverter and Using NumberConverter, respectively.

• Bind the value of the component to a managed bean property of the same type as the converter. This is the most common technique.

• Refer to the converter from the component tag's converter attribute, specifying the ID of the converter class.

• Nest an f:converter tag inside of the component tag, and use either the f:converter tag's converterId attribute or its binding attribute to refer to the converter.

As an example of the second technique, if you want a component's data to be converted to an Integer, you can simply bind the component's value to a managed bean property. Here is an example:

Integer age = 0;
public Integer getAge(){ return age;}
public void setAge(Integer age) {this.age = age;}

The data from the h:inputText tag in the this example will be converted to a java.lang.Integer value. The Integer type is a supported type of NumberConverter. If you don't need to specify any formatting instructions using the f: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.

You can also nest an f: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 that uses one of the converter IDs listed in Table 11-1:

<h:inputText value="#{loginBean.age}">
    <f:converter converterId="javax.faces.Integer" />
</h:inputText>

Instead of using the converterId attribute, the f:converter tag can use the binding attribute. The binding attribute must resolve to a bean property that accepts and returns an appropriate Converter instance.

You can also create custom converters and register them on components using the f:converter tag. For details, see Creating and Using a Custom Converter.

11.1.2 Using DateTimeConverter

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 11-2 lists the attributes.

Here is a simple example of a convertDateTime tag:

<h:outputText value="#{cashierBean.shipDate}">
    <f:convertDateTime type="date" dateStyle="full" />
</h:outputText>

When binding the DateTimeConverter to a component, ensure that the managed bean property to which the component is bound is of type java.util.Date. In the preceding example, cashierBean.shipDate must be of type java.util.Date.

The example tag can display the following output:

Saturday, September 21, 2013

You can also display the same date and time by using the following tag in which the date format is specified:

<h:outputText value="#{cashierBean.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:outputText value="#{cashierBean.shipDate}">
    <f:convertDateTime dateStyle="full"
                       locale="es"
                       timeStyle="long" type="both" />
</h:outputText>

This tag would display the following output:

jueves 24 de octubre de 2013 15:07:04 GMT

Refer to the "Customizing Formats" lesson of the Java Tutorial at http://docs.oracle.com/javase/tutorial/i18n/format/simpleDateFormat.html for more information on how to format the output using the pattern attribute of the convertDateTime tag.

11.1.3 Using NumberConverter

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 11-3 lists the attributes.

The following example uses a convertNumber tag to display the total prices of the contents of a shopping cart:

<h:outputText value="#{cart.total}">
    <f:convertNumber currencySymbol="$" type="currency"/>
</h:outputText>

When binding the NumberConverter to a component, ensure that the managed bean property to which the component is bound is of a primitive type or has a type of java.lang.Number. In the preceding example, cart.total is of type double.

Here is an example of a number that this tag can display:

$934

This result can also be displayed by using the following tag in which the 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://docs.oracle.com/javase/tutorial/i18n/format/decimalFormat.html for more information on how to format the output by using the pattern attribute of the convertNumber tag.