Introduction to Input Components and Forms

9-4 Web User Interface Developers Guide for Oracle Application Development Framework All input components have JavaScript client APIs that you can use to set or get property values. For more information, see the ADF Faces JavaScript API documentation.

9.2 Defining Forms

A form is a component that serves as a container for other components. When a submit action occurs within the form, any modified input values are submitted. For example, you can create an input form that consists of input and selection components, and a submit command button, all enclosed within a form. When the user enters values into the various input fields and clicks the Submit button, those new input values will be sent for processing. By default, when you create a JSF page in JDeveloper, it automatically inserts a form component into the page. When you add components to the page, they will be inserted inside the form component. Example 9–1 shows two input components and a Submit button that when clicked will submit both input values for processing. Example 9–1 ADF Faces Form as a Container for Input Components af:form af:panelFormLayout af:inputText value={myBean.firstName} label={First Name} af:inputText af:inputText value={myBean.lastName} label={Last Name} af:inputText f:facet name=footer af:commandButton text=Submit f:facet af:panelFormLayout af:form Because there can be only one form component on a page, you can use subforms within a form to create separate regions whose input values can be submitted. Within a region, the values in the subform will be validated and processed only if a component inside the subform caused the values to be submitted. You can also nest a subform within another subform to create nested regions whose values can be submitted. For more information about subforms, see Section 4.5, Using Subforms to Create Regions on a Page. Example 9–2 shows a form with two subforms, each containing its own input components and Submit button. When a Submit button is clicked, only the input values within that subform will be submitted for processing. Example 9–2 ADF Faces Subform Within a Form af:form af:subform af:panelFormLayout Tip: If you do not already have an af:form tag on the page, and you drag and drop an ADF Faces component onto the page, JDeveloper will prompt you to enclose the component within a form component. Using Input Components and Defining Forms 9-5 af:inputText value={myBean.firstName} af:inputText af:inputText value={myBean.lastName} af:inputText f:facet name=footer af:commandButton text=Submit f:facet af:panelFormLayout af:subform af:subform af:panelFormLayout af:inputText value={myBean.primaryPhone} af:inputText af:inputText value={myBean.cellPhone} af:inputText f:facet name=footer af:commandButton text=Submit f:facet af:panelFormLayout af:subform af:form Aside from the basic Submit button, you can add any other command component within a form and have it operate on any field within the form. ADF Faces provides a specialized command component: the resetButton component, which when clicked, resets all the input and selection components within a form. That is, it updates all components whose values can be edited with the current values of the model. The resetButton component is different from HTML reset in that the resetButton component will reset the input components to their previous state which was partially or fully submitted successfully to the server without any validation or conversion error. For example, if a user enters value A and clicks the Submit button, and then changes the value from A to B and clicks the resetButton component, the value A will be restored.

9.2.1 How to Add a Form to a Page

In most cases, JDeveloper will add the form component for you. However, there may be cases where you must manually add a form, or configure the form with certain attribute values. To add a form to a page: 1. In the Component Palette, from the Common Components panel, drag and drop a Form onto the page. 2. In the Property Inspector expand the Common section, where you can optionally set the following: ■ DefaultCommand : Specify the ID attribute of the command component whose action should be invoked when the Enter key is pressed and the focus is inside the form. ■ UsesUpload : Specify whether or not the form supports uploading files. For more information about uploading files, see Section 9.9, Using File Upload. ■ TargetFrame : Specify where the new page should be displayed. Acceptable values are any of the valid values for the target attribute in HTML. The default is _self. 9-6 Web User Interface Developers Guide for Oracle Application Development Framework

9.2.2 How to Add a Subform to a Page

You should add subform components within a form component when you need a section of the page to be capable of independently submitting values. To add subforms to a page: 1. In the Component Palette, from the Common Components panel, drag and drop a Subform onto the page as a child to a form component. 2. Use the Property Inspector to set the following: ■ Default : Specify whether or not the subform should assume it has submitted its values. When set to the default value of false, this subform component will consider itself to be submitted only if no other subform component has been submitted. When set to true, this subform component assumes it has submitted its values. ■ Default Command : Specify the ID attribute of the command component whose action should be invoked when the Enter key is pressed and the focus is inside the subform.

9.2.3 How to Add a Reset Button to a Form

You can add the resetButton component inside a form or a subform. The reset button will act upon only those components within that form or subform. To add a reset button to a page: 1. In the Component Palette, from the Common Components panel, drag and drop a Reset Button onto the page. 2. Use the Property Inspector to set the following: ■ Text : Specify the textual label of the button. ■ Disabled : Specify whether or not the button should be disabled. For example, you could enter an EL expression that determines certain conditions under which the button should be disabled.

9.3 Using the inputText Component

Although input components include many variations, such as pickers, sliders, and a spinbox, the inputText component is the basic input component for entering values. You can define an inputText component as a single-row input field or as a text area by setting the rows attribute to more than 1. However, if you want to create a multiple row text input, consider using the richTextEditor component as described in Section 9.8, Using the richTextEditor Component. You can hide the input values from being displayed, such as for passwords, by setting the secret attribute to true. Like other ADF Faces components, the inputText component supports label, text, and messages. When you want this component to be displayed without a label, you set the simple attribute to true. Figure 9–4 shows a single-row inputText component. Tip: A subform is considered submitted if an event is queued by one of its children or facets for a phase later than Apply Request Values that is, for later than decode. For more information about lifecycle phases, see Chapter 4, Using the JSF Lifecycle with ADF Faces. Using Input Components and Defining Forms 9-7