Documentation

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

Tag

Description

Purpose: A Tag Input is used to choose a subset amount of tags (techn.: array of strings) out of a finite list of tags. The Tag Field SHOULD be used, whenever it is not required or not possible to display all available options, e.g. because the amount is too high when the options are "all users" or "all tags. Besides the tags to choose from, the user can provide own tags by typing them into the Input (@see Tag::withUserCreatedTagsAllowed).
Composition: The Input is presented as a text-input and prepended by already selected tags presented as texts including a close-button. (e.g. [ Amsterdam X ] ) The input is labeled by the label given. Suggested tags are listed in a dropdown-list beneath the text-input. All mentioned elements are not taken from the UI-Service.
Effect: As soon as the user types in the text-input, the Tag Input suggests matching tags from the given list of tags. Suggestions will appear after a defined amount of characters, one by default. Clicking on one of these tags closes the list and transfers the selected tag into the text-input, displayed as a tag with a close-button. By clicking on a close-button of a already selected tag, this tag will disappear from the Input. All mentioned elements are not taken from the UI-Service.

Context

Tag Input is used in forms.

Rules

Usage

A Tag 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 Tag Input MUST NOT be used whenever a user has to perform a choice from a list of options where only one Option has to be selected. A Select MUST be used in this case (Not yet part of the KitchenSink).
A Tag Input SHOULD be used whenever a User should be able to extend the list of given options.
A Tag Input MUST NOT be used when a User has to choose from a finite list of options which can't be extended by users Input, a Multi Select MUST be used in this case
The tags provided SHOULD NOT have long titles (50 characters).

Example 1: Base

<?php
 
declare(strict_types=1);
 
namespace ILIAS\UI\examples\Input\Field\Tag;
 
/**
 * Example show how to create and render a basic tag input field and attach it to a
 * form. This example does not contain any data processing.
 */
function base()
{
    //Step 0: Declare dependencies
    global $DIC;
    $ui = $DIC->ui()->factory();
    $renderer = $DIC->ui()->renderer();
 
    //Step 1: Define the tag input field
    $tag_input = $ui->input()->field()->tag(
        "Basic Tag",
        ['Interesting', 'Boring', 'Animating', 'Repetitious'],
        "Just some tags"
    );
 
 
    //Step 2: Define the form and attach the section.
    $form = $ui->input()->container()->form()->standard("#", [$tag_input]);
 
    //Step 3: Render the form with the text input field
    return $renderer->render($form);
}

Example 2: Base with data

No result yet.

<?php
 
declare(strict_types=1);
 
namespace ILIAS\UI\examples\Input\Field\Tag;
 
/**
 * Example show how to create and render a basic tag input field and attach it to a
 * form. This example does not contain any data processing.
 */
function base_with_data()
{
    // Step 0: Declare dependencies
    global $DIC;
    $ui = $DIC->ui()->factory();
    $renderer = $DIC->ui()->renderer();
    $request = $DIC->http()->request();
 
    // Step 1: Define the tag input field
    $tag_input = $ui->input()->field()->tag(
        "Basic TagInput",
        ['Interesting & fascinating', 'Boring, dull', 'Animating', 'Repetitious'],
        "Just some tags"
    );
 
    // Step 2, define form and form actions
    $form = $ui->input()->container()->form()->standard('#', ['f2' => $tag_input]);
 
    // Step 3, implement some form data processing.
    if ($request->getMethod() === "POST") {
        $form = $form->withRequest($request);
        $result = $form->getData();
    } else {
        $result = "No result yet.";
    }
 
    // Step 4, return the rendered form with data
    return "<pre>"
        . print_r($result, true)
        . "</pre><br/>"
        . $renderer->render($form);
}

Example 3: Base with value

<?php
 
declare(strict_types=1);
 
namespace ILIAS\UI\examples\Input\Field\Tag;
 
/**
 * Example show how to create and render a basic tag input field and attach it to a
 * form. This example does not contain any data processing.
 */
function base_with_value()
{
    //Step 0: Declare dependencies
    global $DIC;
    $ui = $DIC->ui()->factory();
    $renderer = $DIC->ui()->renderer();
 
    //Step 1: Define the tag input field
    $tag_input = $ui->input()->field()->tag(
        "Basic TagInput",
        ['Interesting', 'Boring', 'Animating', 'Repetitious'],
        "Just some tags"
    )->withValue(["Interesting"]);
 
    //Step 2, define form and form actions
    $form = $ui->input()->container()->form()->standard("#", [$tag_input]);
 
    //Return the rendered form
    return  $renderer->render($form);
}

Example 4: Disabled

<?php
 
declare(strict_types=1);
 
namespace ILIAS\UI\examples\Input\Field\Tag;
 
/**
 * Example show how to create and render a disabled tag input field and attach it to a
 * form. This example does not contain any data processing.
 */
function disabled()
{
    //Step 0: Declare dependencies
    global $DIC;
    $ui = $DIC->ui()->factory();
    $renderer = $DIC->ui()->renderer();
 
    //Step 1: Define the tag input field
    $tag_input = $ui->input()
        ->field()
        ->tag(
            "Basic Tag",
            ['Interesting', 'Boring', 'Animating', 'Repetitious'],
            "Just some tags"
        )->withDisabled(true)->withValue(["Boring", "Animating"]);
 
    //Step 2: Define the form and attach the section.
    $form = $ui->input()->container()->form()->standard("#", [$tag_input]);
 
    //Step 3: Render the form with the text input field
    return $renderer->render($form);
}

Relations

Parents

UIComponent
Input
Field