Paginator¶

Шаблоны PaginatorHelper¶

Внутренне PaginatorHelper использует серию простых HTML-шаблонов для генерации разметки. Вы можете изменить эти шаблоны, чтобы настроить HTML, сгенерированный PaginatorHelper.

Шаблоны используют {{var}} метки стиля. Важно не добавлять никаких пробелов вокруг {{}} иначе замены не будут работать.

// В вашем /src/view/AppView.php
public function initialize()
{
    ...
    $this->loadHelper('Paginator', ['templates' => 'paginator-templates']);
}

// В вашем /src/view/AppView.php
public function initialize()
{
    ...
    $this->loadHelper('Paginator', ['templates' => 'MyPlugin.paginator-templates']);
}

return [
    'number' => '<a href="{{url}}">{{text}}</a>',
];

// Прочитаем текущее значение шаблона.
$result = $this->Paginator->getTemplates('number');
// Prior to 3.4
$result = $this->Paginator->templates('number');

// Сменим шаблон
$this->Paginator->setTemplates([
    'number' => '<em><a href="{{url}}">{{text}}</a></em>'
]);

Создание сортировки ссылок¶

Cake\View\Helper\PaginatorHelper::sort($key, $title = null, $options = [])¶

Параметры:

• $key (string) – Имя столбца, в котором должен быть отсортирован набор записей.

• $title (string) – Заголовок для ссылки. Если $title имеет значение null, $key будет использоваться для преобразования в формат «Title Case» и как заголовок.

• $options (array) – Опции для сортировки ссылки.

Создаёт сортировку. Устанавливает параметры querystring для сортировки и направления. Ссылки по умолчанию будут сортироваться по asc (возрастанию). После первого клика по ссылке сгенерированный с помощью sort(), автоматически обрабатывает переключение направления. Если resultset сортируется по asc (возрастанию) по указанному ключу, возвращаемая ссылка будет сортироваться по desc (убыванию).

Принятые ключи для $options:

• escape Если вы хотите, чтобы содержимое HTML-объекта было закодировано, используйте true.

• model Модель используемая по умолчанию для PaginatorHelper::defaultModel().

• direction Используется по умолчанию, когда ссылка неактивна.

• lock Направление блокировки. Будет использоваться только по умолчанию, по умолчанию false.

Предполагается, что вы размещаете страницы на нескольких страницах и находитесь на первой странице:

echo $this->Paginator->sort('user_id');

Вывод:

<a href="/posts/index?page=1&amp;sort=user_id&amp;direction=asc">User Id</a>

Вы можете использовать параметр title для создания пользовательского текста для своей ссылки:

echo $this->Paginator->sort('user_id', 'Учетная запись пользователя');

Вывод:

<a href="/posts/index?page=1&amp;sort=user_id&amp;direction=asc">Учетная запись пользователя</a>

Если вы используете HTML-изображения в своих ссылках, не забудьте установить их выход:

echo $this->Paginator->sort(
  'user_id',
  '<em>Учетная запись пользователя</em>',
  ['escape' => false]
);

Вывод:

<a href="/posts/index?page=1&amp;sort=user_id&amp;direction=asc"><em>Учетная запись пользователя</em></a>

Опцию direction можно использовать для установки направления по умолчанию для ссылки. Когда ссылка активна, она автоматически переключит направление, как обычно:

echo $this->Paginator->sort('user_id', null, ['direction' => 'desc']);

Вывод:

<a href="/posts/index?page=1&amp;sort=user_id&amp;direction=desc">User Id</a>

Опцию блокировки можно использовать для блокировки сортировки в указанном направлении:

echo $this->Paginator->sort('user_id', null, ['direction' => 'asc', 'lock' => true]);

Cake\View\Helper\PaginatorHelper::sortDir(string $model = null, mixed $options = [])¶

Возвращает текущее направление сортировки записей.

Cake\View\Helper\PaginatorHelper::sortKey(string $model = null, mixed $options = [])¶

Возвращает текущий ключ, по которому сортируется набор записей.

Создание ссылок на номера страниц¶

Cake\View\Helper\PaginatorHelper::numbers($options = [])¶

