Documentation

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

Toggle

Description

Purpose: The Toggle Button triggers the activation/deactivation of some control already shown on the screen, i.e. a filter. The deactivation of a control means, that it is still shown and the user can still interact with it, but it has no effect on the system.
Composition: The Toggle Button uses different background colors for the on and off state. The toggle of the Toggle Button is placed on the left side when it is off, and on the right side when it is on.
Effect: Clicking the Toggle Button activates/deactivates the related control. The on/off state of the control is visually noticeable for the user, i.e. by greying out the control in the off state.

Rivals

Checkbox: Checkboxes are established as controls for choosing a value for submission and are therefore handled as Inputs. Toggle Buttons are used for switching the activation of some control and are therefore handled as Buttons.
Collapse/Expand Glyph: Collapse and Expand Glyphs hide or trigger the display of some content. Toggle Buttons leave a control visible to the user, but activate or deactivate it.
Mode View Control: Mode View Controls enable the switching between different aspects of some data. Toggle Buttons activate/deactivate some control, but do not change or switch the control which the user see currently.

Rules

Usage

The Toggle Button MUST be placed next to the control it activates/deactivates.

Ordering

The Toggle Button SHOULD be placed above the control it activates/deactivates.

Style

The Toggle Button MUST contain a label inside, representing its current status (ON/OFF).

Accessibility

The functionality of the Toggle Button MUST be indicated for screen readers by an aria-label.
The state of the Toggle Button MUST be indicated for screen readers by using the aria-pressed attribute.

Example 1: Base

<?php
 
declare(strict_types=1);
 
namespace ILIAS\UI\examples\Button\Toggle;
 
function base()
{
    global $DIC;
    $factory = $DIC->ui()->factory();
    $renderer = $DIC->ui()->renderer();
 
    $message1 = 'Toggle Button has been turned on';
    $message2 = 'Toggle Button has been turned off';
    $form_action = $DIC->ctrl()->getFormActionByClass('ilsystemstyledocumentationgui');
 
    $modal = $factory->modal()->interruptive('ON', $message1, $form_action);
    $modal2 = $factory->modal()->interruptive('OFF', $message2, $form_action);
 
    //Note, important do not miss to set a proper aria-label (see rules above).
    //Note that aria-pressed is taken care off by the default implementation.
    $button = $factory->button()->toggle("", $modal->getShowSignal(), $modal2->getShowSignal())
        ->withAriaLabel("Switch the State of XY");
 
    return $renderer->render([$button, $modal, $modal2]);
}

Example 2: Unavailable action

<?php
 
declare(strict_types=1);
 
namespace ILIAS\UI\examples\Button\Toggle;
 
/**
 * This example provides the given button with an unavailable action. Note
 * that the disabled attribute is set in the DOM. No action must be fired, even
 * if done by keyboard
 */
function unavailable_action()
{
    global $DIC;
    $f = $DIC->ui()->factory();
    $renderer = $DIC->ui()->renderer();
 
    $button = $f->button()->toggle('', '#', '#')
                          ->withAriaLabel("Switch the State of XY")
                          ->withUnavailableAction();
 
    return $renderer->render([$button]);
}

Example 3: With tooltip

<?php
 
declare(strict_types=1);
 
namespace ILIAS\UI\examples\Button\Toggle;
 
function with_tooltip()
{
    global $DIC;
    $f = $DIC->ui()->factory();
    $renderer = $DIC->ui()->renderer();
 
    $button = $f->button()->toggle('', '#', '#')
                          ->withAriaLabel("Switch the State of XY")
                          ->withHelpTopics(
                              ...$f->helpTopics("ilias", "learning management system")
                          );
 
    return $renderer->render([$button]);
}

Relations

Parents

UIComponent
Button