6.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 return from the findServiceRequestById method, which contains all the attributes necessary to edit a given service request.

This section provides information on creating a form that returns data to be viewed or edited. You can also use a constructor or the method itself to create a form used to populate data instead of return data. For more information about creating that type of form, see Section 10.7, "Creating an Input Form for a New Record".

6.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.

These procedures are for creating a form that displays all objects from a collection returned by a method that takes no parameters. If you want to use a collection returned from a method that takes parameters, you need to have those parameters set in order for the form to display the proper records. For procedures and information about setting parameters, see Section 10.6.1, "How to Create a Form or Table Using a Method That Takes Parameters".

To create a form that allows a user to create a new record, you need to use a method that creates the new instance, given some values for that instance. If your data control was configured to support updates, then it will include constructors, which are objects you can use to create a form that creates a new object, populating values for all attributes on the object. For more information, see Section 10.7, "Creating an Input Form for a New Record".

Whether you use a collection, a constructor, or a method to create a form, you may also want to add a command button that invokes a method to, for example, insert the data into the data source or update the data. For procedures and more information, see Section 10.3, "Creating Command Components to Execute Methods".

To create a basic form:

1. From the Data Control Palette, select a collection that is a return of a findAll method.

   To display the value of existing attributes, drop the returned collection from a method used to find records. Figure 6-3 shows the ServiceRequest collection for the findAllServiceRequest() method from the SRDemo application. This method creates a form with data already populated in the input text fields.

   Figure 6-3 Attributes Associated with a Returned Collection in the Data Control Palette

   
   

2. 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, 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 12.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 6.4, "Incorporating Range Navigation into Forms". You can also elect to include a Submit button used to submit the form. Note that this button will not perform any updates to the data, it simply submits the HTML form. 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 Creation Form: Not to be used when using TopLink Java objects and an EJB session bean. Use constructors or custom methods instead. For more information, see Section 10.7, "Creating an Input Form for a New Record".

3. If you are building a form that allows users to update data, you now need to drag and drop a method that will perform the update. For more information, see Section 10.3, "Creating Command Components to Execute Methods".

6.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 6-6 shows the code generated on the JSF page when you drop the ServiceRequest collection for the findAllServiceRequest() method as a default ADF Form.

Example 6-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}"/>
        <f:convertNumber groupingUsed="false"
                         pattern="#{bindings.svrId.format}"/>
      </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:inputText value="#{bindings.problemDescription.inputValue}"
                    label="#{bindings.problemDescription.label}"
                    required="#{bindings.problemDescription.mandatory}"
                    columns="#{bindings.problemDescription.displayWidth}">
        <af:validator binding="#{bindings.problemDescription.validator}"/>
      </af:inputText>
      <af:selectInputDate value="#{bindings.assignedDate.inputValue}"
                          label="#{bindings.assignedDate.label}"
                          required="#{bindings.assignedDate.mandatory}">
        <af:validator binding="#{bindings.assignedDate.validator}"/>
        <f:convertDateTime pattern="#{bindings.assignedDate.format}"/>
      </af:selectInputDate>
      <f:facet name="footer">
        <af:commandButton text="Submit"/>
      </f:facet>
</af:panelForm>

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

6.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 6-4 shows the command button in the panelForm's footer facet.

Figure 6-4 Footer Facet for the Panel Form

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

Example 6-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 6.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 6-5 shows both full and empty facets for a panelPage component

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