Oracle® Fusion Middleware Web User Interface Developer's Guide for Oracle Application Development Framework 11g Release 1 (11.1.1.7.2) Part Number B31973-18 |
|
|
PDF · Mobi · ePub |
This chapter describes how to use a list-of-values component to display a model-driven list of objects from which a user can select a value.
This chapter includes the following sections:
ADF Faces provides two list-of-values (LOV) input components that can display multiple attributes of each list item and can optionally allow the user to search for the needed item. These LOV components are useful when a field used to populate an attribute for one object might actually be contained in a list of other objects, as with a foreign key relationship in a database. For example, suppose you have a form that allows the user to edit employee information. Instead of having a separate page where the user first has to find the employee record to edit, that search and select functionality can be built into the form, as shown in Figure 11-1.
In this form, the employee name field is an LOV that contains a list of employees. When the user clicks the search icon of the inputListOfValues
component, a Search and Select dialog displays all employees, along with a search field that allows the user to search for the employee, as shown in Figure 11-2.
When the user returns to the page, the current information for that employee is displayed in the form, as shown in Figure 11-3. The user can then edit and save the data.
Other list components, such as selectOneChoice
, also allow users to select from a list, but they do not include a popup dialog and they are intended for smaller lists. This chapter describes only the inputListOfValues
and inputComboboxListOfValues
LOV components. For more information about select choice components, list box components, and radio buttons, see Chapter 9, "Using Input Components and Defining Forms."
As shown in the preceding figures, the inputListOfValues
component provides a popup dialog from which the user can search for and select an item. The list is displayed in a table. In contrast, the inputComboboxListOfValues
component allows the user two different ways to select an item to input: from a simple dropdown list, or by searching as you can in the inputListOfValues
component.
You can also create custom content to be rendered in the Search and Select dialog by using the searchContent
facet. You define the returnPopupDataValue
attribute and programmatically set it with a value when the user selects an item from the Search and Select dialog and then closes the dialog. This value will be the return value from ReturnPopupEvent to the returnPopupListener
. When you implement the returnPopupListener
, you can perform functions such as setting the value of the LOV component, its dependent components, and displaying the custom content. In the searchContent
facet you can add components such as tables, trees, and inputText to display your custom content.
If you implement both the searchContent
facet and the ListOfValues
model, the searchContent
facet implementation will take precedence in rendering the Search and Select dialog. Example 11-1 show the code to display custom content using a table component.
Example 11-1 Adding Custom Content to the Search and Select Dialog
<af:inputListOfValues model="#{bean.listOfValuesModel}" ... returnPopupDataValue="#{bean.returnPopupDataValue}" returnPopupListener="#{bean.returnPopupListener}"> <f:facet name="searchContent"> <af:table id="t1" value="#{bean.listModel}" var="row" selectionListener="#{bean.selected}" ... </f:facet> </af:inputListOfValues>
If the readOnly
attribute is set to true
, the input field is disabled. If readOnly
is set to false
, then the editMode
attribute determines which type of input is allowed. If editMode
is set to select
, the value can be entered only by selecting from the list. If editMode
is set to input
, then the value can also be entered by typing.
You can also implement the LOV component to automatically display a list of suggested items when the user types in a partial value. For example, when the user enters Ca
, then a suggested list which partially matches Ca
is displayed as a suggested items list, as shown in Figure 11-4.
The user can select an item from this list to enter it into the input field, as shown in Figure 11-5.
You add the auto suggest behavior by adding the af:autoSuggestBehavior
tag inside the LOV component with the tag's suggestItems
values set to a method that retrieves and displays the list. You can create this method in a managed bean. If you are using ADF Model, the method is implemented by default.
In your LOV model implementation, you can implement a smart list that filters the list further. You can implement a smart list for both LOV components. If you are using ADF Model, the inputComboboxListOfValues
allows you declaratively select a smart list filter defined as a view criteria for that LOV. If the smart list is implemented, and auto suggest behavior is also used, auto suggest will search from the smart list first. If the user waits for two seconds without a gesture, auto suggest will also search from the full list and append the results. The maxSuggestedItems
attribute specifies the number of items to return (-1 indicates a complete list). If maxSuggestedItems > 0
, a More link is rendered for the user to click to launch the LOV's Search and Select dialog. Example 11-2 shows the code for an LOV component with both auto suggest behavior and smart list.
Example 11-2 Auto Suggest Behavior and Smart List
<af:autoSuggestBehavior suggestItems="#{bean.suggestItems}" smartList="#{bean.smartList}" maxSuggestedItems="7"/>
Figure 11-6 shows how a list can be displayed by an inputComboboxListOfValues
component. If the popup dialog includes a query panel, then a Search link is displayed at the bottom of the dropdown list. If a query panel is not used, a More link is displayed.
The dropdown list of the inputComboboxListOfValues
component can display the following:
Full list: As shown in Figure 11-6, a complete list of items returned by the ListOfValuesModel.getItems()
method.
Favorites list: A list of recently selected items returned by the ListOfValuesModel.getRecentItems()
method.
Search link: A link that opens a popup Search and Select dialog. The link is not on the scrollable region on the dropdown list.
customActions
facet: A facet for adding additional content. Typically, this contains one or more commandLink
components. You are responsible for implementing any logic for the commandLink
to perform its intended action, for example, launching a popup dialog.
The number of columns to be displayed for each row can be retrieved from the model using the getItemDescriptors()
method. The default is to show all the columns.
The popup dialog from within an inputListOfValues
component or the optional search popup dialog in the inputComboboxListOfValues
component also provides the ability to create a new record. For the inputListOfValues
component, when the createPopupId
attribute is set on the component, a toolbar
component with a commandToolbarButton
is displayed with a create icon. At runtime, a commandToolbarButton
component appears in the LOV popup dialog, as shown in Figure 11-7.
When the user clicks the Create button, a popup dialog is displayed that can be used to create a new record. For the inputComboboxListOfValues
, instead of a toolbar, a commandLink
with the label Create is displayed in the customActions
facet, at the bottom of the dialog. This link launches a popup where the user can create a new record. In both cases, you must provide the code to actually create the new record.
Tip:
Instead of having to build your own create functionality, you can use ADF Business Components and ADF data binding. For more information, see the "Creating an Input Table" section of the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.
Like the query components, the LOV components rely on a data model to provide the functionality. This data model is the ListOfValuesModel
class. This model uses a table model to display the list of values, and can also access a query model to perform a search against the list. You must implement the provided interfaces for the ListOfValuesModel
in order to use the LOV components.
Tip:
Instead of having to build your own ListOfValuesModel
class, you can use ADF Business Components to provide the needed functionality. For more information, see the "Creating Databound Selection Lists and Shuttles" chapter of the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.
When the user selects an item in the list, the data is returned as a list of objects for the selected row, where each object is the rowData
for a selected row. The list of objects is available on the ReturnPopupEvent
event, which is queued after a selection is made.
If you choose to also implement a QueryModel
class, then the popup dialog will include a Query
component that the user can use to perform a search and to filter the list. Note the following about using the Query
component in an LOV popup dialog:
The saved search functionality is not supported.
The Query
component in the popup dialog and its functionality is based on the corresponding QueryDescriptor
class.
The only components that can be included in the LOV popup dialog are query
, toolbar
, and table
.
When the user clicks the Search button to start a search, the ListOfValuesModel.performQuery()
method is invoked and the search is performed. For more information about the query model, see Chapter 12, "Using Query Components."
Both components support the auto-complete feature, which allows the user to enter a partial value in the input field, tab out, and have the dialog populated with the rows that match the partial criteria. For this to work, you must implement logic so that when the user tabs out after a partial entry, the entered value is posted back to the server. On the server, your model implementation filters the list using the partially entered value and performs a query to retrieve the list of values. ADF Faces provides APIs for this functionality.
Before you can use the LOV components, you must have a data model that uses the ADF Faces API to access the LOV functionality. Figure 11-8 shows the class diagram for a ListOfValues
model.
To create a ListOfValues model and associated events:
Create implementations of each of the interface classes shown in Figure 11-8. Table 11-1 provides a description of the APIs.
Table 11-1 ListOfValues Model API
Method | Functionality |
---|---|
|
Called when the search icon is clicked or the value is changed and the user tabs out from the input field, as long as |
|
Called when the value is selected from the Search and Select dialog and the OK button is clicked. This method gives the model a chance to update the model based on the selected value. |
|
Returns a boolean to decide whether or not the auto complete is enabled. |
|
Returns the implementation of the |
|
Return the |
|
Return the list of |
|
Return the |
|
Called when the search button in the |
For an example of a ListOfValues
model, see the DemoLOVBean
and DemoComboboxLOVBean
classes located in the oracle.adfdemo.view.lov
package, found in the Application Sources directory of the ADF Faces application.
For the inputListOfValues
component, provide logic in a managed bean (it can be the same managed bean used to create your LOV model) that accesses the attribute used to populate the list. The inputComboboxListOfValues
component uses the getItems()
and getRecentItems()
methods to return the list.
For the Search and Select dialog used in the InputListOfValues
component, or if you want the InputComboboxListOfValues
component to use the Search and Select dialog, implement the ListOfValuesModel.autoCompleteValue()
and ListOfValuesModel.valueSelected()
methods. These methods open the popup dialog and apply the selected values onto the component.
The inputListOfValues
component uses the ListOfValues
model you implemented to access the list of items, as documented in Section 11.2, "Creating the ListOfValues Data Model."
Before you begin:
You should already have a created a page or page fragment. If you also implemented the search API in the model, the component would also allows the user to search through the list for the value.
To add an inputListOfValues component:
In the Component Palette, from the Common panel, drag an Input List Of Values component and drop it onto the page.
In the Property Inspector, expand the Common section and set the following attributes:
model: Enter an EL expression that resolves to your ListOfValuesModel
implementation, as created in Section 11.2, "Creating the ListOfValues Data Model."
value: Enter an EL expression that resolves to the attribute values used to populate the list, as created in Section 11.2, "Creating the ListOfValues Data Model."
Expand the Appearance section and set the following attribute values:
popupTitle: Specify the title of the Search and Select popup dialog.
searchDesc: Enter text to display as a mouseover tip for the component.
Placeholder: Specify the text that appears in the inputListOfValues
component if the component is empty and does not have focus. When the component gets focus, or has a value, then the placeholder text is hidden.
The placeholder text is used to inform the user what should be entered in the inputListOfValues
component.
The rest of the attributes in this section can be populated in the same manner as any other input component. For more information, see Section 9.3, "Using the inputText Component."
Expand the Behavior section and set the following attribute values:
autoSubmit: Set to true
if you want the component to automatically submit the enclosing form when an appropriate action takes place (a click, text change, and so on). This will allow the auto-complete feature to work.
createPopupId: If you have implemented a popup dialog used to create a new object in the list, specify the ID of that popup component. Doing so will display a toolbar
component above the table that contains a commandToolbarButton
component bound to the popup dialog you defined. If you have added a dialog to the popup, then it will intelligently decide when to refresh the table. If you have not added a dialog to the popup, then the table will be always refreshed.
launchPopupListener: Enter an EL expression that resolves to a launchPopupListener
that you implement to provide additional functionality when the popup is launched.
returnPopupListener: Enter an EL expression that resolves to a returnPopupListener
component that you implement to provide additional functionality when the value is returned.
Usage: Specify how the inputListOfValues
component will be rendered in HTML 5 browser. The valid values are auto
, text
, and search
. Default is auto
.
If the usage type is search
, the inputListOfValues
component will render as an HTML 5 search input type. Some HTML 5 browsers may add a Cancel icon that can be used to clear the search text.
The rest of the attributes in this section can be populated in the same manner as any other input component. For more information, see Section 9.3, "Using the inputText Component."
If you want users to be able to create a new item, create a popup dialog with the ID given in Step 4. For more information, see Chapter 13, "Using Popup Dialogs, Menus, and Windows."
In the Component Palette, from the Operations panel, drag an Auto Suggest Behavior and drop it as a child to the inputListOfValues
component.
In the Property Inspector, for each of the auto suggest attributes, enter the:
EL expression that resolves to the suggestItems
method.
The method should return List<javax.model.SelectItem>
of the suggestItems
. The method signature should be of the form List<javax.model.SelectItem> suggestItems(javax.faces.context.FacesContext, oracle.adf.view.rich.model.AutoSuggestUIHints)
EL expression that resolves to the smartList
method. The method should return List<javax.model.SelectItem>
of the smart list items.
number of items to be displayed in the auto suggest list. Enter -1 to display the complete list.
If you are implementing this method in a managed bean, the JSF page entry should have the format shown in Example 11-3.
Example 11-3 autoSuggestBehavior Tag in an LOV
<af:inputListOfValues value="#{bean.value}" id="inputId"> ... <af:autoSuggestBehavior suggestItems="#{bean.suggestItems}" smartList="#{bean.smartList}" maxSuggestedItems="7"/> </af:inputListOfValues>
If the component is being used with a data model such as ADF Model, the suggestItem
method should be provided by the default implementation.
If you are not using ADF Model, create the suggestItems
method to process and display the list. The suggestItems
method signature is shown in Example 11-4.
By default, the search and select dialogs that the InputComboboxListOfValues
and InputListOfValues
components can be resized by end users when they render. You can disable the end user's ability to resize these dialogs by setting the value of the -tr-stretch-search-dialog
selector key to false
in your application's skin file, as shown in Example 11-5. The default value of the -tr-stretch-search-dialog
selector key is true
. For more information about skinning, see the skinning chapter.
The inputComboboxListOfValues
component allows a user to select a value from a dropdown list and populate the LOV field, and possibly other fields, on a page, similar to the inputListOfValues
component. However, it also allows users to view the values in the list either as a complete list, or by most recently viewed. You can also configure the component to perform a search in a popup dialog, as long as you have implemented the query APIs, as documented in Section 11.2, "Creating the ListOfValues Data Model."
For more information about skinning and the Search and Select dialog sizing, see Section 11.3.2, "What You May Need to Know About Skinning the Search and Select Dialogs in the LOV Components."
Before you begin:
You should already have a created a page or page fragment.
To add an inputComboboxListOfValues component:
In the Component Palette, from the Common panel, drag an Input Combobox List Of Values and drop it onto the page.
In the Property Inspector, expand the Common section and set the following attributes:
model: Enter an EL expression that resolves to your ListOfValuesModel
implementation, as created in Section 11.2, "Creating the ListOfValues Data Model."
value: Enter an EL expression that resolves to the attribute values used to populate the list, as created in Section 11.2, "Creating the ListOfValues Data Model."
Expand the Appearance section and set the following attribute values:
popupTitle: Specify the title of the Search and Select popup dialog.
searchDesc: Enter text to display as a mouseover tip for the component.
Placeholder: Specify the text that appears in the inputComboboxListOfValues
component if the component is empty and does not have focus. When the component gets focus, or has a value, then the placeholder text is hidden.
The placeholder text is used to inform the user what should be entered in the inputComboboxListOfValues
component.
The rest of the attributes in this section can be populated in the same manner as any other input component. For more information, see Section 9.3, "Using the inputText Component."
Expand the Behavior section and set the following attribute values:
autoSubmit: Set to true
if you want the component to automatically submit the enclosing form when an appropriate action takes place (a click, text change, and so on). This will allow the auto complete feature to work.
createPopupId: If you have implemented a popup dialog used to create a new object in the list, specify the ID of that popup component. Doing so will display a toolbar
component above the table that contains a commandToolbarButton
component bound to the dialog you defined. If you have added a dialog to the popup, then it will intelligently decide when to refresh the table. If you have not added a dialog to the popup, then the table will always be refreshed.
launchPopupListener: Enter an EL expression that resolves to a launchPopupListener
handler that you implement to provide additional functionality when the popup dialog is opened.
returnPopupListener: Enter an EL expression that resolves to a returnPopupListener
handler that you implement to provide additional functionality when the value is returned.
Usage: Specify how the inputComboboxListOfValues
component will be rendered in HTML 5 browser. The valid values are auto
, text
, and search
. Default is auto
.
If the usage type is search
, the inputComboboxListOfValues
component will render as an HTML 5 search input type. Some HTML 5 browsers may add a Cancel icon that can be used to clear the search text.
The rest of the attributes in this section can be populated in the same manner as any other input component. For more information, see Section 9.3, "Using the inputText Component."
If you are using a launchPopupListener
, you can use the getPopupType()
method of the LaunchPopupEvent
class to differentiate the source of the event. getPopupType()
returns DROPDOWN_LIST
if the event is a result of the launch of the LOV Search and Select dialog, and SEARCH_DIALOG
if the event is the result of the user clicking the Search button in the dialog.
If you want users to be able to create a new item, create a popup dialog with the ID given in Step 5. For more information, see Chapter 13, "Using Popup Dialogs, Menus, and Windows."
In the Component Palette, from the Operations panel, drag an Auto Suggest Behavior and drop it as child to the inputComboboxListOfValues
component.
In the Property Inspector, for each of the auto suggest attributes, enter the:
EL expression that resolves to the suggestItems
method.
The method should return List<javax.model.SelectItem>
of the suggestItems
. The method signature should be of the form List<javax.model.SelectItem> suggestItems(javax.faces.context.FacesContext, oracle.adf.view.rich.model.AutoSuggestUIHints)
EL expression that resolves to the smartList
method. The method should return List<javax.model.SelectItem>
of the smart list items.
number of items to be displayed in the auto suggest list. Enter -1 to display the complete list.
If you are implementing this method in a managed bean, the JSF page entry should have the format shown in Example 11-6.
Example 11-6 autoSuggestBehavior Tag in an LOV
<af:inputComboboxListOfValues value="#{bean.value}" id="inputId"> ... <af:autoSuggestBehavior suggestItems="#{bean.suggestItems}" smartList="#{bean.smartList}" maxSuggestedItems="7"/> </af:inputComboboxListOfValues>
If the component is being used with a data model such as ADF Model, the suggestItem
method should be provided by the default implementation.
If you are not using the component with ADF Model, create the suggestItems
method to process and display the list. The suggestItems
method signature is shown in Example 11-7.