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 form in modal

no results yet.

<?php
 
declare(strict_types=1);
 
namespace ILIAS\UI\examples\Modal\RoundTrip;
 
function show_form_in_modal()
{
    global $DIC;
 
    $renderer = $DIC->ui()->renderer();
    $request = $DIC->http()->request();
    $factory = $DIC->ui()->factory();
 
    // declare roundtrip with inputs and form action.
    $modal = $factory->modal()->roundtrip(
        'roundtrip with form',
        null,
        [
            $factory->input()->field()->text('some text'),
            $factory->input()->field()->numeric('some numbere'),
        ],
        '#'
    );
 
    // declare something that triggers the modal.
    $open = $factory->button()->standard('open modal', '#')->withOnClick($modal->getShowSignal());
 
    // please use ilCtrl to generate an appropriate link target
    // and check it's command instead of this.
    if ('POST' === $request->getMethod()) {
        $modal = $modal->withRequest($request);
        $data = $modal->getData();
    } else {
        $data = 'no results yet.';
    }
 
    return
        '<pre>' . print_r($data, true) . '</pre>' .
        $renderer->render([$open, $modal]);
}

Example 2: Show multi step modal

<?php
 
declare(strict_types=1);
 
namespace ILIAS\UI\examples\Modal\RoundTrip;
 
use ILIAS\UI\Implementation\Component\ReplaceSignal;
 
function show_multi_step_modal()
{
    global $DIC;
    $f = $DIC->ui()->factory();
    $r = $DIC->ui()->renderer();
    $refinery = $DIC->refinery();
    $request_wrapper = $DIC->http()->wrapper()->query();
 
    $url = $_SERVER['REQUEST_URI'];
 
    $page = "";
    if ($request_wrapper->has('page')) {
        $page = $request_wrapper->retrieve('page', $refinery->kindlyTo()->string());
    }
    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());
        return $r->render([$modal, $button]);
    } else {
        $signalId = "";
        if ($request_wrapper->has('replaceSignal')) {
            $signalId = $request_wrapper->retrieve('replaceSignal', $refinery->kindlyTo()->string());
        }
        $replaceSignal = new 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", [$legacy])->withActionButtons([$button1, $button2]);
        }
        if ($page == "register") {
            $legacy = $f->legacy("<p>The Registration Page</p>");
            $modal = $f->modal()->roundtrip("Registration", [$legacy])->withActionButtons([$button1, $button2]);
        }
 
        echo $r->renderAsync([$modal]);
        exit;
    }
}

Example 3: Show the same modal with different buttons

<?php
 
declare(strict_types=1);
 
namespace ILIAS\UI\examples\Modal\RoundTrip;
 
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);
}

Example 4: With custom labels

<?php
 
declare(strict_types=1);
 
namespace ILIAS\UI\examples\Modal\RoundTrip;
 
/**
 * An example showing how you can set a custom label for the
 * modals cancel-button.
 */
function with_custom_labels()
{
    global $DIC;
    $factory = $DIC->ui()->factory();
    $renderer = $DIC->ui()->renderer();
 
    $modal = $factory->modal()->roundtrip(
        'Showing something off',
        [
            $factory->messageBox()->info('I am something.'),
        ]
    )->withCancelButtonLabel(
        'Thank you and goodbye'
    )->withActionButtons([$factory->button()->standard('Nothing todo here', '#')]);
 
    $trigger = $factory->button()->standard('I will show you something', $modal->getShowSignal());
 
    return $renderer->render([$modal, $trigger]);
}

Relations

Parents

UIComponent
Modal