function pager_default_initialize in Zircon Profile 8

Same name and namespace in other branches

1. 8.0 core/includes/pager.inc \pager_default_initialize()

Initializes a pager.

This function sets up the necessary global variables so that the render system will correctly process #type 'pager' render arrays to output pagers that correspond to the items being displayed.

If the items being displayed result from a database query performed using Drupal's database API, and if you have control over the construction of the database query, you do not need to call this function directly; instead, you can simply extend the query object with the 'PagerSelectExtender' extender before executing it. For example:

$query = db_select('some_table')
  ->extend('Drupal\\Core\\Database\\Query\\PagerSelectExtender');

However, if you are using a different method for generating the items to be paged through, then you should call this function in preparation.

The following example shows how this function can be used in a controller that invokes an external datastore with an SQL-like syntax:

// First find the total number of items and initialize the pager.
$where = "status = 1";
$total = mymodule_select("SELECT COUNT(*) FROM data " . $where)
  ->result();
$num_per_page = \Drupal::config('mymodule.settings')
  ->get('num_per_page');
$page = pager_default_initialize($total, $num_per_page);

// Next, retrieve the items for the current page and put them into a
// render array.
$offset = $num_per_page * $page;
$result = mymodule_select("SELECT * FROM data " . $where . " LIMIT %d, %d", $offset, $num_per_page)
  ->fetchAll();
$render = [];
$render[] = [
  '#theme' => 'mymodule_results',
  '#result' => $result,
];

// Finally, add the pager to the render array, and return.
$render[] = [
  '#type' => 'pager',
];
return $render;

A second example involves a controller that invokes an external search service where the total number of matching results is provided as part of the returned set (so that we do not need a separate query in order to obtain this information). Here, we call pager_find_page() to calculate the desired offset before the search is invoked:

// Perform the query, using the requested offset from pager_find_page().
// This comes from a URL parameter, so here we are assuming that the URL
// parameter corresponds to an actual page of results that will exist
// within the set.
$page = pager_find_page();
$num_per_page = \Drupal::config('mymodule.settings')
  ->get('num_per_page');
$offset = $num_per_page * $page;
$result = mymodule_remote_search($keywords, $offset, $num_per_page);

// Now that we have the total number of results, initialize the pager.
pager_default_initialize($result->total, $num_per_page);

// Create a render array with the search results.
$render = [];
$render[] = [
  '#theme' => 'search_results',
  '#results' => $result->data,
  '#type' => 'remote',
];

// Finally, add the pager to the render array, and return.
$render[] = [
  '#type' => 'pager',
];
return $render;

Parameters

int $total: The total number of items to be paged.

int $limit: The number of items the calling code will display per page.

int $element: (optional) An integer to distinguish between multiple pagers on one page.

Return value

int The number of the current page, within the pager represented by $element. This is determined from the URL query parameter \Drupal::request()->query->get('page), or 0 by default. However, if a page that does not correspond to the actual range of the result set was requested, this function will return the closest page actually within the result set.

2 calls to pager_default_initialize()

PagerSelectExtender::execute in core/lib/Drupal/Core/Database/Query/PagerSelectExtender.php

Override the execute method.

QueryBase::initializePager in core/lib/Drupal/Core/Entity/Query/QueryBase.php

Gets the total number of results and initialize a pager for the query.

File

core/includes/pager.inc, line 127

Functions to aid in presenting database results as a set of pages.

Code

function pager_default_initialize($total, $limit, $element = 0) {
  global $pager_page_array, $pager_total, $pager_total_items, $pager_limits;
  $page = pager_find_page($element);

  // We calculate the total of pages as ceil(items / limit).
  $pager_total_items[$element] = $total;
  $pager_total[$element] = ceil($pager_total_items[$element] / $limit);
  $pager_page_array[$element] = max(0, min($page, (int) $pager_total[$element] - 1));
  $pager_limits[$element] = $limit;
  return $pager_page_array[$element];
}