Skip Headers

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

Previous | Next |

# 10.8 Creating Search Pages

You can create a search form using a method that finds records by taking parameters. The results can then be displayed in a table. In this type of search form, users must enter information for each parameter. Figure 10-11 shows the SRSearch search form used to find all service requests, given an ID, status, and a problem description.

Figure 10-11 The SRSearch Form

## 10.8.1 How to Create a Search Form

You create search form by dropping an existing method that contains the logic to find and return the records based on parameters. This method must already exist on the data control. Figure 10-12 shows the `findServiceRequestSearch(Integer, String, String)` method used to create the search form shown in Figure 10-11. This method finds and returns all service requests given an ID, status, and description.

Figure 10-12 A Search Method That Takes Parameters in the Data Control Palette

To create the search form, you drop the method as a parameter form. You then drop the returned collection as a table to display the results. The SRSearch page hides the results table if it is the first time in a session that the user visits the page. For procedures for conditionally hiding the results table, see Section 10.9, "Conditionally Displaying the Results Table on a Search Page".

To create a search form and results table:

1. From the Data Control Palette, drag a find method that takes parameters.

2. From the context menu, choose Parameters > ADF Parameter Form.

3. From the Data Control Palette, drag the return of that method and drop it as any type of table.

## 10.8.2 What Happens When You Use Parameter Methods

When you drop a method as a parameter form, JDeveloper:

- Defines the following in the page definition file: variables to hold the data values, a method binding for the method, and the attribute bindings for the associated attributes.

- Inserts code in the JSF page for the form using ADF Faces `inputText` components and an ADF Faces `commandButton` component. This code is the same as code for any other input form or command button.

Just as when you drop a collection that is a return of a method, when you drop a method that takes parameters onto a JSF page, JDeveloper creates a method action binding. However, because the method requires parameters to run, JDeveloper also creates `NamedData` elements for each parameter. These represent the parameters of the method. Each is bound to a value binding for the corresponding attribute. These bindings allow the method to access the correct attribute's value for the parameter on execution.

For example, the `findServiceRequestSearch` method action binding contains a `NamedData` element for each of the parameters it takes. The `statusParam` `NamedData` element is bound to the `findServiceRequestSearch_statusParam` attribute binding using an EL expression. Example 10-13 shows the method action binding and some of the attribute bindings created when you drop the `findServiceRequestSearch` method as a parameter form.

Example 10-15 Method Action Binding in the Page Definition File

    <bindings>
      <methodAction id="findServiceRequestSearch"
                        MethodName="findServiceRequestSearch"
                        RequiresUpdateModel="true" Action="999"
                        DataControl="SRPublicFacade"
                        InstanceName="SRPublicFacade.dataProvider"
                        ReturnName="SRPublicFacade.methodResults.SRPublicFacade_
                                 dataProvider_findServiceRequestSearch_result">
        <NamedData NDName="svrIdParam" NDType="java.lang.Integer"
                   NDValue="${bindings.findServiceRequestSearch_svrIdParam}"/>
        <NamedData NDName="statusParam" NDType="java.lang.String"
                   NDValue="${bindings.findServiceRequestSearch_statusParam}"/>
        <NamedData NDName="problemParam" NDType="java.lang.String"
                   NDValue="${bindings.findServiceRequestSearch_problemParam}"/>
      </methodAction>
    ...
      <attributeValues id="svrIdParam" IterBinding="variables">
        <AttrNames>
          <Item Value="findServiceRequestSearch_svrIdParam"/>
        </AttrNames>
      </attributeValues>
      <attributeValues id="problemParam" IterBinding="variables">
        <AttrNames>
          <Item Value="findServiceRequestSearch_problemParam"/>
        </AttrNames>
      </attributeValues>
    ...
    </bindings>

Because you dropped the method and not the return, the attributes reference a variable iterator that accesses and iterates over variables instead of a method iterator that accesses and iterates over a collection. This is because the method (unlike the returned collection) does not need to access an instance of an object; therefore, there is nothing to hold the values entered on the page. Variables act as these data holders.

JDeveloper creates a variable for each method parameter. The variables are declared as children to the variable iterator, and are local, meaning they "live" only as long as the associated binding context. Example 10-16 shows the variable iterator and variables created when using the `findServiceRequestSearch` method. The variable iterator is used both by the form and by the button.

Example 10-16 Variable Iterator and Variables in the Page Definition File

    <executables>
      <variableIterator id="variables">
        <variable Type="java.lang.Integer"
                  Name="findServiceRequestSearch_svrIdParam" IsQueriable="false"/>
        <variable Type="java.lang.String"
                  Name="findServiceRequestSearch_statusParam"
                  IsQueriable="false"/>
        <variable Type="java.lang.String"
                  Name="findServiceRequestSearch_problemParam"
                  IsQueriable="false"/>
      </variableIterator>
    ...
    </executables>

When you then drop the returned collection for the results table, JDeveloper adds a method iterator that iterates over the returned collection. Since the results are in a table, a table binding is also created. Example 10-17 shows the code generated for the method iterator and table binding.

Example 10-17 Page Definition Code for a Returned Collection

    <executables>
      <variableIterator id="variables">
    ...
      </variableIterator>
      <methodIterator id="findServiceRequestSearchIter"
                      Binds="findServiceRequestSearch.result"
                      DataControl="SRPublicFacade" RangeSize="10"
                      BeanClass="oracle.srdemo.model.entities.ServiceRequest"/>
    </executables>
    <bindings>
    ...
      <table id="findAllServiceRequest1" IterBinding="resultsIterator">
        <AttrNames>
          <Item Value="assignedDate"/>
          <Item Value="problemDescription"/>
          <Item Value="requestDate"/>
          <Item Value="status"/>
          <Item Value="svrId"/>
        </AttrNames>
      </table>
    ...
    </bindings>

Note that because the same method is used, when you drop the table, a new method binding is not created. For more information, see Section 7.2.2, "What Happens When You Use the Data Control Palette to Create a Table".

## 10.8.3 What Happens at Runtime

When the user enters data and submits the form, the variables are populated and the attribute binding can then provide the value for the method's parameters using the EL expression for the value of the `NamedDataElement`.

Tip: When the search form and results table are on the same page, the first time a user accesses the page, the table displays all records from the iterator. You can make it so that the results table does not display until the user actually executes the search. For procedures, see Section 10.9, "Conditionally Displaying the Results Table on a Search Page".

When the user enters `Closed` as the status in the corresponding `inputText` component, and clicks the command button, the following happens:

- The `findServiceRequestSearch_status` variable is populated with the value `Closed`.

- Because the attribute binding refers to the variable iterator, the attribute binding can get the value for `status`:

        <attributeValues id="status" IterBinding="variables">
          <AttrNames>
            <Item Value="findServiceRequestSearch_statusParam"/>
          </AttrNames>
        </attributeValues>

- Because the `NamedData` element has an EL expression that evaluates to the item value of the attribute binding, the parameter can also access the value:

      <NamedData NDName="status" NDType="java.lang.String"
          NDValue="${bindings.findServiceRequests_statusParam}"/>

- The `findServiceRequestSearch` method is executed with the parameters taking their values from the `NamedData` elements.

- The `findServiceRequestSearch` method returns a collection of records that match the parameter values.

- The `findServiceRequestSearchIter` iterator iterates over the collection, allowing the table to display the results. For more information about tables at runtime, see Section 7.2.2, "What Happens When You Use the Data Control Palette to Create a Table".