12-6 Web User Interface Developers Guide for Oracle Application Development Framework
Table 12–1 Query UI Artifacts and Associated Model Class Operations and Properties
UI Artifact Class PropertyMethods Used
Comments
1 Search panel
The QueryDescriptor instance provides the items displayed in the
panel. Based on a saved search.
2 Disclosure icon
Opens or closes the search panel 3
Match type radio button
Available through the getConjunction method on the
ConjunctionCriterion class. Displays the default conjunction to use
between search fields, when a query is performed. If a default is set, and it is the
same for all search fields, it appears selected. If the search fields are configured
such that a mix of different conjunctions must be used between them, then a value
may not be selected on the UI.
For example, if the All conjunction type is used between all the search fields, then
All appears selected. If it is a mix of All and Any, then none of the radio buttons
appears selected.
The Match Type will be read only if the conjunctionReadOnly property is set to
true. Its not rendered at all when the displayMode attribute is set to simple.
Using Query Components 12-7
Table 12–2 shows the behaviors of the different UI artifacts, and the associated
methods invoked to execute the behavior. 4
Group of search fields
The collection of search fields for a QueryDescriptor object is
represented by a ConjunctionCriterion object,
returned by the method getConjunctionCriterion on the
QueryDescriptor class. The getCriterionList method returns
a ListCriterion list. Displays one or more search fields
associated with the currently selected search.
5 Search field
An AttributeCriterion class provides information specific to a search
field instance. An AttributeCriterion object is an
item in the ListCriterion list returned by getCriterionList
method on the ConjunctionCriterion class see
4.
An AttributeDescriptor class provides static information pertaining to
a search field. This is available through the method getAttribute, on the
AttributeCriterion class.
The getConverter method of the AttributeDescriptor class can be
overridden to return a converter object of type
javax.faces.convert.Converter. When defined, the attribute value is
converted using this converter instance. The default return value is null.
The hasDependentCriterion method in the AttributeCriterion
class returns true if the criterion has dependents. If the criterion has
dependents, then the dependent criterion fields are refreshed when the
value for this criterion changes. By default this method returns false.
Each search field contains a label, an operator, one or more value components
for example, an input text component, and an optional delete icon. The
information required to render these can be either specific to an instance of a search
field in a saved search or it can be generic and unchanging regardless of which saved
search it is part of.
For example, assume an Employee business object contains the search fields
Employee Name and Salary.
A user can then configure two different searches: one named Low Salaried
Employees and one named High Salaried Employees. Both searches contain two
search fields based on the Employee and Salary attributes. Even though both
saved searches are based on the same attributes of the Employee object, the
search field Salary is configured to have its default operator as less than and value as
50000.00
for the low Salaried Employees search and for the High Salaried
Employees search, with a default operator of greater than and value of 100000.00.
Selecting the saved searches on the UI will show the appropriate operator and values
for that search.
Regardless of the search selected by the user, the search field for Salary always has
to render a number component, and the label always has to show Salary.
6 Saved Searches
dropdown System- and user-saved searches are
available through the methods getSystemQueries and
getUserQueries on the QueryModel class.
Displays a list of available system- and user-saved searches.
A Personalize option is also added if the saveQueryMode property is set to
default. Selecting this option opens a Personalize dialog, which allows users to
personalize saved searches. They can duplicate or update an existing saved
search.
Table 12–1 Cont. Query UI Artifacts and Associated Model Class Operations and
UI Artifact Class PropertyMethods Used
Comments
12-8 Web User Interface Developers Guide for Oracle Application Development Framework
Table 12–2 UI Artifact Behaviors and Associated Methods
UI Artifact Class Method Invoked
Event Generated Comments
7 Delete icon
During the Invoke Application phase, the method
removeCriterion on the QueryDescriptor class is
called automatically by an internal ActionListener
handler registered with the command component.
ActionEvent Deletes a search field
from the current QueryDescriptor
object.
8 Search button
During the Apply Request Values phase of the JSF lifecycle,
a QueryEvent event is queued, to be broadcast during the
Invoke Application phase.
During the Update Model Values phase, the selected operator and
the values entered in the search fields are automatically updated
to the model using the EL expressions added to the
operator and value components for more information, see
Section 12.4.1, How to Add the Query Component
. These expressions should invoke the
getsetOperator; getsetOperators; and
getValues methods, respectively, on the
AttributeCriterion class.
During the Invoke Application phase, the QueryListener
registered with the query component is invoked and this
performs the search.
You must implement this listener.
QueryEvent Rendered always on the
footer footer contents are not rendered at all
when the displayMode attribute is simple
Performs a query using the select operator and
selected Match radio if no selection is made the
default is used, and the values entered for every
search field.
9 Reset button
During the Apply Request Values phase of the JSF lifecycle,
a QueryOperationEvent event is queued with the
operation type QueryOperationEvent.
Operation.RESET, to be broadcast during the Invoke
Application phase.
During the Invoke Application phase, the method reset on
the QueryModel class is called. This is done automatically by an
internal QueryOperationListener
handler registered with the query component. You must
override this method to reset the QueryDescriptor object to its
original state. QueryOperationEvent
an internal QueryOperation
Listener handler is registered with the query
component that in turn calls the model methods.
Resets the search fields to its previous saved
state.
Using Query Components 12-9
10 Save button
During the Apply Request Values phase of the JSF lifecycle,
a QueryOperationEvent event is queued with the
operation type QueryOperationEvent.
Operation.SAVE, to be broadcast during the Invoke
Application phase.
During the Invoke Application phase, the method create on
the QueryModel class is called. After the call to the create
method, the update method is called to save the hints
selected by the user in the dialog onto the new saved
search. This is done automatically by an internal
QueryOperationListener handler registered with the
query component. You must override this method to create a
new object based on the argument passed in.
QueryOperationEvent an internal
QueryOperation Listener handler is
registered with the query component that in turn
calls the model methods. Creates a new saved
search based on the current saved search
settings, including any new search fields added
by the user.
11 Add Fields
dropdown list During the Invoke Application
phase, the method addCriterion on the
QueryDescriptor class is called automatically by an
internal ActionListener handler registered with the
command component. You must override this method to create a
new AttributeCriterion object based on the
AttributeDescriptor object identified by the name
argument. ActionEvent
Adds an attribute as a search field to the
existing saved search.
12 Mode Basic or
Advanced button During the Apply Request
Values phase of the JSF lifecycle, a QueryOperationEvent
event is queued with the operation type
QueryOperationEvent. Operation.MODE_CHANGE, to
be broadcast during the Invoke Application phase.
During the Invoke Application phase, the method
changeModeon the QueryModel class is called.
QueryOperationEvent an internal
QueryOperation Listener handler is
registered with the query component that in turn
calls the model methods. Clicking the mode
button toggles the mode.
Table 12–2 Cont. UI Artifact Behaviors and Associated Methods
UI Artifact Class Method Invoked
Event Generated Comments
12-10 Web User Interface Developers Guide for Oracle Application Development Framework
12.3 Using the quickQuery Component
The quickQuery component has one dropdown list that allows a user to select an attribute to search on. The available searchable attributes are drawn from your
implementation of the model or from a managed bean. The user can search against the selected attribute or against all attributes.
A quickQuery component may be used as the starting point of a more complex search using a query component. For example, the user may perform a quick query
search on one attribute, and if successful, may want to continue to a more complex search. The quickQuery component supports this by allowing you to place command
13 Delete button
During the Invoke Application phase, the method delete on
the QueryModel class is called. This is done automatically by an
internal QueryOperationListener
handler registered with the query component. You must
override this method order to delete the QueryDescriptor
object. ActionEvent
Deletes the selected saved search, unless it is
the one currently in use.
14 Apply button
During the Apply Request Values phase of the JSF lifecycle,
a QueryOperationEvent event is queued with the
operation type QueryOperationEvent.
Operation.UPDATE, to be broadcast during the Invoke
Application phase.
During the Invoke Application phase, the method update on
the QueryModel class is called. This is done automatically by an
internal QueryOperationListener
handler registered with the query component. You must
override this method in order to update the QueryDescriptor
object using the arguments passed in.
QueryOperationEvent an internal
QueryOperation Listener is registered
with the query component that in turn
calls the model methods. Applies changes made to
the selected saved search.
15 OK button
Same as the Apply button. QueryOperationEvent
an internal QueryOperation
Listener handler is registered with the query
component that in turn calls the model methods.
Applies changes made to the selected saved search
and the dialog is closed afterwards.
16 Cancel button
No method defined for this action.
QueryOperationEvent an internal
QueryOperation Listener handler is
registered with the query component that in turn
calls the model methods. Cancels any edits made
in the dialog.
Table 12–2 Cont. UI Artifact Behaviors and Associated Methods
UI Artifact Class Method Invoked
Event Generated Comments
Using Query Components 12-11
components in the end facet, which you can bind to a method on a managed bean that allows the user to switch from a quickQuery to a query component.
The quickQuery component renders the searchable criteria in a dropdown list and then, depending on the type of the criteria chosen at runtime, the quickQuery
component renders different criteria fields based on the attribute type. For example, if the attribute type is Number, it renders an inputNumberSpinbox component. You
do not need to add these components as long as you have implemented the complete model for your query. If instead you have the logic in a managed bean and do not
need a complete model, then you create the quickQuery component artifacts manually. For more information, see
Section 12.3.2, How to Use a quickQuery Component Without a Model.
12.3.1 How to Add the quickQuery Component Using a Model
Before you begin Implement a QueryModel class and associated classes. For more information, see
Section 12.2, Implementing the Model for Your Query.
To add a quickQuery component: 1.
In the Component Palette, from the Common Components panel, drag a Quick Query
and drop it onto the page.
2. Expand the Common section of the Property Inspector and set the following
attributes:
■
id : Enter a unique ID for the component.
■
layout : Specify if you want the component to be displayed horizontally with
the criterion and value next to each other, as shown in Figure 12–2
, or vertically as shown in
Figure 12–5 .
Figure 12–5 A quickQuery Component Set to Display Vertically
■
model : Enter an EL expression that evaluates to the class that implements the
QueryModel class, as created in Section 12.2, Implementing the Model for
Your Query.
■
value : Enter an EL expression that evaluates to the class that implements the
QueryDescriptor class, as created in Section 12.2, Implementing the Model
for Your Query.
3. Expand the Behavior section and set the following attributes:
■
conjunctionReadOnly : Specify whether or not the user should be able to set
the Match Any or Match All radio buttons. When set to false, the user can set the conjunction. When set to true, the radio buttons will not be rendered.
■
queryListener : Enter an EL expression that evaluates to the QueryListener
handler you created in Section 12.2, Implementing the Model for Your
Query.
12-12 Web User Interface Developers Guide for Oracle Application Development Framework
4.
Drag and drop a table or other component that will display the search results onto the page. Set the results component’s PartialTriggers with the ID of the
quickQuery component. The value of this component should resolve to a CollectionModel object that contains the filtered results.
5. If you want users to be able to click the Advanced link to turn the quickQuery
component into a full query component, add a command component to the End facet of the quickQuery component, and implement logic that will hide the
quickQuery component and display the query component.
12.3.2 How to Use a quickQuery Component Without a Model
You can use the quickQuery component without a model, for example if all your query logic resides in a simple managed bean, including a QueryListener handler
that will execute the search and return the results. You must to manually add and bind the components required to create the complete quickQuery component.
To add a quickQuery component: 1.
On a managed bean, create a valueChangeListener handler for the selectOneChoice component that will display the attributes on which the user
can search. The valueChangeListener handler should handle the choice for which attribute to search on.
2. On a managed bean, create the QueryListener handle to execute the search.
This handle will use the ID of the input component used to enter the search criterion value, to retrieve the component and the value to execute the query.
3. In the Component Palette, from the Common Components panel, drag a Quick
Query and drop it onto the page.
4. In the Property Inspector, expand the Common section, and set the following
attributes:
■
id : Enter a unique ID for the component.
■
layout : Specify if you want the component to display horizontally with the
criterion and value next to each other, as shown in Figure 12–2
, or vertically, as shown in
Figure 12–5 .
5. Expand the Behavior section and set the QueryListener attribute to an EL
expression that evaluates to the QueryListener handler created in Step 2.
6. In the Component Palette, from the Common Components panel, drag a Select
One Choice and drop it onto the criteriaItems facet of the quickQuery
component. In the dialog, choose either to enter an EL expression that evaluates to the list of attributes on which the user can search, or to enter a static list. For help
with the dialog, press F1 or click Help.
7.
In the Structure window, select the selectOneChoice component in the criteriaItems facet, and set the following attributes:
■
simple : Set to true so that no label for the component displays.
■
valueChangeListener : Enter an EL expression that evaluates to the listener
created in Step 1.
■
autoSubmit : Set to true.
8.
From the Component Palette, add select list items as needed. For more information about using the selectOneChoice and selectItems components,
see Section 9.6, Using Selection Components.
Using Query Components 12-13
9.
In the Component Palette, from the Common Components panel, drag an inputText
component as a direct child to the quickQuery component. Set the following attributes:
■
simple : Set to true so that the label is not displayed.
■
value : Enter an EL expression that evaluates to the property that will contain
the value that the user enters.
10. If you want users to be able to click the Advanced link to turn the quickQuery
component into a full query component, add a command component to the End facet of the quickQuery component, and implement logic that will hide the
quickQuery component and display the query component.
11. In the Component Palette, from the Common Components panel, drag a table or
other component that will display the search results onto the page. Set the results component’s PartialTriggers with the ID of the quickQuery component.
The value of this component should resolve to a CollectionModel object that contains the filtered results.
12.3.3 What Happens at Runtime: How the Framework Renders the quickQuery Component and Executes the Search
When the quickQuery component is bound to a QueryDescriptor object, the selectOneChoice and inputText components are automatically added at runtime
as the page is rendered. However, you can provide your own components. If you do provide both the component to display the searchable attributes and the inputText
components, then you need the QueryListener handler to get the name-value pair from your components.
If you provide only your own component to show the searchable attributes and use the default input text component, the framework will display an input text
component. You must have your QueryListener handler get the attribute name from the dropdown list and the value from the
QueryDescriptor.getCurrentCriterion method to perform the query.
If you provide only your own component to collect the searchable attribute value and use the default selectOneChoice component to provide the attribute name, then
the framework will display the selectOneChoice component. You must have your QueryListener handler get the attribute name from the
QueryDescriptor.getCurrentCriterion method and the value from your component.
If you choose not to bind the QuickQuery component value attribute to a QueryDescriptor object, and you provide both components, when the Go button is
clicked, the framework queues a QueryEvent event with a null QueryDescriptor object. The provided QueryListener handler then executes the query using the
changeValueListener handler to access the name and the input component to access the value. You will need to implement a QueryListener handler to retrieve
the attribute name from your selectOneChoice component and the attribute value from your inputText component, and then perform a query.
Tip: If you do not provide an inputText component, then at
runtime, a disabled inputText component and a disabled Go icon will be rendered.