13.3 Creating a Basic Form

Instead of dropping individual attributes to create a form, JDeveloper allows you to drop a complete form that displays or collects data for all the attributes on an object. For example, the SREdit page was created by dropping the ServiceRequests collection, which contains all the attributes necessary to edit a given service request.

You can also create forms that provide more functionality than displaying data from a collection. For information about creating a form that allows a user to update data, see Section 13.5, "Creating a Form to Edit an Existing Record". For information about creating forms that allow users to create a new object for the collection, see Section 13.6, "Creating an Input Form". You can also create search forms. For more information, see Chapter 18, "Creating a Search Form".

13.3.1 How to Use the Data Control Palette to Create a Form

To create a form using a data control, you bind the UI components to the attributes on the corresponding object in the data control. JDeveloper allows you to do this declaratively by dragging and dropping a collection or a structured attribute from the Data Control Palette.

To create a basic form:

From the Data Control Palette, select the collection that represents the data you wish to display. Figure 13-3 shows the ServiceRequests collection for the SRService data control.

Figure 13-3 Collections Can Be Used to Create Forms that Display Data
Drag the collection onto the page, and from the context menu choose the type of form to display or collect data for the object. For a form, you are given the following choices:
- ADF Form: Launches the Edit Form Fields dialog that allows you to select individual attributes instead of creating a field for every attribute by default. It also allows you to select the label and UI component used for each attribute. By default, ADF inputText components are used, except for dates, which use the selectInputDate component. Each inputText component contains a validator tag that allows you to set up validation for the attribute. For more information, see Section 20.3, "Adding Validation".
  
  You can elect to include navigational controls that allow users to navigate through all the data objects in the collection. For more information, see Section 13.4, "Incorporating Range Navigation into Forms". You can also elect to include a Submit button used to submit the form. This button submits the HTML form and applies the data in the form to the bindings as part of the JSF/ADF page lifecycle. For additional help in using the dialog, click Help. All UI components are placed inside a panelForm component.
- ADF Read-Only Form: Same as the ADF Form, but by default, outputText components are used. Since the form is meant to display data, no validator tags are added. The label attribute is populated for each component. Attributes of type Date also use the outputText component. All components are placed inside panelLabelAndMessage components, which are in turn placed inside a panelForm component.
- ADF Search Form: Creates a form that can be used to execute a Query-By-Example (QBE) search. For more information, see Chapter 18, "Creating a Search Form".
- ADF Creation Form: Creates an input form that allows users to create a new instance for the collection. For more information, see Section 13.6, "Creating an Input Form".
If you are building a form that allows users to update data, you now need to drag and drop an operation that will perform the update. For more information, see Section 13.5, "Creating a Form to Edit an Existing Record".

13.3.2 What Happens When You Use the Data Control Palette to Create a Form

Dropping an object as a form from the Data Control Palette has the same effect as dropping a single attribute, except that multiple attribute bindings and associated UI components are created. The attributes on the UI components (such as value) are bound to properties on that attribute's binding object (such as inputValue). Example 13-6 shows the code generated on the JSF page when you drop the ServiceRequests collection as a default ADF Form.

Example 13-6 Code on a JSF Page for an Input Form

<af:panelForm>
  <af:inputText value="#{bindings.SvrId.inputValue}"
                label="#{bindings.SvrId.label}"
                required="#{bindings.SvrId.mandatory}"
                columns="#{bindings.SvrId.displayWidth}">
    <af:validator binding="#{bindings.SvrId.validator}"/>
  </af:inputText>
  <af:inputText value="#{bindings.Status.inputValue}"
                label="#{bindings.Status.label}"
                required="#{bindings.Status.mandatory}"
                columns="#{bindings.Status.displayWidth}">
    <af:validator binding="#{bindings.Status.validator}"/>
  </af:inputText>
  <af:selectInputDate value="#{bindings.RequestDate.inputValue}"
                      label="#{bindings.RequestDate.label}"
                      required="#{bindings.RequestDate.mandatory}">
   <af:validator binding="#{bindings.RequestDate.validator}"/>
   <f:convertDateTime pattern="#{bindings.RequestDate.format}"/>
 </af:selectInputDate>
...
</af:panelForm>

Note:

For information regarding the validator and converter tag, see Chapter 20, "Using Validation and Conversion".

13.3.2.1 Using Facets

JSF components use facet tags to hold other components that require a special relationship with the parent component, for example, headers and footers for columns within a table, or the footer facet for the panelForm component. When you use the Data Control Palette to drop a widget, any preferred facets are included.

Many components use facets, and when you use widgets to create complex components (such as panelForm), output tags are often automatically created and inserted into the facets. You can manually edit these components or add other components to facets.

When you choose to include a Submit button when you drop a collection as an input form, a command button is added to the panelForm's footer facet. This command button causes the form that holds the panelForm to be submitted. By default, the text is Submit. Figure 13-4 shows the command button in the panelForm's footer facet.

Figure 13-4 Footer Facet for the Panel Form

Footer facet in the structure window and the form

Example 13-7 shows the corresponding code in the JSF page.

Example 13-7 Facet in a JSF Page

<af:panelForm>
... 
  <f:facet name="footer">
    <af:commandButton text="Submit"/>
  </f:facet>
</af:panelForm>

Each facet can hold only one component. If you need a facet to hold more than one component, then you need to nest those components in a container component, which can then be nested in the facet. For an example of how the panelGroup and panelButtonBar components are used to group all buttons in the footer facet of a form, see Section 13.4.2.3, "Using EL Expressions to Bind to Navigation Operations".

Also note that JDeveloper displays all facets available to the component in the Structure window. However, only those that contain UI components appear activated. Any empty facets are "grayed" out. Figure 13-5 shows both full and empty facets for a panelPage component

Figure 13-5 Empty and Full Facet Folders in the Structure Window

All the facets for the PanelPage in the Structure window.