Using the Query Component
The af:query component is used for transactional searches. It has a basic and an advanced mode which the user can toggle by clicking a button.
The basic mode query form features include:
* dropdown list of selectable search criteria operators
* selectable WHERE clause conjunction of either AND or OR (match all or match any)
* saved searches and seeded searches
* personalizing saved searches
The advanced mode query form also includes the ability for user to dynamically add search criteria by selecting from a list of searchable attributes. The user can subsequently delete any criteria that was added.
When an af:query component is dropped onto a JSF page, it offers the user a search panel that includes one or more input fields for entering search criteria values. The user can select from the dropdown list of operators to create a SQL Query WHERE clause for the search. The input fields may be configured to be list of value (LOV), number spinners, date picker, or other modifications. If a search criteria’s underlying attribute was defined as an LOV, inorder for the auto completion feature to work, you must set autoSubmit to true on the LOV component. Also, the query component will support the af:inputListOfValues LOV component. If the af:inputComboboxListOfValues component is defined instead in the model, the af:inputListOfValues component will be inserted in its place. For more informaton about LOV, see Chapter 9, “Using LOV Components”.
A Match All/Match Any radio button group further modifies the query. A Match All selection is essentially an AND function. The query will only return rows that match all the selected criteria. A Match Any selection is an OR function. The query will return all rows that match any one of the criteria.
After the user entered all the search criteria values (including null values) and selected the Match All/Any radio button, the user can click the Search button to initiate the query. The query results can be displayed in any output component. Typically, the output component will be a table or tree table, but you can associate other display components such as af:forms, af:outputText, and graphics to be the results component.
If the basic/advanced button is present, the user can toggle between the two modes. Each mode will display only the search criteria that were defined for that mode. A search criteria field can be defined to appear only for basic, only for advanced, or for both modes.
In advanced mode, the control panel also includes an Add Fields button that exposes a popup list of searchable attributes. When the user selects any of these attributes, a dynamically generated search criteria input field and dropdown operator appears. The position of all search criteria input fields as wells as newly added fields are determined by the model implementation.
This newly created search criteria field will also have an delete icon next to it. The user can subsequently click on this icon to delete the added field. The originally defined search criteria fields do not have a delete icon and therefore cannot be deleted by the user.
The user can also save the entered search criteria and the mode by clicking on the Save button. A popup dialog allows the user to provide a name for the save search and specify hints by selecting checkboxes. A saved search persists for the duration of the session. A persistent data store is required if the save search is to be available beyond the session. For more information about persistence, see Chapter 28, “Using Change Persistence”.
A seeded search is a essentially a saved search that was created by the application developer. When the component is initialized, any seeded searches associated with that query component become available for the user to select.
Any user created saved searches and seeded system searches appear in the Saved Search dropdown list. The seeded searches and user saved searches are separated by a divider.
Users can also personalize the save searches for future use. Personalization of saved searches requires the availability of a persistent data store. For more information about persistence, see Chapter 28, “Using Change Persistence”.