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

SRSearch searches for ID, status, and problem

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

Custom search method uses parameters to return data

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:

From the Data Control Palette, drag a find method that takes parameters.
From the context menu, choose Parameters > ADF Parameter Form.
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".