8 Creating Databound Search Forms

This chapter describes how to create search forms to perform complex searches on multiple attributes and search forms to search on a single attribute. It also includes information on using filtered table searches.

This chapter includes the following sections:

Section 8.1, "Introduction to Creating Search Forms"
Section 8.2, "Creating Query Search Forms"
Section 8.3, "Setting Up Search Form Properties"
Section 8.4, "Creating Quick Query Search Forms"
Section 8.5, "Creating Standalone Filtered Search Tables"

8.1 Introduction to Creating Search Forms

You can create search forms that allow users to enter search criteria into input fields for known attributes of an object. The search criteria can be entered via input text fields or selected from a list of values in a popup list picker or dropdown list box. The entered criteria is constructed into a query to be executed. The results of the query can be displayed as a table, a form, or another UI component.

Search forms are region-based components that are reusable and personalizable. They encapsulate and automate many of the actions and iterator management operations required to perform a query. You can create several search forms on the same page without any need to change or create new iterators.

The search forms are based on the model-driven af:query and af:quickQuery components. Because these underlying components are model-driven, the search form will change automatically to reflect changes in the model. The view layer does not need to be changed.

The query search form is a full-featured search form. The quick query search form is a simplified form with only one search criteria. Each of these search forms can be combined with a filtered table to display the results, thereby enabling additional search capabilities. You can also create a standalone filtered table to perform searches without the query or quick query search panel.

A filtered table is a table that has additional Query-by-Example (QBE) search criteria fields above each searchable column. When the filtering option of a table is enabled, you can enter QBE-style search criteria for each column to filter the query results.

For more information about individual query and table components, see the "Using Query Components" and the "Using Tables and Trees" chapters of the Oracle Fusion Middleware Web User Interface Developer's Guide for Oracle Application Development Framework.

8.1.1 Query Search Forms

The query search form is the standard form for complex transactional searches. You can build complex search forms with multiple search criteria fields each with a dropdown list of built-in operators. You can also add custom operators and customize the list. The query search form supports lists of values, AND and OR conjunctions, and saving searches for future use.

A query search form has a basic mode and an advanced mode. The user can toggle between the two modes using the basic/advanced button. At design time, you can declaratively specify form properties (such as setting the default state) to be either basic or advanced. Figure 8-1 shows an advanced mode query search form with three search criteria.

Figure 8-1 Advanced Mode Query Search Form with Three Search Criteria Fields

The advanced mode query form features are:

Selecting search criteria operators from a dropdown list
Adding custom operators and deleting standard operators
Selecting WHERE clause conjunctions of either AND or OR (match all or match any)
Dynamically adding and removing search criteria fields at runtime
Saving searches for future use
Personalizing saved searches

Typically, the query search form in either mode is used with an associated results table or tree table. For example, the query results for the search form in Figure 8-1 may be displayed in a table, as shown in Figure 8-2.

Figure 8-2 Results Table for a Query Search

The basic mode has all the features of the advanced mode except that it does not allow the user to dynamically add search criteria fields. Figure 8-3 shows a basic mode query search form with three search criteria field. Notice the lack of a dropdown list next to the Save button used to add search criteria fields in the advanced mode.

Figure 8-3 Basic Mode Query Form with Three Search Criteria Fields

In either mode, each search criteria field can be modified by selecting operators such as Greater Than and Equal To from a dropdown list, and the entire search panel can be modified by the Match All/Any radio buttons. Partial page rendering is also supported by the search forms in almost all situations. For example, if a Between operator is chosen, another input field will be displayed to allow the user to select the upper range.

A Match All selection implicitly uses AND conjunctions between the search criteria in the WHERE clause of the query. A Match Any selection implicitly uses OR conjunctions in the WHERE clause. Example 8-1 shows how a simplified WHERE clause may appear (the real WHERE in the view criteria is different) when Match All is selected for the search criteria shown in Figure 8-1.

Example 8-1 Simplified WHERE Clause Fragment When "Match All" Is Selected

              WHERE (OrderId=4) AND (Quantity < 50) AND (Price > 100)

Example 8-2 shows a simplified WHERE clause if Match Any is selected for the search criteria shown in Figure 8-3.

