com.sun.webui.jsf.component
Class Checkbox

java.lang.Object
  extended by javax.faces.component.UIComponent
      extended by javax.faces.component.UIComponentBase
          extended by javax.faces.component.UIOutput
              extended by javax.faces.component.UIInput
                  extended by com.sun.webui.jsf.component.WebuiInput
                      extended by com.sun.webui.jsf.component.Selector
                          extended by com.sun.webui.jsf.component.RbCbSelector
                              extended by com.sun.webui.jsf.component.Checkbox
All Implemented Interfaces:
com.sun.webui.jsf.component.ComplexComponent, com.sun.webui.jsf.component.SelectorManager, javax.faces.component.EditableValueHolder, javax.faces.component.NamingContainer, javax.faces.component.StateHolder, javax.faces.component.ValueHolder

public class Checkbox
extends com.sun.webui.jsf.component.RbCbSelector

The Checkbox component is used to display a checkbox input element.

The Checkbox can be used as a single checkbox or one checkbox among a group of checkboxes. A group of checkboxes represents a multiple selection list which can have any number of checkboxes selected, or none selected. A checkbox can represent a Boolean value, a String value, or a developer defined Object value.

Detecting a selected checkbox

The Checkbox uses both the selected and selectedValue properties to pass information about the checkbox's selection status. The selected property is used to indicate that the checkbox is selected. The selectedValue property is used to pass a data value, a string by default, for the checkbox. A checkbox is considered to be selected when the value of the selected property is equal to the value of the selectedValue property. A checkbox can be initally selected by assigning the same value to the selectedValue and the selected properties. isChecked is called to determine if this Checkbox is selected.

If the selectedValue property is not specified or its value is null then the checkbox behaves like a boolean control. If the checkbox is selected, the value of the selected property is a true Boolean instance. If the checkbox is not selected, the value of the selected property will be a false Boolean instance.

Note that a value binding expression that evaluates to a primitive boolean value can be assigned to the selected property. Proper type coercion from Boolean to boolean occurs.

When checkboxes are part of a group, an ArrayList of selected checkboxes is maintained. If any checkboxes within a group are selected, a request attribute whose name is the value of the name property is created and added to the RequestMap. The request attribute value is an ArrayList containing the value of the selectedValue property of each selected checkbox. If no checkboxes are selected, no request attribute is created. The selected property of each selected checkbox within the group will also contain the value of the selectedValue property of the respective selected checkbox.

Using a checkbox tag as a boolean control

If the selectedValue property is not specified or its value is null then the checkbox behaves like a boolean control.

To use the Checkbox as a boolean control, do not specify a value for the selectedValue property. The checkbox is selected if the selected property is not null and has the value of a Boolean instance with a true value. If the checkbox is not selected, then the value of the selected property is a false Boolean instance.

Note that using a boolean checkbox in a group and referencing the request property for the selected checkboxes is not useful, since the value of the request property will be an ArrayList of indistinguishable true values.

Using a Checkbox to represent a developer defined value

The selectedValue property can be assigned a developer defined object value to represent the value of a selected checkbox. If the checkbox is selected, the value of the selected property is assigned the value of the selectedValue property.

If the value of the selectedValue property is a developer defined object, a Converter must be registered to convert to and from a String value.
In addition the object must support an equals method that returns true when the value of the selectedValue property is compared to the selected property value in order to detect a selected checkbox.

Using a Checkbox as one control in a group

The name property determines whether a checkbox is part of a group. A checkbox is treated as part of a group of checkboxes if the name property of the checkbox is assigned a value equal to the name property of the other checkboxes in the group. In other words, all checkboxes of a group have the same name property value. The group behaves like a multiple selection list, where zero or more checkboxes can be selected. The value of the name property must be unique within the scope of the Form parent containing the checkboxes.

Facets

The following facets are supported:

Add an image or label facet to the Checkbox if more control over the properties of the subcomponents is needed.

Note that if a facet is exists, Checkbox properties that would normally be assigned to the created subcomponent, will not be assigned to the facet

Note that unexpected layout of the Checkbox may occur if the component specified by the facet is not a ImageComponent for the image facet or Label for the label facet.

ImageComponent and Label subcomponents

An image and a label may be associated with the Checkbox.
If the imageURL property is not null and an image facet does not exist then a ImageComponent component is created.
If the label property is not null and a label facet does not exist then a Label component is created.

The following Checkbox properties are assigned to the subcomponents only if a facet does not exist.
For the ImageComponent subcomponent

