Documentation

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

Optional Group

Description

Purpose: An optional group is a collection of input where the user needs to make a conscious decision to use or not use the provided inputs.
Composition: An optional group is composed of a checkbox that bears the label and the byline of the group and the contained inputs that are arranged in a way to make them visually belong to the checkbox.
Effect: If the checkbox is checked, the contained inputs are revealed, while they are hidden when the checkbox is not checked.

Rules

Usage

There MUST NOT be a nesting of more than one optional and/or switchable group. The only exception to this rule is the required quantification of a subsetting by a date or number. These exceptions MUST individually accept by the Jour Fixe.

Example 1: Base

No result yet.

<?php
 
declare(strict_types=1);
 
namespace ILIAS\UI\examples\Input\Field\OptionalGroup;
 
/**
 * Example showing how a dependant group (aka sub form) might be attached to a checkbox.
 */
function base()
{
    //Step 0: Declare dependencies
    global $DIC;
    $ui = $DIC->ui()->factory();
    $renderer = $DIC->ui()->renderer();
    $request = $DIC->http()->request();
 
    //Step 1: Define the fields in the group
    $dependant_field = $ui->input()->field()->text("Item 1", "Just some dependent group field");
    $dependant_field2 = $ui->input()->field()->datetime("Item 2", "a dependent date");
 
    //Step 2: define the checkbox and attach the dependant group
    $checkbox_input = $ui->input()->field()->optionalGroup(
        [
            "dependant_text" => $dependant_field,
            "dependant_date" => $dependant_field2
        ],
        "Optional Group",
        "Check to display group field."
    );
 
    //Step 3: define form and form actions
    $form = $ui->input()->container()->form()->standard('#', [ $checkbox_input]);
 
    //Step 4: 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 5: Render the checkbox with the enclosing form.
    return
        "<pre>" . print_r($result, true) . "</pre><br/>" .
        $renderer->render($form);
}

Example 2: With required sub inputs

No result yet.

<?php
 
declare(strict_types=1);
 
namespace ILIAS\UI\examples\Input\Field\OptionalGroup;
 
/**
 * Example showing how an optional group (of inputs) which shows, that
 * the optional input will not be required even though it's sub inputs
 * are.
 */
function with_required_sub_inputs()
{
    global $DIC;
    $factory = $DIC->ui()->factory();
    $renderer = $DIC->ui()->renderer();
    $request = $DIC->http()->request();
 
    $optional_group = $factory->input()->field()->optionalGroup([
        $factory->input()->field()->text(
            'this input is required',
            'but only if the optional group is checked'
        )->withRequired(true)
    ], 'this input is not required');
 
    $form = $factory->input()->container()->form()->standard('#', [$optional_group]);
 
    if ("POST" === $request->getMethod()) {
        $form = $form->withRequest($request);
        $result = $form->getData();
    } else {
        $result = "No result yet.";
    }
 
    return "<pre>" . print_r($result, true) . "</pre>" . $renderer->render($form);
}

Relations

Parents

UIComponent
Input
Field