18.4 Creating Search Page Using Named Bind Variables

You can create a search form using a query from a view object that uses named bind variables to find matching objects. For example, the StaffListByEmailNameRole view object uses the following named bind variables:

TheFirstName
TheLastName
EmailAddress
Role

Figure 18-5 shows the SRStaffSearch search form, created using the StaffListByEmailNameRole view object. This page is used to find a staff user, given a first name, last name, email address, and role.

Figure 18-5 The SRStaffSearch Form

SRStafSearch searches for name, email, and role

18.4.1 How to Create a Parameterized Search Form

Because a parameterized search uses variables that represent parameters, instead of using the Execute operation to invoke the query, you use the ExecuteWithParams operation. You create the search form by dropping ExecuteWithParams operation as a parameterized form. You then drop the corresponding collection as a table a table to display the results. Figure 18-5 shows the ExecuteWithParams operation for the StaffListByEmailNameRole collection.

Figure 18-6 The ExecuteWithParams Operation Uses Parameters

ExecuteWithParams operation has parameters for each variable

To create a search form and results table:

From the Data Control Palette, drag the ExecuteWithParams operation.
From the context menu, choose Parameters > ADF Parameter Form.
Use the Edit Form Fields dialog to change the display of the fields.
From the Data Control Palette, drag the corresponding collection, and drop it as any type of table or form.

18.4.2 What Happens When You Use Parameter Methods

When you drop the ExecuteWithParams operation as a parameter form, JDeveloper:

Defines the following in the page definition file: variables to hold the data values, an action binding for the operation, and the attribute bindings for the associated attributes.
Inserts code in the JSF page for the form using ADF Faces inputText components bound to the attribute bindings, and an ADF Faces commandButton component bound to the ExecuteWithParams operation. This code is the same as code for any other input form or command button.

Just as when you drop an operation such as Execute or Next, when you drop the ExecuteWithParams operation, JDeveloper creates an action binding. However, because the operation requires parameters to run, JDeveloper also creates NamedData elements for each parameter. These represent the named bind variables on the associated view object. Each NamedData element is bound to a value binding for the corresponding attribute. These bindings allow the operation to access the correct attribute's value for the parameter on execution.

For example, the action binding for the ExecuteWithParams operation on the StaffListByEmailNameRole collection contains a NamedData element for each of the named bind variables on the StaffListByEmailNameRole view object. The EmailAddress NamedData element is bound to the StaffListByEmailNameRole_EmailAddres attribute binding using an EL expression. Example 18-4 shows the action binding and some of the attribute bindings created when you drop the ExecuteWithParameters operation on the StaffListByEmailNameRole collection as a parameter form.

Example 18-4 Method Action Binding in the Page Definition File

<bindings>
  <action id="ExecuteWithParams"
          IterBinding="StaffListByEmailNameRoleIterator"
          InstanceName="SRService.StaffListByEmailNameRole"
          DataControl="SRService" RequiresUpdateModel="true" Action="95">
    <NamedData NDName="EmailAddress" NDType="java.lang.String"
               NDValue="${bindings.StaffListByEmailNameRole_EmailAddress}"/>
    <NamedData NDName="Role" NDType="java.lang.String"
               NDValue="${bindings.StaffListByEmailNameRole_Role}"/>
    <NamedData NDName="TheFirstName" NDType="java.lang.String"
               NDValue="${bindings.StaffListByEmailNameRole_TheFirstName}"/>
    <NamedData NDName="TheLastName" NDType="java.lang.String"
               NDValue="${bindings.StaffListByEmailNameRole_TheLastName}"/>
  </action>
  <attributeValues id="EmailAddress" IterBinding="variables">
    <AttrNames>
      <Item Value="StaffListByEmailNameRole_EmailAddress"/>
    </AttrNames>
  </attributeValues>
...
</bindings>

Because you dropped the ExecuteWithParams operation, the attributes reference a variable iterator that accesses the variables instead of a collection's iterator. This is because the operation (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 named bind variable. The variables are declared as children to the variable iterator, and are local, meaning they live only during a single request, and while they are carried across subsequent post-backs to the same form, they would be forgotten (and re-initialized) when a user navigates to some other page. Example 18-3 shows the variable iterator and variables created when dropping the ExecuteWithParameters operation on the StaffListByEmailNameRole collection. The variable iterator is used both by the form and by the button.

Example 18-5 Variable Iterator and Variables in the Page Definition File

<executables>
  <iterator id="StaffListByEmailNameRoleIterator" RangeSize="10"
            Binds="StaffListByEmailNameRole" DataControl="SRService"/>
  <variableIterator id="variables">
    <variableUsage DataControl="SRService"
                   Binds="StaffListByEmailNameRole.variablesMap.EmailAddress"
                   Name="StaffListByEmailNameRole_EmailAddress"
                   IsQueriable="false"/>
    <variableUsage DataControl="SRService"
                   Binds="StaffListByEmailNameRole.variablesMap.Role"
                   Name="StaffListByEmailNameRole_Role" IsQueriable="false"/>
    <variableUsage DataControl="SRService"
                   Binds="StaffListByEmailNameRole.variablesMap.TheFirstName"
                   Name="StaffListByEmailNameRole_TheFirstName"
                   IsQueriable="false"/>
    <variableUsage DataControl="SRService"
                   Binds="StaffListByEmailNameRole.variablesMap.TheLastName"
                   Name="StaffListByEmailNameRole_TheLastName"
                   IsQueriable="false"/>
  </variableIterator>
</executables>

18.4.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 named bind variables 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 18.5, "Conditionally Displaying the Results Table on a Search Page".

When the user enters Smith as the last name in the corresponding inputText component, and clicks the command button, the following happens:

The StaffListByEmailNameRole_TheLastName variable is populated with the value Smith. If no values were entered for the other fields, then the corresponding variables use the default value set for the named bind variables on the view object. For more information, see Section 5.9, "Using Named Bind Variables".

Because the attribute binding refers to the variable iterator, the attribute binding can get the value for TheLastName, and any other variable values:

  <attributeValues id="TheLastName" IterBinding="variables">
    <AttrNames>
      <Item Value="StaffListByEmailNameRole_TheLastName"/>
    </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="TheLastName" NDType="java.lang.String"
    NDValue="${bindings.StaffListByEmailNameRole_TheLastName}"/>
```
The ExecuteWithParams operation is executed with the parameters taking their values from the NamedData elements.
The operation applies the named bind variable values and executes the query.
The StaffListByEmailNameRoleIterator iterator iterates over the collection, allowing a table to display the results. For more information about tables at runtime, see Section 14.2.2, "What Happens When You Use the Data Control Palette to Create a Table".