Documentation

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

Radio

Description

Purpose: A Radio Input is used to depict a choice of options excluding each other.
Composition: The Radio is considered as one field with a label and a number of options. Each option in turn bears a label in form of a positive statement.
Effect: If used in a form, each option of a Radio may open a Dependant Section (formerly known as Sub Form).

Rivals

Checkbox Field: Use a Checkbox Field for a binary yes/no choice.
Select: Use Selects to choose items from a longer list as the configuration of an aspect; when the choice has severe effects on, e.g. service behavior, or needs further configuration, stick to radios.

Rules

Usage

A Radio Input SHOULD contain 3 to 5 options. If there are more, the Select Input might be the better option.
Radios MAY also be used to select between two options where one is not automatically the inverse of the other

Wording

Each option MUST be labeled.
The options' labels MUST state something positive.
An option's label SHOULD not simply repeat the label of the Radio. A meaningful labeling SHOULD be chosen instead.

Ordering

The presumably most relevant option SHOULD be the first option.

Example 1: Base

No result yet.

<?php
 
declare(strict_types=1);
 
namespace ILIAS\UI\examples\Input\Field\Radio;
 
/**
 * Base example showing how to plug a radio into a form
 */
function base()
{
    //Step 1: Declare dependencies
    global $DIC;
    $ui = $DIC->ui()->factory();
    $renderer = $DIC->ui()->renderer();
    $request = $DIC->http()->request();
 
    //Step 2: define the radio with options
    $radio = $ui->input()->field()->radio("Radio", "check an option")
        ->withOption('value1', 'label1', 'byline1')
        ->withOption('10', 'numeric value (ten)', 'byline2')
        ->withOption('030', 'not-numeric value', 'byline3');
 
    //Step 3: define form and form actions
    $form = $ui->input()->container()->form()->standard('#', ['radio' => $radio]);
 
    //Step 4: implement some form data processing.
    if ($request->getMethod() == "POST") {
        $form = $form->withRequest($request);
        $result = $form->getData();
    } else {
        $result = "No result yet.";
    }
 
    //Step 5: Render the radio 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\Radio;
 
/**
 * Example showing how to plug a disabled radio 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 radio
    $radio = $ui->input()->field()->radio("Radio", "Cannot check an option")
        ->withOption('value1', 'label1')
        ->withOption('value2', 'label2')
        ->withOption('value3', 'label3')
        ->withDisabled(true);
 
 
    //Step 2: define form and form actions
    $form = $ui->input()->container()->form()->standard('#', ['radio' => $radio]);
 
    //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 radio with the enclosing form.
    return
        "<pre>" . print_r($result, true) . "</pre><br/>" .
        $renderer->render($form);
}

Relations

Parents

UIComponent
Input
Field