19.8 Creating a Shuttle

The selectManyShuttle and selectOrderShuttle components render two list boxes, and buttons that allow the user to select multiple items from the leading (or "available") list box and move or shuttle the items over to the trailing (or "selected") list box, and vice versa. Figure 19-24 shows an example of a rendered selectManyShuttle component. You can specify any text you want for the headers that display above the list boxes.

Figure 19-24 Shuttle (SelectManyShuttle) Component

Shuttle showing available list and selected list of items

Note:

In addition to using the supplied Move and Remove buttons to shuttle items from one list to the other, you can also double-click an item in either list. Double-clicking an item in one list moves the item to the other list. For example, if you double-click an item in the leading list, the item is automatically moved to the trailing list, and vice versa.

The only difference between selectManyShuttle and selectOrderShuttle is that in the selectOrderShuttle component, the user can reorder the items in the trailing list box by using the up and down arrow buttons on the side, as shown in Figure 19-25.

Figure 19-25 Shuttle Component (SelectOrderShuttle) with Reorder Buttons

Shuttle with reorder buttons on the side

In the SRDemo application, the SRSkills page uses a selectManyShuttle component to let managers assign product skills to a technician. Figure 19-26 shows the SRSkills page created for the sample application. The leading list box on the left displays products such as washing machines and dryers; the trailing list box on the right displays the products that a technician is skilled at servicing.

Figure 19-26 SelectManyShuttle Component on the SRSkills Page

Technician skills page for assigning skills with shuttle

Only users with the manager role can access the SRSkills page. To review and change product skill assignments, a manager first selects a technician's name from the dropdown list above the shuttle component. The application then displays the technician's existing skill assignments in the trailing list (Assigned Skills).

To add new skill assignments for the selected technician, the manager selects the products from the leading list (Available Products) and then clicks the Move button.

To remove skills from the Assigned Skills list, the manager selects the products from the trailing list and then clicks the Remove button.

Below the leading and trailing lists are optional boxes for displaying a description of a product. To view a description of a product, the manager can select an item from either list box, and the application displays the product's description in the box below the list, as shown in Figure 19-27.

Figure 19-27 Shuttle Component with Descriptions Shown

Descriptions of selected items in shuttle

19.8.1 How to Create a Shuttle

Like other ADF Faces selection list components, the selectManyShuttle component can use the f:selectItems tag to provide the list of items available for display and selection in the leading list.

Before you can bind the f:selectItems tag, create a generic class that can be used by any page that requires a shuttle. In the class, declare and include getter and setter methods for the properties that describe the view object instance names that should be used for the list of all available choices (leading list or available products) and the list of selected choices (trailing list or assigned skills). Example 19-61 shows the ShuttlePageBackingBeanBase class that is created to manage the population and selection state of the shuttle component on the SRSkills page.

Example 19-61 ShuttlePageBackingBeanBase Class

package oracle.srdemo.view.util;
import java.util.List;
import javax.faces.event.ValueChangeEvent;
public class ShuttlePageBackingBeanBase {
  String allItemsIteratorName;
  String allItemsValueAttrName;
  String allItemsDisplayAttrName;
  String allItemsDescriptionAttrName;
  String selectedValuesIteratorName;
  String selectedValuesValueAttrName;
  List selectedValues;
  List allItems;
  private boolean refreshSelectedList = false;

  public void setAllItemsIteratorName(String allItemsIteratorName) {
    this.allItemsIteratorName = allItemsIteratorName;
  }
  public String getAllItemsIteratorName() {
    return allItemsIteratorName;
  }
// other getter and setter methods are omitted
  public void setSelectedValues(List selectedValues) {
    this.selectedValues = selectedValues;
  }
  public void refreshSelectedList(ValueChangeEvent event) {
      refreshSelectedList = true;
    }
  public List getSelectedValues() {
    if (selectedValues == null || refreshSelectedList) {
      selectedValues = ADFUtils.
       attributeListForIterator(selectedValuesIteratorName,
                                selectedValuesValueAttrName);
    }
    return selectedValues;
  }
  public void setAllItems(List allItems) {
    this.allItems = allItems;
  }
  public List getAllItems() {
    if (allItems == null) {
       allItems = ADFUtils.selectItemsForIterator(allItemsIteratorName, 
                                                  allItemsValueAttrName,
                                                  allItemsDisplayAttrName,
                                                  allItemsDescriptionAttrName);
    }
    return allItems;
  }
}

The getAllItems() method populates the shuttle's leading list. The getSelectedValues() method also returns a List, but the list defines the items in the shuttle's trailing list. Note that the ShuttlePageBackingBeanBase class calls several utility methods in the ADFUtils class.

The SRSkills page backing bean (backing_SRSkills), which extends the ShuttlePageBackingBeanBase class, is injected with values for several properties of the base bean. Example 19-62 shows the managed bean and managed properties configured in faces-config.xml for working with the shuttle component.

Example 19-62 Managed Bean for the Shuttle Component in the faces-config.xml File

<managed-bean>
  <managed-bean-name>backing_SRSkills</managed-bean-name>
  <managed-bean-class>oracle.srdemo.view.backing.SRSkills</managed-bean-class>
  <managed-bean-scope>request</managed-bean-scope>
  <managed-property>
    <property-name>allItemsIteratorName</property-name>
    <value>ProductListIterator</value>
  </managed-property>
  <managed-property>
    <property-name>allItemsValueAttrName</property-name>
    <value>ProdId</value>
  </managed-property>
  <managed-property>
    <property-name>allItemsDisplayAttrName</property-name>
    <value>Name</value>
  </managed-property>
  <managed-property>
    <property-name>allItemsDescriptionAttrName</property-name>
    <value>Description</value>
  </managed-property>
  <managed-property>
    <property-name>selectedValuesIteratorName</property-name>
    <value>StaffExpertiseAreasIterator</value>
  </managed-property>
  <managed-property>
    <property-name>selectedValuesValueAttrName</property-name>
    <value>ProdId</value>
  </managed-property>
