Documentation

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

Wrapper

Description

Purpose: A wrapper dropzone is used to display other ILIAS UI components inside it. In contrast to the standard dropzone, the wrapper dropzone is not visible by default. Only the wrapped components are visible. Any wrapper dropzone gets highlighted once the user is dragging files over the browser window. Thus, a user needs to have the knowledge that there are wrapper dropzones present. They can be introduced to offer additional approaches to complete some workflow more conveniently. Especially in situation where space is scarce such as appointments in the calendar.
Composition: A wrapper dropzone contains one or multiple ILIAS UI components. A roundtrip modal is used to present the dropped files and to initialize the upload process with a file input.
Effect: All wrapper dropzones on the page are highlighted when the user dragging files over the browser window. After dropping the files, the roundtrip modal is opened showing all files. The modal contains a button to start the upload process.

Rivals

Rival 1: A standard dropzone displays a message instead of other ILIAS UI components.

Rules

Usage

Most pages SHOULD NOT contain a wrapper dropzone. Whenever you want to introduce a new usage of the Wrapper-Dropzone, propose it to the Jour Fixe.
Wrapper dropzones MUST contain one or more ILIAS UI components.
Wrapper dropzones MUST NOT contain any other file dropzones.
Wrapper dropzones MUST NOT be used in modals.

Example 1: Base

no results yet.

Information Message

Drag and drop files onto me!

<?php
 
declare(strict_types=1);
 
namespace ILIAS\UI\examples\Dropzone\File\Wrapper;
 
function base()
{
    global $DIC;
 
    $factory = $DIC->ui()->factory();
    $renderer = $DIC->ui()->renderer();
    $request = $DIC->http()->request();
    $wrapper = $DIC->http()->wrapper()->query();
 
    $submit_flag = 'dropzone_wrapper_base';
    $post_url = "{$request->getUri()}&$submit_flag";
 
    $dropzone = $factory
        ->dropzone()->file()->wrapper(
            'Upload your files here',
            $post_url,
            $factory->messageBox()->info('Drag and drop files onto me!'),
            $factory->input()->field()->file(
                new \ilUIAsyncDemoFileUploadHandlerGUI(),
                'Your files'
            )
        );
 
    // please use ilCtrl to generate an appropriate link target
    // and check it's command instead of this.
    if ($wrapper->has($submit_flag)) {
        $dropzone = $dropzone->withRequest($request);
        $data = $dropzone->getData();
    } else {
        $data = 'no results yet.';
    }
 
    return '<pre>' . print_r($data, true) . '</pre>' .
        $renderer->render($dropzone);
}

Example 2: With additional input

no results yet.

Information Message

Drag and drop files onto me!

<?php
 
declare(strict_types=1);
 
namespace ILIAS\UI\examples\Dropzone\File\Wrapper;
 
function with_additional_input()
{
    global $DIC;
 
    $factory = $DIC->ui()->factory();
    $renderer = $DIC->ui()->renderer();
    $request = $DIC->http()->request();
    $wrapper = $DIC->http()->wrapper()->query();
 
    $submit_flag = 'dropzone_wrapper_with_additional_input';
    $post_url = "{$request->getUri()}&$submit_flag";
 
    $dropzone = $factory
        ->dropzone()->file()->wrapper(
            'Upload your files here',
            $post_url,
            $factory->messageBox()->info('Drag and drop files onto me!'),
            $factory->input()->field()->file(
                new \ilUIAsyncDemoFileUploadHandlerGUI(),
                'Your files'
            ),
            $factory->input()->field()->text(
                'Additional Input',
                'Additional input which affects all files of this upload.'
            )
        );
 
    // please use ilCtrl to generate an appropriate link target
    // and check it's command instead of this.
    if ($wrapper->has($submit_flag)) {
        $dropzone = $dropzone->withRequest($request);
        $data = $dropzone->getData();
    } else {
        $data = 'no results yet.';
    }
 
    return '<pre>' . print_r($data, true) . '</pre>' .
        $renderer->render($dropzone);
}

Example 3: With clear button

Information Message

Drag and drop files onto me!

<?php
 
declare(strict_types=1);
 
namespace ILIAS\UI\examples\Dropzone\File\Wrapper;
 
function with_clear_button()
{
    global $DIC;
 
    $factory = $DIC->ui()->factory();
    $renderer = $DIC->ui()->renderer();
    $request = $DIC->http()->request();
 
    $submit_flag = 'dropzone_wrapper_with_clear_button';
    $post_url = "{$request->getUri()}&$submit_flag";
 
    $dropzone = $factory
        ->dropzone()->file()->wrapper(
            'Upload your files here',
            $post_url,
            $factory->messageBox()->info('Drag and drop files onto me!'),
            $factory->input()->field()->file(
                new \ilUIAsyncDemoFileUploadHandlerGUI(),
                'Your files'
            )
        );
 
    $dropzone = $dropzone->withActionButtons([
        $factory->button()->standard('Clear files!', '#')->withOnClick($dropzone->getClearSignal())
    ]);
 
    return $renderer->render($dropzone);
}

Relations

Parents

UIComponent
Dropzone
File