Возвращает набор чисел вычисленного набора страниц. Использует modulus для вычисления, сколько номеров будет отображаться на каждой стороне от текущей страницы. По умолчанию, будут созданы 8 ссылок по обе стороны от текущей страницы, если эти страницы будут существовать. Ссылки не создаются для страниц, которые не существуют. Текущая страница также не будет являться ссылкой.

Поддерживаемые параметры:

• before Содержимое должно быть вставлено перед номерами.

• after Содержимое вводится после номеров.

• model Модель для создания чисел, по умолчанию PaginatorHelper::defaultModel().

• modulus Сколько номеров будет включено по обе стороны текущей страницы, по умолчанию 8.

• first Если вы хотите, чтобы генерировались первые ссылки, задайте целое число определяющее количество „первых“ ссылок для генерации. По умолчанию используется false. Если строка установлена как ссылка на первую страницу, то она будет сгенерирована со значением как и заглавие:

  echo $this->Paginator->numbers(['first' => 'Первая страница']);
  

• last Если вы хотите сгенерировать ссылки на последние страницы, установите целое число для определения числа „последних“ ссылок для генерации. По умолчанию используется false. Следуйте той же логике, как и для опции first. Или, если хотите, используйте last().

Хотя этот метод позволяет много настроек его вывода, но можно просто вызвать метод без каких-либо параметров:

echo $this->Paginator->numbers();

Используя первый и последний варианты, вы можете создавать ссылки на начало и конец набора страниц. Ниже будет создан набор ссылок на страницы, которые включают ссылки на 2 первые и 2 последние страницы в результатах:

echo $this->Paginator->numbers(['first' => 2, 'last' => 2]);

Создание ссылок для перехода¶

В дополнение к созданию ссылок, которые ведут непосредственно на конкретные номера страниц, вам часто понадобятся ссылки, которые переходят к предыдущим и последующим ссылкам, первым и последним страницам в выгружаемом наборе данных.

Cake\View\Helper\PaginatorHelper::prev($title = '<< Previous', $options = [])¶

Параметры:

• $title (string) – Заголовок для ссылки.

• $options (mixed) – Параметры ссылки для разбивки на страницы.

Создает ссылку на предыдущую страницу в наборе выгружаемых записей.

$options поддерживает следующие клавиши:

• escape Если вы хотите, чтобы содержимое HTML-объекта было закодировано, установите в true.

• model Используемая модель, по умолчанию используется PaginatorHelper::defaultModel().

• disabledTitle Текст для использования, когда ссылка отключена. По умолчанию используется параметр $title.

Простой пример:

echo $this->Paginator->prev(' << ' . __('previous'));

Если вы в настоящее время находитесь на второй странице постов, вы получите следующее:

<li class="prev">
    <a rel="prev" href="/posts/index?page=1&amp;sort=title&amp;order=desc">
        &lt;&lt; previous
    </a>
</li>

Если бы не было предыдущих страниц, то:

<li class="prev disabled"><span>&lt;&lt; previous</span></li>

Чтобы изменить шаблоны, используемые этим методом, см. Шаблоны PaginatorHelper.

Cake\View\Helper\PaginatorHelper::next($title = 'Next >>', $options = [])¶

Этот метод идентичен prev(), за несколькими исключениями. Он создаёт ссылки, указывающие на следующую страницу, а не на предыдущую. Это также использует next в качестве значения атрибута rel вместо prev.

Cake\View\Helper\PaginatorHelper::first($first = '<< first', $options = [])¶

Возвращает первое или набор чисел для первых страниц. Если строка задана, то будет создана только ссылка на первую страницу с предоставленным текстом:

echo $this->Paginator->first('< first');

Вышеуказанное создаёт единственную ссылку для первой страницы. Не выдаст ничего, если вы находитесь на первой странице. Вы также можете использовать целое число, чтобы указать, сколько пейджинговых ссылок вы хотите создать:

echo $this->Paginator->first(3);

Вышеуказанное создаст ссылки на первые 3 страницы, как только вы доберётесь до третьей или большей страницы. До этого ничего не будет выводиться.

Параметр options принимает следующее:

• model Модель используемая по умолчанию PaginatorHelper::defaultModel()

• escape Следует ли экранировать текст. Установите значение false, если ваш контент содержит HTML.

Cake\View\Helper\PaginatorHelper::last($last = 'last >>', $options = [])¶