Example 8-2 Simplified WHERE Clause Fragment When "Match Any" Is selected

              WHERE (orderId=4) OR (Quantity = 20) OR (Price > 100)

Advanced mode query forms allow users to dynamically add search criteria fields to the query panel to perform more complicated queries. These user-created search criteria fields can be deleted, but the user cannot delete existing fields. Figure 8-4 shows how the Add Fields dropdown list is used to add the CategoryId criteria field to the search form.

Figure 8-4 Dynamically Adding Search Criteria Fields at Runtime

Figure 8-5 shows a user-added search criteria with the delete icon to its right. Users can click the delete icon to remove the criteria.

Figure 8-5 User-Added Search Criteria with Delete Icon

If either Match All or Match Any is selected and then the user dynamically adds the second instance of a search criteria, then both Match All and Match Any will be deselected. The user must reselect either Match All or Match Any before clicking the Search button.

If you intend for a query search form to have both a basic and an advanced mode, you can define each search criteria field to appear only for basic, only for advanced, or for both. When the user switches from one mode to the other, only the search criteria fields defined for that mode will appear. For example, suppose three search fields for basic mode (A, B, C) and three search fields for advanced mode (A, B, D) are defined for a query. When the query search form is in basic mode, search criteria fields A, B, and C will appear. When it is in advanced mode, then fields A, B, and D will appear. Any search data that was entered into the search fields will also be preserved when the form returns to that mode. If the user entered 35 into search field C in basic mode, switched to advanced mode, and then switched back to basic, field C would reappear with value 35.

Along with using the basic or advanced mode, you can also determine how much of the search form will display. The default setting displays the whole form. You can also configure the query component to display in compact mode or simple mode. The compact mode has no header or border, and the Saved Search dropdown lists moves next to the expand/collapse icon. Figure 8-6 shows a query component set to compact mode.

Figure 8-6 Query Component in Compact Mode

The simple mode displays the component without the header and footer, and without the buttons normally displayed in those areas. Figure 8-7 shows the same query component set to simple mode.

Figure 8-7 Query Component in Simple Mode

Users can also create saved searches at runtime to save the state of a search for future use. The entered search criteria values, the basic/advanced mode state, and the layout of the results table/component can be saved by clicking the Save button to open a Save Search dialog, as shown in Figure 8-8. User-created saved searches persist for the session. If they are intended to be available beyond the session, you must configure a persistent data store to store them. For Oracle ADF, you can use an access-controlled data source such as MDS. For more information about using MDS, see the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.

Figure 8-8 Runtime Saved Search Dialog Window

Table 8-1 lists the possible scenarios for creators of saved searches, the method of their creation, and their availability.

Table 8-1 Design Time and Runtime Saved Searches

Creator	Created at Design time as View Criteria	Created at Runtime with the Save Button
Developer	Developer-created saved searches (system searches) are created during application development and typically are a part of the software release. They are created at design time as view criteria. They are usually available to all users of the application and appear in the lower part of the Saved Search dropdown list.
Administrator		Administrator-created saved searches are created during predeployment by site administrators. They are created before the site is made available to the general end users. Administrators can create saved searches (or view criteria) using the JDeveloper design time when they are logged in with the appropriate role. These saved searches (or view criteria) appear in the lower part of the Saved Search dropdown list.
End User		End-user saved searches are created at runtime using the query form Save button. They are available only to the user who created them. End-user saved searches appear in the top part of the Saved Search dropdown list.

End users can manage their saved searches by using the Personalize function in the Saved Search dropdown list to bring up the Personalize Saved Searches dialog, as shown in Figure 8-9.

End users can use the Personalize function to:

Update a user-created saved search
Delete a user-created saved search
Set a saved search as the default
Set a saved search to run automatically
Set the saved search to show or hide from the Saved Search dropdown list

Figure 8-9 Personalize Saved Searches Dialog

8.1.2 Quick Query Search Forms

