Checkbox

Zend\Form\Element\Checkbox is meant to be paired with the Zend\Form\View\Helper\FormCheckbox for HTML inputs with type checkbox. This element adds an InArray validator to its input filter specification in order to validate on the server if the checkbox contains either the checked value or the unchecked value.

Basic Usage

This element automatically adds a "type" attribute of value "checkbox".

use Zend\Form\Element;
use Zend\Form\Form;

$checkbox = new Element\Checkbox('checkbox');
$checkbox->setLabel('A checkbox');
$checkbox->setUseHiddenElement(true);
$checkbox->setCheckedValue("good");
$checkbox->setUncheckedValue("bad");

$form = new Form('my-form');
$form->add($checkbox);

Using the array notation:

use Zend\Form\Form;

$form = new Form('my-form');
$form->add(array(
    'type' => 'Zend\Form\Element\Checkbox',
    'name' => 'checkbox',
    'options' => array(
        'label' => 'A checkbox',
        'use_hidden_element' => true,
        'checked_value' => 'good',
        'unchecked_value' => 'bad'
    )
));

When creating a checkbox element, setting an attribute of checked will result in the checkbox always being checked regardless of any data object which might subsequently be bound to the form. The correct way to set the default value of a checkbox is to set the value attribute as for any other element. To have a checkbox checked by default make the value equal to the checked_value eg:

use Zend\Form\Form;

$form = new Form('my-form');
$form->add(array(
    'type' => 'Zend\Form\Element\Checkbox',
    'name' => 'checkbox',
    'options' => array(
        'label' => 'A checkbox',
        'use_hidden_element' => true,
        'checked_value' => 'yes',
        'unchecked_value' => 'no'
    ),
    'attributes' => array(
         'value' => 'yes'
    )
));

Public Methods

The following methods are in addition to the inherited methods of Zend\Form\Element .

setOptions(array $options)

Set options for an element of type Checkbox. Accepted options, in addition to the inherited options of Zend\Form\Element , are: "use_hidden_element", "checked_value" and "unchecked_value" , which call setUseHiddenElement, setCheckedValue and setUncheckedValue , respectively.

setUseHiddenElement(boolean $useHiddenElement)

If set to true (which is default), the view helper will generate a hidden element that contains the unchecked value. Therefore, when using custom unchecked value, this option have to be set to true.

useHiddenElement()

Return if a hidden element is generated.

Return type:boolean

setCheckedValue(string $checkedValue)

Set the value to use when the checkbox is checked.

getCheckedValue()

Return the value used when the checkbox is checked.

Return type:string

setUncheckedValue(string $uncheckedValue)

Set the value to use when the checkbox is unchecked. For this to work, you must make sure that use_hidden_element is set to true.

getUncheckedValue()

Return the value used when the checkbox is unchecked.

Return type:string

getInputSpecification()

Returns a input filter specification, which includes a Zend\Validator\InArray to validate if the value is either checked value or unchecked value.

Return type:array

isChecked()

Checks if the checkbox is checked.

Return type:boolean

setChecked(bool $value)

Checks or unchecks the checkbox.