webuijsf
Tag listbox


Use the webuijsf:listbox tag to display in the rendered HTML page a box that allows users to select one or more items from a list. The list box shows more than one list option at a time. Use the webuijsf:dropDown tag if you want to display one line and open the list when the user selects it.

HTML Elements and Layout

The listbox component is rendered as an XHTML <select> element. The <option> elements within the <select> element are derived from the webuijsf:listbox tag's items attribute.

Configuring the webuijsf:listbox tag

Use the items attribute to specify the options to be displayed in the listbox. The value of the items attribute must be a JavaServer Faces EL expression that identifies an array, a java.util.Collection or a java.util.Map of com.sun.webui.jsf.Option.

Use the multiple attribute to specify that a user can select more than one item. By default multiple is set to false. If multiple selections are allowed, the model object property that is specified in the selected attribute must be either an array of primitives, an array of objects, or a subclass of java.util.List.

Use the selected attribute to associate the component with a model object that represents the current choice, by setting the value to a JavaServer Faces EL expression that corresponds to a property of a managed bean. The first time the component is rendered, the options that correspond to the value of the selected model object property are marked as selected, using the equals method on the model object.

Use the rows attribute to specify the number of list items that can be seen at once, without scrolling.

The list items will be rendered using a monospace font if the monospace attribute is set to true.

To optionally specify a label for the component, use the label attribute, or specify a label facet.

Grouping Options in the Listbox

The XHTML <select> element can contain an <optgroup> element to define a group of related items in a listbox. The <optgroup> has a label, and the options within the group are indented in the displayed listbox. You can configure the list of items created with the webuijsf:listbox tag to be rendered with <optgroup> elements by setting up your backing bean to use a com.sun.webui.jsf.model.OptionGroup model bean. A backing bean object that populates the listbox from an array with grouped options might look as follows.
 public BackingFileChoice() {
airports = new Option[3];
OptionGroup groupCA = new OptionGroup();
groupCA.setLabel("California");
caAirports = new Option[4];
caAirports[0] = new Option("SFO", "San Francisco");
caAirports[1] = new Option("OAK", "Oakland");
caAirports[2] = new Option("SAN", "San Diego");
caAirports[3] = new Option("LAX", "Los Angeles");
groupCA.setOptions(caAirports);
airports[0] = groupCA;
OptionGroup groupNY = new OptionGroup();
groupNY.setLabel("New York");
nyAirports = new Option[4];
nyAirports[0] = new Option("ALB", "Albany");
nyAirports[1] = new Option("JFK", "New York, JFK");
nyAirports[2] = new Option("LGA", "New York, LaGuardia");
nyAirports[3] = new Option("BUF", "Buffalo");
groupNY.setOptions(nyAirports);
airports[1] = groupNY;
OptionGroup group = new OptionGroup();
group.setLabel("Other airports");
otherAirports = new Option[3];
otherAirports[0] = new Option("PDX", "Portland"); otherAirports[1] = new Option("NRT", "Tokyo");
otherAirports[2] = new Option("TBD", "Future Airport");
otherAirports[2].setDisabled(true);
group.setOptions(otherAirports);
airports[2] = group;
}

The listbox that is rendered with this backing bean will appear as follows:


The important points to note in the sample backing bean are:

Facets

The label facet is used to specify a custom component for the label. The label facet overrides the label attribute.

Theme Identifiers

TBA

Client-side JavaScript Functions

When the component is rendered, a DOM object corresponding to the component is created. To manipulate the component on the client side, you may invoke functions on the DOM object. With reference to the DOM id, to disable the component, invoke document.getElementById(id).setProps({visible: false}).

getProps() Use this function to get widget properties. Please see setProps() function for a list of supported properties.
getSelectElement() Use this function to access the HTML <select> element that is rendered by the component.
getSelectedLabel() Use this function to get the label of the first selected option on the listbox. If no option is selected, this function returns null.
getSelectedValue() Use this function to get the value of the first selected option on the listbox. If no option is selected, this  function returns null.
refresh(execute) Use this function to asynchronously refresh the component.
  • [optional] execute: Comma separated string containing a list of client ids against which the execute portion of the request processing lifecycle must be run. If omitted, no other components are executed.
