Oracle® Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework 11g Release 1 (11.1.1) B31974-03 |
|
![]() Previous |
![]() Next |
This chapter describes how to add selection lists and shuttle components to pages.
This chapter includes the following sections:
Selection lists and shuttles work the same way as do 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.
List of values (LOV) are UI components that allow the user to enter values by picking from a list that is generated by a query. The LOV displays inside a modal popup dialog that typically includes search capabilities. The af:inputListOfValues
and af:inputComboboxListOfValues
components, for example, offer additional features that are not available in selection lists, such as search fields inside the LOV modal dialog and queries based on multiple table columns. For more information, see Section G.2.6, "How to Create a Popup List of Values" and the Oracle Fusion Middleware Web User Interface Developer's Guide for Oracle Application Development Framework.
ADF Faces Core includes components for selecting a single value and multiple values from a list. Single selection lists are described in Table 24-1.
Table 24-1 ADF Faces Single and Multiple List Components
ADF Faces component | Description | Example |
---|---|---|
Select a single value from a list of items. |
![]() |
|
Select a single value from a set of radio buttons. |
![]() |
|
Select a single value from a scrollable list of items. |
|
|
Select multiple values from a scrollable list of checkboxes. Each selection displays at the top of the list. |
![]() |
|
Select multiple values from a group of checkboxes. |
|
|
Select multiple values from a scrollable list of checkboxes, |
|
You can create selection lists using the SelectOneChoice
ADF Faces component. The steps are similar for creating other single value selection lists, such as SelectOneRadio
and SelectOneListbox
. As shown Figure 24-1, the Fusion Order Demo application home page uses a SelectOneChoice
component that allows a user to choose item quantities when adding a selected item to the shopping cart region.
The SelectOneChoice
component is located on the embeddedCartSummary.jsff
page fragment. The page fragment is a view activity on the embeddedCartSummary-task-flow
bounded task flow, which is added to the home page as an ADF region.
A databound selection list displays values from a data control collection or a static list and updates an attribute in another collection or a method parameter based on the user's selection. When adding a binding to a list, you use an attribute from the data control that will be populated by the selected value in the list.
Note: Using an ADF Model list binding with thevaluePassThru=true on a selectOneChoice component is not supported. The list binding will return indexes, not values. |
To create a selection list, you choose a base data source and a list data source in the Edit List Binding editor:
Base data source: Contains the data that will be updated when the end user selects a value in the list. For example, selecting a number in the SelectOneChoice
list in the shopping cart updates the OrderItems
data collection.
List data source: Contains the data used to populate the list. For example, the quantities attribute of the ProductQuantities
view supplies the values that display in the list shown in Figure 24-1.
ProductQuantities
is a view collection object that contains the Quantity
, QuantityonHand
, and Product_Id
attributes. The view collection object was created based on attributes in the WarehouseStockLevels
and Orders
data collections. For more information about creating a view object, see Section 5.2.1, "How to Create an Entity-Based View Object".
You can create three types of selection lists in the Edit List Binding dialog:
Model-driven list: List selections are based on a list of values bound to a data collection. This type of selection list offers significant advantages over the other two, as described in Section 24.2.2, "How to Create a Model-Driven List".
Static list: List selections are based on a fixed list that you create a manually by entering values one at a time into the editor. For more information, see Section 24.2.3, "How to Create a Selection List Containing Fixed Values".
Dynamic list: List selections are generated dynamically based on one or more databound attribute values. For more information, see Section 24.2.4, "How to Create a Selection List Containing Dynamically Generated Values".
A model-driven list is based on a list of values that is bound to a view data object. Lists of Values are typically used in forms to enable an end user to select an attribute value from a dropdown list instead of having to enter it manually. When the user submits the form with the selected values, ADF data bindings in the ADF Model layer update the value on the view object attributes corresponding to the databound fields.
Note: One way to create a model-driven list is to drag a collection from the Data Controls Panel onto a JSF page, choose one of the ADF Forms in the popup menu, and accept the defaults. The advantage is that if there are LOVs defined on the underlying view object attributes, all the LOVs on the entire form will be configured automatically. For more information, see Section 5.12.1, "How to Define a Single LOV-Enabled View Object Attribute". |
You can also use the list of values as the basis for creating a selection list. The advantages of creating a model-driven list based on a list of values are:
Reuse: The list of values is bound to a view data collection. Any selection list that you create based on the data collection can use the same List of Values. Because you define the LOV on the individual attributes of Business Components, you can customize the LOV usage for an attribute once and expect to see the changes anywhere that the business component is used in the user interface.
Translation: Values in the list of values can be included in resource bundles used for translation.
Before you can create the selection list,
Create a list of values that is bound to an attribute on the base data source for the selection list. For example, you can create a list of values bound to the CountryId attribute of the Addresses view data object.
The procedure for creating a list of values is:
Create a view object.
Create a view accessor on the object.
Create a list of values on an attribute of the view object.
This procedure is described in detail in Section 5.12.1, "How to Define a Single LOV-Enabled View Object Attribute".
To create a model-driven selection list:
In the editor, open the JSF page where you plan to add the selection list.
In the Data Controls Panel, expand the view object collection that will be the base data source.
This is the data collection that contains the attribute which created the list of values according to the steps in Section 5.12.1, "How to Define a Single LOV-Enabled View Object Attribute". In the Fusion Order Demo application, for example, you could select the Addresses
view object collection as the base data source.
In the Data Controls Panel, select the attribute under the view object collection, for example, CountryId
.
Drag the attribute from the Data Controls Panel and drop it on the JSF page.
Choose Create > Single Selections > ADF Select One Choice.
The Edit List Binding dialog displays. The view object collection containing the attribute you dropped on the JSF page is selected by default in the Base Data Source list.
To select a different view data collection, click the Add icon next to the list.
Select the Model Driven List radio button.
In the Base Data Source Attribute list, select an attribute on which you based a List of Values, for example, CountryId
.
The list contains all the attributes for the view data collection selected in the Base Data Source list. For example, if you selected Addresses
as the base data source, you could select as its CountryId
attribute.
If a list of values was created for the attribute you selected, it will be listed in the Server List Binding Name list.
For example, you could select LOV_CountryId
in the Server List Binding Name list because a list of values was created for the CountryId
attribute.
Click OK.
You can create a selection list containing selections that you code yourself, rather than retrieving the values from another data source. See Section 24.2.4, "How to Create a Selection List Containing Dynamically Generated Values" for information about populating selection lists with values that are dynamically generated from another data source.
To create a list bound to a fixed list of values:
In the editor, open the JSF page where you plan to add the selection list.
In the Data Controls Panel, expand the view object collection that will be the base data source.
This data is updated when the end user selects a value in the selection list. In the Fusion Order Demo application, for example, you could select the CountryCodes
view object collection as the base data source.
In the Data Controls Panel, select an attribute under the view object collection, for example, CountryName
.
Drag the attribute from the Data Controls Panel and drop it on the JSF page.
Choose Create > Single Selections > ADF Select One Choice.
The Edit List Binding dialog displays. The view object collection containing the attribute you dropped on the JSF page is selected by default in the Base Data Source list.
To select a different view data collection, click the Add icon next to the list.
Select the Fixed List radio button.
The Fixed List option lets end users choose a value from a static list that you define.
In the Base Data Source Attribute list, choose an attribute.
The Base Data Source Attribute list contains all of the attributes in the view data collection you selected in the Base Data Source list. For example, if you selected CountryCodes
as the Base Data Source, you can choose CountryName
in the list.
In the Set of Values box, enter each value you want to appear in the list. Press the 'Enter key to set a value before typing the next value. For example, you could add the country codes India, Japan, and Russia.
The order in which you enter the values is the order in which the list items are displayed in the SelectOneRadio
control at runtime.
The SelectOneRadio
component supports a null
value. 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.
Click OK.
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.
Tip: Another option is to create a static view object or a database view object within a shared application module. Then use a model- driven LOV to create the list. This provides caching and translatability. |
To create a selection list bound containing dynamically generated values:
In the editor, open the JSF page where you plan to add the selection list.
In the Data Controls Panel, expand the view object collection that will be the base data source.
This data is updated when the end user selects a value in the selection list. In the Fusion Order Demo application, for example, you could select the OrderItems v
iew object collection as the base data source.
In the Data Controls Panel, select an attribute under the view object collection, for example, Quantities
.
Drag the attribute from the Data Controls Panel and drop it on the JSF page.
Choose Create > Single Selections > ADF Select One Choice.
The Edit List Binding dialog displays. The view object collection containing the attribute you dropped on the JSF page is selected by default in the Base Data Source list.
To select a different view data collection, click the Add icon next to the list.
Select the Dynamic List radio button.
The Dynamic List option lets you specify one or more base data source attributes that will be updated from another set of bound values.
Click the Add button next to List Data Source.
In the Add Data Source dialog, select the view data collection that will populate the values in the selection list.
In the Fusion Order Demo application, for example, you could select ProductQuantities
.
Note: The list and base collections do not have to form a master-detail relationship, but the attribute in the list collection must have the same type as the base collection attributes. |
Accept the default Iterator Name and click OK.
The Data Mapping section of the Edit List Binding dialog updates with a default Data Value and List Attribute. The Data Value control contains the attribute on the data collection that is updated when the user selects an item in the selection list. The List Attribute contains the attribute that populates the values in the selection list.
You can accept the default mapping or select different attributes items from the Data Value and List Attribute lists to update the mapping.
To add a second mapping, click Add.
Click OK.
When you drag and drop an attribute from the Data Controls Panel, JDeveloper does many things for you. For a full description of what happens and what is created when you use the Data Controls Panel, see Section 21.2.2, "What Happens When You Create a Text Field".
Example 24-1 shows the page source code after you add a model-driven SelectOneChoice
component to it.
Example 24-1 Model-Driven SelectOneChoice List in JSF Page Source Code
<af:selectOneChoice value="#{bindings.CountryId1.inputValue}" label="#{bindings.CountryId1.label}"> <f:selectItems value="#{bindings.CountryId1.items}"/> </af:selectOneChoice>
The f:selectItems
tag, which provides the list of items for selection, is bound to the items
property on the CountryId1
list binding object in the binding container. For more information about ADF data binding expressions, see Section 12.7, "Creating ADF Data Binding EL Expressions".
In the page definition file, JDeveloper adds the list binding object definitions in the bindings element, as shown in Example 24-2.
Example 24-2 List Binding Object for the Model-Driven List in the Page Definition File
<bindings> <list IterBinding="AddressesView1Iterator" id="CountryId" Uses="LOV_AddressId" StaticList="false" ListOperMode="0"> <AttrNames> <Item Value="AddressId"/> </AttrNames> </list> <list IterBinding="AddressesView1Iterator" id="CountryId1" Uses="LOV_CountryId" StaticList="false" ListOperMode="0"> <AttrNames> <Item Value="CountryId"/> </AttrNames> </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 do other collections of data. The AttrNames
element specifies the attribute value returned by the iterator.
For more information about the page definition file and ADF data binding expressions, see Section 12.6, "Working with Page Definition Files"and Section 12.7, "Creating ADF Data Binding EL Expressions".
Example 24-3 shows the page source code after you add a fixed SelectOneChoice
component to it.
Example 24-3 Fixed SelectOneChoice List in JSF Page Source Code
<af:selectOneChoice value="#{bindings.CountryId.inputValue}" label="#{bindings.CountryId.label}"> <f:selectItems value="#{bindings.CountryId.items}"/> </af:selectOneChoice>
The f:selectItems
tag, which provides the list of items for selection, is bound to the items
property on the CountryId
list binding object in the binding container. For more information about ADF data binding expressions, see Section 12.7, "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 24-4.
Example 24-4 List Binding Object for the Fixed Selection List in the Page Definition File
<executables> <iterator Binds="Addresses1" RangeSize="10" DataControl="StoreFrontModuleDataControl" id="Addresses1Iterator"/> </executables> <bindings> <list IterBinding="Addresses1Iterator" id="CountryId" ListOperMode="0" StaticList="true"> <AttrNames> <Item Value="CountryId"/> </AttrNames> <ValueList> <Item Value="India"/> <Item Value="Japan"/> <Item Value="Russia"/> </ValueList> </list> </bindings>
For complete information about page definition files, see Section 12.6, "Working with Page Definition Files".
Once you have created a list binding, you may want to access a value in the list. If you attempt to get the value of the list binding directly using an EL expression, for example, #{bindings.deptList.inputValue}
, the expression returns an index number that specifies the position of the selected item in the list, not the value of the selected item.
Example 24-5 shows the page source code after you add a dynamic SelectOneChoice
component to it.
Example 24-5 Dynamic SelectOneChoice List in JSF Page Source Code
<af:selectOneChoice value="#{bindings.Quantity.inputValue}" label="#{bindings.Quantity.label}"> <f:selectItems value="#{bindings.Quantity.items}"/> </af:selectOneChoice>
The f:selectItems
tag, which provides the list of items for selection, is bound to the items
property on the Quantity
list binding object in the binding container. For more information about ADF data binding expressions, see Section 12.7, "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 Figure 24-3.
Example 24-6 List Binding Object for the Dynamic Selection List in the Page Definition File
<executables> <iterator Binds="OrderItems" RangeSize="-1" DataControl="StoreFrontModuleDataControl1" id="OrderItemsIterator"/> <iterator Binds="ProductQuantities" RangeSize="10" DataControl="StoreFrontModuleDataControl1" id="ProductQuantitiesIterator"/> </executables> <bindings> <list IterBinding="AddressesView1Iterator" id="CountryId" Uses="LOV_AddressId" StaticList="false" ListOperMode="0"> <AttrNames> <Item Value="AddressId"/> </AttrNames> </list> <list IterBinding="ProductQuantities1Iterator" id="Quantity" StaticList="false" ListOperMode="0" ListIter="OrderItems1Iterator"> <AttrNames> <Item Value="Quantity"/> </AttrNames> <ListAttrNames> <Item Value="Quantity"/> </ListAttrNames> <ListDisplayAttrNames> <Item Value="OrderId"/> </ListDisplayAttrNames> </list> </bindings>
By default, JDeveloper sets the RangeSize
attribute on the iterator
element for the OrderItems
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 ProductQuantities
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.6, "Working with Page Definition Files".
Navigation list binding lets 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.
To create a list that uses navigation list binding:
In Data Controls Panel, expand a project node, for example, the StoreFrontAMDataControl
.
Drag and drop the collection to the page and choose Create > Navigation > ADF Navigation Lists. The Edit List Binding dialog displays.
In the Display Attributes section, double-click the attributes of the collection that you don't want to be displayed in the list, moving them to the Available Attributes section.
In the Base Data Source dropdown list, the default iterator name for the collection is shown. Accept the default or click Add to create a new name for the iterator.
Click OK.
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 24-3 shows an example of a rendered selectManyShuttle
component. You can specify any text you want for the headers that display above the list boxes.
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 noted in the sample application, the Fusion Order Demo application uses a selectManyShuttle
component to select customer interest categories from a Categories of Interest list box to an I am interested in list box. The leading list box on the left displays all the categories. The trailing list box on the right displays the categories the customer has selected.
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 product categories) and the list of selected choices (trailing list or assigned product categories). Example 24-7 shows the CustRegBasicInformationBean
class that is created to manage the population and selection state of the shuttle component on the basicInformation.jsff
page.
Example 24-7 CustRegBasicInformationBean Class
package oracle.fodemo.storefront.account.view.managed; import java.io.Serializable; import java.util.List; import javax.faces.application.FacesMessage; import javax.faces.context.FacesContext; import oracle.binding.OperationBinding; import oracle.binding.BindingContainer; import oracle.fodemo.storefront.adf.util.ADFUtils; import javax.faces.event.ValueChangeEvent; import oracle.fodemo.storefront.jsf.util.JSFUtils; public class CustRegBasicInformationBean implements Serializable { String allItemsIteratorName; String allItemsValueAttrName; String allItemsDisplayAttrName; String allItemsDescriptionAttrName; String selectedValuesIteratorName; String selectedValuesValueAttrName; List selectedValues; List allItems; private boolean refreshSelectedList = false; public CustRegBasicInformationBean() { } 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 CustRegBasicInformationBean class calls several utility methods in the ADFUtils
class. Also note that this class is injected with values for several properties of the base bean. Example 24-8 shows the managed bean and managed properties configured in customer-registration-task-flow.xml
for working with the shuttle component.
Example 24-8 Managed Bean for the Shuttle Component in the customer-registration-task-flow File
<managed-bean> <managed-bean-name> custRegBasicInformationBean</managed-bean-name> <managed-bean-class> oracle.fodemo.storefront.account.view.managed.CustRegBasicInformationBean </managed-bean-class> <managed-bean-scope>view</managed-bean-scope> <managed-property> <property-name>allItemsIteratorName</property-name> <value>AvailableCategoriesShuttleListIterator</value> </managed-property> <managed-property> <property-name>allItemsValueAttrName</property-name> <value>CategoryId</value> </managed-property> <managed-property> <property-name>allItemsDisplayAttrName</property-name> <value>CategoryName</value> </managed-property> <managed-property> <property-name>allItemsDescriptionAttrName</property-name> <value>CategoryDescription</value> </managed-property> <managed-property> <property-name>selectedValuesIteratorName</property-name> <value>SelectedCategoriesShuttleListIterator</value> </managed-property> <managed-property> <property-name>selectedValuesValueAttrName</property-name> <value>CategoryId</value> </managed-property> </managed-bean>
The basicInformation.jsff
page uses the following iterator objects:
CustomerRegistrationIterator
: Iterates over the CustomerRegistration
collection, which provides the context for the form above the shuttle.
SelectedCategoriesShuttleListIterator
: Iterates over the SelectedCategoriesShuttleList
collection, which provides the list of categories assigned to the current customer.
AvailableCategoriesShuttleListIterator
: Iterates over the AvailableCategoriesShuttleList
collection, which provides the list of product categories.
All the bindings of the basicInformation.jsff
page are defined in the file account_basicInformationPageDef.xml
. Example 24-9 shows part of the page definition file for the basicInformation.jsff
page.
Example 24-9 Page Definition File for the basicInformation Page
<?xml version="1.0" encoding="UTF-8" ?> <pageDefinition xmlns="http://xmlns.oracle.com/adfm/uimodel" version="11.1.1.48.68" id="account_basicInformationPageDef" Package="oracle.fodemo.storefront.pageDefs"> <parameters/> <executables> <page path="oracle.fodemo.storefront.pageDefs. templates_StoreFrontTemplatePageDef" id="pageTemplateBinding"/> <iterator Binds="CustomerRegistration" RangeSize="25" DataControl="StoreServiceAMDataControl" id="CustomerRegistrationIterator" Refresh="ifNeeded"/> <iterator id="SelectedCategoriesShuttleListIterator" Binds="SelectedCategoriesShuttleList" RangeSize="-1" DataControl="StoreServiceAMDataControl"/> <iterator id="AvailableCategoriesShuttleListIterator" Binds="AvailableCategoriesShuttleList" RangeSize="-1" DataControl="StoreServiceAMDataControl"/> <invokeAction Binds="setHelpId" id="invokeSetHelpId" Refresh="ifNeeded"/> </executables>
The following procedure assumes you've created the relevant iterator bindings in the page definition file (Example 24-9), a class similar to the CustRegBasicInformationBean class (Example 24-7), and configured the required managed bean and managed properties in the task flow definition or in the case of an unbounded task flow, the adfc-config.xml
(Example 24-8).
To create a shuttle component:
On the ADF Faces page of the Component Palette, drag and drop SelectManyShuttle to the page. JDeveloper displays the Insert SelectManyShuttle wizard, as illustrated in Figure 24-5.
Select Bind to list (select items) and click Bind to open the Expression Builder.
In the Expression Builder, expand ADF Managed Beans > pageFlowScope > CustRegBasicInformationBean > allItems to build the expression #{pageFlowScope.custRegBasicInformationBean.allItems}
and click Next.
This binds the f:selectItems
tag to the getAllItems()
method that populates the shuttle's leading list.
In the Common Properties page, click Bind next to the Value field to open the Expression Builder again.
In the Expression Builder, expand ADF Managed Beans > pageFlowScope > CustRegBasicInformationBean > selectedValues to build the expression #{pageFlowScope.custRegBasicInformationBean.selectedValues}
and click Finish.
This binds the value
attribute of the selectManyShuttle
component to the getSelectedValues()
method that populates the shuttle's trailing list.
Example 24-10 shows the code for the selectManyShuttle
component after you complete the Insert SelectManyShuttle dialog.
Example 24-10 SelectManyShuttle Component in basicInformation.jsff File
<af:selectManyShuttle value="#{pageFlowScope.custRegBasicInformationBean.selectedValues}" leadingHeader="#{res['basicinfo.leadingHeader']}" trailingHeader="#{res['basicinfo.trailingHeader']}" leadingDescShown="true" size="8" trailingDescShown="true" inlineStyle="background-color:transparent;" id="sms1"> <f:selectItems value="#{pageFlowScope.custRegBasicInformationBean.allItems}"/> </af:selectManyShuttle>