For the Label subcomponent

Note that if a value binding exists for one of the Checkbox properties mentioned above, the value binding is set on the subcomponent for that property.


Field Summary
static java.lang.String CB_ID
           
 
Fields inherited from class com.sun.webui.jsf.component.RbCbSelector
IMAGE_FACET, LABEL_FACET
 
Fields inherited from class javax.faces.component.UIInput
COMPONENT_FAMILY, COMPONENT_TYPE, CONVERSION_MESSAGE_ID, REQUIRED_MESSAGE_ID, UPDATE_MESSAGE_ID
 
Fields inherited from interface javax.faces.component.NamingContainer
SEPARATOR_CHAR
 
Constructor Summary
Checkbox()
          Constructor for a Checkbox.
 
Method Summary
 java.lang.String getFamily()
          Return the family for this component.
 java.lang.String getHtmlTemplate()
          Get alternative HTML template to be used by this component.
 java.lang.Object getItems()
          Specifies the options that the web application user can choose from.
 java.lang.String getLabeledElementId(javax.faces.context.FacesContext context)
          Returns the absolute ID of an HTML element suitable for use as the value of an HTML LABEL element's for attribute.
 int getLabelLevel()
          Sets the style level for the generated label, provided the label attribute has been set.
 java.lang.String getRendererType()
           
static java.util.ArrayList getSelected(java.lang.String name)
          Return an ArrayList containing the value of the selectedValue property of each selected checkbox in the group of checkboxes identified by the name parameter.
 java.lang.Object getValue()
           
 boolean isRequired()
           
 void restoreState(javax.faces.context.FacesContext _context, java.lang.Object _state)
          Restore the state of this component.
 java.lang.Object saveState(javax.faces.context.FacesContext _context)
          Save the state of this component.
 void setHtmlTemplate(java.lang.String htmlTemplate)
          Set alternative HTML template to be used by this component.
 void setLabelLevel(int labelLevel)
          Sets the style level for the generated label, provided the label attribute has been set.
 void validate(javax.faces.context.FacesContext context)
          Update the request parameter that holds the value of the selectedValue property of the selected check box.
 
Methods inherited from class com.sun.webui.jsf.component.RbCbSelector
encodeBegin, getConvertedValue, getConvertedValue, getFocusElementId, getImageComponent, getImageURL, getIndicatorComponent, getLabelComponent, getName, getPrimaryElementID, getSelected, getSelectedValue, getValueExpression, isChecked, setImageURL, setItems, setName, setSelected, setSelectedValue, setValueExpression
 
Methods inherited from class com.sun.webui.jsf.component.Selector
getLabel, getOnBlur, getOnChange, getOnClick, getOnDblClick, getOnFocus, getOnKeyDown, getOnKeyPress, getOnKeyUp, getOnMouseDown, getOnMouseMove, getOnMouseOut, getOnMouseOver, getOnMouseUp, getOnSelect, getRendersChildren, getStyle, getStyleClass, getTabIndex, getToolTip, isDisabled, isMultiple, isReadOnly, isVisible, setDisabled, setLabel, setMultiple, setOnBlur, setOnChange, setOnClick, setOnDblClick, setOnFocus, setOnKeyDown, setOnKeyPress, setOnKeyUp, setOnMouseDown, setOnMouseMove, setOnMouseOut, setOnMouseOver, setOnMouseUp, setOnSelect, setReadOnly, setStyle, setStyleClass, setTabIndex, setToolTip, setVisible, toString
 
Methods inherited from class com.sun.webui.jsf.component.WebuiInput
broadcast, getValidator, getValidatorExpression, getValueChangeListener, getValueChangeListenerExpression, processDecodes, processUpdates, processValidators, setConverter, setId, setImmediate, setRendered, setRequired, setValidatorExpression, setValueChangeListenerExpression
 
Methods inherited from class javax.faces.component.UIInput
addValidator, addValueChangeListener, decode, getConverterMessage, getRequiredMessage, getSubmittedValue, getValidatorMessage, getValidators, getValueChangeListeners, isImmediate, isLocalValueSet, isValid, removeValidator, removeValueChangeListener, resetValue, setConverterMessage, setLocalValueSet, setRequiredMessage, setSubmittedValue, setValid, setValidator, setValidatorMessage, setValue, setValueChangeListener, updateModel
 
Methods inherited from class javax.faces.component.UIOutput
getConverter, getLocalValue
 