setProps(props) Use this function to change any of the following supported properties:
  • id
  • dir
  • disabled
  • label
  • lang
  • multiple
  • monospace
  • onBlur
  • onChange
  • onClick
  • onDblClick
  • onFocus
  • onMouseDown
  • onMouseOut
  • onMouseOver
  • onMouseUp
  • onMouseMove
  • onKeyPress
  • onKeyUp
  • onSelect
  • options
  • size
  • style
  • tabIndex
  • title
  • visible
submit(execute)
Use this function to asynchronously submit the component.
  • [optional] execute: Comma separated string containing a list of client ids against which the execute portion of the request processing lifecycle must be run. If omitted, the component on which the function has been invoked, is submitted.
subscribe(topic, obj, func) Use this function to subscribe to an event topic.
  • topic: The event topic to subscribe to.
  • obj: The object in which a function will be invoked, or null for default scope.
  • func The name of a function in context, or a function reference to invoke when topic is published.

Client Side JavaScript Events

When the component is manipulated client side, some functions may publish event topics for custom AJAX implementations to listen for. For example, you can listen for the refresh event topic using:

<webuijsf:script>
    var processEvents = {                       
        update: function(props) {
            // Do something...
        }
    }

    // Subscribe to refresh event.
    var domNode = document.getElementById("form1:test1");
    domNode.subscribe(domNode.event.refresh.endTopic, processEvents, "update");


</webuijsf:script>

The following events are supported.

<Node>.event.refresh.beginTopic Event topic published before asynchronously refreshing the component. Supported properties include:
  • [optional] execute - list of the components to be executed along with this component
  • id - The client id to process the event for
<Node>.event.refresh.endTopic Event topic published after asynchronously refreshing the component. Supported properties include: See setProps() function.
  • props - JSON object containing properties of the component. See setProps() function for details on properties and their usage
<Node>.event.submit.beginTopic Event topic published before asynchronously submitting the component. Supported properties include:
  • [optional] execute - list of the components to be executed along with this component
  • id - The client id to process the event for
<Node>.event.submit.endTopic

Event topic published after asynchronously submitting the component. Supported properties include:

  • props - JSON object containing messages (if any) raised by the server.In particular, valdiation messages will be present here if validation failed

Examples

Example 1: Listbox with single selection

     <webuijsf:listbox selected="#{flightSearch.leaveAirport}" 
items="#{dataBean.airports}"
rows="6"
id="leaveAirport"
toolTip="#{msgs.chooseAirport}"
label="#{msgs.chooseDepartureAirport)" />

Example 2: Listbox that uses a label facet

                 
<webuijsf:listbox selected="#{flightSearch.leaveAirport}"
items="#{dataBean.airports}"
rows="6"
id="leaveAirport"
toolTip="#{msgs.chooseAirport}"
label="#{msgs.chooseDepartureAirport)" >
<f:facet name="label">
<webuijsf:label id="aplabel" text="#{msgs.chooseDepartureAirport)"
for="leaveAirport" labelLevel="2"/>
</f:facet>
</webuijsf:listbox>

Example 3: Update client-side listbox properties using the getProps and setProps functions

This example shows how to toggle the disabled state of a listbox client side using the getProps and setProps functions. When the user clicks the radio button, the listbox is either disabled or enabled.

<webuijsf:radioButton id="rb1" name="rb1" label="Hide Listbox" onClick="toggleDisabled()"/>
<webuijsf:listbox
id="list1"
    items="#{dataBean.airports}"
    label="#{msgs.chooseDepartureAirport}"
    selected="#{flightSearch.leaveAirport}"
    tooltip="#{msgs.chooseAirport}"/>

