Documentation

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

Pagination

Description

Purpose: Pagination allows structured data being displayed in chunks by limiting the number of entries shown. It provides the user with controls to leaf through the chunks of entries.
Composition: Pagination is a collection of shy-buttons to access distinct chunks of data, framed by next/back glyphs. When used with the "DropdownAt" option, a dropdown is rendered if the number of chunks exceeds the option's value.
Effect: A click on a chunk-option will change the offset of the displayed data-list, thus displaying the respective chunk of entries. The active option is rendered as an unavailable shy-button. Clicking the next/back-glyphs, the previous (respectively: the next) chunk of entries is being displayed. If a previous/next chunk is not available, the glyph is rendered unavailable. If the pagination is used with a maximum of chunk-options to be shown, both first and last options are always displayed.

Rules

Usage

A Pagination MUST only be used for structured data, like tables and lists.
A Pagination MUST NOT be used standalone.
Paginations MUST be visually close to the list or table their operation will have effect upon. They MAY be placed directly above and/or below the list.
You MUST use the default label if dealing with tables.
You MAY use a different label, if the default one is not working for the use case. But indicating the total number of items (X of Y) MUST be kept anyway.

Accessibility

Pagination MUST be operable via keyboard only.

Example 1: Base

Show 10 entries starting at 0

<?php
 
declare(strict_types=1);
 
namespace ILIAS\UI\examples\ViewControl\Pagination;
 
function base()
{
    global $DIC;
    $factory = $DIC->ui()->factory();
    $renderer = $DIC->ui()->renderer();
    $url = $DIC->http()->request()->getRequestTarget();
    $refinery = $DIC->refinery();
    $request_wrapper = $DIC->http()->wrapper()->query();
 
    $parameter_name = 'page';
    $current_page = 0;
    if ($request_wrapper->has($parameter_name)) {
        $current_page = $request_wrapper->retrieve($parameter_name, $refinery->kindlyTo()->int());
    }
 
    $pagination = $factory->viewControl()->pagination()
        ->withTargetURL($url, $parameter_name)
        ->withTotalEntries(98)
        ->withPageSize(10)
        ->withCurrentPage($current_page);
 
    list($range_offset, $range_length) = $pagination->getRange()->unpack();
    $result = "Show $range_length entries starting at $range_offset";
 
    return $renderer->render($pagination)
        . '<hr>'
        . $result;
}

Example 2: Many pages dropdown

Show 10 entries starting at 0

<?php
 
declare(strict_types=1);
 
namespace ILIAS\UI\examples\ViewControl\Pagination;
 
function many_pages_dropdown()
{
    global $DIC;
    $factory = $DIC->ui()->factory();
    $renderer = $DIC->ui()->renderer();
    $url = $DIC->http()->request()->getRequestTarget();
    $refinery = $DIC->refinery();
    $request_wrapper = $DIC->http()->wrapper()->query();
 
    $parameter_name = 'page3';
    $current_page = 0;
    if ($request_wrapper->has($parameter_name)) {
        $current_page = $request_wrapper->retrieve($parameter_name, $refinery->kindlyTo()->int());
    }
 
    $pagination = $factory->viewControl()->pagination()
        ->withTargetURL($url, $parameter_name)
        ->withTotalEntries(102)
        ->withPageSize(10)
        ->withDropdownAt(5)
        ->withCurrentPage($current_page);
 
    $custom_pagination = $pagination
        ->withDropdownLabel('current page is %1$d (of %2$d pages in total)');
 
    list($range_offset, $range_length) = $pagination->getRange()->unpack();
    $result = "Show $range_length entries starting at $range_offset";
 
    return $renderer->render([$pagination, $custom_pagination])
        . '<hr>'
        . $result;
}

Example 3: Many pages

Show 2 entries starting at 0

<?php
 
declare(strict_types=1);
 
namespace ILIAS\UI\examples\ViewControl\Pagination;
 
function many_pages()
{
    global $DIC;
    $factory = $DIC->ui()->factory();
    $renderer = $DIC->ui()->renderer();
    $url = $DIC->http()->request()->getRequestTarget();
    $refinery = $DIC->refinery();
    $request_wrapper = $DIC->http()->wrapper()->query();
 
    $parameter_name = 'page2';
    $current_page = 0;
    if ($request_wrapper->has($parameter_name)) {
        $current_page = $request_wrapper->retrieve($parameter_name, $refinery->kindlyTo()->int());
    }
 
    $pagination = $factory->viewControl()->pagination()
        ->withTargetURL($url, $parameter_name)
        ->withTotalEntries(1000)
        ->withPageSize(2)
        ->withMaxPaginationButtons(5)
        ->withCurrentPage($current_page);
 
    list($range_offset, $range_length) = $pagination->getRange()->unpack();
    $result = "Show $range_length entries starting at $range_offset";
 
    return $renderer->render($pagination)
        . '<hr>'
        . $result;
}

Example 4: No pages

<?php
 
declare(strict_types=1);
 
namespace ILIAS\UI\examples\ViewControl\Pagination;
 
/**
 * A Pagination with one page only will render as empty string
 */
function no_pages()
{
    global $DIC;
    $factory = $DIC->ui()->factory();
    $renderer = $DIC->ui()->renderer();
    $url = $DIC->http()->request()->getRequestTarget();
 
    $pagination = $factory->viewControl()->pagination()
        ->withPageSize(10)
        ->withTotalEntries(10);
 
    return $renderer->render($pagination);
}

Example 5: With signal

<?php
 
declare(strict_types=1);
 
namespace ILIAS\UI\examples\ViewControl\Pagination;
 
function with_signal()
{
    global $DIC;
    $factory = $DIC->ui()->factory();
    $renderer = $DIC->ui()->renderer();
 
    $image = $factory->image()->responsive("src/UI/examples/Image/mountains.jpg", "Image source: https://stocksnap.io, Creative Commons CC0 license");
    $page = $factory->modal()->lightboxImagePage($image, 'Mountains');
    $modal = $factory->modal()->lightbox($page);
 
    $pagination = $factory->viewControl()->pagination()
        ->withTotalEntries(98)
        ->withPageSize(10)
        ->withResetSignals()
        ->withOnSelect($modal->getShowSignal());
 
    return $renderer->render([$pagination, $modal]);
}

Relations

Parents

UIComponent
View Control