Skip Headers

Oracle® Application Development Framework Developer's Guide 10g Release 3 (10.1.3) B25386-01 |
| Home | Solution Area | Contents | Index

Previous | Next |

# 12.5 Adding Conversion

A web application can store data of many types (such as `int`, `long`, `date`) in the model layer. When viewed in a client browser, however, the user interface has to present the data in a manner that can be read or modified by the user. For example a date field in a form might represent a `java.util.Date` object as a text string in the format pattern `mm/dd/yyyy`. When a user edits a date field and submits the form, the string must be converted back to the type that is required by the application. Then the data is validated against any rules and conditions.

When you create an `inputText` component by dropping an attribute that is of a type for which there is a converter, JDeveloper automatically adds that converter's tag as a child of the input component. This tag invokes the converter, which will convert the `String` entered by the user back into the type expected by the object.

The JSF standard converters, which handle conversion between `Strings` and simple data types, implement the `javax.faces.convert.Converter` interface. The supplied JSF standard converter classes are:

- `BigDecimalConverter`

- `BigIntegerConverter`

- `BooleanConverter`

- `ByteConverter`

- `CharacterConverter`

- `DateTimeConverter`

- `DoubleConverter`

- `FloatConverter`

- `IntegerConverter`

- `LongConverter`

- `NumberConverter`

- `ShortConverter`

Table 12-5 shows the converters provided by ADF Faces.

Table 12-5 ADF Faces Converters

Validator | Description
--- | ---
`ColorConverter` | Converts `java.lang.String` objects to`java.awt.Color` objects. You specify a set of color patterns as an attribute of the converter.
`DateTimeConverter` | Converts `java.lang.String` objects to `java.util.Date` objects. You specify the pattern and style of the date as attributes of the converter.
`NumberConverter` | converts `java.lang.String` objects to `java.lang.Number` objects. You specify the pattern and type of the number as attributes of the converter.
`Validator` | Allows you to specify a validator. Use this tag when you create custom validators for which you did not create an associated tag. When you create an input text field using the Data Control Palette, this tag is automatically added and bound to the validator property on the associated binding. This binding allows access to ADF Model layer validation.

As with validators, these ADF Faces converters are also run on the client side unless client-side validation is explicitly disabled in the `adf-faces-config.xml` file.

Note: JSF converters are not run on the client-side

In addition to JavaScript-enabled converters for color, date, and number, ADF Faces also provides JavaScript-enabled converters for input text fields that are bound to any of these Java types:

- `java.lang.Integer`

- `java.lang.Long`

- `java.lang.Short`

- `java.lang.Byte`

- `java.lang.Float`

- `java.lang.Double`

Unlike the other converters, these are automatically used whenever needed. They do not have associated tags that can be nested in the component.

## 12.5.1 How to Use Converters

Whenever you drop an attribute for which there is an ADF Faces converter, JDeveloper automatically adds the converter to the input component. You can also manually insert a converter.

To add ADF Faces converters that have a tag:

1. In the Structure window, right-click the component for which you'd like to add a converter.

2. In the context menu, choose Insert inside <UI component> > ADF Faces Core to insert and ADF Faces converter or JSF Core to insert a JSF converter.

3. Choose a converter tag.

4. In the Property Inspector, set values for the attributes. For additional help, right-click any of the attributes and choose Help.

## 12.5.2 What Happens When You Add Conversion

When you use the Data Control Palette to create input fields that are of a type supported by a converter, JDeveloper automatically provides ADF Faces conversion code on the JSF page by:

- Adding an `af:messages` tag as a child of the `body` tag. By default the `globalOnly` attribute is set to `false`, and the message and text attributes are not set. You need to configure these. For more information, see Section 12.7, "Displaying Error Messages".

- Adding a converter tag as a child of the input component.

  By default, the `pattern` attribute is bound to the `format` property of the associated binding. The `format` property determines the how the `String` is formatted. For example, for the `convertNumber` converter, it might determine whether decimals are used. This binding evaluates to the format property as it is set on the data control itself.

For example, if you drop the `prodId` attribute from the `findAllProducts` method as an `inputText` component, JDeveloper automatically adds the `convertNumber` converter as a child of the input component, as shown in Example 12-9.

Example 12-9 Converter Tag in a JSF Page

    <af:inputText value="#{bindings.productId.inputValue}"
                           label="#{bindings.productId.label}"
                           required="#{bindings.productId.mandatory}"
                                        columns="#{bindings.productId.displayWidth}
      <af:validator binding="#{bindings.productId.validator}"/>
      <f:convertNumber groupingUsed="false"
                         pattern="#{bindings.productId.format}"/>

## 12.5.3 What Happens at Runtime

When the user submits the page containing converters, the ADF Faces `validate()` method calls the converter's `getAsObject()` method to convert the string value to the required object type. When there isn't an attached converter and if the component is bound to a bean property in the model, then JSF automatically uses the converter that has the same data type as the bean property. If conversion fails, the submitted value is marked as invalid and JSF adds an error message to a queue that is maintained by `FacesContext`. If conversion is successful and there are no validators attached to the component, the converted value is stored as a local value that is later used to update the model.