<webuijsf:script>
    function toggleDisabled() {
        var domNode = document.getElementById("form1:list
1"); // Get list
        return domNode.setProps({disabled: !domNode.getProps().disabled}); // Toggle disabled state
    }
</webuijsf:script>

Example 4: Asynchronously update button using refresh function

This example shows how to asynchronously update a listbox using the refresh function. When the user clicks on the radio button, the listbox is asynchronously updated with new data.

<webuijsf:radioButton id="rb1" name="rb1" label="Refresh Listbox" onClick="refreshList()"/>
<webuijsf:listbox id="list1"
    items="#{dataBean.airports}"
    label="#{msgs.chooseDepartureAirport}"
    selected="#{flightSearch.leaveAirport}"
    tooltip="#{msgs.chooseAirport}"/>

<webuijsf:script>
    function refreshList() {
        var domNode = document.getElementById("form1:list1"); // Get list
        return domNode.refresh(); // Asynchronously refresh list
    }
</webuijsf:script>

Note that the refresh function can optionally take a list of elements to execute. Thus, a comma-separated list of ids can be provided to update components server-side: refresh("form1:id1,form2:id2,..."). When no parameter is given, the refresh function acts as a reset. That is, the component will be redrawn using values set server-side, but not updated.

Example 5: Asynchronously update button using refresh function

This example shows how to asynchronously update a listbox using the refresh function. The execute property of the refresh function is used to define the client id which is to be submitted and updated server-side. As the user types in the text field, the input value is updated server-side and the listbox label is updated client-side -- all without a page refresh.

<webuijsf:listbox id="list1"
    items="#{dataBean.airports}"
    label="
#{MyBean.label}"
    selected="#{flightSearch.leaveAirport}"
    tooltip="#{msgs.chooseAirport}"/>
<webuijsf:textField id="field1"
    text="#{MyBean.label}"
    label="Change list Label"
    onKeyUp="refreshList()"/> // Field used to asynchronously update label.

<webuijsf:script>
    function
refreshList() {
        var domNode = document.getElementById("form1:list1"); // Get list
        return domNode.refresh("form1:field1"); // Asynchronously refresh while submitting field value
    }
</webuijsf:script>

Note that the refresh function can optionally take a list of elements to execute. Thus, a comma-separated list of ids can be provided to update components server-side: refresh("form1:id1,form2:id2,...")
 



Tag Information
Tag Classcom.sun.webui.jsf.component.ListboxTag
TagExtraInfo ClassNone
Body ContentJSP
Display NameNone

Attributes
NameRequiredRequest-timeTypeDescription
bindingfalsefalsejava.lang.String A ValueExpression that resolves to the UIComponent that corresponds to this tag. This attribute allows the Java bean that contains the UIComponent to manipulate the UIComponent, its properties, and its children.
toolTipfalsefalsejava.lang.String

Sets the value of the title attribute for the HTML element. The specified text will display as a tooltip if the mouse cursor hovers over the HTML element.

htmlTemplatefalsefalsejava.lang.String Alternative HTML template to be used by this component.
multiplefalsefalsejava.lang.String

Flag indicating that the application user can make select more than one option at a time from the listbox.

monospacefalsefalsejava.lang.String

When set to true, this attribute causes the list items to be rendered in a monospace font.

readOnlyfalsefalsejava.lang.String

If this attribute is set to true, the value of the component is rendered as text, preceded by the label if one was defined.

Deprecated: The attribute is deprecated starting from version 4.1
onDblClickfalsefalsejava.lang.String

Scripting code that is executed when a mouse double-click occurs over this component.

labelOnTopfalsefalsejava.lang.String

If true, the label is rendered above the component. If false, the label is rendered next to the component. The default is false.

onKeyPressfalsefalsejava.lang.String

Scripting code that is executed when the user presses and releases a key while the component has the focus.

onFocusfalsefalsejava.lang.String

Scripting code that is executed when this component receives focus. An element receives focus when the user selects the element by pressing the tab key or clicking the mouse.

renderedfalsefalsejava.lang.String Indicates whether the HTML code for the component should be included in the rendered HTML page. If set to false, the rendered HTML page does not include the HTML for the component. If the component is not rendered, it is also not processed on any subsequent form submission.
idfalsetruejava.lang.StringNo Description
onKeyUpfalsefalsejava.lang.String

Scripting code that is executed when the user releases a key while the component has the focus.

onMouseUpfalsefalsejava.lang.String

Scripting code that is executed when the user releases a mouse button while the mouse pointer is on the component.

styleClassfalsefalsejava.lang.String

CSS style class or classes to be applied to the outermost HTML element when this component is rendered.

itemsfalsefalsejava.lang.String

Specifies the options that the web application user can choose from. The value must be one of an array, Map or Collection whose members are all subclasses ofcom.sun.webui.jsf.model.Option.

stylefalsefalsejava.lang.String

CSS style or styles that are applied to the outermost HTML element when the component is rendered.

onClickfalsefalsejava.lang.String

Scripting code that is executed when a mouse click occurs over the component.

onBlurfalsefalsejava.lang.String

Scripting code that is executed when this element loses the focus.

onMouseDownfalsefalsejava.lang.String

Scripting code that is executed when the user presses a mouse button while the mouse pointer is on the component.

rowsfalsefalsejava.lang.String

The number of items to display. The default value is 12.

converterfalsefalsejava.lang.String Specifies a method to translate native property values to String and back for this component. The converter attribute value must be one of the following:
  • A JavaServer Faces EL expression that resolves to a backing bean or bean property that implements the javax.faces.converter.Converter interface; or
  • the ID of a registered converter (a String).
requiredfalsefalsejava.lang.String Flag indicating that an input value for this field is mandatory, and failure to provide one will trigger a validation error.
disabledfalsefalsejava.lang.String

Flag indicating that the user is not permitted to activate this component, and that the component's value will not be submitted with the form.

validatorExpressionfalsefalsejava.lang.String Used to specify a method in a backing bean to validate input to the component. The value must be a JavaServer Faces EL expression that resolves to a public method with return type void. The method must take three parameters:
  • a javax.faces.context.FacesContext
  • a javax.faces.component.UIComponent (the component whose data is to be validated)
  • a java.lang.Object containing the data to be validated.

The backing bean where the method is defined must implement java.io.Serializable or javax.faces.component.StateHolder.

The method is invoked during the Process Validations Phase.

onMouseOutfalsefalsejava.lang.String

Scripting code that is executed when a mouse out movement occurs over this component.

separatorsfalsefalsejava.lang.String

Flag indicating that items corresponding to com.sun.webui.jsf.model.Option that are defined inside a com.sun.webui.jsf.model.OptionGroup should be surrounded by separators inside the list. The default value is true. If false, no separators are shown. To manually specify the location of separators, set this flag to false and place instances of com.sun.webui.jsf.model.Separator between the relevant com.sun.webui.jsf.model.Option instances when specifying the items attribute.

onMouseOverfalsefalsejava.lang.String

Scripting code that is executed when the user moves the mouse pointer into the boundary of this component.

onMouseMovefalsefalsejava.lang.String

Scripting code executed when the user moves the mouse pointer while over the component.

selectedfalsefalsejava.lang.String

The object that represents the selections made from the available options. If multiple selections are allowed, this must be bound to an Object array, or an array of primitives.

immediatefalsefalsejava.lang.String Flag indicating that event handling for this component should be handled immediately (in Apply Request Values phase) rather than waiting until Invoke Application phase.
labelfalsefalsejava.lang.String

If set, a label is rendered adjacent to the component with the value of this attribute as the label text.

onChangefalsefalsejava.lang.String

Scripting code executed when the element value of this component is changed.

visiblefalsefalsejava.lang.String

Indicates whether the component should be viewable by the user in the rendered HTML page. If set to false, the HTML code for the component is present in the page, but the component is hidden with style attributes. By default, visible is set to true, so HTML for the component HTML is included and visible to the user. If the component is not visible, it can still be processed on subsequent form submissions because the HTML is present.

onKeyDownfalsefalsejava.lang.String

Scripting code that is executed when the user presses down on a key while the component has the focus.

labelLevelfalsefalsejava.lang.String

Sets the style level for the generated label, provided the label attribute has been set. Valid values are 1 (largest), 2 and 3 (smallest). The default value is 2.

valueChangeListenerExpressionfalsefalsejava.lang.String Specifies a method to handle a value-change event that is triggered when the user enters data in the input component. The attribute value must be a JavaServer Faces EL expression that resolves to a backing bean method. The method must take a single parameter of type javax.faces.event.ValueChangeEvent, and its return type must be void. The backing bean where the method is defined must implement java.io.Serializable or javax.faces.component.StateHolder.
tabIndexfalsefalsejava.lang.String

Describes the position of this element in the tabbing order of the current document. Tabbing order determines the sequence in which elements receive focus when the tab key is pressed. The value must be an integer between 0 and 32767.


Variables
No Variables Defined.


Output Generated by Tag Library Documentation Generator. Java, JSP, and JavaServer Pages are trademarks or registered trademarks of Sun Microsystems, Inc. in the US and other countries. Copyright 2002-4 Sun Microsystems, Inc. 4150 Network Circle Santa Clara, CA 95054, U.S.A. All Rights Reserved.