| |||||||
FRAMES NO FRAMES |
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.
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.
webuijsf:listbox
tagUse 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.
<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 OptionGroups each have a setLabel
method that
sets the label of the corresponding <optgroup>
.
A separator (a series of dashes) is rendered above the optgroup
labels. By default, the separator is rendered above each optgroup in a
listbox. The separators can be removed by setting the webuijsf:listbox
tag's separators
attribute to false.
The setOptions
method sets the options of each
subgroup to the appropriate array values.
The setDisabled
method can be used to disable any
of the options in the listbox.
The label
facet is used to specify a custom component
for the label. The label
facet overrides the label
attribute.
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.
|
setProps(props) |
Use this function to change any of the following supported
properties:
|
submit(execute) |
Use this function to
asynchronously submit the component.
|
subscribe(topic, obj, func) |
Use this function to subscribe
to an event topic.
|
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:
|
<Node>.event.refresh.endTopic | Event topic published after asynchronously refreshing the
component. Supported properties include: See setProps() function.
|
<Node>.event.submit.beginTopic | Event topic published before asynchronously submitting the
component. Supported properties include:
|
<Node>.event.submit.endTopic |
Event topic published after asynchronously submitting the component. Supported properties include:
|
<webuijsf:listbox selected="#{flightSearch.leaveAirport}"
items="#{dataBean.airports}"
rows="6"
id="leaveAirport"
toolTip="#{msgs.chooseAirport}"
label="#{msgs.chooseDepartureAirport)" />
<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>
<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>
<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.
<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 Class com.sun.webui.jsf.component.ListboxTag
TagExtraInfo Class None
Body Content JSP
Display Name None
Attributes
Name Required Request-time Type Description
binding false false java.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.
toolTip false false java.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.
htmlTemplate false false java.lang.String
Alternative HTML template to be used by this component.
labelOnTop false false java.lang.String
If true, the label is rendered above the
component. If false, the label is rendered next to the
component.
If this property is not set by the application, a themed default
value will be sought, using the key listbox.labelOnTop
from the messages.properties
file. If there is no
value for the key, false
is returned.
multiple false false java.lang.String
Flag indicating that the application user can make select
more than one option at a time from the listbox.
If this property is not set by the application, a themed default
value will be sought, using the key listbox.multiple
from the messages.properties
file. If there is no
value for the key, false
is returned.
monospace false false java.lang.String
When set to true, this attribute causes the list items to be rendered
in a monospace font.
If this property is not set by the application, a themed default
value will be sought, using the key listbox.monospace
from the messages.properties
file. If there is no
value for the key, false
is returned.
readOnly false false java.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
onDblClick false false java.lang.String
Scripting code that is executed when a mouse double-click
occurs over this component.
width false false java.lang.String
The width
property is a value for the CSS width
property suitable for the select
HTML element.
onKeyPress false false java.lang.String
Scripting code that is executed when the user presses and releases a key while
the component has the focus.
onFocus false false java.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.
rendered false false java.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.
id false true java.lang.String
No Description
onKeyUp false false java.lang.String
Scripting code that is executed when the user releases a key while the
component has the focus.
onMouseUp false false java.lang.String
Scripting code that is executed when the user releases a mouse button while
the mouse pointer is on the component.
styleClass false false java.lang.String
CSS style class or classes to be applied to the outermost HTML element when this
component is rendered.
items false false java.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
.
style false false java.lang.String
CSS style or styles that are applied to the outermost HTML element when the
component is rendered.
onClick false false java.lang.String
Scripting code that is executed when a mouse click
occurs over the component.
onBlur false false java.lang.String
Scripting code that is executed when this element loses the focus.
onMouseDown false false java.lang.String
Scripting code that is executed when the user presses a mouse button while the
mouse pointer is on the component.
rows false false java.lang.String
The number of items to display, Integer.MIN_VALUE
is returned if no value has been set, or there is no value binding.
Subclasses should provide a reasonable default.
converter false false java.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).
required false false java.lang.String
Flag indicating that an input value for this field is mandatory, and
failure to provide one will trigger a validation error.
disabled false false java.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.
validatorExpression false false java.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.
onMouseOut false false java.lang.String
Scripting code that is executed when a mouse out movement
occurs over this component.
separators false false java.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.
onMouseOver false false java.lang.String
Scripting code that is executed when the user moves the mouse pointer into
the boundary of this component.
onMouseMove false false java.lang.String
Scripting code executed when the user moves the mouse pointer while
over the component.
selected false false java.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.
immediate false false java.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.
label false false java.lang.String
If set, a label is rendered adjacent to the component with the
value of this attribute as the label text.
onChange false false java.lang.String
Scripting code executed when the element
value of this component is changed.
visible false false java.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.
onKeyDown false false java.lang.String
Scripting code that is executed when the user presses down on a key while the
component has the focus.
labelLevel false false java.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.
valueChangeListenerExpression false false java.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
.
tabIndex false false java.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.
Overview Library Tag Help
FRAMES
NO FRAMES
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.