Этот метод очень похож на метод first(). Однако он имеет несколько отличий. Он не будет создавать никаких ссылок для строковых значений $last, если вы находитесь на последней странице. Для целочисленного значения $last никакие ссылки не будут сгенерированы после того, как пользователь окажется в диапазоне последних страницы.

Создание тегов ссылок в заголовке¶

PaginatorHelper можно использовать для создания тегов ссылок пагинации на вашей странице в элементе <head>:

// Создайте следующие/предыдущие ссылки для текущей модели.
echo $this->Paginator->meta();

// Создайте следующие/предыдущие и первые/последние ссылки для текущей модели.
echo $this->Paginator->meta(['first' => true, 'last' => true]);

Проверка состояния пагинации¶

Cake\View\Helper\PaginatorHelper::current(string $model = null)¶

Получает набор записей, на текущей странице, для данной модели:

// Our URL is: http://example.com/comments/view/page:3
echo $this->Paginator->current('Comment');
// Output is 3

Cake\View\Helper\PaginatorHelper::hasNext(string $model = null)¶

Возвращает true, если данный результирующий набор не находится на последней странице.

Cake\View\Helper\PaginatorHelper::hasPrev(string $model = null)¶

Возвращает true, если данный результирующий набор не находится на первой странице.

Cake\View\Helper\PaginatorHelper::hasPage(string $model = null, integer $page = 1)¶

Возвращает true, если заданный набор результатов имеет номер страницы, заданный $page.

Cake\View\Helper\PaginatorHelper::total(string $model = null)¶

Возвращает общее количество страниц для предоставленной модели.

Добавлено в версии 3.4.0.

Создание счетчика страниц¶

Cake\View\Helper\PaginatorHelper::counter($options = [])¶

Возвращает строку счетчика для вычисленного набора результатов. Используя предоставленную строку форматирования и ряд параметров, вы можете создавать локализованные и прикладные индикаторы того, где пользователь находится в выгружаемом наборе данных.

Существует ряд опций для counter(). Поддерживаемые:

• format Формат счетчика. Поддерживаемые форматы: „range“ (диапазон), „pages“ (страницы) и пользовательские. По умолчанию страницы, будут выводиться как „1 of 10“. В пользовательском режиме строка с параметрами анализируется, а токены заменяются фактическими значениями. Доступными токенами являются:

  • {{page}} - отображается текущая страница.

  • {{pages}} - общее количество страниц.

  • {{current}} - текущее количество отображаемых записей.

  • {{count}} - общее количество записей в наборе результатов.

  • {{start}} - номер первой отображаемой записи.

  • {{end}} - номер последней отображаемой записи.

  • {{model}} - Плурализованная человеческая форма названия модели. Если ваша модель была „RecipePage“, {{model}} будет „recipe pages“.

  Вы можете предоставить только строку методу счетчика, используя доступные токены. Для примера:

  echo $this->Paginator->counter(
      'Page {{page}} of {{pages}}, showing {{current}} records out of
       {{count}} total, starting on record {{start}}, ending on {{end}}'
  );
  

  Установка „format“ для диапазона будет выводиться как „1 - 3 of 13“:

  echo $this->Paginator->counter([
      'format' => 'range'
  ]);
  

• model Имя модели, разбитой на страницы, по умолчанию является PaginatorHelper::defaultModel(). И используется в соединение с пользовательской строкой в опции „format“.

Создание URL-адресов для пагинации¶

Cake\View\Helper\PaginatorHelper::generateUrl(array $options = [], $model = null, $full = false)¶

По умолчанию возвращается строка полного URL-адреса для использования в нестандартных контекстах (например, JavaScript):

echo $this->Paginator->generateUrl(['sort' => 'title']);

Создание элемента управления с ограничениями¶

Cake\View\Helper\PaginatorHelper::limitControl(array $limits = [], $default = null, array $options = [])¶

Создание выпадающего элемента управления, который изменяет параметр запроса limit:

// Используется значение по умолчанию.
echo $this->Paginator->limitControl();

// Определите, какие параметры лимита вы хотите.
echo $this->Paginator->limitControl([25 => 25, 50 => 50]);

// Пользовательские лимиты и установка выбранной опции
echo $this->Paginator->limitControl([25 => 25, 50 => 50], $user->perPage);

The generated form and control will automatically submit on change.

Настройка параметров пагинации¶

