Pager · Mecha CMS

Table of Contents

Types
1. Page
2. Peek
Hooks

To enable the numbered page navigation feature, find a line of code that looks like this in the pages.php file of your currently active layout:

<?= self::pager(); ?>

Replace that line with the code below:

<?= self::pager('peek'); ?>

Types

There are several types of page navigation available in this extension that you can use.

Page

A page navigation for single page view.

<?= self::pager('page', [
    '0' => 'nav',
    '1' => null,
    '2' => [],
    'next' => true,
    'prev' => true,
    'previous' => true // Alias of `prev`
]);

Key	Accept	Description
`0`	`false\|null\|string`	Set this value to a HTML element name to wrap the page navigation layout with a HTML element. For example, if you set this value to `'div'`, then the output will automatically be wrapped in a `'<div class="pager pager-page"> … </div>'` element.
`1`	`array\|null`	Reserved.
`2`	`array`	Use this key to add more HTML attributes to the page navigation layout wrapper. Will only work if the `0` key is set to a value other than `false` and `null`.
`next`	`bool\|string`	Set this value to `false` to remove the “Next” link. If the value is a string, it will be used to change the label of the “Next” link.
`prev`	`bool\|string`	Set this value to `false` to remove the “Previous” link. If the value is a string, it will be used to change the label of the “Previous” link.
`previous`	`bool\|string`	This key is an alias of the `prev` key.

Peek

A page navigation for multiple page view with numbered page navigation style.

<?= self::pager('peek', [
    '0' => 'nav',
    '1' => null,
    '2' => [],
    'chunk' => $pager->chunk,
    'count' => $pager->parent->count,
    'next' => true,
    'part' => $pager->current->part,
    'peek' => 2,
    'prev' => true,
    'previous' => true // Alias of `prev`
]);

Key	Accept	Description
`0`	`false\|null\|string`	Set this value to a HTML element name to wrap the page navigation layout with a HTML element. For example, if you set this value to `'div'`, then the output will automatically be wrapped in a `'<div class="pager pager-peek"> … </div>'` element.
`1`	`array\|null`	Reserved.
`2`	`array`	Use this key to add more HTML attributes to the page navigation layout wrapper. Will only work if the `0` key is set to a value other than `false` and `null`.
`chunk`	`int`	By default, the `chunk` value of the current page is used. Specify the value manually if you are using external navigation data.
`count`	`int`	By default, the `count` value of the current page is used. Specify the value manually if you are using external navigation data.
`next`	`bool\|string`	Set this value to `false` to remove the “Next” link. If the value is a string, it will be used to change the label of the “Next” link.
`part`	`int`	By default, it uses the `part` value of the current page. Specify the value manually if you are using external navigation data.
`peek`	`int`	Specify how many numeric links need to be displayed before and after the currently active numeric link.
`prev`	`bool\|string`	Set this value to `false` to remove the “Previous” link. If the value is a string, it will be used to change the label of the “Previous” link.
`previous`	`bool\|string`	This key is an alias of the `prev` key.

The following is an example of using the page navigation layout with external data, such as from a database:

<?php

$chunk = 100;
$count = $base->row('SELECT count("id") AS "count" FROM "page" WHERE "parent" = ?', [$page->id])['count'] ?? 0;
$part = $site->part ?? 1;

echo self::pager('peek', [
    'chunk' => $chunk,
    'count' => $count,
    'part' => $part
]);

?>

Hooks

There are several layout hooks that you can use to modify the page navigation output through the tokenization level if the available options are not sufficient to meet your customization needs:

// Specific hook for the `page` pager type
Hook::set('y.pager.page', function ($y) {
    return $y;
});

// Specific hook for the `peek` pager type
Hook::set('y.pager.peek', function ($y) {
    $y[1]['description'] = [
        0 => 'span',
        1 => $description = i('Page %d of %d', [$y['part'] ?? 1, $y['of'] ?? 1]),
        2 => ['style' => 'margin-inline-start: auto;']
    ];
    $y[2]['aria-description'] = $description;
    return $y;
});