Documentation

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

Textarea

Description

Purpose: A textarea is intended for entering multi-line texts.
Composition: Textarea fields will render an textarea HTML tag. If a limit is set, a byline about limitation is automatically set.
Effect: Textarea inputs are NOT restricted to one line of text. A textarea counts the amount of character input by user and displays the number.

Rivals

text field: Use a text field if users should input only one line of text.
numeric field: Use a numeric field if users should input numbers.
alphabet field: Use an alphabet field if the user should input single letters.

Rules

Usage

Textarea Input MUST NOT be used for choosing from predetermined options.
Textarea input MUST NOT be used for numeric input, a Numeric Field is to be used instead.
Textarea Input MUST NOT be used for letter-only input, an Alphabet Field is to be used instead.
Textarea Input MUST NOT be used for single-line input, a Text Field is to be used instead.
If a min. or max. number of characters is set for textarea, a byline MUST be added stating the number of min. and/or max. characters.

Interaction

Textarea Input MAY limit the number of characters, if a certain length of text-input may not be exceeded (e.g. due to database-limitations).

Example 1: Base

No result yet.

<?php
 
declare(strict_types=1);
 
namespace ILIAS\UI\examples\Input\Field\Textarea;
 
/**
 * Example show how to create and render a basic textarea field and attach it to a
 * form.
 */
function base()
{
    //Step 0: Declare dependencies
    global $DIC;
    $ui = $DIC->ui()->factory();
    $request = $DIC->http()->request();
    $renderer = $DIC->ui()->renderer();
 
    //Step 1: Define the textarea input field
    $textarea_input = $ui->input()->field()->textarea("Textarea Input", "Just a textarea input.");
 
    //Step 2: Define the form action to target the input processing
    $DIC->ctrl()->setParameterByClass(
        'ilsystemstyledocumentationgui',
        'example_name',
        'base'
    );
    $form_action = $DIC->ctrl()->getFormActionByClass('ilsystemstyledocumentationgui');
 
    //Step 3: Define the form and form actions.
    $form = $ui->input()->container()->form()->standard($form_action, [$textarea_input]);
 
    //Step 4: Define some data processing.
    if ($request->getMethod() == "POST" && $request->getQueryParams()['example_name'] == 'base') {
        $form = $form->withRequest($request);
        $result = $form->getData();
    } else {
        $result = "No result yet.";
    }
 
    //Step 5: Render the form with the text input field
    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\Textarea;
 
/**
 * Example show how to create and render a disabled textarea field and attach it to a
 * form.
 */
function disabled()
{
    //Step 0: Declare dependencies
    global $DIC;
    $ui = $DIC->ui()->factory();
    $renderer = $DIC->ui()->renderer();
    $ctrl = $DIC->ctrl();
    $request = $DIC->http()->request();
 
    //Step 1: Define the textarea input field
    $textarea_input = $ui->input()->field()->textarea("Disabled Textarea Input", "Just a disabled textarea input.")
        ->withDisabled(true);
 
    //Step 2: Define the form action to target the input processing
    $DIC->ctrl()->setParameterByClass(
        'ilsystemstyledocumentationgui',
        'example_name',
        'disabled'
    );
    $form_action = $DIC->ctrl()->getFormActionByClass('ilsystemstyledocumentationgui');
 
    //Step 3: Define the form and form actions.
    $form = $ui->input()->container()->form()->standard($form_action, [$textarea_input]);
 
    //Step 4: implement some form data processing.
    if ($request->getMethod() == "POST" && $request->getQueryParams()['example_name'] == 'disabled') {
        $form = $form->withRequest($request);
        $result = $form->getData();
    } else {
        $result = "No result yet.";
    }
 
    //Step 5: Render the form with the text input field
    return
        "<pre>" . print_r($result, true) . "</pre><br/>" .
        $renderer->render($form);
}

Example 3: With limits

No result yet.

<?php
 
declare(strict_types=1);
 
namespace ILIAS\UI\examples\Input\Field\Textarea;
 
/**
 * This example shows how to create and render a basic textarea field with minimum and maximum number of characters limit.
 * the input is attached to a form.
 */
function with_limits()
{
    //Step 0: Declare dependencies
    global $DIC;
    $ui = $DIC->ui()->factory();
    $renderer = $DIC->ui()->renderer();
    $ctrl = $DIC->ctrl();
    $request = $DIC->http()->request();
 
    $min_limit = 3;
    $max_limit = 20;
 
    //Step 1: Define the textarea input field
    $textarea_input = $ui->input()->field()->textarea("Textarea Input", "Just a textarea input.")->withMinLimit($min_limit)->withMaxLimit($max_limit);
 
    //Step 2: Define the form action to target the input processing
    $DIC->ctrl()->setParameterByClass(
        'ilsystemstyledocumentationgui',
        'example_name',
        'with_limits'
    );
    $form_action = $DIC->ctrl()->getFormActionByClass('ilsystemstyledocumentationgui');
 
    //Step 3: Define the form and form actions.
    $form = $ui->input()->container()->form()->standard($form_action, [$textarea_input]);
 
    //Step 4: implement some form data processing.
    if ($request->getMethod() == "POST" && $request->getQueryParams()['example_name'] == 'with_limits') {
        $form = $form->withRequest($request);
        $result = $form->getData();
    } else {
        $result = "No result yet.";
    }
 
    //Step 5: Render the form with the text input field
    return
        "<pre>" . print_r($result, true) . "</pre><br/>" .
        $renderer->render($form);
}

Relations

Parents

UIComponent
Input
Field