Add Remove List Component

See Also | Tutorials

You can drag the Add Remove List component  from the Palette's Composite category to the Visual Designer to create a component that enables the user to select items from a list of items, and then add them to or remove them from another list of items.

This component is composed of two listboxes, one for available options and one for selected options, together with buttons to move the options between the lists. Optionally, you can add buttons to order the selected options.

In the Add Remove component properties window, you can set the component's properties.

Here are some things you can do with the component:

• Use the items property to specify the options from which the web application user can choose. See Bind to Data below.
   
  
• Use the selected property to associate the component with a model object that represents the current choice, by setting the value to an expression that corresponds to a property of a managed bean. You can right-click the component and choose Property Bindings to bind the selected property.
   
  The first time the component is rendered, the option that corresponds to the value of the selected model object property is marked as selected by using the equals method on the model object.
   
  
• To optionally specify a label for the component, either set the label property or associate a Label component with the component.
   
  
• Right-click the component and choose one of the following pop-up menu items:
  • Edit Event Handler. Write code for one of the following event handlers.
    • validate. Opens the Java Editor with the cursor positioned in the component's validate method so you can insert code to validate the value of the component.
       
      
    • processValueChange. Opens the Java Editor with the cursor positioned in the component's processValueChange method so you can insert code that executes when the value of this component changes. For example, the user changes the value of another component that is controlling the value of this component.
       
      
    
     
    
  • Set Initial Focus. Gives this component focus when the user opens the page.
     
    
  • Auto-submit on Change. Causes the form to be automatically submitted if the value of the component changes. Sets the component's JavaScript onclick property to common_timeoutSubmitForm(this.form, 'component-id');. At runtime, this code causes the form to be automatically submitted if the user changes the component value. Once the form is submitted, conversion and validation occur on the server and any value change listener methods execute, and then the page is redisplayed.
     
    A component configured to Auto-submit on Change can use virtual forms to limit the input fields that are processed when the form is submitted. If the auto-submit component is defined to submit a virtual form, only the participants in that virtual form will be processed when the auto-submit occurs.
     
    
  • Bind to Data. Bind the component's items property to an object or to a data provider for a database table, web service, or Enterprise JavaBeans object.
    • To bind the items property to an object, select the Bind to Object tab and then select a bean property that will be used to populate the list. The bean property must be an Object array, map, or collection whose members are all subclasses of com.sun.rave.web.ui.model.Option. For a tutorial showing how to associate a listbox with an array, which is similar to associating a checkbox group with an array, see the following web page:
      Using Listbox Components
       
      
    • To bind the items property to a data provider that will be used to populate the list, select the Bind to Data Provider tab and choose a data provider. If there are none, you must add a database table, web service, or Enterprise JavaBeans object to the page. For more information, see Bind to Data Dialog Box: List Component.
       
      
    
     
    
  • Property Bindings. Bind the component's properties to an object or data provider. A typical property to bind is the selected property, which you can bind to an Object array, array of primitives, or ArrayList. You must have added the array to a managed bean, such as the session bean, as a property. You can use this bean property to evaluate what the user chose after the page is submitted.
     
    
  • Configure Default Options. Enables you to edit the default addRemoveList#defaultOptions object and change the displayed list items. It is more likely that you will want to bind the items property to a database or object to use to set list items, as described above under Bind to Data.
     
    
  • Configure Virtual Forms. Enables you to add the component to a virtual form.
     
    
  
   
  

• The Javadoc and code completion for the Add Remove List component show a getSelectedItems() method, which returns an Iterator. Do not use this method, as it is intended for internal rendering purposes only and does not reflect the actual selected items.
   
  

See Also

Binding Component Properties

Working With Components

Component Tasks: Quick Reference

Component Web Tutorials

Data Source Web Tutorials

About the Palette

Tutorials

Using Listbox Components Tutorial

Delving Into Components Tutorial

Using Virtual Forms