SelectManyCheckbox 2.x - roberts-sandbox/test-wiki-page-title GitHub Wiki

TOCSTART

TOCEND

The SelectManyCheckbox component supports all of the features of the standard JSF Checkbox component and extends it with some additional features like customizing checkbox images, rollover and focused styles, distribution of the checkboxes into columns and rows, and so on.

Online Demo

• All features of the standard SelectManyCheckbox component
• Customizing appearance of checkboxes with images
• Extended styling

The SelectManyCheckbox component can be added to a page using the <o:selectManyCheckbox> tag. This tag is just an extended version of the standard <h:selectManyCheckbox> tag. Therefore, you can safely replace the standard SelectManyCheckbox components with OpenFaces SelectManyCheckbox components, which provide you with an additional functionality. Just like in the standard <h:selectManyCheckbox> the value attribute lets you specify the current value of the component.

The following example shows a definition of a simple SelectManyCheckbox component with three items.

<o:selectManyCheckbox value="#{ManyCheckboxTest.CheckboxGroupExample}">
  <f:selectItem value="1" itemLabel="Option 1"/>
  <f:selectItem value="2" itemLabel="Option 2"/>
  <f:selectItem value="3" itemLabel="Option 3"/>
</o:selectManyCheckbox>

You can customize various states of each Checkbox by applying images to it. The images are defined by the following attributes:

When you click on any of the checkboxes its view changes appropriately depending on its state.
You can also specify a custom style for this component as described below.

You can apply styles for the SelectManyCheckbox when it is in the enabled or disabled state, selected or unselected state, focused or rollover state.

The table below lists all style attributes:

The following example demonstrates the usage of style-related attributes of the SelectManyCheckbox component:

<o:selectManyCheckbox id="selectManyCheckboxStyled"
                  value="#{ManyCheckboxTest.CheckboxGroupExample}"
       enabledClass="enClass" enabledStyle="background-color: #B0AFFF;"
       disabledClass="desClass" disabledStyle="background-color: #6F6F6F;"
       focusedClass="focClass" focusedStyle="border: 1px solid #DDDF29;"
       rolloverClass="rollovClass" rolloverStyle="border: 1px solid #33DF29;">
  <f:selectItem value="1" itemLabel="Option 1"/>
  <f:selectItem value="2" itemLabel="Option 2"/>
  <f:selectItem value="3" itemLabel="Option 3"/>
</o:selectManyCheckbox>

You can also apply styles to the labels of the SelectManyCheckbox items. You can specify their view in the focused, selected, rollover, and pressed state.

The table below lists all style attributes:

The SelectManyCheckbox component supports different kinds of layout of checkboxes. Similar to the standard <h:selectManyCheckbox> component, the SelectManyCheckbox can display checkboxes in a horizontal or a vertical layout, which can be controlled with the layout attribute. It can take one of the two standard values:

• "lineDirection" – displays checkboxes horizontally;
• "pageDirection" – displays checkboxes vertically.

In addition to these standard possibilities, the SelectManyCheckbox component introduces the multi-row and multi-column layouts. These layouts can be activated using either the columns or the rows attribute, which specify the number of columns or rows into which the displayed checkboxes will be distributed. If the number of columns is specified, then the checkboxes occupy the minimum number of rows. Similarly, if the number of rows is specified, then the checkboxes occupy the minimum number of columns.

Note, that the rows and the columns attributes are mutually exclusive and cannot be used together.

You can still use the layout attribute along with the columns or rows attributes to configure the order of elements in such multi-row/multi-column layout. Use the "lineDirection" layout value to fill the layout row by row in a left-to-right order (or a right-to-loft one, depending on the document's line direction), and "pageDirection" to fill the layout column by column in a top-to-bottom order.

The SelectManyCheckbox component supports a set of standard client-side events such as onclick, ondblclick, onmousedown, onmouseover, onmouseup, onmouseout, onmousemove, onselect, onchange, onfocus, onblur, onkeyup, onkeydown, onkeypress.

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