19.7 Creating Selection Lists

ADF Faces list components for selecting a single value from a list include selectOneRadio, 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 SRStaffSearch page uses a selectOneRadio component to let users pick the staff role to perform a search on. The list of staff roles is bound to a static list of values that is provided by the developer. In the SRCreate page, a selectOneListbox component is used to let users select an appliance from a list of values that is populated dynamically at runtime. In the SRSkills page, a selectOneChoice component is used to let users traverse through the objects in a collection. In all cases, the f:selectItems tag is used to provide the list items for display and selection.

19.7.1 How to Create a List with a Fixed List of Values

The SRStaffSearch page uses a selectOneRadio component to let users pick the staff role to perform a search on. For example, the user can refine the search on staff members who have the role of Manager or Technician. Figure 19-19 shows the Search for Staff form in the SRDemo application.

Figure 19-19 SelectOneRadio Component for Selecting a Staff Role

Staff Role list for refining search on staff

The Search for Staff form uses a query from a view object that has named bind variables to find matching objects via the ExecuteWithParams operation. For information about how to create a search form using parameters, see Section 18.4.1, "How to Create a Parameterized Search Form".

In the SRStaffSearch page definition file, as shown in Example 19-54, the variable StaffListByEmailNameRole_Role is bound to the Role named bind variable in the StaffListByEmailNameRole view object. The StaffListByEmailNameRole view object extends the StaffList view object to add the bind variables used by this search page.

The iterator StaffListByEmailNameRoleIterator iterates over the StaffListByEmailNameRole collection. The StaffListByEmailNameRoleIterator is also related to the ExecuteWithParams action, which encapsulates the details about how to invoke the action and what parameters the action is expecting. The NamedData elements show the parameters to be passed to the ExecuteWithParams action.

When the user selects a Role radio button, the selectOneRadio component in the SRStaffSearch page populates the appropriate page definition variable with the selected value.

For information about variable iterators and variables, see Section 12.5.2.2, "Binding Objects Defined in the executables Element".

Example 19-54 SRStaffSearch Page Definition File

<?xml version="1.0" encoding="UTF-8" ?>
<pageDefinition xmlns="http://xmlns.oracle.com/adfm/uimodel"
                version="10.1.3.35.83" id="app_staff_SRStaffSearchPageDef"
                Package="oracle.srdemo.view.pageDefs" ...>
  <parameters/>
  <executables>
    <iterator id="StaffListByEmailNameRoleIterator"
              Binds="StaffListByEmailNameRole"
              RangeSize="10" DataControl="SRService"/>
    <variableIterator id="variables">
      <variableUsage DataControl="SRService"
                     Binds="StaffListbyEmailNameRole.variablesMap.Role"
                     Name="StaffListByEmailNameRole_Role" IsQueriable="false"/>
      ...
      <variableUsage DataControl="SRService"
                     Binds="StaffListByEmailNameRole.variablesMap.TheFirstName"
                     Name="StaffListByEmailNameRole_TheFirstName"
                     IsQueriable="false"/>
      <variableUsage DataControl="SRService"
                     Binds="StaffListByEmailNameRole.variablesMap.TheLastName"
                     Name="StaffListByEmailNameRole_TheLastName" 
                     IsQueriable="false"/>
    </variableIterator>
    ...
  </executables>
  <bindings>
    <action id="ExecuteWithParams" IterBinding="StaffListByEmailNameRoleIterator"
            InstanceName="SRService.StaffListByEmailNameRole"
            DataControl="SRService" RequiresUpdateModel="true"
            Action="95">
      <NamedData NDName="Role" NDType="java.lang.String"
                 NDValue="${bindings.StaffListByEmailNameRole_Role}"/>
      ...
      <NamedData NDName="TheFirstName" NDType="java.lang.String"
                 NDValue="${bindings.StaffListByEmailNameRole_TheFirstName}"/>
      <NamedData NDName="TheLastName" NDType="java.lang.String"
                 NDValue="${bindings.StaffListByEmailNameRole_TheLastName}"/>
    </action>
    ...
    <attributeValues id="TheFirstName" IterBinding="variables">
      <AttrNames>
        <Item Value="StaffListByEmailNameRole_TheFirstName"/>
      </AttrNames>
    </attributeValues>
    <attributeValues id="TheLastName" IterBinding="variables">
      <AttrNames>
        <Item Value="StaffListByEmailNameRole_TheLastName"/>
      </AttrNames>
    </attributeValues>
    ...
  </bindings>
</pageDefinition>

The following procedure assumes you've already created a parameter search form that uses the ExecuteWithParams operation.

To use a variable to create a list bound to a fixed list of values:

Open the JSF page in the visual editor.
If necessary, delete the inputText component that was created for the Role field because you want to use a selection list component instead.
From the Data Control Palette, expand StaffListByEmailNameRole > Operations > ExecuteWithParams > Parameters.

