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.