</managed-bean>

The SRSkills page uses the following iterator objects:

StaffListIterator: Iterates over the StaffList collection, which provides the technician names in the dropdown list above the shuttle.
StaffExpertiseAreasIterator: Iterates over the StaffExpertiseAreas collection, which provides the list of skills assigned to a selected technician name.
ProductListIterator: Iterates over the ProductList collection, which provides the list of product names.

All the bindings of the SRSkills page are defined in the file app_management_SRSkillsPageDef.xml. Example 19-63 shows part of the page definition file for the SRSkills page.

Example 19-63 Page Definition File for the SRSkills Page

<?xml version="1.0" encoding="UTF-8" ?>
<pageDefinition xmlns="http://xmlns.oracle.com/adfm/uimodel"
                version="10.1.3.36.2" id="app_management_SRSkillsPageDef"
                Package="oracle.srdemo.view.pageDefs">
  <parameters/>
  <executables>
    <iterator id="StaffListIterator" Binds="StaffList" RangeSize="10"
              DataControl="SRService"/>
    <iterator id="StaffExpertiseAreasIterator" Binds="StaffExpertiseAreas"
              RangeSize="10" DataControl="SRService"/>
    <iterator id="ProductListIterator" Binds="ProductList" RangeSize="10"
              DataControl="SRService"/>
  </executables>
  ...
</pageDefinition>

The following procedure assumes you've already created the selectOneChoice component for selecting a technician from a dropdown list. For instructions on how to create the dropdown list, see Section 19.7.5, "How to Create a List with Navigation List Binding".

The procedure also assumes you've created the relevant iterator bindings in the page definition file (Example 19-63), a class similar to the ShuttlePageBackingBeanBase class (Example 19-61), and configured the required managed bean and managed properties in faces-config.xml (Example 19-62).

To create a shuttle component that is associated with a navigation list component:

In the JSF page that contains the navigation list component, select the selectOneChoice component. In the Property Inspector, set the Id attribute to a value (for example, technicianList), and then set the ValueChangeListener attribute to the refreshSelectedList() method in the backing_SRSkills managed bean (for example, #{backing_SRSkills.refreshSelectedList}).
From the ADF Faces Core page of the Component Palette, drag and drop SelectManyShuttle to the page. JDeveloper displays the Insert SelectManyShuttle dialog, as illustrated in Figure 19-28.

Figure 19-28 Insert SelectManyShuttle Dialog
Select Bind to list (select items) and click Bind... to open the Expression Builder.
In the Expression Builder, expand JSF Managed Beans > backing_SRSkills. Double-click allItems to build the expression #{backing_SRSkills.allItems}. Click OK.

This binds the f:selectItems tag to the getAllItems() method that populates the shuttle's leading list.
In the Insert SelectManyShuttle dialog, click Common Properties. Click Bind... next to the Value field to open the Expression Builder again.
In the Expression Builder, expand JSF Managed Beans > backing_SRSkills. Double-click selectedValues to build the expression #{backing_SRSkills.selectedValues}. Click OK.

This binds the value attribute of the selectManyShuttle component to the getSelectedValues() method that populates the shuttle's trailing list.
Close the Insert SelectManyShuttle dialog.
In the Property Inspector, set the partialTriggers attribute on the selectManyShuttle component to the Id of the selectOneChoice component (for example, technicianList) that provides the navigation dropdown list of technician names.

Example 19-64 shows the code for the selectManyShuttle component after you complete the Insert SelectManyShutle dialog.

Example 19-64 SelectManyShuttle Component in the SRSkills.jspx File

<af:selectManyShuttle value="#{backing_SRSkills.selectedValues}"
                      partialTriggers="technicianList"
                      ...
  <f:selectItems value="#{backing_SRSkills.allItems}"/>
</af:selectManyShuttle>

For more information about using the shuttle component, see the ADF Faces Core tags at

http://www.oracle.com/technology/products/jdev/htdocs/partners/addins/exchange/jsf/doc/tagdoc/core/index.html

19.8.2 What Happens at Runtime

When the SRSkills page is first accessed, the iterator StaffListIterator executes and iterates over the StaffList collection. By default, the first item displayed in the selectOneChoice component is selected because the component has a navigation list binding, whose value is always set to the current row in the iterator. The initial selection automatically drives the master-detail coordination between the StaffList and StaffExpertiseAreas collections, thus the selectManyShuttle component is updated with the selected technician's product skills in the trailing list.

When the manager selects another technician name from the navigation dropdown list, the selectOneChoice component makes the new selection the current row in the StaffList iterator. Because the selectOneChoice component is listed as a partialTriggers component on the selectManyShuttle component, the shuttle rerenders with the newly selected technician's product skills in the trailing list.

The partialTriggers attribute setting on the selectManyShuttle component causes the shuttle to redisplay with the updated values in the leading and trailing lists.

When the Save skill changes command button (see Figure 19-26) is clicked, the current technician's associated List of product IDs (that is, assigned skills) are retrieved and sent to the updateSkillsForCurrentStaff() method.

Example 19-65 shows the code for the commandButton component on the SRSkills.jspx page.

Example 19-65 CommandButton Component in the SRSkills.jspx File

<af:commandButton action="#{backing_SRSkills.onUpdateSkills}"
                  actionListener="#{bindings.
                                    updateSkillsForCurrentStaff.execute}"../>