apache > cocoon

- Home

# Booleanfield widget

## Concept

An fd:booleanfield is a field that has a value of true or false. Usually is rendered as a checkbox.

It is different from a field widget with a `boolean` datatype because an HTML checkbox submits no request parameter if the checkbox is unchecked. If you would render it instead as a listbox with true and false values, you could also use a regular field widget. Since the styling preference might change over time, it is however better to use consistently the fd:booleanfield widget.

A booleanfield cannot be marked as "required", because it is always required. It is either true or false. If you want tripples (true/false/none), use a normal field widget with a selection list.

## Definition

    <fd:booleanfield id="..." state="...">
      <fd:true-param-value>...</fd:true-param-value>
      <fd:initial-value>...</fd:initial-value>
      <fd:label>...</fd:label>
      <fd:help>...</fd:help>
      <fd:hint>...</fd:hint>
      <fd:validation>
        [...]
      </fd:validation>
      <fd:on-value-changed>
         [...]
      </fd:on-value-changed>
      <fd:on-create>
         [...]
      </fd:on-create>
      <fd:attributes>
        <fd:attribute name="..." value="..."/>
      </fd:attributes>
    </fd:booleanfield>

See field widget for a description of the configuration options.

The optional element fd:true-param-value specifies the parameter value that indicates true. By default this is "true".

## Template

A booleanfield widget is inserted in a template using the ft:widget tag:

    <ft:widget id="..."/>

## Styling (default HTML XSL)

A booleanfield is rendered as a checkbox. To make the checkbox user-friendly, make sure the label of the checkbox is associated with the checkbox, so that the user can also click the label to (de)select the checkbox:

    <ft:widget id="someId"/> <label for="someId-input"><ft:widget-label id="someId"/></label>

This is automatically taken care of when using the columns group layout as explained here.

Errors and Improvements? If you see any errors or potential improvements in this document please help us: View, Edit or comment on the latest development version (registration required).