You can drag the Standard JavaServer Faces Multi Select Listbox component
from
the Palette to the Visual Designer to create a listbox that enables
the user to select multiple items from a list of items.
- This component is a JavaServer Faces reference implementation that cannot use themes. The Listbox component in the Basic category of the Palette does support themes and provides other features that improve ease of use, such as your choice of a multple selection or a single selection list.
A Multi Select Listbox is a composite component that has the following elements:
- The enclosing component, multiSelectListbox, manages the
style and behavior of the listbox itself. In addition, when
the user submits the page, the value property of this component
is an object array containing the user's choices. You can
bind this component's value property to an ArrayList
object and use that object to test what the user's choices
were.
- The inside component, multiSelectListboxSelectItems,
is intended to be used to bind to a data provider that specifies the actual items in the list.
- A third, related component, multiSelectListboxDefaultItems,
contains an array of initial list items. This array is used
to populate the list only if the list is not bound to a bean
property or data provider. The list defaults to item1,
item2, item3.
After dragging the component to the Visual Designer, you can do a number of things with it:
- Select the Multi Select Listbox component and drag it
to another location on the page.
- Right-click the multiSelectListbox component in the
Outline window and choose Property Bindings to bind its value property
to an Object array that you have added to the session
bean as a property. You can use this session bean property
to evaluate what the user chose after the page is submitted.
For more information, see the value property description
below.
- Right-click the multiSelectListboxSelectItems component
in the Outline window and bind it to a bean property
or data provider that will be used to populate the list. For more
information, see the tutorial "Using Listbox Components"
on the web at
http://developers.sun.com/jscreator/learning/tutorials/index.jsp.
- Select the Multi Select Listbox component on the page
in the Visual Designer and edit its properties in the Multi
Select Listbox property
sheet. These properties affect the overall style and
behavior of the list. Some typical properties you might
set are:
- id. The name of the Multi Select 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 HtmlSelectManyCheckbox
object.
- value. The data that is sent when the page
is submitted.
This component can have more than one value, which has implications about what type of value you can use.- If you use a value binding expression, it must
point to an array of objects or primitives. The
individual elements in this array represent the
currently selected values from the set of all possible
options.
- If you do not use a value binding expression,
the object returned to you when you call multiSelectListbox.getValue()
is an object array.
- There is no usable way to bind this component
to database data, because the value will typically
be represented by multiple rows in a detail table.
One way to process the values chosen by the user is to bind this component to an ArrayList object and check the array values when the user submits the page. For more information, see the tutorial Using Listbox Components on the web at
http://developers.sun.com/jscreator/learning/tutorials/index.jsp.
- If you use a value binding expression, it must
point to an array of objects or primitives. The
individual elements in this array represent the
currently selected values from the set of all possible
options.
- disabledClass. A CSS style class defined in
the page's style sheet or in its <head>
section that is to be applied to the labels for disabled
items in the list.
- enabledClass. A CSS style class defined in
the page's style sheet or in its <head>
section that is to be applied to the labels for enabled
items in the list.
- Note: You disable or enable a list option by setting or
clearing the disabled property of the SelectItems
component used to initialize the option. For more information
on initializing a list with a SelectItems component,
see the Using Listbox Components tutorial on the
web at
.
- id. The name of the Multi Select 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 HtmlSelectManyCheckbox
object.
- Right-click the Multi Select Listbox component in the Visual Designer and choose one of several actions, some of which are
listed below:
- 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 chose two list items and pressed Enter).
- 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.
- Bind to Data. Opens a dialog box that enables you to bind the component to an object or data provider that will update the list dynamically. For example, you might choose this option rather than dropping a table on the component if a database table has already been added to the page. For more information, see Bind to Data Dialog Box.
- 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.
- Configure Virtual Forms. Enables you to add the component to a virtual form.
- 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.
- Edit Event Handler. Write code for one of the following event handlers.
Close