PagerPluginBase.php 6.58 KB
Newer Older
merlinofchaos's avatar
merlinofchaos committed
1
2
3
4
<?php

/**
 * @file
5
 * Definition of Drupal\views\Plugin\views\pager\PagerPluginBase.
merlinofchaos's avatar
merlinofchaos committed
6
7
 */

8
namespace Drupal\views\Plugin\views\pager;
9

10
use Drupal\views\Plugin\views\PluginBase;
11
use Drupal\views\ViewExecutable;
12

merlinofchaos's avatar
merlinofchaos committed
13
14
15
/**
 * @defgroup views_pager_plugins Views pager plugins
 * @{
16
17
18
19
 * The base plugin to handler pagers of a view.
 *
 * The pager takes care about altering the query for its needs, altering some
 * global information of pagers and finally rendering itself.
merlinofchaos's avatar
merlinofchaos committed
20
21
22
23
 */

/**
 * The base plugin to handle pager.
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
 *
 * Pager plugins take care of everything regarding pagers, including getting
 * and setting the total number of items to render the pager and setting the
 * global pager arrays.
 *
 * To define a pager type, extend this base class. The ViewsPluginManager (used
 * to create views plugins objects) adds annotated discovery for pager plugins.
 * Your pager plugin must have an annotation that includes the plugin's metadata,
 * for example:
 * @code
 * @ Plugin(
 *   id = "demo_pager",
 *   title = @ Translation("Display a demonstration pager"),
 *   help = @ Translation("Demonstrate pagination of views items."),
 *   theme = "views_demo_pager"
 * )
 * @endcode
 * Remove spaces after @ in your actual plugin - these are put into this sample
 * code so that it is not recognized as annotation.
 *
 * The plugin annotation contains these components:
 * - id: The unique identifier of your pager plugin.
 * - title: The "full" title for your pager type; used in the views UI.
 * - short_title: (optional) The "short" title for your pager type;
 *   used in the views UI when specified.
 * - help: (optional) A short help string; this is displayed in the views UI.
 * - theme: The theme function used to render the pager's output.
 *
 * @see \Drupal\views\Plugin\ViewsPluginManager
merlinofchaos's avatar
merlinofchaos committed
53
 */
54
abstract class PagerPluginBase extends PluginBase {
55

merlinofchaos's avatar
merlinofchaos committed
56
  var $current_page = NULL;
57

merlinofchaos's avatar
merlinofchaos committed
58
59
  var $total_items = 0;

60
61
62
  /**
   * Overrides Drupal\views\Plugin\Plugin::$usesOptions.
   */
63
  protected $usesOptions = TRUE;
64

merlinofchaos's avatar
merlinofchaos committed
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
  /**
   * Get how many items per page this pager will display.
   *
   * All but the leanest pagers should probably return a value here, so
   * most pagers will not need to override this method.
   */
  function get_items_per_page() {
    return isset($this->options['items_per_page']) ? $this->options['items_per_page'] : 0;
  }

  /**
   * Set how many items per page this pager will display.
   *
   * This is mostly used for things that will override the value.
   */
  function set_items_per_page($items) {
    $this->options['items_per_page'] = $items;
  }

  /**
   * Get the page offset, or how many items to skip.
   *
   * Even pagers that don't actually page can skip items at the beginning,
   * so few pagers will need to override this method.
   */
  function get_offset() {
    return isset($this->options['offset']) ? $this->options['offset'] : 0;
  }

  /**
   * Set the page offset, or how many items to skip.
   */
  function set_offset($offset) {
    $this->options['offset'] = $offset;
  }

  /**
   * Get the current page.
   *
   * If NULL, we do not know what the current page is.
   */
  function get_current_page() {
    return $this->current_page;
  }

  /**
   * Set the current page.
   *
   * @param $number
   *   If provided, the page number will be set to this. If NOT provided,
   *   the page number will be set from the global page array.
   */
  function set_current_page($number = NULL) {
    if (!is_numeric($number) || $number < 0) {
      $number = 0;
    }
    $this->current_page = $number;
  }

