Add Remove List Component Properties Window

See Also | Tutorials

You see the Properties window for an Add Remove List component  when you select the component on a page that you are editing in the Visual Designer.

This component has the following properties.

General

• id. Type: String
  The name of the component in the page bean and the JSP file. In the JSP file, this name is the value of the component's id attribute. In the page bean, this property's value is the name of the AddRemove object.
   
  

Appearance

• availableItemsLabel. Type: String
  The label of the available items list, set by default to Available.
   
  
• label. Type: String
  The label of the Add Remove List component, which displays by default at the top left, above the list labels.
  • Note: The label property is not as flexible as the Label component. You can use the Label component if you want more control over the label's appearance, such as positioning of the label relative to the component.
  
   
  
• labelOnTop. Type: boolean
  If selected, positions the component's label directly above the lists.
   
  
• movebuttons. Type: boolean
  Adds move up and move down buttons to the area between the lists.
   
  
• rows. Type: int
  Determines the number of items that display at one time in the lists. The default value is 12.
   
  
• selectAll. Type: boolean
  Adds Select All and Remove All buttons to the area between the lists.
   
  
• selectedItemsLabel. Type: String
  The label of the select items list, set by default to Selected.
   
  
• style. Type: String
  Cascading Style Sheet rules (CSS level 2) to be applied to the component. For example:
   
     position: absolute; left: 288px; top: 312px
   
  You can enter values directly or click the ellipsis (...) button to use the Style Editor.
  • Note: This property overrides any settings in the theme or the project CSS file for this component. If a style specified in this property does not appear to take effect, it is because an area of the component is obscured by a child component that has different style settings.
  
   
  For a list of CSS2 style attributes, see the web page at
  http://www.w3.org/TR/REC-CSS2/propidx.html
   
  
• styleClass. Type: String
  A space-separated list of CSS2 style classes to be applied when the component is rendered. The style classes must be defined in the project's style sheet or in the theme's CSS file. If you click the ellipsis button (...), you see a list of all styles you can add to this property. For information on adding CSS classes and rules to the project's cascading style sheet, see CSS Editor.
  • Note: See the note above under the style property description for an explanation of why a class added to this property might appear to have no effect on the component.
  • Note: If you add a CSS style class from the current theme to your project CSS file and you redefine the style class, the change affects all components that use this style class. However, you can add your own style classes to the project CSS file that redefine the default style classes, and then when you add them to this property, the changes affect only this instance of this component.

    For the defaulttheme.jar CSS style classes for this component, see Add Remove List Component CSS Classes.

  
   
  
• vertical. Type: boolean If selected, arranges the lists vertically, with the Available list on top, the buttons below it, and the Selected list below the buttons. By default, the layout is horizontal.
   
  

Data

• converter. Type: Converter
  A JavaServer Faces converter that produces the correct type of value for the selected property.
   
  
• duplicateSelections. Type: boolean
  If selected, this property enables the user to add the same item more than once to the Selected list. The change in behavior is that items added to the Selected list remain available in the Available list and can appear more than once in the Selected list.
   
  
• items. Type: Object
  Specifies the items in the Available list. Associates the Available list with an array, a collection, or a map of com.sun.rave.web.ui.model.Option objects to populate the Available list. By default, this property is associated with a com.sun.rave.web.ui.model.MultipleSelectOptionsList object with a name similar to addRemoveList1DefaultOptions, whose node you can see in the Outline window. This object serves simply to populate the list with default items and is in the page bean.
   
  For a tutorial showing how to associate a listbox with an array, see the following web page:
  Using Listbox Components
   
  
• required. Type: boolean
  If selected, the user is required to add at least one item to the Selected column before the page can be submitted. If you add a Message component to the page and link its for property to this component, an error message will be displayed if the user tries to submit the page without adding an item.
   
  If you want to use a validator with this component, you must select this property to ensure that the value is run through the validator.
   
  
• selected. Type: Object
  Associates the component with a model object that represents the items in the Selected list. The model object must be an array of objects whose values represent the values of the com.sun.rave.web.ui.model.Option objects in the Available list. See the items property for more information.
   
  
• sorted. Type: boolean
  If selected, both the Available list and the Selected list are sorted. If you have checked the moveButtons property, this property has no effect on the Selected list because the user is expected to arrange the items in that list.
   
  
• validator. Type: MethodBinding
  Indicates the JavaServer Faces validator that is called when the value is submitted. A validator ensures that the correct value is entered by a user. Choose a validator from the drop-down list. If you choose (null), no validator is called. If you choose a validator, also select the required property to ensure that the validator is used. For descriptions of JavaServer Faces validators, see the list of topics at List of Validators.
  • Note: If you define your own validate method, for example, by right-clicking the component and choosing Edit Event Handler > validate, any value you might have set in this property is overridden.
  
   
  

