Skip Headers
Oracle® Fusion Middleware Web User Interface Developer's Guide for Oracle Application Development Framework
11g Release 1 (11.1.1)

Part Number B31973-02
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
View PDF

11 Using List-of-Values Components

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:

11.1 Introduction to List-of-Values Components

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.

Figure 11-1 List-of-Values Input Field

List of Values field displayed in a browser

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 popup dialog displays all employees, along with a search field that allows the user to search for the employee, as shown in Figure 11-2.

Figure 11-2 The Search Popup Dialog for a List-of-Values Component

Search popup for a list of values component

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.

Figure 11-3 Form Populated Using LOV Component

Fields populated by LOV component

Other list components, such as selectOneChoice, also allow users to select from a list but they do not include a popup dialog, and are intended for smaller lists. This chapter describes only the inputListOfValues and inputComboboxListOfValues LOV components. For more information about select choice, list box, 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. Figure 11-4 shows how a list can be displayed by an inputComboboxListOfValues component.

Figure 11-4 InputComboboxListOfValues Displays a List of Employee Names

inputComboboxListOfValues shows list

The dropdown list of the inputComboboxListOfValues component can display the following:

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-5.

Figure 11-5 Create Icon in Toolbar of Popup Dialog

Create icon in toolbar of popup

When the user clicks on 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 Oracle 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 Oracle 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, that 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:

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.

11.2 Creating the ListOfValues Data Model

Before you can use the LOV components, you must create a data model that uses the ADF Faces API to access the LOV functionality. Figure 11-6 shows the class diagram for a ListOfValues model.

Figure 11-6 Class Diagram for LIstOfValues Model

Class diagram for ListOfValues model

To create a ListOfValues model and associated events:

  1. Create implementations of each of the interface classes shown in Figure 11-6. Table 11-1 provides a description of the APIs.

    Table 11-1 ListOfValues Model API

    Method Functionality

    autoCompleteValue()

    Called when the search icon is clicked or the value is changed and the user tabs out from the input field, as long as autoSubmit is set to true on the component. This method decides whether to open the dialog or to auto-complete the value. The method returns a list of filtered objects.

    valueSelected(value)

    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.

    isAutoCompleteEnabled()

    Returns a boolean to decide whether or not the auto complete is enabled.

    getTableModel()

    Returns the implementation of the TableModel class, on which the table in the search and select dialog will be based and created.

    getItems() and getRecentItems()

    Return the items and recentItems lists to be displayed in the combobox dropdown. Valid only for the inputComboboxListOfValues component. Returns null for the inputListOfValues component.

    getQueryModel() and getQueryDescriptor()

    Return the queryModel based on which the query component inside the Search and Select dialog is created.

    performQuery()

    Called when the search button in the query component is clicked.


    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.

  2. 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.

  3. For the Search and Select popup dialog used in the InputListOfValues component, or if you want the InputComboboxListOfValues component to use the Search and Select popup dialog, implement the ListOfValuesModel.autoCompleteValue() and ListOfValuesModel.valueSelected() methods. These methods open the popup dialog and apply the selected values onto the component.

11.3 Using the inputListOfValues 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". 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:

  1. Drag and drop the Input List Of Values component from the Component Palette onto the page.

  2. In the Property Inspector, expand the Common section and set the following attributes:

  3. 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.

    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".

  4. 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.

    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".

  5. 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".

11.4 Using the InputComboboxListOfValues Component

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".

To add an inputComboboxListOfValues component:

  1. Drag and drop the Input Combobox List Of Values component from the Component Palette onto the page.

  2. In the Property Inspector, expand the Common section and set the following attributes:

  3. 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.

    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".

  4. 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.

    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".

  5. 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".