View Source

h3. Overview

The checkboxButton component is a simple true/false selection used to toggle a value that is bound to the button. When singleSubmit="true" the value will be submitted to the server. When "false", the value is maintained by the client until some other component submits the form the checkboxButton occurs in.

NOTE that rendering with class="ice-skin-sam" renders this component as a checkbutton (use label attr with labelPosition="on")
with class="ice-skin-rime" it is rendered as a checked box (use labelPosition="left")

h3. Usage
{code}
<html ... xmlns:ace="http://www.icefaces.org/icefaces/components">
<!-- can use either ice-skin-sam or ice-skin-rime -->
<h:body class="ice-skin-rime">
<h:form>
<ace:checkboxButton
value="{button.checkedRime}"
labelPosition="left"
label="checkedRime"
singleSubmit="true"/>
</h:form>
</h:body>
</html>
{code}
{code}
<h:panelGroup styleClass="ice-skin-sam">
<ace:checkboxButton
value="#{button.checkedSam}"
label="checkedSam"
        labelPosition="on"
singleSubmit="false"/>
</h:panelGroup>
{code}
h3. Attributes

{info:title=TagLib Documentation}This section covers attributes involved in the typical use-cases for this component. For reference, the complete taglib documentation for this component is available [here|http://www.icefaces.org/docs/v2_0_0b2/ace/taglibdoc/ice/checkboxButton.html].{info}
{panel}
*value* the value binding (bean) tied to the value of the checkboxButton-usually to a backing bean through el.
{panel}
{panel}
*label* The label of the button-what the user sees that relates to that particular button. For example, "Remember Me"
{panel}
{panel}
*labelPosition* position of the label. For ice-skin-sam, the label is placed directly on the button itself so labelPosition is "on". For ice-skin-rime, the label is placed to the left of the button, so labelPosition="left"
{panel}
{panel}
*style* a pass through to the root element of the component.
{panel}
{panel}
*styleClass* a pass through to the root element of the component.
{panel}
{panel}
*tabindex* a pass through to the root element of the component, default=0.
{panel}
{panel}
*disabled* a pass through to the root element of the component.
{panel}
{panel}
*singleSubmit* When singleSubmit attribute is true, the checkbox only submits an event request to the server representing an ajax call with execute=@this and render=@all, if false then only the hidden field is updated on the client and some other component must submit the form for the server model side to be updated.

Default is "true"
{panel}
h3. ARIA and Keyboard Navigation Support

To enable/disable ARIA at page level, the [<icecore:config>|Core Tags#icecoreconfig] tag can used:
{code}
<icecore:config ariaEnabled="true"/>
{code}
To enable/disable ARIA at application level, the following param can be set in web.xml.
{code}
<context-param>
<param-name>org.icefaces.aria.enabled</param-name>
<param-value>false</param-value>
</context-param>
{code}
{panel}
* the space key will toggle the checkbox/checkbutton
{panel}Aria role="button", aria-describedby and aria-disabled properties supported as well as aria-checked.
The ARIA implementation is based on the specification at [check box aria practices|http://www.w3.org/TR/wai-aria-practices/#checkbox]. Currently only the basic ARIA attributes and single-key keyboard shortcuts have been implemented.

h4. Storyboard

|| Action || focus || hover || checked || disabled || onkeypress || aria ||
|| yui-class | yui-button-focus | yui-button-hover | yui-button-checked | yui-button-disabled | space or enter will submit | role, disabled, description, checked ||
|| Submit | | | submit button &update component | none | submit button/update component | ||
|| Single Submit | | | stay on client/update hidden field | none | update hidden field | ||
|| Screen Reader | description | description | role,description, checkedvalue | role | & checked value | ||