Cake\View\Helper\PaginatorHelper::options($options = [])¶

Устанавливает все параметры для PaginatorHelper. Поддерживаемые параметры:

• url URL-адрес действия для разбивки на страницы. „url“ имеет несколько дополнительных опций:

  • sort Ключ к сортировке записей.

  • direction Направление сортировки. По умолчанию используется „ASC“.

  • page Номер страницы для отображения.

  Вышеупомянутые параметры могут использоваться для принудительного создания определенных страниц/направлений. Вы также можете добавить дополнительный URL-адрес во все URL-адреса, созданные в helper:

  $this->Paginator->options([
      'url' => [
          'sort' => 'email',
          'direction' => 'desc',
          'page' => 6,
          'lang' => 'en'
      ]
  ]);
  

  Приведенное выше добавляет параметр маршрута en ко всем ссылкам, которые создаст хелпер(помощник). Он также создаст ссылки со специфическими значениями сортировки, направления и страницы. По умолчанию PaginatorHelper объединит все текущие переданные аргументы и параметры строки запроса.

• escape Определяет, должно ли поле заголовка ссылок ссылаться на HTML. По умолчанию true.

• model Имя модели, разбитой на страницы, по умолчанию PaginatorHelper::defaultModel().

Пример использования¶

Вам решать, как показывать записи пользователю, но чаще всего это будет выполняться внутри HTML-таблиц. Нижеприведенные примеры предполагают табличную компоновку, но PaginatorHelper, доступный во Видах, не всегда должен быть ограничен.

Подробнее см. в API PaginatorHelper. Как уже упоминалось, PaginatorHelper также предлагает функции сортировки, которые могут быть интегрированы в заголовки столбцов таблицы:

<!-- src/Template/Posts/index.ctp -->
<table>
    <tr>
        <th><?= $this->Paginator->sort('id', 'ID') ?></th>
        <th><?= $this->Paginator->sort('title', 'Title') ?></th>
    </tr>
       <?php foreach ($recipes as $recipe): ?>
    <tr>
        <td><?= $recipe->id ?> </td>
        <td><?= h($recipe->title) ?> </td>
    </tr>
    <?php endforeach; ?>
</table>

Ссылки, выводимые PaginatorHelper методом sort(), позволяют пользователям кликнуть заголовки таблиц, чтобы переключать сортировку данных по заданному полю.

Также можно отсортировать столбец на основе ассоциаций:

<table>
    <tr>
        <th><?= $this->Paginator->sort('title', 'Title') ?></th>
        <th><?= $this->Paginator->sort('Authors.name', 'Author') ?></th>
    </tr>
       <?php foreach ($recipes as $recipe): ?>
    <tr>
        <td><?= h($recipe->title) ?> </td>
        <td><?= h($recipe->author->name) ?> </td>
    </tr>
    <?php endforeach; ?>
</table>

Конечным ингредиентом, для отображения страниц в виде просмотров является добавление навигации по страницам, также предоставляемый PaginationHelper:

// Показывает номера страниц
<?= $this->Paginator->numbers() ?>

// Показывает следующую и предыдущую ссылки
<?= $this->Paginator->prev('« Previous') ?>
<?= $this->Paginator->next('Next »') ?>

// Печать X из Y, где X - текущая страница, а Y - количество страниц
<?= $this->Paginator->counter() ?>

Вывод, выданный методом counter(), также можно настроить с помощью специальных маркеров:

<?= $this->Paginator->counter([
    'format' => 'Page {{page}} of {{pages}}, showing {{current}} records out of
             {{count}} total, starting on record {{start}}, ending on {{end}}'
]) ?>

Разбиение на несколько результатов¶

Если вы хотите использовать paginating multiple queries, вам нужно установить опцию model при создании элементов, связанных с разбивкой по страницам. Вы можете использовать опцию model при каждом вызове метода, который вы делаете для PaginatorHelper, или использовать options() для установки модели по умолчанию:

// Установим свой вариант модели
echo $this->Paginator->sort('title', ['model' => 'Articles']);

// Установим модель по умолчанию
$this->Paginator->options(['defaultModel' => 'Articles']);
echo $this->Paginator->sort('title');

Используя опцию model, PaginatorHelper автоматически будет использовать scope, определенную в том случае, когда запрос был разбит на страницы.