A quick query search form is intended to be used in situations where a single search will suffice or as a starting point to evolve into a full query search. Both the query and quick query search forms are ADF Faces components. A quick query search form has one search criteria field with a dropdown list of the available searchable attributes from the associated data collection. Typically, the searchable attributes are all the attributes in the associated view collection. The user can search against the selected attribute or search against all the displayed attributes. The search criteria field type will automatically match the type of its corresponding attribute. An Advanced link built into the form offers you the option to create a managed bean to control switching from quick query to advanced mode query search form. For more information, see the "Using Query Components" chapter in the Oracle Fusion Middleware Web User Interface Developer's Guide for Oracle Application Development Framework.

You can configure the form to have a horizontal layout, as shown in Figure 8-10.

Figure 8-10 Quick Query Search Form in Horizontal Layout

You can also choose a vertical layout, as shown in Figure 8-11.

Figure 8-11 Quick Query Search Form in Vertical Layout

8.1.3 Filtered Table and Query-by-Example Searches

A filtered table can be created standalone or as the results table of a query or quick query search form. Filtered table searches are based on Query-by-Example and use the QBE text or date input field formats. The input validators are turned off to allow for entering characters such as > and <= to modify the search criteria. For example, you can enter >1500 as the search criteria for a number column. Wildcard characters may also be supported. If a column does not support QBE, the search criteria input field will not render for that column.

The filtered table search criteria input values are used to build the query WHERE clause with the AND operator. If the filtered table is associated with a query or quick query search panel, the composite search criteria values are also combined to create the WHERE clause.

Figure 8-12 shows a query search form with a filtered results table. When the user enters a QBE search criteria, such as >200 for the id field, the query result is the AND of the query search criteria and the filtered table search criteria.

Figure 8-12 Query Search Form with Filtered Table

Table 8-2 lists the acceptable QBE search operators that can be used to modify the search value.

Table 8-2 Query-by-Example Search Criteria Operators

Operator	Description
`>`	Greater than
`<`	Less than
`>=`	Greater than or equal to
`<=`	Less than or equal to
`AND`	And
`OR`	Or

8.2 Creating Query Search Forms

You create a query search form by dropping a named criteria from the Data Controls panel onto a page. You have a choice of dropping only a search panel, dropping a search panel with a results table, or dropping a search panel with a tree table.

If you choose to drop the search panel with a table, you can select the filtering option in the dialog to turn the table into a filtered table.

Typically, you would drop a query search panel with the results table or tree table. JDeveloper will automatically create and associate a results table or tree table with the query panel.

If you drop a query panel by itself and want a results component or if you already have an existing component for displaying the results, you will need to match the query panel's ResultsComponentId with the results component's Id.

8.2.1 How to Create a Query Search Form with a Results Table or Tree Table

You create a search form by dragging and dropping a named criteria from the Data Controls panel onto the page. You have the option of having a results table or only the query panel.

Before you begin:

You should have created a accessor returned collection in the Data Control panel.

To create a query search form with a results table or tree table:

From the Data Controls panel, select the accessor returned collection and expand the Named Criteria node to display a list of named criteria.
Drag a named criteria item and drop it onto the page or onto the Structure window.

Note:
Dropping All Queriable Attributes onto the page creates a search form with a search criteria field for each searchable attribute defined in the underlying collection. If you only want to create search criteria fields for some of those attributes, create a named criteria with the attributes you want.
From the context menu, choose Create > Query > ADF Query Panel with Table or Create > Query > ADF Query Panel with Tree Table, as shown in Figure 8-13.

Figure 8-13 Data Controls Panel with Query Context Menu
In the Edit Table Columns dialog, you can rearrange any column and select table options. If you choose the filtering option, the table will be a filtered table.

After you have created the form, you may want to set some of its properties or add custom functions. For more information on how to do this, see Section 8.3, "Setting Up Search Form Properties."

8.2.2 How to Create a Query Search Form and Add a Results Component Later

You create a search form by dragging and dropping a named criteria from the Data Controls panel onto the page. You have the option of having a results table or only the query panel.

Before you begin:

You should have created a accessor returned collection in the Data Control panel.

To create a query search form and add a results component in a separate step:

From the Data Controls panel, select the accessor returned collection and expand the Named Criteria node to display a list of named criteria.
Drag a named criteria item and drop it onto the page or onto the Structure window.

