Documentation

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

Multi Select

Description

Purpose: A Multi Select is used to allow users to pick several options from a list.
Composition: The Multi Select field will render labeled checkboxes according to given options.

Rivals

Checkbox Field: Use a Checkbox Field for a binary yes/no choice.
Tag Field: Use a Tag Input when the user is able to extend the list of given options.
Select Field: Use a Select Input when the user's choice is limited to one option or the options are mutually exclusive.

Rules

Usage

A Multi Select input SHOULD be used when a user has to choose from a finite list of options which cannot be extended by the user's input and where more than one choice can be made.
A Multi Select input MUST NOT be used whenever a user has to perform a binary choice where option is automatically the inverse of the other. A Checkbox MUST be used in this case.
A Multi Select input MUST NOT be used whenever a user has to perform a choice from a list of options where only one option can be selected. A Select MUST be used in this case

Wording

Each option MUST be labeled.
If the option governs a change of (service-)behavior, the option's label MUST be in form of a positive statement.

Example 1: Base

No result yet.

<?php
 
declare(strict_types=1);
 
namespace ILIAS\UI\examples\Input\Field\MultiSelect;
 
/**
 * Base example showing how to plug a Multi-Select into a form
 */
function base()
{
    //declare dependencies
    global $DIC;
    $ui = $DIC->ui()->factory();
    $renderer = $DIC->ui()->renderer();
    $request = $DIC->http()->request();
 
    //define options.
    $options = array(
        "1" => "Pick 1",
        "2" => "Pick 2",
        "3" => "Pick 3",
        "4" => "Pick 4",
    );
 
    //define the select
    $multi = $ui->input()->field()->multiselect("Take your picks", $options, "This is the byline text")
        ->withRequired(true);
 
    //define form and form actions
    $form = $ui->input()->container()->form()->standard('#', ['multi' => $multi]);
 
 
    //implement some form data processing.
    if ($request->getMethod() == "POST") {
        try {
            $form = $form->withRequest($request);
            $result = $form->getData();
        } catch (\InvalidArgumentException $e) {
            $result = "No result. Probably, the other form was used.";
        }
    } else {
        $result = "No result yet.";
    }
 
    //render the select with the enclosing form.
    return
        "<pre>" . print_r($result, true) . "</pre><br/>" .
        $renderer->render($form);
}

Example 2: Empty options

No result yet.

<?php
 
declare(strict_types=1);
 
namespace ILIAS\UI\examples\Input\Field\MultiSelect;
 
/**
 * Multi-Select without options
 */
function empty_options()
{
    global $DIC;
    $ui = $DIC->ui()->factory();
    $renderer = $DIC->ui()->renderer();
    $request = $DIC->http()->request();
 
    $multi = $ui->input()->field()
        ->multiselect("No options", []);
 
    $form = $ui->input()->container()->form()->standard('#', ['empty' => $multi]);
 
    if ($request->getMethod() == "POST") {
        try {
            $form = $form->withRequest($request);
            $result = $form->getData();
        } catch (\InvalidArgumentException $e) {
            $result = "No result. Probably, the other form was used.";
        }
    } else {
        $result = "No result yet.";
    }
 
    return
        "<pre>" . print_r($result, true) . "</pre><br/>" .
        $renderer->render($form);
}

Relations

Parents

UIComponent
Input
Field