Listbox Component

See Also | Tutorials

You can drag the Listbox component  from the Palette's Basic category to the Visual Designer to create a component that enables the user to select items from a list of items. If the box is too small to contain the items in the list, the list box includes scrollbars.

By default, only one item can be selected in the list. The multiple property determines whether one item or multiple items can be selected by the user.

You can set the items property to associate the component either with a database table or with an array, a collection, or a map of com.sun.rave.web.ui.model.Option objects to populate the list. Right-click the component and choose Bind to Data to set this property. In the Outline window, you can see the default object that populates the list, which has a name similar to listbox1DefaultOptions.

You set the selected property to associate the component with a model object that picks up the list items selected by the user. 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 list. The first time the component is rendered, the options that correspond to the value of the selected property, if there are any, are marked as selected.

After adding a Listbox Component to a page, you can do a number of things with it:

• Drag a table from the Servers window and drop it on the component, and then choose whether to fill the list with the table data or set the component up to have its selection driven by another component. For more information, see Binding a List Component to a Database.
   
  
• Select the component and edit its properties in the Listbox property sheet. Some typical properties you might set are:
  • id. The name of the Listbox component. 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 Listbox object.
     
    
  • rows. The number of options to show at one time. If there are more options to show than indicated in this property, a scrollbar is added to the listbox. If this property is not set, all options are shown.
    • Note:
      If you set the rows property to 1, the listbox renders as a drop-down list on most browsers.
    
     
    
  • label. An optional, descriptive label for the list, which can appear on top of the list if you set the labelOnTop property or next to the list if you do not select the labelOnTop property.
    • 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.
    
     
    
  • required. Indicates that the user must select an item from the list. If there is a label, it displays with a required icon.
     
    
  
   
  
• 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)
       
      
    
     
    
  • Bind to Data. Bind the component's items property to an object or to a data provider, as described in Bind to Data Dialog Box.
    • 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, see the following web page:
      Using Listbox Components
       
      
    • To bind the items property to a data provider for a database table or JavaBeans object that will be used to populate the list, select the Bind to Data Provider tab and choose a data provider.
       
      
    
     
    
  • 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.
     
    
  • Property Bindings. Opens a dialog box that enables you to bind the properties of the component to other objects or properties that can update this component's properties automatically. A typical property to bind is the selected property so you can evaluate what the user chose after the page is submitted.
     
    
  
   
  

See Also

Binding Component Properties

Working With Components

Component Tasks: Quick Reference

Component Web Tutorials

Data Source Web Tutorials

About the Palette

Tutorials

Delving Into Components Tutorial

Using Listbox Components