How to Use Selection Components

Using Input Components and Defining Forms 9-25 – When the selectManyChoice component renders, nothing displays in the field, as there has not yet been a selection. – When user clicks drop down, all items are shown. – When user selects items, the corresponding labels for the selected selectItem components are shown in field. – When page is submitted, values are posted back to the model. ■ Subsequent visit: The selectManyChoice and all selectItem components are built again as the page is rendered. Labels for selected selectItem components are displayed in field. This will cause the same performance issues as on the first visit to the page. When the contentDelivery attribute on the selectManyChoice component is set to lazy, the following happens: ■ First visit to the page: – The selectManyChoice is built as the page is rendered, but the selectItem components are not. – When the selectManyChoice component renders, nothing displays in the field, as there has not yet been a selection. – When user clicks drop down, the selectItem components are built. While this is happening, the user sees a busy spinner. Once the components are built, all items are shown. – When user selects items, the corresponding labels for the selected selectItem components are shown in field. – When page is submitted, values are posted back to the model. ■ Subsequent visit: – When page is first rendered, only the selectManyChoice component is built. At this point, the value of the lazySelectedLabel attribute is used to display the selected items. – If user clicks drop down, the selectItem components are built. While this is happening, the user sees a busy spinner. Once the components are built, all items are shown. Once the selectItem components are built, the selectManyChoice component will act as though its contentDelivery attribute is set to immediate, and use the actual value of the selectItem components to display the selected items. Following are limitations for using lazy content delivery for the selectManyChoice component: ■ You cannot store the value of the selectManyChoice is in Request scope. On postback, the value attribute is accessed from the model, rather than decoding what was returned from the client. If the value is stored in Request scope, that value will be empty. Do not store the value in Request scope. ■ On postbacks, converters are not called. If you are relying on converters for postbacks, then you should not use lazy content delivery. ■ The contentDelivery attribute is ignored when in screen reader mode. The selectItem components will always be built when the page is rendered. 9-26 Web User Interface Developers Guide for Oracle Application Development Framework

9.7 Using Shuttle Components

The selectManyShuttle and selectOrderShuttle components present the user with two list boxes and buttons to move or shuttle items from one list box to the other. The user can select a single item or multiple items to shuttle between the leading Available values list box and the trailing Selected values list box. For either component, if you want the label to appear above the control, place them in a panelFormLayout component. The selectManyShuttle component is shown in Figure 9–26 . Figure 9–26 selectManyShuttle component The selectOrderShuttle component additionally includes up and down arrow buttons that the user can use to reorder values in the Selected values list box, as shown in Figure 9–27 . When the list is reordered, a ValueChangeEvent event is delivered. If you set the readOnly attribute to true, ensure the values to be reordered are selected values that will be displayed in the trailing list Selected values . Figure 9–27 selectOrderShuttle Component The value attribute of these components, like any other selectMany component, must be a List or an Array of values that correspond to a value of one of the contained selectItem components. If a value of one of the selectItems is in the List or Array, that item will appear in the trailing list. You can convert a selectManyListbox component directly into a selectManyShuttle; instead of the value driving which items are selected in the listbox, it affects which items appear in the trailing list of the selectOrderShuttle component. Similar to other select components, the List or Array of items are composed of selectItem components nested within the selectManyShuttle or selectOrderShuttle component. Example 9–5 shows a sample selectOrderShuttle component that allows the user to select the top five file types from a list of file types. Example 9–5 selectOrderShuttle JSF Page Code af:selectOrderShuttle value={helpBean.topFive} Using Input Components and Defining Forms 9-27 leadingHeader={explorerBundle[help.availableFileTypes]} trailingHeader={explorerBundle[help.top5]} simple=true af:selectItem label=XLS af:selectItem label=DOC af:selectItem label=PPT af:selectItem label=PDF af:selectItem label=Java af:selectItem label=JWS af:selectItem label=TXT af:selectItem label=HTML af:selectItem label=XML af:selectItem label=JS af:selectItem label=PNG af:selectItem label=BMP af:selectItem label=GIF af:selectItem label=CSS af:selectItem label=JPR af:selectItem label=JSPX f:validator validatorId=shuttle-validator af:selectOrderShuttle If you set the reorderOnly attribute of a selectOrdershuttle component to true, the shuttle function will be disabled, and only the Selected Values listbox appears. The user can only reorder the items in the listbox, as shown in Figure 9–28 . Figure 9–28 selectOrderShuttle Component in Reorder-Only Mode

9.7.1 How to Add a selectManyShuttle or selectOrderShuttle Component

