Oracle® Fusion Middleware Java EE Developer's Guide for Oracle Application Development Framework 11g Release 1 (11.1.1.7.2) Part Number E16272-07 |
|
|
PDF · Mobi · ePub |
This chapter describes how to create search forms to perform complex searches on multiple attributes and search forms to search on a single attribute. For complex query search forms, it describes how to set up the query search form mode, results table, saved searches list, and personalization. For single attribute search forms, it describes how to configure the form layout. In addition, it includes information on using Query-by-Example (QBE) filtered table searches.
This chapter includes the following sections:
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.
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 7-1 shows an advanced mode query search form with three search criteria.
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 7-1 may be displayed in a table, as shown in Figure 7-2.
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 7-3 shows a basic mode query search form with one 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.
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 7-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 7-1.
Example 7-1 Simplified WHERE Clause Fragment When "Match All" Is Selected
WHERE (ProductId=4) AND (InStock > 2) AND (ProductName="Ipod")
Example 7-2 shows a simplified WHERE
clause if Match Any is selected for the search criteria shown in Figure 7-3.
Example 7-2 Simplified WHERE Clause Fragment When "Match Any" Is selected
WHERE (ProductId=4) OR (InStock > 2) OR (ProductName="Ipod")
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 7-4 shows how the Add Fields dropdown list is used to add the CategoryId criteria field to the search form.
Figure 7-5 shows a user-added search criteria with the delete icon to its right. Users can click the delete icon to remove the criteria.
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 7-6 shows a query component set to compact mode.
The simple mode displays the component without the header and footer, and without the buttons normally displayed in those areas. Figure 7-7 shows the same query component set to 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 7-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 "Customizing Applications with MDS" chapter in the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.
When you perform a saved search, you can specify whether the layout of the results component is also saved. Creating saved searches and saving the results components layout require that MDS is configured. If you set the query component's saveResultsLayout
attribute to always
, the results component layout will be saved. If saveResultsLayout
is set to never
, the layout is not saved.
Example 7-3 web.xml Entry for Saving Query Results Component Layout
<context-param> <description>Saving results layout</description> <param-name>oracle.adf.view.rich.query.SAVE_RESULTS_LAYOUT</param-name> <param-value>true</param-value> </context-param>
If saveResultsLayout
is not defined, saving layout defaults to the application-level property oracle.adf.view.rich.query.SAVE_RESULTS_LAYOUT
in the web.xml
file. The default value of oracle.adf.view.rich.query.SAVE_RESULTS_LAYOUT
is true
.
If the user made changes to the layout of a saved search and proceeds without saving, a warning message appears to remind the user to save, otherwise the changes will be lost. In addition, if the user adds or deletes search fields and proceeds without saving, a warning message also appears.
Table 7-1 shows the saveResultsLayout
and SAVE_RESULTS_LAYOUT
values and their resultant action. Note that MDS must be configured to save layout.
Table 7-1 Save Results Component Layout Attributes
web.xml SAVE_RESULT_LAYOUT | Query Component saveResultsLayout | Resultant action |
---|---|---|
true |
always |
Saves layout |
true |
never |
Not saved |
true |
not defined |
Saves layout |
false |
always |
Not saved |
false |
never |
Not saved |
false |
not defined |
Not saved |
Table 7-2 lists the possible scenarios for creators of saved searches, the method of their creation, and their availability.
Table 7-2 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 7-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
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 7-10.
You can also choose a vertical layout, as shown in Figure 7-11.
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 7-12 shows a query search form with a filtered results table. When the user enters a QBE search criteria, such as >100
for the PersonId
field, the query result is the AND
of the query search criteria and the filtered table search criteria.
Table 7-3 lists the acceptable QBE search operators that can be used to modify the search value.
You create a query search form by dropping the All Queriable Attributes item 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
.
You create a search form by dragging and dropping All Queriable Attributes 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 All Queriable Attributes.
Drag the All Queriable Attributes 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, you can create another accessor returned collection in the Data Control panel that returns only the attributes you want. You can then drag and drop All Queriable Attributes from this new accessor returned collection.
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 7-13.
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 7.3, "Setting Up Search Form Properties."
You create a search form by dragging and dropping All Queriable Attributes 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 All Queriable Attributes.
Drag the All Queriable Attributes 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, you can create another accessor returned collection in the Data Control panel that returns only the attributes you want. You can then drag and drop All Queriable Attributes from this new accessor returned collection.
Choose Create > Query > ADF Query Panel from the context menu, as shown in Figure 7-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 7.3, "Setting Up Search Form Properties," for more information.
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 7-4 shows an adf-config.xml
file with the /persdef
namespace defined.
Example 7-4 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.
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 7.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 7-5 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 SupplierFacadeLocalIterator
The accessorIterator Binds
property is set to the accessor. In the example, the value is set to productFindAll.
The accessorIterator id
property is set to the accessor iterator. In the example, the value is set to productFindAllIterator.
The searchRegion
Criteria
property is set to _ImplicitViewCriteria_
.
The searchRegion
Binds
property is set to the search iterator. In the example, the value is set to productFindAllIterator
The searchRegion
id
property is set to ImplicitViewCriteriaQuery.
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 productFindAllIterator
.
Example 7-5 Search Form Code in the Page Definition File
<executables> <variableIterator id="variables"/> <iterator Binds="root" RangeSize="25" DataControl="SupplierFacadeLocal" id="SupplierFacadeLocalIterator"/> <accessorIterator MasterBinding="SupplierFacadeLocalIterator" Binds="productFindAll" RangeSize="25" DataControl="SupplierFacadeLocal" BeanClass="oracle.fodemo.supplier.model.Product" id="productFindAllIterator"/> <searchRegion Criteria="__ImplicitViewCriteria__" Customizer="oracle.jbo.uicli.binding.JUSearchBindingCustomizer" Binds="productFindAllIterator" id="ImplicitViewCriteriaQuery"/> </executables> <bindings> <tree IterBinding="productFindAllIterator" id="productFindAll"> <nodeDefinition DefName="oracle.fodemo.supplier.model.Product"> <AttrNames> <Item Value="listPrice"/> <Item Value="minPrice"/> <Item Value="objectVersionId"/> <Item Value="productId"/> <Item Value="productName"/> </AttrNames> </nodeDefinition> </tree> </bindings>
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.
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
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 7-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
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.
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 7.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 7.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 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 All Queriable Attributes.
Drag the All Queriable Attributes 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 7-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.
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 All Queriable Attributes
Drag the All Queriable Attributes 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.
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.
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 7.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.
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 7-4. For example, if the search criteria type is date, then inputDate
will be rendered.
Table 7-4 Quick Query Search Criteria Field Components
Attribute Type | Rendered Component |
---|---|
|
|
|
|
|
|
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.
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 7.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 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 All Queriable Attributes.
Drag the All Queriable Attributes 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 7-16.