Documentation

Kitchen Sink documentation of style: 'Delos' of skin: 'ILIAS'

Checkbox

Description

Purpose: A checkbox is used to govern a state, action, or set / not to set a value. Checkboxes are typically used to switch on some additional behaviour or services.
Composition: Each Checkbox is labeled by an identifier stating something positive to describe the effect of checking the Checkbox.
Effect: If used in a form, a checkbox may open a dependant section (formerly known as sub form).

Rules

Usage

A checkbox MUST NOT be used whenever a user has to perform a binary choice where option is not automatically the inverse of the other (such as 'Order by Date' and 'Order by Name'). A Select Input or a Radio Group in MUST be used in this case.

Wording

The checkbox’s identifier MUST always state something positive.

Example 1: Base

No result yet.

<?php
 
declare(strict_types=1);
 
namespace ILIAS\UI\examples\Input\Field\Checkbox;
 
/**
 * Base example showing how to plug a checkbox into a form
 */
function base()
{
    //Step 0: Declare dependencies
    global $DIC;
    $ui = $DIC->ui()->factory();
    $renderer = $DIC->ui()->renderer();
    $request = $DIC->http()->request();
 
    //Step 1: define the checkbox, and turning it on
    $checkbox_input = $ui->input()->field()->checkbox("Checkbox", "Check or not.")
            ->withValue(true);
 
    //Step 2: define form and form actions
    $form = $ui->input()->container()->form()->standard('#', [ $checkbox_input]);
 
    //Step 3: implement some form data processing. Note, the value of the checkbox will
    // be 'checked' if checked an null if unchecked.
    if ($request->getMethod() == "POST") {
        $form = $form->withRequest($request);
        $result = $form->getData();
    } else {
        $result = "No result yet.";
    }
 
    //Step 4: Render the checkbox with the enclosing form.
    return
        "<pre>" . print_r($result, true) . "</pre><br/>" .
        $renderer->render($form);
}

Example 2: Disabled

No result yet.

<?php
 
declare(strict_types=1);
 
namespace ILIAS\UI\examples\Input\Field\Checkbox;
 
/**
 * Example showing how to plug a disabled checkbox into a form
 */
function disabled()
{
    //Step 0: Declare dependencies
    global $DIC;
    $ui = $DIC->ui()->factory();
    $renderer = $DIC->ui()->renderer();
    $request = $DIC->http()->request();
 
    //Step 1: define the checkbox, and making it disabled
    $checkbox_input = $ui->input()->field()->checkbox("Checkbox", "Cannot check.")
        ->withDisabled(true);
 
    //Step 2: define form and form actions
    $form = $ui->input()->container()->form()->standard('#', [ $checkbox_input]);
 
    //Step 3: implement some form data processing. Note, the value of the checkbox will
    // be 'checked' if checked and null if unchecked.
    if ($request->getMethod() == "POST") {
        $form = $form->withRequest($request);
        $result = $form->getData();
    } else {
        $result = "No result yet.";
    }
 
    //Step 4: Render the checkbox with the enclosing form.
    return
        "<pre>" . print_r($result, true) . "</pre><br/>" .
        $renderer->render($form);
}

Relations

Parents

UIComponent
Input
Field