Note:
Dropping All Queriable Attributes onto the page creates a search form with a search criteria field for each searchable attribute defined in the underlying collection. If you only want to create search criteria fields for some of those attributes, create a named criteria for the attributes you want.
Choose Create > Query > ADF Query Panel from the context menu, as shown in Figure 8-13.
If you do not already have a results component, then drag the accessor returned collection and drop it onto the page as a table, tree, or treetable component.
In the Property Inspector for the table, copy the value of the Id field.
In the Property Inspector for the query panel, paste the value of the table's ID into the query's ResultsComponentId field.

After you have created the search form, you may want to set some of its properties or add custom functions. See Section 8.3, "Setting Up Search Form Properties," for more information.

8.2.3 How to Persist Saved Searches into MDS

If you want saved searches to be persisted to MDS, you need to define the /persdef namespace in the adf-config.xml file. In addition, you need to perform the regular MDS configuration, such as specifying metadatapath. Example 8-3 shows an adf-config.xml file with the /persdef namespace defined.

Example 8-3 Sample adf-config.xml with /persdef Namespace

<persistence-config>
   <metadata-namespaces>
        <namespace path="/persdef" metadata-store-usage="mdsstore"/>
   </metadata-namespaces>
   <metadata-store-usages>
        <metadata-store-usage id="mdsstore" deploy-target="true"
                 default-cust-store="true"/>
        </metadata-store-usage>
   </metadata-store-usages>
</persistence-config>

In order for the added saved searches to be available the next time the user logs in, cust-config needs to be defined as part of the MDS configuration. For more information about setting cust-config and MDS, see "How to Create Customization Classes" of the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework

If you are also saving the layout of the results component, the application must have the ADF PageFlow Runtime and ADF Controller Runtime libraries installed. Set the project's technology scope to include ADF Page Flow.

8.2.4 What Happens When You Create a Query Form

When you drop a query search form onto a page, JDeveloper creates an af:query tag on the page. If you drop a query with table or tree table, then an af:table tag or af:treeTable tag will follow the af:query tag.

Under the af:query tag are several attributes that define the query properties. They include:

The id attribute, which uniquely identifies the query.
The resultsComponentId attribute, which identifies the component that will display the results of the query. Typically, this will be the table or tree table that was dropped onto the page together with the query. You can change this value to be the id of a different results component. For more information, see Section 8.2.2, "How to Create a Query Search Form and Add a Results Component Later."

In the page definition file, JDeveloper creates an iterator, accessorIterators, and a searchRegion entry in the executables section. Example 8-4 shows the sample code for a page definition file.

In the page definition file executable section:

The iterator RangeSize property is set to a default value of 25. If you want a different page size, you must edit this value.
The iterator id property is set to the root iterator. In the example, the value is set to OrdersSessionEJBLocalIterator
The accessorIterator Binds property is set to the accessor. In the example, the value is set to itemFindAll.
The accessorIterator id property is set to the accessor iterator. In the example, the value is set to itemFindAllIterator.
The searchRegion Criteria property is set to ItemCriteria.
The searchRegion Binds property is set to the search iterator. In the example, the value is set to itemFindAllIterator
The searchRegion id property is set to ItemCriteriaQuery.

If the query was dropped onto the page with a table or tree, then in the page definition file bindings section, a tree element is added with the Iterbinding property set to the search iterator. In this example, the value is set to itemFindAllIterator.

Example 8-4 Search Form Code in the Page Definition File

  <executables>
    <variableIterator id="variables"/>
    <iterator Binds="root" RangeSize="25" DataControl="OrdersSessionEJBLocal"
              id="OrdersSessionEJBLocalIterator"/>
    <accessorIterator MasterBinding="OrdersSessionEJBLocalIterator"
                      Binds="itemFindAll" RangeSize="25"
                      DataControl="OrdersSessionEJBLocal"
                      BeanClass="model.Item"
                      id="itemFindAllIterator"/>
    <searchRegion Criteria="ItemCriteria"
                  Customizer="oracle.jbo.uicli.binding.JUSearchBindingCustomizer"
                  Binds="itemFindAllIterator"
                  id="ItemCriteriaQuery"/>
  </executables>
  <bindings>
    <tree IterBinding="itemFindAllIterator" id="itemFindAll">
      <nodeDefinition DefName="model.Item">
        <AttrNames>
          <Item Value="itemId"/>
          <Item Value="ordId"/>
          <Item Value="price"/>
          <Item Value="quantity"/>
          <Item Value="quantityShipped"/>
        </AttrNames>
      </nodeDefinition>
    </tree>
  </bindings>

