aleph1.co.uk Git - yaffs-website/blob - web/core/lib/Drupal/Core/Render/Element/Pager.php

   1 <?php
   2
   3 namespace Drupal\Core\Render\Element;
   4
   5 /**
   6  * Provides a render element for a pager.
   7  *
   8  * The pager must be initialized with a call to pager_default_initialize() in
   9  * order to render properly. When used with database queries, this is performed
  10  * for you when you extend a select query with
  11  * \Drupal\Core\Database\Query\PagerSelectExtender.
  12  *
  13  * Properties:
  14  * - #element: (optional, int) The pager ID, to distinguish between multiple
  15  *   pagers on the same page (defaults to 0).
  16  * - #parameters: (optional) An associative array of query string parameters to
  17  *   append to the pager.
  18  * - #quantity: The maximum number of numbered page links to create (defaults
  19  *   to 9).
  20  * - #tags: (optional) An array of labels for the controls in the pages.
  21  * - #route_name: (optional) The name of the route to be used to build pager
  22  *   links. Defaults to '<none>', which will make links relative to the current
  23  *   URL. This makes the page more effectively cacheable.
  24  *
  25  * @code
  26  * $build['pager'] = [
  27  *   '#type' => 'pager',
  28  * ];
  29  * @endcode
  30  *
  31  * @RenderElement("pager")
  32  */
  33 class Pager extends RenderElement {
  34
  35   /**
  36    * {@inheritdoc}
  37    */
  38   public function getInfo() {
  39     return [
  40       '#pre_render' => [
  41         get_class($this) . '::preRenderPager',
  42       ],
  43       '#theme' => 'pager',
  44       // The pager ID, to distinguish between multiple pagers on the same page.
  45       '#element' => 0,
  46       // An associative array of query string parameters to append to the pager
  47       // links.
  48       '#parameters' => [],
  49       // The number of pages in the list.
  50       '#quantity' => 9,
  51       // An array of labels for the controls in the pager.
  52       '#tags' => [],
  53       // The name of the route to be used to build pager links. By default no
  54       // path is provided, which will make links relative to the current URL.
  55       // This makes the page more effectively cacheable.
  56       '#route_name' => '<none>',
  57     ];
  58   }
  59
  60   /**
  61    * #pre_render callback to associate the appropriate cache context.
  62    *
  63    *
  64    * @param array $pager
  65    *   A renderable array of #type => pager.
  66    *
  67    * @return array
  68    */
  69   public static function preRenderPager(array $pager) {
  70     // Note: the default pager theme process function
  71     // template_preprocess_pager() also calls pager_query_add_page(), which
  72     // maintains the existing query string. Therefore
  73     // template_preprocess_pager() adds the 'url.query_args' cache context,
  74     // which causes the more specific cache context below to be optimized away.
  75     // In other themes, however, that may not be the case.
  76     $pager['#cache']['contexts'][] = 'url.query_args.pagers:' . $pager['#element'];
  77     return $pager;
  78   }
  79
  80 }