How to Use the Poll Component

5-24 Web User Interface Developers Guide for Oracle Application Development Framework 6 Validating and Converting Input 6-1 6 Validating and Converting Input This chapter describes how to add conversion and validation capabilities to ADF Faces input components in your application. It also describes how to handle and display any errors, including those not caused by validation. This chapter includes the following sections: ■ Section 6.1, Introduction to ADF Faces Converters and Validators ■ Section 6.2, Conversion, Validation, and the JSF Lifecycle ■ Section 6.3, Adding Conversion ■ Section 6.4, Creating Custom JSF Converters ■ Section 6.5, Adding Validation ■ Section 6.6, Creating Custom JSF Validation

6.1 Introduction to ADF Faces Converters and Validators

ADF Faces input components support conversion capabilities. A web application can store data of many types, such as int, long, and 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 mmddyyyy. 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. Conversely, data stored as something other than a String type can be converted to a String for display and updating. Many components, such as af:inputDate, automatically provide a conversion capability. ADF Faces input components also support validation capabilities. If the required attribute of an input component is set to true you can set one or more validator attributes or you can use the ADF Faces validator components. In addition, you can create your own custom validators to suit your business needs. Validators and converters have a default hint message that is displayed to users when they click in the associated field. For converters, the hint usually tells the user the correct format to use for input values, based on the given pattern. For validators, the hint is used to convey what values are valid, based on the validation configured for the component. If conversion or validation fails, associated error messages are displayed to the user. These messages can be displayed in dialogs, or they can be displayed on the page itself next to the component whose conversion or validation failed. For more information about displaying messages in an ADF Faces application, see Chapter 17, Displaying Tips, Messages, and Help. 6-2 Web User Interface Developers Guide for Oracle Application Development Framework

6.2 Conversion, Validation, and the JSF Lifecycle

When a form with data is submitted, the browser sends a request value to the server for each UI component whose editable value attribute is bound. Request values are decoded during the JSF Apply Request Values phase and the decoded value is saved locally on the component in the sumbittedValue attribute. If the value requires conversion for example, if it is displayed as a String type but stored as a DateTime object, the data is converted to the correct type during the Process Validation phase on a per-UI-component basis. If validation or conversion fails, the lifecycle proceeds to the Render Response phase and a corresponding error message is displayed on the page. If conversion and validation are successful, then the Update Model phase starts and the converted and validated values are used to update the model. When a validation or conversion error occurs, the component whose validation or conversion failed places an associated error message in the queue and invalidates itself. The current page is then redisplayed with an error message. ADF Faces components provide a way of declaratively setting these messages. For detailed information about how conversion and validation works in the JSF Lifecycle, see Chapter 4, Using the JSF Lifecycle with ADF Faces.

6.3 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 mmddyyyy. 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. You can set only one converter on a UI component. When you create an af:inputText component and set 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 type entered by the user back into the type expected by the object. The JSF standard converters, which handle conversion between String types 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 ■ EnumConverter ■ FloatConverter ■ IntegerConverter Validating and Converting Input 6-3 ■ LongConverter ■ NumberConverter ■ ShortConverter Table 6–1 shows the converters provided by ADF Faces. As with validators, the ADF Faces converters are also run on the client side. If no converter is explicitly added, ADF Faces will attempt to create a converter based on the data type. Therefore, if the value is bound to any of the following types, you do not need to explicitly add a converter: ■ java.util.Date ■ java.util.Color ■ java.awt.Color ■ java.lang.Number ■ java.lang.Integer ■ java.lang.Long ■ java.lang.Short ■ java.lang.Byte ■ java.lang.Float ■ java.lang.Double Unlike the converters listed in Table 6–1 , the JavaScript-enabled converters are applied by type and used instead of the standard ones, overriding the class and id attributes. They do not have associated tags that can be nested in the component. Some oracle.jbo.domain datatypes are automatically converted. For some oracle.jbo.domain datatypes that are not handled automatically, you can add a oracle.jbo.domain converter to your component as described in Section 6.3.4, How to Add oracle.jbo.domain Converters.

6.3.1 How to Add a Standard ADF Faces Converter

You can also manually insert a converter into a UI component. Table 6–1 ADF Faces Converters Converter Tag Name Description ColorConverter af:convertColor Converts java.lang.String objects to java.awt.Color objects. You specify a set of color patterns as an attribute of the converter. DateTimeConverter af:convertDateTime 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 af:convertNumber Converts java.lang.String objects to java.lang.Number objects. You specify the pattern and type of the number as attributes of the converter.