Documentation

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

Notification

Description

Purpose: Notifications in this context are messages from the system published to the user. Notification Items are used to bundle information (such as title and description) about such notifications and possible interactions with them (such as opening the mail folder containing a new mail).
Composition: Notification Items always contain a title and an icon, which indicates the service or module triggering the notification. They also contain a close button. They might contain meta data such as various properties or a description and they further contain a set of interactions allowing the user to react in various ways. The first of those interaction is placed on the title of the Notification Item. Notification Items might also aggregate information about a set of related notifications and display them in the form of such an aggregate.
Effect: The main interaction of the item is placed on the title and will be fired by clicking on the Notification Items title. If more than one is passed, they will be listed in a dropdown. The interaction fired by clicking on the Notification Item's title directs in most cases to some repository holding the entry which fired the notification. Clicking on the close button removes the Notification permanently. Exceptions are Notification Items displaying aggregated information. In such a case, clicking on the title displays the list of the Notifications being aggregated and it will only be closed if all Notifications being aggregated are closed.

Rules

Interaction

The main interaction offered by clicking on the Notification Items title SHOULD open some repository holding the entry which fired the notification (e.g. Mailbox in case of new Mail).
Clicking on the title of a Notification Item displaying aggregated information of other Notification Items will open a Notification Slate displaying those Notification Items.
Clicking on the Close Button MUST remove the Notification Item permanently from the list of Notification Items.
If the Notification Item aggregates information on other Notification Items, closing all the aggregates MUST close the aggregating Notification Item as well.

Accessibility

All interactions offered by a notification item MUST be accessible by only using the keyboard.
The purpose of each interaction MUST be clearly labeled by text.

Example 1: Base

Inbox

You have 23 unread mails in your inbox

Time3 days ago

<?php
 
declare(strict_types=1);
 
namespace ILIAS\UI\examples\Item\Notification;
 
function base()
{
    global $DIC;
    $f = $DIC->ui()->factory();
    $renderer = $DIC->ui()->renderer();
 
    //Creating a Mail Notification Item
    $mail_icon = $f->symbol()->icon()->standard("mail", "mail");
    $mail_title = $f->link()->standard("Inbox", "#");
    $mail_notification_item = $f->item()->notification($mail_title, $mail_icon)
                                ->withDescription("You have 23 unread mails in your inbox")
                                ->withProperties(["Time" => "3 days ago"]);
 
 
    return $renderer->render($mail_notification_item);
}

Example 2: Closable

Inbox

You have 23 unread mails in your inbox

Time3 days ago

<?php
 
declare(strict_types=1);
 
namespace ILIAS\UI\examples\Item\Notification;
 
function closable()
{
    global $DIC;
    $refinery = $DIC->refinery();
    $request_wrapper = $DIC->http()->wrapper()->query();
 
    $close_url = $_SERVER['REQUEST_URI'] . '&mail_closed=true';
 
    //If closed, an ajax request is fired to the set close_url
    if ($request_wrapper->has('mail_closed') && $request_wrapper->retrieve('mail_closed', $refinery->kindlyTo()->bool())) {
        //Do Some Magic needed to be done, when this item is closed.
        exit;
    }
 
    //Creating a closable Mail Notification Item
    $f = $DIC->ui()->factory();
    $renderer = $DIC->ui()->renderer();
 
    $mail_icon = $f->symbol()->icon()->standard("mail", "mail");
    $mail_title = $f->link()->standard("Inbox", "#");
    $mail_notification_item = $f->item()->notification($mail_title, $mail_icon)
                                ->withDescription("You have 23 unread mails in your inbox")
                                ->withProperties(["Time" => "3 days ago"])
                                ->withCloseAction($close_url);
 
 
    return $renderer->render($mail_notification_item);
}

Example 3: Include aggregates

Item

Notification Item with Aggregates

Property 1Content 1

Property 2Content 2

Aggregate of Item

Is shown when top item is clicked

Property 1Content 1

Property 2Content 2

Aggregate of Item

Is shown when top item is clicked

Property 1Content 1

Property 2Content 2

<?php
 
declare(strict_types=1);
 
namespace ILIAS\UI\examples\Item\Notification;
 
function include_aggregates()
{
    global $DIC;
    $f = $DIC->ui()->factory();
    $renderer = $DIC->ui()->renderer();
    $refinery = $DIC->refinery();
    $request_wrapper = $DIC->http()->wrapper()->query();
 
    $close_url = $_SERVER['REQUEST_URI'] . '&aggregate_closed=true';
 
    //If closed, an ajax request is fired to the set close_url
    if (
        $request_wrapper->has('aggregate_closed') &&
        $request_wrapper->retrieve('aggregate_closed', $refinery->kindlyTo()->bool())
    ) {
        //Do Some Magic needed to be done, when this item is closed.
        exit;
    }
 
    //Some generic notification Items
    $generic_icon1 = $f->symbol()->icon()->standard("cal", "generic");
    $generic_title1 = $f->link()->standard("Aggregate of Item", "#");
    $generic_item1 = $f->item()->notification($generic_title1, $generic_icon1)
                                       ->withDescription("Is shown when top item is clicked")
                                       ->withProperties(["Property 1" => "Content 1", "Property 2" => "Content 2"])
                                       ->withActions(
                                           $f->dropdown()->standard([
                                               $f->button()->shy("Link to ilias.de", "https://www.ilias.de"),
                                               $f->button()->shy("Link to github", "https://www.github.com")
                                           ])
                                       )
                                        ->withCloseAction($close_url);
 
    $generic_title2 = $f->link()->standard("Item", "just_opens_the_list_of_aggregates");
    $generic_item2 = $f->item()->notification($generic_title2, $generic_icon1)
                       ->withDescription("Notification Item with Aggregates")
                       ->withProperties(["Property 1" => "Content 1", "Property 2" => "Content 2"])
                       ->withAggregateNotifications([$generic_item1, $generic_item1]);
 
 
    return $renderer->render($generic_item2);
}

Relations

Parents

UIComponent
Item