11.7 Creating Databound Dropdown Lists

ADF Faces selection list components include selectOneChoice and selectOneListbox, which work in the same way as standard JSF list components. ADF Faces list components, however, provide extra functionality such as support for label and message display, automatic form submission, and partial page rendering.

In the SRDemo application, the SRSearch page uses a selectOneChoice component to let users pick the type of service request to perform a search on. With the selectOneChoice component, you can provide a static list of items for selection, or you can create a list that is populated dynamically. In either case, you use a f:selectItems tag to provide the items for display and selection.

11.7.1 How to Create a Dropdown List with a Fixed List of Values

The SRSearch page uses a selectOneChoice component to let users pick the type of service request to perform a search on. For example, instead of searching on all service requests, the user can refine the search on requests that have the status of open, pending, or closed. Figure 11-19 shows the search form in the SRDemo application where a selectOneChoice component is used.

Figure 11-19 SelectOneChoice Component for Selecting a Service Request Status

Status dropdown list for refining search on service requests

The search form is created using a method that takes parameters. For information about how to create a search form using parameters, see Section 10.8, "Creating Search Pages". The following procedure describes, without using parameters, how to create a dropdown list that is bound to a fixed list of values.

To create a dropdown list bound to a fixed list of values using the Data Control Palette:

From the Data Control Palette, expand a business service method, and then expand a method return that returns a data collection. Drag and drop the data collection attribute you desire onto the page, and then choose Create > Single Selections > ADF Select One Choice from the context menu. The List Binding Editor displays, as illustrated in Figure 11-20.

Using the service request status example, you would expand findAllServiceRequest(), then expand ServiceRequest, and drag and drop the status attribute. Because you want users to be able to search on a service request type, therefore you use the status attribute on the ServiceRequest data collection, which is a collection of all requests returned by the findAllServiceRequest() method.

Figure 11-20 List Binding Editor with the Fixed List Option Selected
In the List Binding Editor, select Fixed List. Then select the status attribute from the Base Data Source Attribute dropdown list.

The Fixed List option lets users choose a value from a predefined list, which is useful when you want to update a data object attribute with values that you code yourself, rather than getting the values from another data collection.

When a value is selected from the list, Base Data Source Attribute is the attribute of the bound data collection that is to be updated to the selected value.
Enter the following in the Set of Values box, pressing Enter to set a value before typing the next value:
- Open
- Pending
- Closed
The order in which you enter the values is the order in which the items are displayed in the selectOneChoice control at runtime.
In the List Items section, select Include Labeled Item from the "No Selection" Item dropdown list. Then enter Any Status in the box next to it.

The selectOneChoice component supports a null value, that is, if the user has not selected an item, the label of the item is shown as blank, and the value of the component defaults to an empty string. Instead of using blank or an empty string, you can specify a string to represent the null value. By default, the new string appears at the top of the list of values that is defined in step 3.

Tip:

In the SRDemo application, the findServiceRequestSearch(Integer, String, String) method contains the logic to find and return service records based on three parameters, one of which is statusParam. Each method parameter has an associated variable. For information about variable iterators and variables, see Section 10.8.2, "What Happens When You Use Parameter Methods".

If you created the search form using the method with parameters (as described in Section 10.8.1, "How to Create a Search Form"), delete the inputText component created for the Status field, and replace it with a selectOneChoice component by dragging and dropping statusParam from the Data Control Palette. In the List Binding Editor, for the Base Data Source Attribute, select the variable name findServiceRequestSearch_statusParam.

11.7.2 What Happens When You Create a Dropdown List Bound to a Fixed List

When you drag and drop from the Data Control Palette, JDeveloper does many things for you. For a full description of what happens and what is created when you use the Data Control Palette, see Section 5.2.3, "What Happens When You Create a Component From the Data Control Palette".

Example 11-54 shows the code for the selectOneChoice component after you've completed the List Binding Editor.

Example 11-54 SelectOneChoice Component After You Complete Binding

<af:selectOneChoice value="#{bindings.ServiceRequeststatus.inputValue}"
                    label="#{bindings.ServiceRequeststatus.label}: ">
  <f:selectItems value="#{bindings.ServiceRequeststatus.items}"/>
</af:selectOneChoice>

The f:selectItems tag, which provides the list of items for selection, is bound to the items property on the ServiceRequeststatus list binding object in the binding container.

In the page definition file (for example, SRSearchPageDef.xml), JDeveloper adds the list binding object definition in the bindings element, as shown in Example 11-55.

Example 11-55 List Binding Object for the Fixed Dropdown List in the Page Definition File

<bindings>
  ...
  <list id="ServiceRequeststatus" IterBinding="findAllServiceRequestIter"
        ListOperMode="0" StaticList="true" NullValueFlag="1">
    <AttrNames>
      <Item Value="status"/>
    </AttrNames>
    <ValueList>
      <Item Value="Any Status"/>
      <Item Value="Open"/>
      <Item Value="Pending"/>
      <Item Value="Closed"/>
    </ValueList>
  </list>
  ...
</bindings>

For more information about the page definition file and ADF data binding expressions, see Section 5.5, "Working with Page Definition Files" and Section 5.6, "Using ADF Databinding EL Expressions".

11.7.3 How to Create a Dropdown List with a Dynamic List of Values

Instead of getting values from a static list, you can populate a selectOneChoice component with values dynamically at runtime. The steps for creating a dropdown list bound to a dynamic list are almost the same as those for creating a dropdown list bound to a fixed list, with the exception that you define two data sources—one for the list data collection that provides the dynamic list of values, and the other for the base data collection that is to be updated based on the user's selection.

To create a dropdown list bound to a dynamic list of values using the Data Control Palette:

From the Data Control Palette, expand a business service method, and then expand a method return that returns a data collection. Next, expand an accessor return that returns a detail collection. Drag and drop the attribute you desire onto the page, and then choose Create > Single Selections > ADF Select One Choice from the context menu. The List Binding Editor displays, as illustrated in Figure 11-21.

For example, if users want to be able to pick a product before searching on service requests, you might expand findAllServiceRequest(), followed by ServiceRequest, and product. Then drag and drop the name attribute. Because you want users to be able to search service requests based on a product name, therefore you use the name attribute on the Product detail collection.

Note:
The list and base data collections do not have to form a master-detail relationship, but the items in the list data collection must be the same type as the base data collection attribute.

Figure 11-21 List Binding Editor with the Dynamic List Option Selected
In the List Binding Editor, select Dynamic List.
In the Base Data Source dropdown list, select the data collection that is to be updated with the list value selected by a user. For example, ServiceRequest: SRPublicFacade.findAllServiceRequest.product.
In the List Data Source dropdown list, select the data collection that provides the list values dynamically. For example, Product: SRPublicFacade findAllProduct.
In the mapping area, select name from Base Data Source Attribute, and name from List Data Source Attribute. This maps the list source attribute to the base source attribute you want to update.
In the List Items section, select name from the Display Attribute dropdown list. This populates the values users see in the list.

11.7.4 What Happens When You Create a Dropdown List Bound to a Dynamic List

Example 11-56 shows the code for the selectOneChoice component after you've completed the List Binding Editor.

Example 11-56 SelectOneChoice Component After You Complete Binding

<af:selectOneChoice value="#{bindings.Productname.inputValue}"
                    label="#{bindings.Productname.label}">
  <f:selectItems value="#{bindings.Productname.items}"/>
</af:selectOneChoice>

The f:selectItems tag, which provides the list of items for selection, is bound to the items property on the Productname list binding object in the binding container. For further descriptions about ADF data binding expressions, see Section 5.6, "Using ADF Databinding EL Expressions".

In the page definition file (for example, SRDemopage.xml), JDeveloper adds the list binding object definition into the bindings element, as shown in Example 11-57.

Example 11-57 List Binding Object for the Dynamic Dropdown List in the Page Definition File

<bindings>
  ...
  <list id="Productname" IterBinding="productIterator" StaticList="false"
        ListOperMode="0" ListIter="findAllProductIter"..>
    <AttrNames>
      <Item Value="name"/>
    </AttrNames>
    <ListAttrNames>
      <Item Value="name"/>
    </ListAttrNames>
    <ListDisplayAttrNames>
      <Item Value="name"/>
    </ListDisplayAttrNames>
  </list>
  ...
</bindings>

The id attribute specifies the name of the list binding object. The IterBinding attribute specifies the iterator binding object, which exposes and iterates over the collection returned by the findAllProduct() method. The AttrNames element defines the base data source attribute returned by the iterator. The ListAttrNames element defines the list data source attribute that is mapped to the base data source attribute returned by the iterator. The ListDisplayAttrNames element defines the list data source attribute that populates the values users see in the list.

For complete information about page definition files, see Section 5.5, "Working with Page Definition Files".

11.7.5 How to Use Variables with Dropdown Lists

Sometimes you might want to use a variable with a selectOneChoice component to hold the value of the item selected by a user. On the SRSkills page (as shown later in Figure 11-25), a manager selects a staff member name from the dropdown list to display the member's assigned product skills in the shuttle component. The selectOneChoice component in the SRSkills page populates a variable in the page definition file when the user makes a selection.

The following procedure shows how to manually add a variable to a page definition file.

To create a variable iterator and variable in a page definition file:

Open the page definition file (for example, <pageName>PageDef.xml) for the JSF page in which a selectOneChoice component will be used.
In the Structure window, right-click the topmost node and choose Insert inside <pageName>PageDef > executables to add the executables node, if not added already.
In the Structure window, right-click executables and choose Insert inside executables > variableIterator to add the variables node, if not added already.
In the Structure window, right-click variables and choose Insert inside variables > variable.
In the Insert Variable dialog, enter a name and type for the variable. For example, you might enter someStaffIdVar for the name, and java.lang.Integer for the type, if you want the variable to hold data about the selected staff member.

Example 11-58 shows the page definition file after you've created a variable.

Example 11-58 Variable Iterator and Variable in the Page Definition File

<?xml version="1.0" encoding="UTF-8" ?>
<pageDefinition xmlns="http://xmlns.oracle.com/adfm/uimodel"
                version="10.1.3.36.61" id="app_management_untitled4PageDef"
                Package="oracle.srdemo.view.pageDefs">
  <executables>
    <variableIterator id="variables">
      <variable Name="someStaffIdVar" Type="java.lang.Integer"/>
    </variableIterator>
  </executables>
</pageDefinition>

For more information about variable iterators and variables, see Section 5.5.2.2, "About Bindings in the executables Element".

The next procedure shows how to use the variable to create a dropdown list that lets users select a staff member's name from a dynamic list.

To create a dynamic dropdown list:

Open the JSF page in which you want to add a selectOneChoice component.
From the Data Control Palette, expand findAllStaff() > User. Drag and drop the userId attribute to the page, and then choose Create > Single Selections > ADF Select One Choice from the context menu.
In the List Binding Editor, select variables from the Base Data Source dropdown list.
Select Dynamic List.
From the List Data Source dropdown list, select User: SRPublicFacade:findAllStaff.
In the mapping area, select someStaffIdVar from the Base Data Source Attribute dropdown list, and userId from the List Data Source Attribute dropdown list.
In the List Items section, from the Display Attribute dropdown list, select Select Multiple, and add firstName and lastName to the Attributes to Display list in the Select Multiple Display Attributes dialog.
From the "No Selection" Item dropdown list, select Include Labeled Item.