Methods inherited from class javax.faces.component.UIComponentBase
encodeChildren, encodeEnd, findComponent, getAttributes, getChildCount, getChildren, getClientId, getFacet, getFacetCount, getFacets, getFacetsAndChildren, getId, getParent, getValueBinding, invokeOnComponent, isRendered, isTransient, processRestoreState, processSaveState, queueEvent, restoreAttachedState, saveAttachedState, setParent, setRendererType, setTransient, setValueBinding
 
Methods inherited from class javax.faces.component.UIComponent
encodeAll, getContainerClientId
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface com.sun.webui.jsf.component.SelectorManager
getClientId
 
Methods inherited from interface javax.faces.component.ValueHolder
getConverter, getLocalValue
 

Field Detail

CB_ID

public static final java.lang.String CB_ID
See Also:
Constant Field Values
Constructor Detail

Checkbox

public Checkbox()
Constructor for a Checkbox.

Method Detail

getFamily

public java.lang.String getFamily()

Return the family for this component.

Overrides:
getFamily in class com.sun.webui.jsf.component.RbCbSelector

getRendererType

public java.lang.String getRendererType()
Overrides:
getRendererType in class javax.faces.component.UIComponentBase

getSelected

public static java.util.ArrayList getSelected(java.lang.String name)
Return an ArrayList containing the value of the selectedValue property of each selected checkbox in the group of checkboxes identified by the name parameter. A Checkbox is one of a group of checkboxes if more than on checkbox has the same value for the name property.
When one of the checkboxes among that group is selected, the value of its selectedValue property is maintained within an ArrayList that is stored in a request attribute identified by the value of its name property.

Parameters:
name - the value a Checkbox name property.

validate

public void validate(javax.faces.context.FacesContext context)

Update the request parameter that holds the value of the selectedValue property of the selected check box.

If the name property has been set a request attribute is created. The value of the name property will be used for the request attribute name and the value of the request attribute will be an ArrayList containing the value of the selectedValue property of the selected check boxes that have the same name property value. If no check box is selected then no request attribute will be created.

The request attribute described above is available during a ValueChangeEvent.

Overrides:
validate in class javax.faces.component.UIInput
Parameters:
context - The context of this request.

getLabeledElementId

public java.lang.String getLabeledElementId(javax.faces.context.FacesContext context)
Returns the absolute ID of an HTML element suitable for use as the value of an HTML LABEL element's for attribute. If the ComplexComponent has sub-compoents, and one of the sub-components is the target of a label, if that sub-component is a ComplexComponent, then getLabeledElementId must called on the sub-component and the value returned. The value returned by this method call may or may not resolve to a component instance.

Specified by:
getLabeledElementId in interface com.sun.webui.jsf.component.ComplexComponent
Overrides:
getLabeledElementId in class com.sun.webui.jsf.component.RbCbSelector
Parameters:
context - The FacesContext used for the request
Returns:
An absolute id suitable for the value of an HTML LABEL element's for attribute.

getItems

public java.lang.Object getItems()
Description copied from class: Selector

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.

Overrides:
getItems in class com.sun.webui.jsf.component.RbCbSelector

isRequired

public boolean isRequired()
Specified by:
isRequired in interface javax.faces.component.EditableValueHolder
Overrides:
isRequired in class javax.faces.component.UIInput

getValue

public java.lang.Object getValue()
Specified by:
getValue in interface javax.faces.component.ValueHolder
Overrides:
getValue in class javax.faces.component.UIOutput

getLabelLevel

public int getLabelLevel()

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 3.

Overrides:
getLabelLevel in class Selector

setLabelLevel

public void setLabelLevel(int labelLevel)

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 3.

Overrides:
setLabelLevel in class Selector
See Also:
getLabelLevel()

getHtmlTemplate

public java.lang.String getHtmlTemplate()

Get alternative HTML template to be used by this component.


setHtmlTemplate

public void setHtmlTemplate(java.lang.String htmlTemplate)

Set alternative HTML template to be used by this component.


restoreState

public void restoreState(javax.faces.context.FacesContext _context,
                         java.lang.Object _state)

Restore the state of this component.

Specified by:
restoreState in interface javax.faces.component.StateHolder
Overrides:
restoreState in class com.sun.webui.jsf.component.RbCbSelector

saveState

public java.lang.Object saveState(javax.faces.context.FacesContext _context)

Save the state of this component.

Specified by:
saveState in interface javax.faces.component.StateHolder
Overrides:
saveState in class com.sun.webui.jsf.component.RbCbSelector


Copyright © 2008 Sun Microsystems, Inc. All Rights Reserved.