The procedures for adding shuttle components are the same for both components. First you add the selection component and configure its attributes. Then you add any number of selectItem components for the individual items in the list, and configure those. To add a selectManyShuttle or selectOrderShuttle component: 1. In the Component Palette, from the Common Components panel, drag and drop a Select Many Shuttle or Select Order Shuttle from the Component Palette onto the page. 2. A dialog appears where you choose either to bind to a value in a managed bean, or to create a static list. On the second page of the dialog, you can set the following: ■ Label : Enter the label for the list. ■ RequiredMessageDetail : Enter the message that should be displayed if a selection is not made by the user. For more information about messages, see Section 17.3, Displaying Hints and Error Messages for Validation and Conversion. 9-28 Web User Interface Developers Guide for Oracle Application Development Framework ■ Size : Specify the display size number of items of the lists. The size specified must be between 10 and 20 items. If the attribute is not set or has a value less than 10, the size would have a default or minimum value of 10. If the attribute value specified is more than 20 items, the size would have the maximum value of 20. ■ Validator : Enter an EL expression that resolves to a validation method on a managed bean. ■ Value : Specify the value of the component. If the EL binding for the value points to a bean property with a get method but no set method, the component will be rendered in read-only mode. ■ ValueChangeListener : Enter an EL expression that resolves to a listener on a managed bean that handles value change events. 3. In the Property Inspector, expand the Appearance section and set the following: ■ Layout : Specify whether the component will be in horizontal or vertical layout. The default is horizontal, meaning the leading and trailing list boxes are displayed next to each other. When set to vertical, the leading list box is displayed above the trailing list box. ■ LeadingHeader : Specify the header text of the leading list of the shuttle component. ■ LeadingDescShown : Set to true to display a description of the selected item at the bottom of the leading list box. ■ TrailingHeader : Specify the header of the trailing list of the shuttle component. ■ TrailingDescShown : Set to true to display a description of the selected item at the bottom of the trailing list box. 4. Expand the Behavior section and optionally set the following attributes: ■ ValuePassThru : Specify whether or not the values are passed through to the client. When valuePassThru is false, the value and the options values are converted to indexes before being sent to the client. Therefore, when valuePassThru is false, there is no need to write your own converter when you are using custom objects as your values, options, or both. If you need to know the actual values on the client-side, then you can set valuePassThru to true. This will pass the values through to the client, using your custom converter if it is available; a custom converter is needed if you are using custom objects. The default is false. ■ ReorderOnly selectOrderShuttle component only: Specify whether or not the shuttle component is in reorder-only mode, where the user can reorder the list of values, but cannot add or remove them. 5. In the Structure window, select one of the selectItem components, and in the Property Inspector, set any needed attributes.

9.7.2 What You May Need to Know About Using a Client Listener for Selection Events

You can provide the user with information about each selected item before the user shuttles it from one list to another list by creating JavaScript code to perform Tip: If you elected to have the leading or trailing list box display a description, you must set a value for the shortDesc attribute for each selectItem component. Using Input Components and Defining Forms 9-29 processing in response to the event of selecting an item. For example, your code can obtain additional information about that item, then display it as a popup to help the user make the choice of whether to shuttle the item or not. Figure 9–29 shows a selectManyShuttle component in which the user selects Meyers and a popup provides additional information about this selection. Figure 9–29 selectManyShuttle with selectionListener You implement this feature by adding a client listener to the selectManyShuttle or selectOrderShuttle component and then create a JavaScript method to process this event. The JavaScript code is executed when a user selects an item from the lists. For more information about using client listeners for events, see Section 3.2, Listening for Client Events. How to add a client listener to a shuttle component to handle a selection event: 1. In the Component Palette, from the Operations panel, drag a Client Listener and drop it as a child to the shuttle component.

2. In the Insert Client Listener dialog, enter a function name in the Method field you

will implement this function in the next step, and select propertyChange from the Type dropdown. If for example, you entered showDetails as the function, JDeveloper would enter the code shown in bold in Example 9–6 . Example 9–6 Using a clientListener to Register a Selection af:selectManyShuttle value={demoInput.manyListValue1} valuePassThru=true ... af:clientListener type=propertyChange method=showDetails af:selectItem label=coffee value=bean ... af:selectManyShuttle This code causes the showDetails function to be called any time the property value changes. 3. In your JavaScript, implement the function entered in the last step. This function should do the following: ■ Get the shuttle component by getting the source of the event. ■ Use the client JavaScript API calls to get information about the selected items. In Example 9–7 , AdfShuttleUtils.getLastSelectionChange is called to get the value of the last selected item Example 9–7 Sample JavaScript methods showDetails used to process a selection function showDetailsevent