Documentation

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

Roundtrip

Description

Purpose: Round-Trip modals are to be used if the context would be lost by performing this action otherwise. Round-Trip modals accommodate sub-workflows within an overriding workflow. The Round-Trip modal ensures that the user does not leave the trajectory of the overriding workflow. This is typically the case if an ILIAS service is being called while working in an object.
Composition: Round-Trip modals are completed by a well defined sequence of only a few steps that might be displayed on a sequence of different modals connected through some "next" button.
Effect: Round-Trip modals perform sub-workflow involving some kind of user input. Sub-workflow is completed and user is returned to starting point allowing for continuing the overriding workflow.

Rules

Usage

Round-Trip modals MUST contain at least two buttons at the bottom of the modals: a button to cancel (right) the workflow and a button to finish or reach the next step in the workflow (left).
Round-Trip modals SHOULD be used, if the user would lose the context otherwise. If the action can be performed within the same context (e.g. add a post in a forum, edit a wiki page), a Round-Trip modal MUST NOT be used.
When the workflow is completed, Round-Trip modals SHOULD show the same view that was displayed when initiating the modal.
Round-Trip modals SHOULD NOT be used to add new items of any kind since adding item is a linear workflow redirecting to the newly added item setting- or content-tab.
Round-Trip modals SHOULD NOT be used to perform complex workflows.

Wording

The label of the Button used to close the Round-Trip-Modal MAY be adapted, if the default label (cancel) does not fit the workflow presented on the screen.

Example 1: Show a modal which cannot be closed with the keyboard

function show_a_modal_which_cannot_be_closed_with_the_keyboard()
{
    global $DIC;
    $factory = $DIC->ui()->factory();
    $renderer = $DIC->ui()->renderer();
 
    $modal = $factory->modal()->roundtrip('My Modal 1', $factory->legacy('You cannot close this modal with the ESC key'));
    $modal = $modal->withCloseWithKeyboard(false);
    $button1 = $factory->button()->standard('Open Modal 1', '#')
        ->withOnClick($modal->getShowSignal());
 
    return $renderer->render([$button1, $modal]);
}

Example 2: Show form in modal

function show_form_in_modal()
{
    global $DIC;
    $factory = $DIC->ui()->factory();
    $renderer = $DIC->ui()->renderer();
 
    require_once('./Services/Form/classes/class.ilPropertyFormGUI.php');
    require_once('./Services/Form/classes/class.ilTextInputGUI.php');
    require_once('./Services/Form/classes/class.ilCountrySelectInputGUI.php');
 
    // Build the form
    $form = new ilPropertyFormGUI();
    $form->setId(uniqid('form'));
    $item = new ilTextInputGUI('Firstname', 'firstname');
    $item->setRequired(true);
    $form->addItem($item);
    $item = new ilTextInputGUI('Lastname', 'lastname');
    $item->setRequired(true);
    $form->addItem($item);
    $form->addItem(new ilCountrySelectInputGUI('Country', 'country'));
    $form->setFormAction("#");
    $item = new ilHiddenInputGUI('cmd');
    $item->setValue('submit');
    $form->addItem($item);
 
    // Build a submit button (action button) for the modal footer
    $form_id = 'form_' . $form->getId();
    $submit = $factory->button()->primary('Submit', '#')
        ->withOnLoadCode(function ($id) use ($form_id) {
            return "$('#{$id}').click(function() { $('#{$form_id}').submit(); return false; });";
        });
 
    // Check if the form was submitted, if validation fails, show it again in a modal
    $out = '';
    $valid = true;
    if (isset($_POST['cmd']) && $_POST['cmd'] == 'submit') {
        if ($form->checkInput()) {
            $panel = $factory->panel()->standard('Form validation successful', $factory->legacy(print_r($_POST, true)));
            $out = $renderer->render($panel);
        } else {
            $form->setValuesByPost();
            $valid = false;
        }
    }
 
    $modal = $factory->modal()->roundtrip('User Details', $factory->legacy($form->getHTML()))
        ->withActionButtons([$submit]);
 
    // The modal triggers its show signal on load if validation failed
    if (!$valid) {
        $modal = $modal->withOnLoad($modal->getShowSignal());
    }
    $button1 = $factory->button()->standard('Show Form', '#')
        ->withOnClick($modal->getShowSignal());
 
    return $renderer->render([$button1, $modal]) . $out;
}

Example 3: Show multi step modal

function show_multi_step_modal()
{
    global $DIC;
    $f = $DIC->ui()->factory();
    $r = $DIC->ui()->renderer();
 
    $url = $_SERVER['REQUEST_URI'];
 
    $page = $_GET["page"];
    if ($page == "") {
        $modal = $f->modal()->roundtrip("Modal Title", $f->legacy("b"));
        $asyncUrl = $url . '&page=login&replaceSignal=' . $modal->getReplaceSignal()->getId();
        $modal = $modal->withAsyncRenderUrl($asyncUrl);
        $button = $f->button()->standard("Sign In", '#')
            ->withOnClick($modal->getShowSignal());
        $content = $r->render([$modal, $button]);
        return $content;
    } else {
        $signalId = $_GET['replaceSignal'];
        $replaceSignal = new \ILIAS\UI\Implementation\Component\ReplaceSignal($signalId);
        $button1 = $f->button()->standard('Login', '#')
            ->withOnClick($replaceSignal->withAsyncRenderUrl($url . '&page=login&replaceSignal=' . $replaceSignal->getId()));
        $button2 = $f->button()->standard('Registration', '#')
            ->withOnClick($replaceSignal->withAsyncRenderUrl($url . '&page=register&replaceSignal=' . $replaceSignal->getId()));
 
        $modal = null;
        if ($page == "login") {
            $legacy = $f->legacy("<p>The Login Page</p>");
            $modal = $f->modal()->roundtrip("Login", [$button1, $button2, $legacy]);
        }
        if ($page == "register") {
            $legacy = $f->legacy("<p>The Registration Page</p>");
            $modal = $f->modal()->roundtrip("Registration", [$button1, $button2, $legacy]);
        }
 
        echo $r->renderAsync([$modal]);
        exit;
    }
}

Example 4: Show the same modal with different buttons

function show_the_same_modal_with_different_buttons()
{
    global $DIC;
    $factory = $DIC->ui()->factory();
    $renderer = $DIC->ui()->renderer();
 
    $modal = $factory->modal()->roundtrip('My Modal 1', $factory->legacy('My Content'))
        ->withActionButtons([
            $factory->button()->primary('Primary Action', ''),
            $factory->button()->standard('Secondary Action', ''),
        ]);
 
    $out = '';
    $button1 = $factory->button()->standard('Open Modal 1', '#')
        ->withOnClick($modal->getShowSignal());
    $out .= ' ' . $renderer->render($button1);
 
    $button2 = $button1->withLabel('Also opens modal 1');
    $out .= ' ' . $renderer->render($button2);
 
    $button3 = $button2->withLabel('Does not open modal 1')
        ->withResetTriggeredSignals();
    $out .= ' ' . $renderer->render($button3);
 
    return $out . $renderer->render($modal);
}

Relations

Parents

UIComponent
Modal