facesdoc.HTML_BASIC.javax.faces.SelectManyjavax.faces.Listbox.html Maven / Gradle / Ivy
Show all versions of javax.faces-api Show documentation
<font size="-1">component-family:</font> javax.faces.SelectMany <font size="-1">renderer-type:</font> javax.faces.Listbox
HTML_BASIC render-kit
component-family: javax.faces.SelectMany renderer-type: javax.faces.Listbox
Render an HTML option
list.
Decode Behavior
This section documents the decode behavior for all renderers
that handle UISelectMany or UISelectOne
components.
Decode Behavior for
UISelectMany components
Obtain the Map from the
"requestParameterValuesMap" property of the
ExternalContext. If the Map contains
an entry for the "clientId" of the component, pass the value of
the entry, cast to a String [], to the
setSubmittedValue() method of the component, which
must be an EditableValueHolder. If the
Map does not contain an entry, create an empty
String array and call
setSubmittedValue() with it.
Please check the javadoc for UISelectMany.getConvertedValue()
for additional requirements for renderers that render this kind
of component.
Decode Behavior for
UISelectOne components
Obtain the Map from the "requestParameterMap"
property of the ExternalContext. If there is a
Map entry for the "clientId" property of the
component, pass it to the setSubmittedValue() method
of the component. If the
Map does not contain an entry, call
setSubmittedValue() passing an empty
String as the argument.
Encode Behavior
Render an HTML "select" element. Render the clientId of
the component as the value of the "name" attribute. If the "styleClass"
attribute is specified, render its value as the value of the "class"
attribute on the "select" element. If the component is a
UISelectMany instance, render "multiple" as the value of the
"multiple" attribute. If the "size" attribute is specified, render its
value as the value of the "size" attribute. Otherwise use the number of
items as the value of the "size" attribute.
Rendering the "option" elements
The only valid children of this component are
UISelectItem or UISelectItems
instances. Iterate over the children of this component, and accrue
a list of javax.faces.model.SelectItem instances.
If the current child is a
SelectItem whose noSelctionProperty is
true, and the UISelectOne or
UISelectMany parent of this option has one or more
selected values that are not the "no selection"
SelectItem, and the component has a
"hideNoSelectionLabel" attribute whose value is true,
then the current option, which is the "no selection" option, must
not be rendered. If the current child is a
UISelectItem create a SelectIteminstance
from its itemValue, itemLabel, itemEscaped, and
itemDescription properties, add it to the list. If
the current child is a UISelectItems instance, call
its getValue() method. If the result is a
SelectItem bean, add it to the list. If the result
is an array of SelectItem beans, add each one to the
list. If the result is a Collection of
SelectItem beans, add each one to the list. If the
result is a Map, create a SelectItem
bean for each entry in the Map using the key as the
label, the value as the value, and null as the
description.
Iterate over the list
of SelectItem beans. If the current element is a
SelectItemGroup, render an "optgroup" element with a
"label" attribute, the value of which is the "label" property from
the current element, then call getSelectItems() and
render each element as below. If the current element is not a
SelectItemGroup, render an "option" element. Follow
the conversion rules in the spec to obtain a renderable
String from the "value" property of the current
element, render that as the value of the "value" atribute. Now it
is time to see if the current element is the selected value. Call
its getSubmittedValue() method, casting the result to
an Object [], otherwise the component must be a
UISelectOne instance, call its
getSubmittedValue() method and create an Object
[] around the result. Determine the type of the resultant
array, if the resultant array is non-null, otherwise the type is
String. Coerce the current item value to this type
following the Expression Language coercion rules. If the
resultant array is non-null, we look in the array for a
value that, when we pass the renderable value to its
equals() method, it returns true,
meaning the current element is selected. If the resultant array
is null, if the component is a
UISelectMany, call its getValue()
method. If the result is a List obtain the values in
the list as an array. Otherwise, the component must be a
UISelectOne instance. Call its
getValue() method, which must be an Object array.
Look for an element in the resultant array that, 1. when we pass
the renderable value to its equals() method, it
returns true , or 2. if the renderable value is null,
and there is a null element in the array, also conclude that the
current element is selected. Otherwise the current element is not
selected. Now, if the current value is selected, write out an
HTML boolean property "selected". If the current
SelectItem.isDisabled() returns true, render "disabled" as the
value of the "disabled" attribute. If the value of the
escape property is true, use the
writeText() method of ResponseWriter to
write out the value of the label property.
Otherwise, use the write() method of the
ResponseWriter to do so.
This renderer is responsible for rendering its children.
Note:
Attributes with a pass-through value of
true are not interpreted by the renderer and are passed
straight through to the rendered markup, without checking for validity. Attributes with a
pass-through value of false are interpreted
by the renderer, and may or may not be checked for validity by the renderer.
Attributes
attribute-name
pass-through
attribute-class
description
default-value
accesskey
true
java.lang.String
Access key that, when pressed, transfers focus
to this element.
undefined
collectionType
false
java.lang.String Optional
attribute that is a literal string that is the fully qualified
class name of a concrete class that implements
java.util.Collection, or an EL expression that
evaluates to either 1. such a String, or 2. the
Class object itself.
undefined
dir
true
java.lang.String
Direction indication for text that does not inherit directionality.
Valid values are "LTR" (left-to-right) and "RTL" (right-to-left).
undefined
disabled
false
boolean
Flag indicating that this element must never receive focus or
be included in a subsequent submit. A value of false causes
no attribute to be rendered, while a value of true causes the
attribute to be rendered as disabled="disabled".
undefined
disabledClass
false
java.lang.String
CSS style class to apply to the rendered label
on disabled options.
undefined
enabledClass
false
java.lang.String
CSS style class to apply to the rendered label
on enabled options.
undefined
hideNoSelectionOption
false
boolean
Flag indicating that, if this component is activated by the user,
The "no selection option", if any, must be hidden.
undefined
lang
true
java.lang.String
Code describing the language used in the generated markup
for this component.
undefined
onblur
true
java.lang.String
Javascript code executed when this element loses focus.
undefined
onchange
false
java.lang.String
Javascript code executed when this element loses focus
and its value has been modified since gaining focus.
undefined
onclick
true
java.lang.String
Javascript code executed when a pointer button is
clicked over this element.
undefined
ondblclick
true
java.lang.String
Javascript code executed when a pointer button is
double clicked over this element.
undefined
onfocus
true
java.lang.String
Javascript code executed when this element receives focus.
undefined
onkeydown
true
java.lang.String
Javascript code executed when a key is
pressed down over this element.
undefined
onkeypress
true
java.lang.String
Javascript code executed when a key is
pressed and released over this element.
undefined
onkeyup
true
java.lang.String
Javascript code executed when a key is
released over this element.
undefined
onmousedown
true
java.lang.String
Javascript code executed when a pointer button is
pressed down over this element.
undefined
onmousemove
true
java.lang.String
Javascript code executed when a pointer button is
moved within this element.
undefined
onmouseout
true
java.lang.String
Javascript code executed when a pointer button is
moved away from this element.
undefined
onmouseover
true
java.lang.String
Javascript code executed when a pointer button is
moved onto this element.
undefined
onmouseup
true
java.lang.String
Javascript code executed when a pointer button is
released over this element.
undefined
onselect
true
java.lang.String
Javascript code executed when text within this
element is selected by the user.
undefined
readonly
false
boolean
Flag indicating that this component will prohibit changes by
the user. The element may receive focus unless it has also
been disabled. A value of false causes
no attribute to be rendered, while a value of true causes the
attribute to be rendered as readonly="readonly".
undefined
size
false
int
Number of available options to be shown at all times.
If not specified, all available options are shown.
undefined
style
true
java.lang.String
CSS style(s) to be applied when this component is rendered.
undefined
styleClass
false
java.lang.String
Space-separated list of CSS style class(es) to be applied when
this element is rendered. This value must be passed through
as the "class" attribute on generated markup.
undefined
tabindex
true
java.lang.String
Position of this element in the tabbing order
for the current document. This value must be
an integer between 0 and 32767.
undefined
title
true
java.lang.String
Advisory title information about markup elements generated
for this component.
undefined
Copyright (c) 2003-2010 Oracle America, Inc. All Rights Reserved.