SelectBooleanCheckbox

The SelectBooleanCheckbox component is an extended version of the standard <h:selectBooleanCheckbox> component that adds such possibilities as tri-state support, customizing checkbox images and state-dependent styles.


API Reference | Tag Reference
Online Demo

Key Features

  • All features of the standard <h:selectBooleanCheckbox> component.
  • Tri-state mode that allows support for the third "undefined" state.
  • Customizing state list and toggle order when in tr-state mode.
  • Customizing checkbox appearance with images.
  • Customizing state-dependent styles for rollover, focused and disabled states.

Basic Configuration

The SelectBooleanCheckbox component can be added to a page using the <o:selectBooleanCheckbox> tag. This tag is just an extended version of the standard <h:selectBooleanCheckbox> tag. Therefore, you can safely replace the standard SelectBooleanCheckbox components with OpenFaces SelectBooleanCheckbox components which gives you an additional functionality. Similar to the standard <h:selectBooleanCheckbox> you can use the value attribute to specify the current state of the checkbox and use <h:outputLabel> tag to show a label for the checkbox.

Here's an example that shows a definition of a simple SelectBooleanCheckbox with a label and its value attribute bound to a backing bean.

<o:selectBooleanCheckbox id="rememberMe" value="#{CheckboxBean.rememberMe}" />
<h:outputLabel for="rememberMe" value="Remember me"/>

Tri-State Mode

The SelectBooleanCheckbox supports the tri-state mode where a third "undefined" state is added to the standard "selected" and "unselected" states. This mode can be turned on by specifying the triSateAllowed attribute with a value of true. In case of the third "undefined" state the property bound to the value attribute receives the null value to indicate this state.

By default the user is allowed to cycle only through "selected" and "unselected" states.
It's possible to change the default behabiour and specify a set and an order of SelectBooleanCheckbox states in the tri-state mode to cycle through. The stateList attribute should be specified as a list of checkbox states in the desired toggle order. When specifying a literal attribute value, it should be a space-separated value of the following strings "selected", "unselected" and "undefined".
The examples below shows tri-state checkboxes with a customized stateList attribute.

<o:selectBooleanCheckbox triStateAllowed="true" stateList="undefined selected" value="false"/>

<o:selectBooleanCheckbox triStateAllowed="true" stateList="#{CheckboxTest.states}" values="#{CheckboxTest.state}"/>

Customizing Checkbox Style And Images

It's possible to apply a style and rollover style for the checkbox using the style/styleClass and rolloverStyle/rolloverClass attributes. In addition, there are the following attributes that are applied for selected, unselected and undefined checkbox: selectedStyle/selectedClass, unselectedStyle/unselectedClass, undefinedStyle/undefinedClass.

By default, the <o:selectBooleanCheckbox> displays the native client operating system checkboxes just like the standard <h:selectBooleanCheckbox> component. Though the <o:selectBooleanCheckbox> component allows overriding the default checkbox appearance with images corresponding to all checkbox's states so it's possible to apply an arbitrary design to the component.

The minimum set of attributes that should be defined for changing the look of SelectBooleanCheckbox are the selectedImageUrl, unselectedImageUrl, and optionally the undefinedImageUrl in case of tri-state mode. Though it's also possible to change some apearance aspects in component's rollover, pressed and disabled states, which is possible using the following attributes:

Attributes Description
rolloverSelectedImageUrl, rolloverUnselectedImageUrl, rolloverUndefinedImageUrl These images will be applied when a mouse hovers over the component.
pressedSelectedImageUrl, pressedUnselectedImageUrl, pressedUndefinedImageUrl These images will be applied when a checkbox is pressed.
disabledSelectedImageUrl, disabledUnselectedImageUrl, disabledUndefinedImageUrl These images will be applied when a checkbox is disabled.

Client-Side API

All client-side API methods for the SelectBooleanCheckbox component are listed in the following table:

Method Description
isSelected() Returns true if the checkbox is checked and false otherwise.
setSelected(selected) Checks or unchecks the checkbox when true or false is passed for the selected parameter appropriately.
isDefined() Returns true if the checkbox is not in the "undefined" state, which is possible only in the tri-state mode.
setDefined(defined) Allows switching the checkbox into the "undefined" state if this function is called with a false value for the defined parameter.
getDisabled() Returns true if the checkbox is disabled and false otherwise.
setDisabled(selected) Disables or enables the checkbox when true or false is passed for the selected parameter appropriately.
OpenFaces