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

Part Number B31973-09
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
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 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. Note that the columns of the table will not stretch to the full width of the dialog.

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.

Figure 11-4 Suggested Items List for an LOV

Suggested Items list.

The user can select an item from this list to enter it into the input field, as shown in Figure 11-5.

Figure 11-5 Suggested Items Selected

Suggested Items selected.

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. You also need to set the component's autoSubmit property to true.

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.

Figure 11-6 InputComboboxListOfValues Displays a List of Employee Names

inputComboboxListOfValues shows list

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

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.

Figure 11-7 Create Icon in Toolbar of Popup Dialog

Create icon in toolbar of popup

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:

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

Figure 11-8 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-8. 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.

    getItemDescriptors()

    Return the list of columnDescriptors to be displayed in the dropdown list for an inputComboboxListOfValues 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."

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:

  1. In the Component Palette, from the Common panel, drag an Input List Of Values component and drop it 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. If you are adding the auto suggest behavior, you must set autoSubmit to true.

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

  6. In the Component Palette, from the Operations panel, drag an Auto Suggest Behavior and drop it as a child to the inputListOfValues component.

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

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

    Example 11-4 suggestItems Method Signature

    List<javax.model.SelectItem> suggestItems(javax.faces.context.FacesContext,
        oracle.adf.view.rich.model.AutoSuggestUIHints) 
    

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

Before you begin:

You should already have a created a page or page fragment.

To add an inputComboboxListOfValues component:

  1. In the Component Palette, from the Common panel, drag an Input Combobox List Of Values and drop it 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. If you are adding the auto-suggest behavior, you must set autoSubmit to true.

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

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

  7. In the Component Palette, from the Operations panel, drag an Auto Suggest Behavior and drop it as child to the inputComboboxListOfValues component.

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

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

  9. 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-6.

    Example 11-6 suggestItems Method Signature

    List<javax.model.SelectItem> suggestItems(javax.faces.context.FacesContext,
        oracle.adf.view.rich.model.AutoSuggestUIHints)