Using Converters, Listeners, and Validators

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.

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:

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 Converter Classes and Converter IDs:

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.

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. Attributes for the f:convertDateTime Tag lists the attributes.

Here is a simple example of a convertDateTime tag:

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:

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

If you want to display the example date in Spanish, you can use the locale attribute:

This tag would display the following output:

Refer to the "Customizing Formats" lesson of the Java Tutorial at https://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.

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. Attributes for the f:convertNumber Tag lists the attributes.

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

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:

This result can also be displayed by using the following tag in which the currency pattern is specified:

See the "Customizing Formats" lesson of the Java Tutorial at https://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.

A page author can register a ValueChangeListener implementation on a component that implements EditableValueHolder by nesting an f:valueChangeListener tag within the component’s tag on the page. The f:valueChangeListener tag supports the attributes shown in Attributes for the f:valueChangeListener Tag, one of which must be used.

The following example shows a value-change listener registered on a component:

In the example, the core tag type attribute specifies the custom NameChanged listener as the ValueChangeListener implementation registered on the name component.

After this component tag is processed and local values have been validated, its corresponding component instance will queue the ValueChangeEvent associated with the specified ValueChangeListener to the component.

The binding attribute is used to bind a ValueChangeListener implementation to a managed bean property. This attribute works in a similar way to the binding attribute supported by the standard converter tags. See Binding Component Values and Instances to Managed Bean Properties for more information.

A page author can register an ActionListener implementation on a command component by nesting an f:actionListener tag within the component’s tag on the page. Similarly to the f:valueChangeListener tag, the f:actionListener tag supports both the type and binding attributes. One of these attributes must be used to reference the action listener.

Here is an example of an h:commandLink tag that references an ActionListener implementation:

The type attribute of the f:actionListener tag specifies the fully qualified class name of the ActionListener implementation. Similarly to the f:valueChangeListener tag, the f:actionListener tag also supports the binding attribute. See Binding Converters, Listeners, and Validators to Managed Bean Properties for more information about binding listeners to managed bean properties.

In addition to the actionListener tag that allows you register a custom listener onto a component, the core tag library includes the f:setPropertyActionListener tag. You use this tag to register a special action listener onto the ActionSource instance associated with a component. When the component is activated, the listener will store the object referenced by the tag’s value attribute into the object referenced by the tag’s target attribute.

The bookcatalog.xhtml page of the Duke’s Bookstore application uses f:setPropertyActionListener with two components: the h:commandLink component used to link to the bookdetails.xhtml page and the h:commandButton component used to add a book to the cart:

The h:commandLink and h:commandButton tags are within an h:dataTable tag, which iterates over the list of books. The var attribute refers to a single book in the list of books.

The object referenced by the var attribute of an h:dataTable tag is in page scope. However, in this case you need to put this object into request scope so that when the user activates the commandLink component to go to bookdetails.xhtml or activates the commandButton component to go to bookcatalog.xhtml, the book data is available to those pages. Therefore, the f:setPropertyActionListener tag is used to set the current book object into request scope when the commandLink or commandButton component is activated.

In the preceding example, the f:setPropertyActionListener tag’s value attribute references the book object. The f:setPropertyActionListener tag’s target attribute references the value expression requestScope.book, which is where the book object referenced by the value attribute is stored when the commandLink or the commandButton component is activated.

To validate a component’s value using a particular validator, you need to register that validator on the component. You can do this in one of the following ways.

See Referencing a Method That Performs Validation for more information on using the validator attribute.

The validatorId attribute works similarly to the converterId attribute of the converter tag, as described in Converting a Component’s Value.

Keep in mind that validation can be performed only on components that implement EditableValueHolder, because these components accept values that can be validated.

The following example shows how to use the f:validateLongRange validator tag on an input component named quantity:

This tag requires the user to enter a number that is at least 1. The validateLongRange tag also has a maximum attribute, which sets a maximum value for the input.

The attributes of all the standard validator tags accept EL value expressions. This means that the attributes can reference managed bean properties rather than specify literal values. For example, the f:validateLongRange tag in the preceding example can reference managed bean properties called minimum and maximum to get the minimum and maximum values acceptable to the validator implementation, as shown in this snippet from the guessnumber-faces example:

The following f:validateRegex tag shows how you might ensure that a password is from 4 to 10 characters long and contains at least one digit, at least one lowercase letter, and at least one uppercase letter:

If your page includes a component, such as a button or a link, that causes the application to navigate to another page when the component is activated, the tag corresponding to this component must include an action attribute. This attribute does one of the following:

The following example shows how to reference a navigation method:

See Writing a Method to Handle Navigation for information on how to write such a method.

If a component on your page generates an action event, and if that event is handled by a managed bean method, you refer to the method by using the component’s actionListener attribute.

The following example shows how such a method could be referenced:

The actionListener attribute of this component tag references the chooseBookFromLink method using a method expression. The chooseBookFromLink method handles the event when the user clicks the link rendered by this component. See Writing a Method to Handle an Action Event for information on how to write such a method.

If the input of one of the components on your page is validated by a managed bean method, refer to the method from the component’s tag by using the validator attribute.

The following simplified example from The guessnumber-cdi CDI Example shows how to reference a method that performs validation on inputGuess, an input component:

The managed bean method validateNumberRange verifies that the input value is within the valid range, which changes each time another guess is made. See Writing a Method to Perform Validation for information on how to write such a method.

If you want a component on your page to generate a value-change event and you want that event to be handled by a managed bean method instead of a ValueChangeListener implementation, you refer to the method by using the component’s valueChangeListener attribute:

The valueChangeListener attribute of this component tag references the processValueChange method of CashierBean by using a method expression. The processValueChange method handles the event of a user entering a name in the input field rendered by this component.

Writing a Method to Handle a Value-Change Event describes how to implement a method that handles a ValueChangeEvent.