8.2.5 What Happens at Runtime: Search Forms

At runtime, the search form displays as a search panel on the page. The search panel will display in either basic mode or advanced mode.

After the user enters the search criteria and clicks Search, a query is executed and the results are displayed in the associated table, tree table, or component.

8.3 Setting Up Search Form Properties

Search form properties that can be set after the query component has been added to the JSF page include:

id of the results table or results component
Show or hide of the basic/advanced button
Position of the mode button
Default, simple, or compact mode for display

8.3.1 How to Set Search Form Properties on the Query Component

After you have dropped the query search form onto a page, you can edit other form properties in the Property Inspector, as shown in Figure 8-14. Some of the common properties you may set are:

Enabling or disabling the basic/advanced mode button
Setting the ID of the query search form
Setting the ID of the results component (for example, a results table)
Selecting the default, simple, or compact mode for display

Figure 8-14 Property Inspector for a Query Component

Query component in the Property Inspector

One common option is to show or hide the basic/advanced button.

To enable or hide the basic/advanced button in the query form:

In the Structure window, double-click af:query.
In the Property Inspector, click the Appearance tab.
To enable the basic/advanced mode button, select true from the ModeChangeVisible field. To hide the basic/advance mode button, select false from the ModeChangeVisible field.

8.4 Creating Quick Query Search Forms

You can use quick query search forms to let users search on a single attribute of a collection. Quick query search form layout can be either horizontal or vertical. Because they occupy only a small area, quick query search forms can be placed in different areas of a page. You can create a managed bean to enable users to switch from a quick query to a full query search. For more information about switching from quick query to query using a managed bean, see the "Using Query Components" chapter in the Oracle Fusion Middleware Web User Interface Developer's Guide for Oracle Application Development Framework.

If you drop a quick query panel with a results table or tree, JDeveloper will automatically create the results table, as described in Section 8.4.1, "How to Create a Quick Query Search Form with a Results Table or Tree Table." If you drop a quick query panel by itself and subsequently want a results table or component or if you already have one, you will need to match the quick query Id with the results component's partialTrigger value, as described in Section 8.4.2, "How to Create a Quick Query Search Form and Add a Results Component Later."

8.4.1 How to Create a Quick Query Search Form with a Results Table or Tree Table

You can create quick query searches using the full set of searchable attributes and simultaneously add a table or tree table as the results component.

Before you begin:

Create an accessor returned collection in the Data Control panel.

To create a quick query search form with a results table:

From the Data Controls panel, select the accessor returned collection and expand the Named Criteria node to display a list of named criteria.
Drag a named criteria item and drop it onto the page or onto the Structure window.
From the context menu, choose Create > Quick Query > ADF Quick Query Panel with Table or Create > Quick Query > ADF Quick Query Panel with Tree Table, as shown in Figure 8-15.
In the Edit Table Columns dialog, you can rearrange any column and select table options. If you choose the filtering option, the table will be a filtered table.

Figure 8-15 Data Control Panel with Quick Query Context Menu

8.4.2 How to Create a Quick Query Search Form and Add a Results Component Later

You can create quick query searches using the full set of searchable attributes and add a table or tree table as the results component later.

Before you begin:

Create an accessor returned collection in the Data Control panel.

To create a quick query search form and add a results component in a separate step:

From the Data Controls panel, select the accessor returned collection and expand the Named Criteria node to display a list of named criteria.
Drag a named criteria item and drop it onto the page or onto the Structure window.
From the context menu, choose Create > Quick Query > ADF Quick Query Panel.
If you do not already have a results component, then drag the accessor returned collection and drop it onto the page as a table, tree, or treetable component.
In the Property Inspector for the quick query, copy the value of the Id field.
In the Property Inspector for the results component (for example, a table), paste or enter the value into the PartialTriggers field.

