Bitte zum Testen nur aktuelle Browser verwenden! ILIAS unterstützt alle aktuellen Browser wie z.B. Firefox, Safari, Microsoft Edge, Chrome und Chromium. Der von Micosoft nicht mehr unterstützte und weiterentwickelte 'Internet Explorer' kann nicht zum Testen von ILIAS 7 verwendet werden.
Testers are the best!

Documentation

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

Standard

Description

Purpose
Standard Forms are used for creating content of sub-items or for configuring objects or services.
Composition
Standard forms provide a submit-button.
Effect
The users manipulates input-values and saves the form to apply the settings to the object or service or create new entities in the system.

Rules

Usage
  1. Standard Forms MUST NOT be used on the same page as tables.
  2. Standard Forms MUST NOT be used on the same page as toolbars.
Composition
  1. Each form SHOULD contain at least one section displaying a title.
  2. Standard Forms MUST only be submitted by their submit-button. They MUST NOT be submitted by anything else.
  3. Wording of labels of the fields the form contains and their ordering MUST be consistent with identifiers in other objects if some for is used there for a similar purpose. If you feel a wording or ordering needs to be changed, then you MUST propose it to the JF.
  4. On top and bottom of a standard form there SHOULD be the “Save” button for the form.
  5. In some rare exceptions the Buttons MAY be named differently: if “Save” is clearly a misleading since the action is more than storing the data into the database. “Send Mail” would be an example of this.

Example 1: Base

Section 1

Just some basic input
/**
 * Example show how to create and render a basic form with one input. 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 some input field to plug into the form.
    $text_input = $ui->input()->field()->text("Basic Input", "Just some basic input");
 
    //Step 2: Define some section carrying a title and description with the previously
    //defined input
    $section1 = $ui->input()->field()->section([$text_input], "Section 1", "Description of Section 1");
 
    //Step 3: Define the form and attach the section.
    $form = $ui->input()->container()->form()->standard("", [$section1]);
 
    //Step 4: Render the form
    return $renderer->render($form);
}
 

Example 2: Data processing

No result yet.

Put in the name of a number from one to ten.
Put in the name of a number from one to ten.
/**
 * Example showing how constraints and transformation can be attached to a form.
 */
function data_processing()
{
    //Step 0: Declare dependencies
    global $DIC;
    $ui = $DIC->ui()->factory();
    $renderer = $DIC->ui()->renderer();
    $request = $DIC->http()->request();
    $refinery = $DIC->refinery();
    //Step 1: Define transformations
    $sum = $refinery->custom()->transformation(function ($vs) {
        list($l, $r) = $vs;
        $s = $l + $r;
        return "$l + $r = $s";
    });
 
    $from_name = $refinery->custom()->transformation(function ($v) {
        switch ($v) {
            case "one": return 1;
            case "two": return 2;
            case "three": return 3;
            case "four": return 4;
            case "five": return 5;
            case "six": return 6;
            case "seven": return 7;
            case "eight": return 8;
            case "nine": return 9;
            case "ten": return 10;
        }
        throw new \LogicException("PANIC!");
    });
 
    //Step 2: Define custom constraint
    $valid_number = $refinery->custom()->constraint(function ($v) {
        return in_array($v, ["one", "two", "three", "four", "five", "six", "seven", "eight", "nine", "ten"]);
    }, "This is not a number I know...");
 
    //Step 3: Define the input field and attach the previously defined constraint an
    // validation.
    $number_input = $ui->input()->field()
        ->text("number", "Put in the name of a number from one to ten.")
        ->withAdditionalTransformation($valid_number)
        ->withAdditionalTransformation($from_name);
 
    //Step 4: Define the form action to target the input processing
    $DIC->ctrl()->setParameterByClass(
        'ilsystemstyledocumentationgui',
        'example_name',
        'data_processing'
    );
    $form_action = $DIC->ctrl()->getFormActionByClass('ilsystemstyledocumentationgui');
 
    //Step 5: Define the form, plugin the inputs and attach some transformation acting
    // on the complete input of the form.
    $form = $ui->input()->container()->form()->standard(
        $form_action,
        [ $number_input->withLabel("Left")
        , $number_input->withLabel("Right")
        ]
    )
        ->withAdditionalTransformation($sum);
 
    //Step 6: Define some data processing.
    if ($request->getMethod() == "POST"
            && $request->getQueryParams()['example_name'] == 'data_processing') {
        $form = $form->withRequest($request);
        $result = $form->getData();
    } else {
        $result = "No result yet.";
    }
 
    //Step 7: Render the form and the result of the data processing
    return
        "<pre>" . print_r($result, true) . "</pre><br/>" .
        $renderer->render($form);
}
 

Example 3: With keys

No result yet.

Any Input
Any Input
/**
 * Example showing how keys can be used when attaching input fields to a form.
 */
function with_keys()
{
    //Step 0: Declare dependencies
    global $DIC;
    $ui = $DIC->ui()->factory();
    $renderer = $DIC->ui()->renderer();
    $request = $DIC->http()->request();
 
    //Step 1: Define the input fields
    $some_input = $ui->input()->field()
        ->text("Input", "Any Input");
 
    //Step 2: Define the form action to target the input processing
    $DIC->ctrl()->setParameterByClass(
        'ilsystemstyledocumentationgui',
        'example_name',
        'keys'
    );
    $form_action = $DIC->ctrl()->getFormActionByClass('ilsystemstyledocumentationgui');
 
    //Step 5: Define the form, plugin the inputs and attach some transformation acting
    // on the complete input of the form.
    $form = $ui->input()->container()->form()->standard(
        $form_action,
        [ 'input1' => $some_input->withLabel("Input 1")
        , 'input2' => $some_input->withLabel("Input 2")
        ]
    );
 
    //Step 6: Define some data processing.
    if ($request->getMethod() == "POST"
            && $request->getQueryParams()['example_name'] == 'keys') {
        $form = $form->withRequest($request);
        $result = $form->getData();
    } else {
        $result = "No result yet.";
    }
 
    //Step 7: Render the form and the result of the data processing
    return
        "<pre>" . print_r($result, true) . "</pre><br/>" .
        $renderer->render($form);
}
 

Example 4: With required input

Section with required field

User needs to fill this field
 
declare(strict_types=1);
 
/**
 * Example showing a Form with required fields. An explaining hint is displayed below the Form.
 */
function with_required_input()
{
    global $DIC;
    $ui = $DIC->ui()->factory();
    $renderer = $DIC->ui()->renderer();
 
    $text_input = $ui->input()->field()
        ->text("Required Input", "User needs to fill this field")
        ->withRequired(true);
 
    $section = $ui->input()->field()->section(
        [$text_input], 
        "Section with required field", 
        "The Form should show an explaining hint at the bottom"
    );
 
    $form = $ui->input()->container()->form()->standard("", [$section]);
    return $renderer->render($form);
}
 

Relations

Parents
  1. UIComponent
  2. Input
  3. Container
  4. Form