Events

Set the event properties by right-clicking the component in the Visual Designer and choosing Edit Event Handler > eventname.

• validate. Indicates the name of the method that is called to validate the value of the component, if any. If you want to code a validate method rather than choosing a JavaServer Faces validator for the validator property, right-click the component and choose Edit Event Handler > validate. The default name for the method is component-id_validate, where component-id is the value of the component's id property. When you define this method in this way, the validator and validate properties are automatically set for you. If you define a validator, also select the required property to ensure that the validator is used.
  • Note: Setting this property also sets the value of the validator property. If you define your own validate method, do not separately change the value of the validator property, or you will lose the connection to your validate method.
  
   
  
• valueChange. Indicates the name of the component value change listener method that is called when the value of the component changes. If this method is not defined, the value of this property is null. You typically define this method in the page bean by right-clicking the component in the Visual Designer and choosing Edit Event Handler > processValueChange. The default name for the method is component-id_processValueChange, where component-id is the value of the component's id property.
   
  

Behavior

• disabled. Type: boolean
  If selected, indicates that the component should never receive focus or be included in a submit. Use this property when the component does not apply to the page. See the note under the readOnly property concerning the effects of using the disabled property versus the effects of using the readOnly property.
   
  
• readOnly. Type: boolean
  If selected, makes it impossible for the user to select items, but still makes it possible for the component's value to be submitted. Use this property when the component does apply but must not be changed.
  • Note: A readonly field is included when the page is submitted, in contrast to a disabled field, which is not included when the page is submitted. If you use the disabled property, JavaServer Faces does not detect that any value at all was submitted.
  
   
  
• toolTip. Type: String
  Sets the HTML title attribute for the component, causing the text value of this property to display if the user hovers the mouse cursor over the component.
• visible. Type: boolean
  Indicates whether or not the component can be seen by the user on the rendered HTML page. This property is selected by default. If you deselect this property, the component's HTML code is rendered on the page, but the component is not visible in the browser because it is hidden by a style setting. Because the HTML code is rendered, the component can still be processed on form submissions, and users who view source in the browser can see the HTML code. In addition, your web application can use client-side JavaScript to show or hide the component.
  • Note: If you need to completely hide the component, for example, because it contains sensitive information that certain users should not see, deselect the rendered property.
  
   
  

Accessibility

• tabIndex. Type: String
  Optionally specifies the position of the component in the tab order of the document, determining when the component will get focus if the user tabs through the document. The value must be an integer between 0 and 32767.
   
  

Advanced

• immediate. Type: boolean
  If this property is selected, when the user activates the component, the code in the page bean is executed before the validation, updating of model values, and so on. Essentially, code execution happens right away on the server, which then returns the page. A simpler way of getting this functionality is to associate the component with a virtual form, and then right-click the component and choose Auto-submit on Change.
   
  The most common example of an immediate action is a Cancel button. You make it immediate so that the normal validation and update steps can be skipped, but the action handler can still do whatever is necessary. Typically, the action handler will navigate back to some previous page. In some designs the action handler might also enqueue an informational message like "Transaction cancelled". It is possible to do more: for example, an application might record the fact that the user cancelled the current operation.
   
  
• rendered. Type: boolean
  If selected, the component is to be rendered and processed on any subsequent page submission. If not selected, the component does not appear on the page at all, not even as a hidden component. If you need the component to be hidden but still processed when the page is submitted, deselect the visible property instead of this property.
   
  You can bind this property to a JavaBeans property that determines when the component does get rendered. For example, an airline reservation form might show a component for frequent flyers and not show it for the general public. To bind this property, click the ellipsis button (...) to the right of the property and choose Use Binding in the dialog box.
   
  
• valueChangeListener. Type: MethodBinding
  See the Event section's valueChange property above, which provides an easier way to set this property's value. The valueChangeListener property is the MethodBinding that underlies the valueChange event property. The valueChangeListener property is updated when you set the method for the valueChange event property.
   
  If you click the ellipsis button next to the valueChange property, you can use that property's property editor to choose an existing method to bind to, or you can create a new method or unbind an existing method. If you are an expert, instead of using the valueChange property, you can type a MethodBinding expression directly into this valueChangeListener property, for example, if you want to call a method that is not in the page bean.
   
  

See Also

Add Remove List Component

Working With Components

Component Tasks: Quick Reference

Tutorials

Delving Into Components Tutorial About Stylesheets and Component Layout

Using Converters Tutorial

Using Validators Tutorial

Understanding Scope and Managed Beans

Customizing Standard Validator Messages Tutorial

Creating a Custom Validator Tutorial