  /**
   * Get the total number of items.
   *
   * If NULL, we do not yet know what the total number of items are.
   */
129
  public function getTotalItems() {
merlinofchaos's avatar
merlinofchaos committed
130
131
132
133
134
135
    return $this->total_items;
  }

  /**
   * Get the pager id, if it exists
   */
136
  public function getPagerId() {
merlinofchaos's avatar
merlinofchaos committed
137
138
139
140
141
142
    return isset($this->options['id']) ? $this->options['id'] : 0;
  }

  /**
   * Provide the default form form for validating options
   */
143
  public function validateOptionsForm(&$form, &$form_state) { }
merlinofchaos's avatar
merlinofchaos committed
144
145
146
147

  /**
   * Provide the default form form for submitting options
   */
148
  public function submitOptionsForm(&$form, &$form_state) { }
merlinofchaos's avatar
merlinofchaos committed
149
150
151
152
153

  /**
   * Return a string to display as the clickable title for the
   * pager plugin.
   */
154
  public function summaryTitle() {
merlinofchaos's avatar
merlinofchaos committed
155
156
157
158
159
160
161
162
    return t('Unknown');
  }

  /**
   * Determine if this pager actually uses a pager.
   *
   * Only a couple of very specific pagers will set this to false.
   */
163
  public function usePager() {
merlinofchaos's avatar
merlinofchaos committed
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
    return TRUE;
  }

  /**
   * Determine if a pager needs a count query.
   *
   * If a pager needs a count query, a simple query
   */
  function use_count_query() {
    return TRUE;
  }

  /**
   * Execute the count query, which will be done just prior to the query
   * itself being executed.
   */
180
  public function executeCountQuery(&$count_query) {
merlinofchaos's avatar
merlinofchaos committed
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
    $this->total_items = $count_query->execute()->fetchField();
    if (!empty($this->options['offset'])) {
      $this->total_items -= $this->options['offset'];
    }

    $this->update_page_info();
    return $this->total_items;
  }

  /**
   * If there are pagers that need global values set, this method can
   * be used to set them. It will be called when the count query is run.
   */
  function update_page_info() {

  }

  /**
   * Modify the query for paging
   *
   * This is called during the build phase and can directly modify the query.
   */
203
  public function query() { }
merlinofchaos's avatar
merlinofchaos committed
204
205
206
207

  /**
   * Perform any needed actions just prior to the query executing.
   */
208
  public function preExecute(&$query) { }
merlinofchaos's avatar
merlinofchaos committed
209
210
211
212

  /**
   * Perform any needed actions just after the query executing.
   */
213
  public function postExecute(&$result) { }
merlinofchaos's avatar
merlinofchaos committed
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236

  /**
   * Perform any needed actions just before rendering.
   */
  function pre_render(&$result) { }

  /**
   * Render the pager.
   *
   * Called during the view render process, this will render the
   * pager.
   *
   * @param $input
   *   Any extra GET parameters that should be retained, such as exposed
   *   input.
   */
  function render($input) { }

  /**
   * Determine if there are more records available.
   *
   * This is primarily used to control the display of a more link.
   */
237
  public function hasMoreRecords() {
merlinofchaos's avatar
merlinofchaos committed
238
239
240
241
242
243
244
245
    return $this->get_items_per_page()
      && $this->total_items > (intval($this->current_page) + 1) * $this->get_items_per_page();
  }

  function exposed_form_alter(&$form, &$form_state) { }

  function exposed_form_validate(&$form, &$form_state) { }

246
  public function exposedFormSubmit(&$form, &$form_state, &$exclude) { }
merlinofchaos's avatar
merlinofchaos committed
247
248
249
250
251

  function uses_exposed() {
    return FALSE;
  }

252
  protected function itemsPerPageExposed() {
merlinofchaos's avatar
merlinofchaos committed
253
254
255
256
257
258
    return FALSE;
  }

  function offset_exposed() {
    return FALSE;
  }
259

merlinofchaos's avatar
merlinofchaos committed
260
261
262
263
264
}

/**
 * @}
 */