Implementing the Model for Your Query

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.