-
Notifications
You must be signed in to change notification settings - Fork 0
SelectBooleanCheckbox 2.x
AlexanderLitus edited this page Aug 5, 2014
·
1 revision
TOCSTART
<div>
<ul>
<li><a href="#SelectBooleanCheckbox2.x-KeyFeatures">Key Features</a></li>
<li><a href="#SelectBooleanCheckbox2.x-BasicConfiguration">Basic Configuration</a></li>
<li><a href="#SelectBooleanCheckbox2.x-TriStateMode">Tri-State Mode</a></li>
<li><a href="#SelectBooleanCheckbox2.x-CustomizingCheckboxStyleAndImages">Customizing Checkbox Style And
Images</a></li>
<li><a href="#SelectBooleanCheckbox2.x-ClientSideAPI">Client-Side API</a></li>
</ul>
</div>
<p>TOCEND</p>
<p>The <cite>SelectBooleanCheckbox</cite> component is an extended version of the standard <u><h:selectBooleanCheckbox></u>
component that adds such possibilities as tri-state support, customizing checkbox images and
state-dependent styles.</p>
<p><span class="image-wrap" style="">
<img
src="/download/attachments/1703957/selectbooleancheckbox.png?version=1&modificationDate=1290511121615"
style="border: 0px solid black"></span><br>
<a href="http://www.openfaces.org/demo/selectbooleancheckbox/" class="external-link" rel="nofollow">Online
Demo</a></p>
<h4><a name="SelectBooleanCheckbox2.x-KeyFeatures"></a>Key Features</h4>
<ul>
<li>All features of the standard <u><h:selectBooleanCheckbox></u> component.</li>
<li>Tri-state mode that allows support for the third "undefined" state.</li>
<li>Customizing state list and toggle order when in tr-state mode.</li>
<li>Customizing checkbox appearance with images.</li>
<li>Customizing state-dependent styles for rollover, focused and disabled states.</li>
</ul>
<h4><a name="SelectBooleanCheckbox2.x-BasicConfiguration"></a>Basic Configuration</h4>
<p>The <cite>SelectBooleanCheckbox</cite> component can be added to a page using the <u><o:selectBooleanCheckbox></u>
tag. This tag is just an extended version of the standard <u><h:selectBooleanCheckbox></u> tag. Therefore,
you can safely replace the standard SelectBooleanCheckbox components with OpenFaces SelectBooleanCheckbox
components which gives you an additional functionality. Similar to the standard <u><h:selectBooleanCheckbox></u>
you can use the <b>value</b> attribute to specify the current state of the checkbox and use <u><h:outputLabel></u>
tag to show a label for the checkbox.</p>
<p>Here's an example that shows a definition of a simple <cite>SelectBooleanCheckbox</cite> with a label and its <b>value</b>
attribute bound to a backing bean.</p>
<div class="code panel" style="border-width: 1px;">
<div class="codeContent panelContent">
<o:selectBooleanCheckbox id="rememberMe" value="#{CheckboxBean.rememberMe}" /> <h:outputLabel for="rememberMe" value="Remember me"/>
</div>
</div>
<p><a name="SelectBooleanCheckbox2.x-tristate"></a></p>
<h4><a name="SelectBooleanCheckbox2.x-TriStateMode"></a>Tri-State Mode</h4>
<p>The <cite>SelectBooleanCheckbox</cite> 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
<b>triSateAllowed</b> attribute with a value of <i>true</i>. In case of the third "undefined" state the property
bound to the <b>value</b> attribute receives the <i>null</i> value to indicate this state.</p>
<p>By default the user is allowed to cycle only through "selected" and "unselected" states.<br>
It's possible to change the default behabiour and specify a set and an order of
<cite>SelectBooleanCheckbox</cite> states in the tri-state mode to cycle through. The <b>stateList</b> 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 <i>"selected"</i>, <i>"unselected"</i>
and <i>"undefined"</i>.<br>
The examples below shows tri-state checkboxes with a customized <b>stateList</b> attribute.</p>
<div class="code panel" style="border-width: 1px;">
<div class="codeContent panelContent">
<o:selectBooleanCheckbox triStateAllowed="true" stateList="undefined selected" value="false"/> <o:selectBooleanCheckbox triStateAllowed="true" stateList="#{CheckboxTest.states}" values="#{CheckboxTest.state}"/>
</div>
</div>
<h4><a name="SelectBooleanCheckbox2.x-CustomizingCheckboxStyleAndImages"></a>Customizing Checkbox Style And Images
</h4>
<p>It's possible to apply a style and rollover style for the checkbox using the <b>style</b>/<b>styleClass</b> and
<b>rolloverStyle</b>/<b>rolloverClass</b> attributes. In addition, there are the following attributes that are
applied for selected, unselected and undefined checkbox: <b>selectedStyle</b>/<b>selectedClass</b>, <b>unselectedStyle</b>/<b>unselectedClass</b>,
<b>undefinedStyle</b>/<b>undefinedClass</b>.</p>
<p>By default, the <u><o:selectBooleanCheckbox></u> displays the native client operating system checkboxes
just like the standard <u><h:selectBooleanCheckbox></u> component. Though the <u><o:selectBooleanCheckbox></u>
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.</p>
<p>The minimum set of attributes that should be defined for changing the look of <cite>SelectBooleanCheckbox</cite>
are the <b>selectedImageUrl</b>, <b>unselectedImageUrl</b>, and optionally the <b>undefinedImageUrl</b> 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:</p>
<div class="table-wrap">
<table class="confluenceTable">
<tbody>
<tr>
<th class="confluenceTh"> Attributes</th>
<th class="confluenceTh"> Description</th>
</tr>
<tr>
<td class="confluenceTd"><b>rolloverSelectedImageUrl</b>, <b>rolloverUnselectedImageUrl</b>, <b>rolloverUndefinedImageUrl</b>
</td>
<td class="confluenceTd"> These images will be applied when a mouse hovers over the component.</td>
</tr>
<tr>
<td class="confluenceTd"><b>pressedSelectedImageUrl</b>, <b>pressedUnselectedImageUrl</b>, <b>pressedUndefinedImageUrl</b>
</td>
<td class="confluenceTd"> These images will be applied when a checkbox is pressed.</td>
</tr>
<tr>
<td class="confluenceTd"><b>disabledSelectedImageUrl</b>, <b>disabledUnselectedImageUrl</b>, <b>disabledUndefinedImageUrl</b>
</td>
<td class="confluenceTd"> These images will be applied when a checkbox is disabled.</td>
</tr>
</tbody>
</table>
</div>
<h4><a name="SelectBooleanCheckbox2.x-ClientSideAPI"></a>Client-Side API</h4>
<p>All client-side API methods for the <cite>SelectBooleanCheckbox</cite> component are listed in the following
table:</p>
<div class="table-wrap">
<table class="confluenceTable">
<tbody>
<tr>
<th class="confluenceTh"> Method</th>
<th class="confluenceTh"> Description</th>
</tr>
<tr>
<td class="confluenceTd"><tt>isSelected()</tt></td>
<td class="confluenceTd"> Returns <i>true</i> if the checkbox is checked and <i>false</i> otherwise.
</td>
</tr>
<tr>
<td class="confluenceTd"><tt>setSelected(selected)</tt></td>
<td class="confluenceTd"> Checks or unchecks the checkbox when <i>true</i> or <i>false</i> is passed for
the <tt>selected</tt> parameter appropriately.
</td>
</tr>
<tr>
<td class="confluenceTd"><tt>isDefined()</tt></td>
<td class="confluenceTd"> Returns <i>true</i> if the checkbox is not in the "undefined" state, which is
possible only in the tri-state mode.
</td>
</tr>
<tr>
<td class="confluenceTd"><tt>setDefined(defined)</tt></td>
<td class="confluenceTd"> Allows switching the checkbox into the "undefined" state if this function is
called with a <i>false</i> value for the <tt>defined</tt> parameter.
</td>
</tr>
<tr>
<td class="confluenceTd"><tt>getDisabled()</tt></td>
<td class="confluenceTd"> Returns <i>true</i> if the checkbox is disabled and <i>false</i> otherwise.
</td>
</tr>
<tr>
<td class="confluenceTd"><tt>setDisabled(selected)</tt></td>
<td class="confluenceTd"> Disables or enables the checkbox when <i>true</i> or <i>false</i> is passed
for the <tt>selected</tt> parameter appropriately.
</td>
</tr>
</tbody>
</table>
</div>