StaffListByEmailNameRole is the view object that contains the Role named bind variable.
Drag and drop the Role parameter to the page, and then choose Create > Single Selections > ADF Select One Radio from the context menu. The List Binding Editor displays, as illustrated in Figure 19-20.

Figure 19-20 List Binding Editor with the Fixed List Option Selected
In the List Binding Editor, make sure variables is selected in the Base Data Source dropdown list.

Base Data Source is the target that will receive the value selected by the user at runtime.
Select the Fixed List radio button.

The Fixed List option lets users choose a value from a predefined list, which is useful when you want a data object attribute to be updated by a list of values that you code yourself, rather than getting the values from another data source.
From the Base Data Source Attribute dropdown list, select StaffListByEmailNameRole_Role.

The Base Data Source Attribute is the variable name of the target.
Enter the following in the Set of Values box, pressing Enter to set a value before typing the next value:
- Technician
- Manager
The order in which you enter the values is the order in which the list items are displayed in the selectOneRadio control at runtime.
In the List Items section, select Include Labeled Item from the "No Selection" Item dropdown list. Then enter Any in the box next to it.

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

19.7.2 What Happens When You Create a List Bound to a Fixed List of Values

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 12.2.3, "What Happens When You Use the Data Control Palette".

Example 19-55 shows the code for the selectOneRadio component after you've completed the List Binding Editor.

Example 19-55 SelectOneRadio Component After You Complete Binding

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

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

In the page definition file, JDeveloper adds the Role list binding object definition in the bindings element, as shown in Example 19-56.

Example 19-56 List Binding Object for the Fixed List in the Page Definition File

<bindings>
  ...
  <list id="Role" IterBinding="variables" ListOperMode="0" StaticList="true"
        NullValueFlag="1">
    <AttrNames>
      <Item Value="StaffListByEmailNameRole_Role"/>
    </AttrNames>
    <ValueList>
      <Item Value="Any"/>
      <Item Value="Technician"/>
      <Item Value="Manager"/>
    </ValueList>
  </list>
  ...
</bindings>

In the list element, the id attribute specifies the name of the list binding object. The IterBinding attribute references the variable iterator, whose current "row" is a row of attributes representing each variable in the binding container. The variable iterator exposes the variable values to the bindings in the same way as other collections of data. The AttrNames element specifies the attribute value returned by the iterator. The ValueList element specifies the fixed list of values to be displayed for selection.

At runtime, when a value is selected from the list, the base data source attribute StaffListByEmailNameRole_Role, which is the target of the Role list binding object, is updated to the selected value.

For more information about the page definition file and ADF data binding expressions, see Section 12.5, "Working with Page Definition Files" and Section 12.6, "Creating ADF Data Binding EL Expressions".

19.7.3 How to Create a List with a Dynamic List of Values

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

The SRCreate page, as shown in Figure 19-21, uses a selectOneListbox component to let users pick an appliance from a product list that is populated dynamically. The list data source is the ProductList collection because you want users to select an appliance (product) from the list. The base data source you want to update with the selected value is the Globals collection. The Globals view object is a transient view object, that is, one containing only transient attributes. Transient view objects are useful for holding temporary values in the data model that need to be presented on different pages of your application.

Figure 19-21 SelectOneListbox Component on the SRCreate Page

To create a list box bound to a dynamic list of values:

Open the JSF page in the visual editor.
From the Data Control Palette, drag and drop any attribute of the base data source to the page. Choose Create > Single Selections > ADF Select One Listbox from the context menu. The List Binding Editor displays, as illustrated in Figure 19-22.

For example, you might expand the Globals collection, then drag and drop the ProductId attribute to the page.

Figure 19-22 List Binding Editor with the Dynamic List Option Selected
In the List Binding Editor, the Base Data Source dropdown list should default to the collection of the attribute you dragged (for example, SRService.Globals).

The Base Data Source is the source that is to be updated with the list value selected by a user at runtime.
Select the Dynamic List radio button.

The Dynamic List option lets you specify one or more base data source attributes to be updated from another set of bound values.
Next to the List Data Source dropdown list, click Add... to select the list data source. In the Add Data Source dialog, select the collection that will provide the list of values dynamically. For example, in the Add Data Source dialog, expand SRService, and then select ProductList. Accept the default iterator name for the selected collection.

The List Data Source is the source that provides the list of values users see in the list box at runtime.

Note:
The list and base collections do not have to form a master-detail relationship, but the items in the list collection must have the same type as the base collection attributes.
In the mapping area, the default base data source attribute should be ProductId and the default list data source attribute should be ProdId, if you dragged the ProductId attribute of Globals in step 2, and selected the ProductList collection in step 5. The mapping specifies the list source attribute to the base source attribute you want to update. Click Add to add another mapping using the dropdown lists, if you wish.

For example, you might select ProductName from the Base Data Source Attribute dropdown list, and then Name from the List Data Source Attribute dropdown list
In the List Items section, select the desired attribute of the list data source from the Display Attribute dropdown list. The list data source attribute populates the list values users see at runtime.