8.4.3 How to Set the Quick Query Layout Format

The default layout of the form is horizontal. You can change the layout option using the Property Inspector.

To set the layout:

In the Structure window, double-click af:quickQuery.
In the Property Inspector, on the Commons page, select the Layout property using the dropdown list to specify default, horizontal, or vertical.

8.4.4 What Happens When You Create a Quick Query Search Form

When you drop a quick query search form onto a page, JDeveloper creates an af:quickQuery tag. If you have dropped a quick query with table or tree table, then an af:table tag or af:treeTable tag is also added.

Under the af:quickQuery tag are several attributes and facets that define the quick query properties. Some of the tags are:

The id attribute, which uniquely identifies the quick query. This value should be set to match the results table or component's partialTriggers value. JDeveloper will automatically assign these values when you drop a quick query with table or tree table. If you want to change to a different results component, see Section 8.4.2, "How to Create a Quick Query Search Form and Add a Results Component Later."
The layout attribute, which specifies the quick query layout to be default, horizontal, or vertical.
The end facet, which specifies the component to be used to display the Advanced link (that changes the mode from quick query to the query). For more information about creating this function, see the "Using Query Components" chapter of the Oracle Fusion Middleware Web User Interface Developer's Guide for Oracle Application Development Framework.

8.4.5 What Happens at Runtime: Quick Query

At runtime, the quick query search form displays a single search criteria field with a dropdown list of selectable search criteria items. If there is only one searchable criteria item, then the dropdown list box will not be rendered. An input component that is compatible with the selected search criteria type will be displayed, as shown in Table 8-3. For example, if the search criteria type is date, then inputDate will be rendered.

Table 8-3 Quick Query Search Criteria Field Components

Attribute Type	Rendered Component
`DATE`	`af:inputDate`
`VARCHAR`	`af:inputText`
`NUMBER`	`af:inputNumberSpinBox`

In addition, a Search button is rendered to the right of the input field. If the end facet is specified, then any components in the end facet are displayed. By default, the end facet contains an Advanced link.

8.5 Creating Standalone Filtered Search Tables

You use query search forms for complex searches, but you can also perform simple QBE searches using the filtered table. You can create a standalone ADF-filtered table without the associated search panel and perform searches using the QBE-style search criteria input fields. For more information about filtered tables, see Section 8.1.3, "Filtered Table and Query-by-Example Searches."

When creating a table, you can make almost any table a filtered table by selecting the filtering option if the option is enabled. There are three ways to create a standalone filtered table:

You can drop a table onto a page from the Component Palette, bind it to a data collection, and set the filtering option. For more information, see the "Using Query Components" chapter of the Oracle Fusion Middleware Web User Interface Developer's Guide for Oracle Application Development Framework.
You can create a filtered table by dragging and dropping an accessor returned collection onto a page and setting the filtering option.
You can also create a filtered table or a read-only filtered table by dropping All Queriable Attributes or a named criteria onto the page. The resulting filtered table will have a column for each searchable attribute and an input search field above each column.

You can set the QBE search criteria for each filterable column to be a case-sensitive or case-insensitive search using the filterFeature attribute of af:column in the af:table component. For more information, see the "Enable Filtering in Tables" section of the Oracle Fusion Middleware Web User Interface Developer's Guide for Oracle Application Development Framework.

Before you begin:

Create an accessor returned collection in the Data Control panel.

To create a filtered table:

From the Data Controls panel, select the accessor returned collection and expand the Named Criteria node to display a list of all named criteria.
Drag a named criteria item and drop it onto the page or onto the Structure window.
From the context menu, choose Create > Tables > ADF Filtered Table or Create > Tables >ADF Read-Only Filtered Table.
In the Edit Table Columns dialog, you can rearrange any column and select table options. Because the table is created by JDeveloper during quick query creation, the filtering option is automatically enabled and not user-selectable, as shown in Figure 8-16.

Figure 8-16 Edit Table Columns Dialog for Filtered Table