For example, you might select Name from the Display Attribute dropdown list because you want users to select a product name from the list.

19.7.4 What Happens When You Create a List Bound to a Dynamic List of Values

Example 19-57 shows the code for the selectOneListbox component after you've completed the List Binding Editor.

Example 19-57 SelectOneListbox Component After You Complete Binding

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

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

In the page definition file, JDeveloper adds the definitions for the iterator binding objects into the executables element, and the list binding object into the bindings element, as shown in Example 19-58.

Example 19-58 List Binding Object for the Dynamic List in the Page Definition File

<executables>
  ...
  <iterator id="ProductListIterator" Binds="ProductList" RangeSize="-1"
            DataControl="SRService"/>
  <iterator id="GlobalsIterator" RangeSize="10" Binds="Globals"
            DataControl="SRService"/>
</executables>
<bindings>
  ...
  <list id="GlobalsProductId" IterBinding="GlobalsIterator" StaticList="false"
        ListOperMode="0" ListIter="ProductListIterator">
    <AttrNames>
      <Item Value="ProductId"/>
      <Item Value="ProductName"/>
    </AttrNames>
    <ListAttrNames>
      <Item Value="ProdId"/>
      <Item Value="Name"/>
    </ListAttrNames>
    <ListDisplayAttrNames>
      <Item Value="Name"/>
    </ListDisplayAttrNames>
  </list>
  ...
</bindings>

By default, JDeveloper sets the RangeSize attribute on the iterator element for the ProductList iterator binding to a value of -1, thus allowing the iterator to furnish the full list of valid products for selection. In the list element, the id attribute specifies the name of the list binding object. The IterBinding attribute references the iterator that iterates over the Globals collection. The ListIter attribute references the iterator that iterates over the ProductList collection. The AttrNames element specifies the base data source attributes returned by the base iterator. The ListAttrNames element defines the list data source attributes that are mapped to the base data source attributes. The ListDisplayAttrNames element specifies the list data source attribute that populates the values users see in the list at runtime.

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

19.7.5 How to Create a List with Navigation List Binding

The SRSkills page has a selectOneChoice component that uses navigation list binding. Navigation list binding is used to let users navigate through the objects in a collection. As the user changes the current object selection using the navigation list component, any other component that is also bound to the same collection through its attributes will display from the newly selected object. In addition, if the collection whose current row you change is the master view object instance in a data model master/detail relationship, the row set in the detail view object instance is automatically updated to show the appropriate data for the new current master row As illustrated later in Figure 19-26, when a manager selects a technician's name from the dropdown list, the shuttle component below the navigation list component is updated to show the selected technician's product skills.

The dropdown list for selecting a technician name is derived from the StaffList collection, which has a detail collection, StaffExpertiseAreas, that is created via the view link ExpertiseAreasForStaffMember.

To create a list that uses navigation list binding:

From the Data Control Palette, expand SRService. Drag and drop the desired collection to the page, and then choose Create > Navigation > ADF Navigation Lists from the context menu. The List Binding Editor displays, as illustrated in Figure 19-23.

For example, you might drop StaffList because you want users to navigate and select a technician name.

Figure 19-23 Navigation List Binding Editor
In the Display Attributes section, double-click the attributes of the StaffList collection that you don't want to be displayed in the list, moving them to the Available Attributes section.
In the Select an Iterator dropdown list, the default iterator name for the collection is shown. Accept the default or click New to create a new name for the iterator.

19.7.6 What Happens When You Create a List With Navigation List Binding

By default JDeveloper creates the list using the selectOneChoice component when you use navigation list binding.

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

Example 19-59 SelectOneChoice Component After You Complete the Binding

<af:selectOneChoice id="navList1" autoSubmit="true"
                                  value="#{bindings.StaffList.inputValue}"
                                  label="#{bindings.StaffList.label}"
  <f:selectItems value="#{bindings.StaffList.items}"/>
</af:selectOneChoice>

The f:selectItems tag provides the list of items for traversing and selecting. In the page definition file, JDeveloper adds the list binding object into the bindings element, and the iterator binding object into the executables element, as shown in Example 19-60.

Example 19-60 List Binding Object for the Navigation List in the Page Definition File

<executables>
  <iterator id="StaffListIterator" Binds="StaffList" RangeSize="10"
            DataControl="SRService"/>
  ...
</executables>
<bindings>
  <list StaticList="false" ListOperMode="1" id="StaffList"
        IterBinding="StaffListIterator">
    <AttrNames>
      <Item Value="FirstName"/>
      <Item Value="LastName"/>
    </AttrNames>
  </list>
  ...
</bindings>

In the list element, the id attribute specifies the name of the list binding object. The IterBinding attribute references the iterator that iterates over the StaffList collection. The AttrNames element specifies the attributes returned by the iterator.