-
-
Notifications
You must be signed in to change notification settings - Fork 77
/
Zebra_Pagination.php
1352 lines (1059 loc) · 58.8 KB
/
Zebra_Pagination.php
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
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
53
54
55
56
57
58
59
60
61
62
63
64
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
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<?php
/**
* A generic, Twitter Bootstrap compatible (versions 3, 4 and 5), pagination script that automatically generates navigation links
* as well as next/previous page links, given the total number of records and the number of records to be shown per page.
* Useful for breaking large sets of data into smaller chunks, reducing network traffic and, at the same time, improving
* readability, aesthetics and usability.
*
* Read more {@link https://github.com/stefangabos/Zebra_Pagination/ here}
*
* @author Stefan Gabos <contact@stefangabos.ro>
* @version 2.4.8 (last revision: June 19, 2024)
* @copyright © 2009 - 2024 Stefan Gabos
* @license https://www.gnu.org/licenses/lgpl-3.0.txt GNU LESSER GENERAL PUBLIC LICENSE
* @package Zebra_Pagination
*/
class Zebra_Pagination {
/**
* defaults and initialize some private variables
*
* @var array<mixed>
* @access private
*/
private $_properties = array(
// should the "previous page" and "next page" links be always visible
'always_show_navigation' => true,
// should we avoid duplicate content
'avoid_duplicate_content' => true,
// whether pagination links should be removed leaving only the next and previous buttons,
// links to the first and last pages, as well as a label showing the current page and
// the total available pages
// if set to 1 will also remove the links to the first and last page
'condensed' => false,
// in condensed mode, the string indicating the current page
'condensed_progress' => '%d / %d',
// CSS classes to assign to the list, list item and to the anchor
'css_classes' => array(
'list' => 'pagination',
'list_item' => 'page-item',
'anchor' => 'page-link',
),
// default method for page propagation
'method' => 'get',
// string for "next page"
'next' => '»',
// by default, prefix page number with zeros
'padding' => true,
// the default starting page
'page' => 1,
// a flag telling whether current page was set manually or determined from the URL
'page_set' => false,
// where should the "next" / "previous" links should be placed, relative to the navigation links
'navigation_position' => 'outside',
// a flag telling whether query strings in base_url should be kept or not
'preserve_query_string' => 0,
// string for "previous page"
'previous' => '«',
// by default, we assume there are no records
// we expect this number to be set after the class is instantiated
'records' => 0,
// records per page
'records_per_page' => 0,
// should the links be displayed in reverse order
'reverse' => false,
// number of selectable pages
'selectable_pages' => 11,
// will be computed later on
'total_pages' => 0,
// trailing slashes are added to generated URLs
// (when "method" is "url")
'trailing_slash' => true,
// this is the variable name to be used in the URL for propagating the page number
'variable_name' => 'page',
);
/**
* Constructor of the class.
*
* Initializes the class and the default properties.
*
* @return void
*/
public function __construct() {
// set the default base url
$this->base_url();
}
/**
* By default, the *previous page* and *next page* links are always shown.
*
* By disabling this feature, the *previous page* and *next page* links will only be shown if there are more pages
* than {@link selectable_pages selectable pages}.
*
* <code>
* // show "previous page" / "next page" only if there are more pages
* // than there are selectable pages
* $pagination->always_show_navigation(false);
* </code>
*
* @param boolean $status (Optional) If set to `FALSE`, the *previous page* and *next page* links will only be
* shown if there are more pages than {@link selectable_pages selectable pages}.
*
* Default is `TRUE`.
*
* @since 2.0
*
* @return void
*/
public function always_show_navigation($status = true) {
// set property
$this->_properties['always_show_navigation'] = $status;
}
/**
* From a search engine's point of view URL `https://www.mywebsite.com/list` points to a different place than where
* `https://www.mywebsite.com/list?page=1` points to (because of the added query string in the second URL), but because
* both have the same content, your page will get an SEO penalization.
*
* In order to avoid this, the library will have for the first page (or last, if you are displaying links in {@link reverse}
* order) the same path as you have for when you are accessing the page for the first (un-paginated) time.
*
* If you want to disable this behavior call this method with its argument set to `FALSE`.
*
* <code>
* // don't avoid duplicate content
* $pagination->avoid_duplicate_content(false);
* </code>
*
* @param boolean $status (Optional) If set to `FALSE`, the library will have for the first page (or last,
* if you are displaying links in {@link reverse} order) a different path than the
* one you have when you are accessing the page for the first (un-paginated) time.
*
* Default is `TRUE`.
*
* @return void
*
* @since 2.0
*/
public function avoid_duplicate_content($status = true) {
// set property
$this->_properties['avoid_duplicate_content'] = $status;
}
/**
* The base URL to be used when generating the navigation links.
*
* This is helpful for the case when the URL where the records are paginated may have parameters that are not needed
* for subsequent requests generated by pagination.
*
* For example, suppose some records are paginated at `https://yourwebsite/mypage/`. When a record from the list is
* updated, the URL could become something like `https://youwebsite/mypage/?action=updated`. Based on the value of
* `action` a message would be shown to the user.
*
* Because of the way this script works, the pagination links would become
*
* `https://youwebsite/mypage/?action=updated&page=[page number]`
*
* when {@link method} is `get` and {@link variable_name} is `page`
*
* `https://youwebsite/mypage/page[page number]/?action=updated`
*
* when {@link method} is `url` and {@link variable_name} is `page`
*
* As a result, whenever the user would paginate, the message would be shown to him again and again because
* `action` will be preserved in the URL!
*
* The solution is to set the `base_url` to `https://youwebsite/mypage/` and in this way, regardless of how the URL
* changes, the pagination links will always be in the form of
*
* `https://youwebsite/mypage/?page=[page number]`
*
* when {@link method} is `get` and {@link variable_name} is `page`
*
* `https://youwebsite/mypage/page[page number]/`
*
* when {@link method} is `url` and {@link variable_name} is `page`
*
* Of course, you may still have query strings in the value of the `base_url` if you wish so, and these will be
* preserved when paginating.
*
* > If you need to preserve the hash in the URL, make sure to include the zebra_pagination.js file in your page!
*
* @param string $base_url (Optional) The base URL to be used when generating the navigation
* links
*
* Defaults is whatever returned by
* {@link https://www.php.net/manual/en/reserved.variables.server.php $_SERVER['REQUEST_URI']}
*
* @param boolean $preserve_query_string (Optional) Indicates whether values in query strings, other than
* those set in `base_url`, should be preserved
*
* Default is `TRUE`
*
* @return void
*/
public function base_url($base_url = '', $preserve_query_string = true) {
// we'll need this in case "variable_name" is an empty string
// (when "base_url" must be explicitly declared)
$this->_properties['base_url_explicit'] = $base_url !== '';
// set the base URL
$base_url = ($base_url == '' ? $_SERVER['REQUEST_URI'] : $base_url);
// parse the URL
$parsed_url = parse_url($base_url);
// cache the "path" part of the URL (that is, everything *before* the "?")
$this->_properties['base_url'] = rtrim($parsed_url['path'], '/');
// cache the "query" part of the URL (that is, everything *after* the "?")
$this->_properties['base_url_query'] = isset($parsed_url['query']) ? $parsed_url['query'] : '';
// store query string as an associative array
parse_str($this->_properties['base_url_query'], $this->_properties['base_url_query']);
// should query strings (other than those set in $base_url) be preserved?
$this->_properties['preserve_query_string'] = $preserve_query_string;
}
/**
* Removes pagination links leaving only the *next* and *previous* buttons, links to the *first* and *last* pages,
* as well as a label showing the current page and the total available pages.
*
* > Setting {@link selectable_pages selectable pages} to a value lower than `5` will automatically turn
* {@link condensed} mode on.
*
* @param boolean $extra_condensed Turning *extra condensed* mode on will also remove the links to the first
* and last pages.
*
* Default is `FALSE`.
*
* @since 2.4.0
*
* @return void
*/
public function condensed($extra_condensed = false) {
$this->_properties['condensed'] = $extra_condensed ? true : 1;
}
/**
* Allows defining of custom CSS class names to be applied to the HTML markup.
*
* @param array<string> $css_classes An associative array with one or more or all of the following keys:
*
* - **list**, for setting the CSS class name to be used for the ordered list (`<kbd><ol></kbd>`)
* - **list_item**, for setting the CSS class name to be used for the list item (`<kbd><li></kbd>`)
* - **anchor**, for setting the CSS class name to be used for the anchor (`<kbd><a></kbd>`)
*
* The default generated HTML markup looks like below:
*
* <code>
* <div class="Zebra_Pagination">
* <ol class="pagination">
* <li class="page-item">
* <a href="path/to/first/page/" class="page-link">1</a>
* </li>
* <li class="page-item">
* <a href="path/to/second/page/" class="page-link">2</a>
* </li>
* ...the other pages...
* </ol>
* </div>
* </code>
*
* Calling this method with the following argument...
*
* <code>
* $pagination->css_classes(array(
* 'list' => 'foo',
* 'list_item' => 'bar',
* 'anchor' => 'baz',
* ));
* </code>
*
* ...would result in the following markup:
*
* <code>
* <div class="Zebra_Pagination">
* <ol class="foo">
* <li class="bar">
* <a href="path/to/first/page/" class="baz">1</a>
* </li>
* <li class="bar">
* <a href="path/to/second/page/" class="baz">2</a>
* </li>
* ...the other pages...
* </ol>
* </div>
* </code>
*
* Default values are:
*
* <code>
* $pagination->css_classes(array(
* 'list' => 'pagination',
* 'list_item' => 'page-item',
* 'anchor' => 'page-link',
* ));
* </code>
*
* These values make the resulting markup to be compatible with versions 3,
* 4 and 5 of Twitter Bootstrap.
*
* @return void
*/
public function css_classes($css_classes) {
// if argument is invalid
if (!is_array($css_classes) || empty($css_classes) || array_keys($css_classes) != array_filter(array_keys($css_classes), function ($value) { return in_array($value, array('list', 'list_item', 'anchor'), true); })) {
// stop execution
trigger_error('Invalid argument. Method <strong>classes()</strong> accepts as argument an associative array with one or more of the following keys: <em>list, list_item, anchor</em>', E_USER_ERROR);
}
// merge values with the default ones
$this->_properties['css_classes'] = array_merge($this->_properties['css_classes'], $css_classes);
}
/**
* Returns the number of the currently selected page.
*
* <code>
* // echoes the current page
* echo $pagination->get_page();
* </code>
*
* @return int Return the number of the currently selected page
*/
public function get_page() {
// unless page was not specifically set through the "set_page" method
if (!$this->_properties['page_set']) {
// if
if (
// page propagation is SEO friendly
$this->_properties['method'] == 'url' &&
// the current page is set in the URL
preg_match('/\b' . str_replace('/', '\/', preg_quote(($this->_properties['variable_name'] === '' ? $this->_properties['base_url'] . '/' : '') . $this->_properties['variable_name'])) . '([0-9]+)\b/i', $_SERVER['REQUEST_URI'], $matches) > 0
) {
// set the current page to whatever it is indicated in the URL
$this->set_page((int)$matches[1]);
// if page propagation is done through GET and the current page is set in $_GET
} elseif (isset($_GET[$this->_properties['variable_name']])) {
// set the current page to whatever it was set to
$this->set_page((int)$_GET[$this->_properties['variable_name']]);
}
}
// if showing records in reverse order we must know the total number of records and the number of records per page
// *before* calling the "get_page" method
if ($this->_properties['reverse'] && $this->_properties['records'] == '') {
trigger_error('When showing records in reverse order you must specify the total number of records (by calling the "records" method) *before* the first use of the "get_page" method!', E_USER_ERROR);
} elseif ($this->_properties['reverse'] && $this->_properties['records_per_page'] == '') {
trigger_error('When showing records in reverse order you must specify the number of records per page (by calling the "records_per_page" method) *before* the first use of the "get_page" method!', E_USER_ERROR);
}
// get the total number of pages
$this->_properties['total_pages'] = $this->get_pages();
// if there are any pages
if ($this->_properties['total_pages'] > 0) {
// if current page is beyond the total number pages
/// make the current page be the last page
if ($this->_properties['page'] > $this->_properties['total_pages']) {
$this->_properties['page'] = $this->_properties['total_pages'];
// if current page is smaller than 1
// make the current page 1
} elseif ($this->_properties['page'] < 1) {
$this->_properties['page'] = 1;
}
}
// if we're just starting and we have to display links in reverse order
// set the first to the last one rather then first
if (!$this->_properties['page_set'] && $this->_properties['reverse']) {
$this->set_page($this->_properties['total_pages']);
}
// return the current page
return (int)$this->_properties['page'];
}
/**
* Returns the total number of available pages.
*
* The value is computed based on the {@link records() total number of records} and the {@link records_per_page() number of records to be shown per page}.
*
* <code>
* // get the total number of pages
* echo $pagination->get_pages();
* </code>
*
* @return int The total number of available pages
*
* @since 2.1
*/
public function get_pages() {
// return the total number of pages based on the total number of records and number of records to be shown per page
return $this->_properties['records_per_page'] > 0 ? ceil($this->_properties['records'] / $this->_properties['records_per_page']) : 0;
}
/**
* Change the labels for the *previous page* and *next page* links as well as the label used to indicate progress
* when in {@link condensed} mode.
*
* <code>
* // change the default labels
* $pagination->labels('Previous', 'Next', 'Page %d of %d pages');
* </code>
*
* @param string $previous (Optional) The label for the *previous page* link.
*
* Default is `«` (which looks like `«`)
*
* @param string $next (Optional) The label for the *next page* link.
*
* Default is `»` (which looks like `»`).
*
* @param string $progress (Optional) The label for showing the current progress when in {@link condensed} mode.
*
* Default is `%d / %d`
*
* First `%d` will be replaced with the current page while the second one with the
* number of total pages.
*
* @return void
*
* @since 2.0
*/
public function labels($previous = '«', $next = '»', $progress = '%d / %d') {
// set the labels
$this->_properties['previous'] = $previous;
$this->_properties['next'] = $next;
$this->_properties['condensed_progress'] = $progress;
}
/**
* Sets the method to be used for page propagation.
*
* <code>
* // set the method to the SEO friendly way
* $pagination->method('url');
* </code>
*
* @param string $method (Optional) The method to be used for page propagation.
*
* Valid values are:
*
* - `url` - page propagation is done in a SEO friendly way
*
* This method requires the {@link https://httpd.apache.org/docs/current/mod/mod_rewrite.html mod_rewrite}
* module to be enabled on your Apache server (or the equivalent for other web servers).
*
* When using this method, the current page will be passed in the URL as
*
* `https://youwebsite.com/yourpage/[variable name][page number]/`
*
* where `variable name` is set through {@link variable_name} and `page number`
* represents the current page.
*
* - `get` - page propagation is done through `GET`
*
* When using this method, the current page will be passed in the URL as
*
* `https://youwebsite.com/yourpage?[variable name]=[page number]`
*
* where `variable name` is set through {@link variable_name} and `page number`
* represents the current page.
*
* Default is `get`.
*
* @return void
*/
public function method($method = 'get') {
// set the page propagation method
$this->_properties['method'] = (strtolower($method) == 'url' ? 'url' : 'get') ;
}
/**
* Sets the position of the *next* and *previous* page, relative to the links to individual pages.
*
* @param string $position By default, the links for the *next* and *previous* page are shown on the outside
* (to the left and right) of the links to individual pages.
*
* These links can also be shown both on the left or both on the right of the links to
* individual pages by setting this argument to `left` or `right` respectively.
*
* Valid values are `left`, `right` and `outside`.
*
* Default is `outside`.
*
* @since 2.1
*
* @return void
*/
public function navigation_position($position) {
// set the positioning of next/previous page links
$this->_properties['navigation_position'] = (in_array(strtolower($position), array('left', 'right')) ? strtolower($position) : 'outside') ;
}
/**
* Sets whether page numbers should be prefixed with zeros.
*
* This is useful to keep the layout consistent by having the same number of characters for each page number.
*
* <code>
* // disable padding numbers with zeros
* $pagination->padding(false);
* </code>
*
* @param boolean $status (Optional) Setting this property to `FALSE` will disable padding.
*
* Default is `TRUE`.
*
* @return void
*/
public function padding($status = true) {
// set padding
$this->_properties['padding'] = $status;
}
/**
* Defines the total number of records that need to be paginated.
*
* Based on this and on the {@link records_per_page number of records to be shown per page}, the script will know
* how many pages there are.
*
* <code>
* // tell the script that there are 100 total records
* $pagination->records(100);
* </code>
*
* @param integer $records The total number of records that need to be paginated.
*
* @return void
*/
public function records($records) {
// the number of records
// make sure we save it as an integer
$this->_properties['records'] = (int)$records;
}
/**
* Defines the number of records that are displayed on a single page.
*
* Based on this and on the {@link records total number of records}, the script will know how many pages there are.
*
* <code>
* // tell the class that there are 20 records displayed on one page
* $pagination->records_per_page(20);
* </code>
*
* @param integer $records_per_page The number of records displayed on a single page.
*
* Default is `10`.
*
* @return void
*/
public function records_per_page($records_per_page) {
// the number of records displayed on one page
// make sure we save it as an integer
$this->_properties['records_per_page'] = (int)$records_per_page;
}
/**
* Generates and outputs or returns the HTML markup for the pagination.
*
* <code>
* // generate output
* // don't echo it but return it instead
* $output = $pagination->render(true);
* </code>
*
* > If {@link https://getbootstrap.com/ Twitter Bootstrap} is not present on the page, make sure to load the
* default styles by including the `zebra_pagination.css` file.
*
* @param boolean $return_output (Optional) Setting this argument to `TRUE` will instruct the script to
* return the generated output rather than outputting it to the screen.
*
* Default is `FALSE`.
*
* @return mixed
*/
public function render($return_output = false) {
// "base_url" must be explicitly declared if "variable_name" is an empty string and "method" is "url"
if ($this->_properties['variable_name'] === '' && $this->_properties['method'] == 'url' && !$this->_properties['base_url_explicit']) {
trigger_error('<strong>base_url</strong> must be explicitly declared if <strong>variable_name</strong> is <strong>an empty string</strong>', E_USER_ERROR);
// "variable_name" cannot be an empty string when "method" is "get"
} elseif ($this->_properties['variable_name'] === '' && $this->_properties['method'] == 'get') {
trigger_error('<strong>variable_name</strong> must not be an empty when <strong>method</strong> is <strong>get</strong>', E_USER_ERROR);
}
// get some properties of the class
$this->get_page();
// if there is a single page or no pages at all, and we don't have to always display navigation, don't display anything
if ($this->_properties['total_pages'] <= 1 && !$this->_properties['always_show_navigation']) {
return '';
}
// start building output
$output = '<div class="Zebra_Pagination"><ol' . ($this->_properties['css_classes']['list'] != '' ? ' class="' . trim($this->_properties['css_classes']['list']) . '"' : '') . '>';
// if we're showing records in reverse order
if ($this->_properties['reverse']) {
// if "next page" and "previous page" links need to be shown to the left of the links to individual pages
if ($this->_properties['navigation_position'] == 'left') {
// first show next/previous and then page links
$output .= $this->_show_next() . $this->_show_previous() . $this->_show_pages();
// if "next page" and "previous page" links need to be shown to the right of the links to individual pages
} elseif ($this->_properties['navigation_position'] == 'right') {
$output .= $this->_show_pages() . $this->_show_next() . $this->_show_previous();
// if "next page" and "previous page" links need to be shown on the outside of the links to individual pages
} else {
$output .= $this->_show_next() . $this->_show_pages() . $this->_show_previous();
}
// if we're showing records in natural order
} else {
// if "next page" and "previous page" links need to be shown to the left of the links to individual pages
if ($this->_properties['navigation_position'] == 'left') {
// first show next/previous and then page links
$output .= $this->_show_previous() . $this->_show_next() . $this->_show_pages();
// if "next page" and "previous page" links need to be shown to the right of the links to individual pages
} elseif ($this->_properties['navigation_position'] == 'right') {
$output .= $this->_show_pages() . $this->_show_previous() . $this->_show_next();
// if "next page" and "previous page" links need to be shown on the outside of the links to individual pages
} else {
$output .= $this->_show_previous() . $this->_show_pages() . $this->_show_next();
}
}
// finish generating the output
$output .= '</ol></div>';
// if $return_output is TRUE
// return the generated content
if ($return_output) {
return $output;
}
// if script gets this far, print generated content to the screen
echo $output;
}
/**
* By default, pagination links are shown in natural order, from 1 to the number of total pages.
*
* Calling this method with the `TRUE` argument will generate links in reverse order, from the number of total pages
* down to 1.
*
* <code>
* // show pagination links in reverse order rather than in natural order
* $pagination->reverse(true);
* </code>
*
* @param boolean $reverse (Optional) Set it to `TRUE` to generate navigation links in reverse order.
*
* Default is `FALSE`.
*
* @return void
*
* @since 2.0
*/
public function reverse($reverse = false) {
// set how the pagination links should be generated
$this->_properties['reverse'] = $reverse;
}
/**
* Defines the number of pagination links to be displayed at once besides *previous page* and *next page* links.
*
* <code>
* // display links to 15 pages
* $pagination->selectable_pages(15);
* </code>
*
* @param integer $selectable_pages The number of pagination links to be displayed at once besides *previous
* page* and *next page* links.
*
* > For optimal results this should be an odd value so that the number of
* links shown to the left and right of the current page is the same.
*
* Setting this to a value lower than `5` will automatically turn {@link condensed}
* mode on.
*
* Default is `11`.
*
* @return void
*/
public function selectable_pages($selectable_pages) {
// the number of selectable pages
// make sure we save it as an integer
$this->_properties['selectable_pages'] = (int)$selectable_pages;
// if less than 5 selectable pages, turn "condensed" mode on
if ($this->_properties['selectable_pages'] < 5) {
$this->condensed();
}
}
/**
* Sets the current page.
*
* <code>
* // sets the fifth page as the current page
* $pagination->set_page(5);
* </code>
*
* @param integer $page The page's number.
*
* A number lower than `1` will be interpreted as `1`, while a number greater than the
* total number of pages will be interpreted as the last page.
*
* @return void
*/
public function set_page($page) {
// set the current page
// make sure we save it as an integer
$this->_properties['page'] = (int)$page;
// if the number is lower than one
// make it '1'
if ($this->_properties['page'] < 1) {
$this->_properties['page'] = 1;
}
// set a flag so that the "get_page" method doesn't change this value
$this->_properties['page_set'] = true;
}
/**
* Enables or disables trailing slash on the generated URLs when {@link method} is `url`.
*
* From an SEO perspective, a page with trailing slash is considered different than the same page without the trailing
* slash. Read more on the subject at {@link https://webmasters.googleblog.com/2010/04/to-slash-or-not-to-slash.html Google Webmaster's official blog}.
*
* <code>
* // disables trailing slashes on generated URLs
* $pagination->trailing_slash(false);
* </code>
*
* @param boolean $status (Optional) Setting this property to `FALSE` will disable trailing slashes on generated
* URLs when {@link method} is `url`.
*
* Default is `TRUE` (trailing slashes are enabled by default).
*
* @return void
*/
public function trailing_slash($status = true) {
// set the state of trailing slashes
$this->_properties['trailing_slash'] = $status;
}
/**
* Sets the variable name to be used for page propagation.
*
* <code>
* // sets the variable name to "foo"
* // now, in the URL, the current page will be passed either as
* // "foo=[page number]" (if method is "get") or as
* // "/foo[page number]" (if method is "url")
* $pagination->variable_name('foo');
* </code>
*
* @param string $variable_name A string representing the variable name to be used for page propagation.
*
* Default is `page`.
*
* @return void
*/
public function variable_name($variable_name) {
// set the variable name
$this->_properties['variable_name'] = strtolower($variable_name);
}
/**
* Returns the URL for the page given as argument.
*
* @param integer $page The page number for which to build the URL for
*
* @access private
*
* @return string
*/
protected function _build_uri($page) {
// if page propagation method is through SEO friendly URLs
if ($this->_properties['method'] == 'url') {
// see if the current page is already set in the URL
// when "variable_name" is an empty string we'll also factor in "base_url" (which is mandatory in this case)
if (
preg_match(
'/\b' . str_replace('/', '\/', preg_quote(($this->_properties['variable_name'] === '' ? $this->_properties['base_url'] . '/' : '') . $this->_properties['variable_name'])) . '([0-9]+)\b/i',
$this->_properties['variable_name'] === '' ? $_SERVER['REQUEST_URI'] : $this->_properties['base_url']
) > 0
) {
// build string
$url = str_replace('//', '/', preg_replace(
// replace the currently existing value
// (also handle the case when "variable_name" is an empty string)
'/\b' . str_replace('/', '\/', preg_quote(($this->_properties['variable_name'] === '' ? $this->_properties['base_url'] . '/' : '') . $this->_properties['variable_name'])) . '([0-9]+)\b/i',
// if on the first page and we are avoiding duplicate content, remove page number
// (also handle the case when "variable_name" is an empty string)
($this->_properties['variable_name'] === '' ? $this->_properties['base_url'] . '/' : '') . ($page == 1 && $this->_properties['avoid_duplicate_content'] ? '' : $this->_properties['variable_name'] . $page),
// handle the case when "variable_name" is an empty string
$this->_properties['variable_name'] === '' ? $_SERVER['REQUEST_URI'] : $this->_properties['base_url']
));
// if the current page is not yet in the URL, set it, unless we're on the first page
// case in which we don't set it in order to avoid duplicate content
} else {
$url = ($this->_properties['variable_name'] !== '' ? $this->_properties['base_url'] . '/' : '') . $this->_properties['variable_name'] . $page;
}
// handle trailing slash according to preferences
$url = rtrim($url, '/') . ($this->_properties['trailing_slash'] ? '/' : '');
// if values in the query string - other than those set through base_url() - are not to be preserved
// preserve only those set initially
// otherwise, get the current query string
$query = !$this->_properties['preserve_query_string'] ? implode('&', $this->_properties['base_url_query']) : (isset($_SERVER['QUERY_STRING']) ? $_SERVER['QUERY_STRING'] : '');
// return the built string also appending the query string, if any
$uri = $url . ($query != '' ? '?' . $query : '');
// if page propagation is to be done through GET
} else {
// if values in the query string - other than those set through base_url() - are not to be preserved
// preserve only those set initially
if (!$this->_properties['preserve_query_string']) {
$query = $this->_properties['base_url_query'];
// otherwise, get the current query string, if any, and transform it to an array
} else {
parse_str(isset($_SERVER['QUERY_STRING']) ? $_SERVER['QUERY_STRING'] : '', $query);
}
// if we are avoiding duplicate content and if not the first/last page (depending on whether the pagination links are shown in natural or reversed order)
if (!$this->_properties['avoid_duplicate_content'] || ($page != ($this->_properties['reverse'] ? $this->_properties['total_pages'] : 1))) {
// add/update the page number
$query[$this->_properties['variable_name']] = $page;
// if we are avoiding duplicate content, don't use the "page" variable on the first/last page
} elseif ($this->_properties['avoid_duplicate_content'] && $page == ($this->_properties['reverse'] ? $this->_properties['total_pages'] : 1)) {
unset($query[$this->_properties['variable_name']]);
}
// make sure the returned HTML is W3C compliant
$uri = htmlspecialchars(html_entity_decode($this->_properties['base_url']) . (!empty($query) ? '?' . http_build_query($query) : ''));
}
// if for whatever reason the URI is an empty string it means it should be pointing to the root ("/")
// we can't leave this as an empty string or it will point to whatever URL is currently open in the browser
return $uri !== '' ? rawurldecode($uri) : '/';
}
/**
* Returns the *next page* URL, depending on whether the pagination links are shown in natural or reversed order.
*
* @access private
*
* @return string
*/
protected function _show_next() {
$output = '';
// if "always_show_navigation" is TRUE or
// if the total number of available pages is greater than the number of pages to be displayed at once
// it means we can show the "next page" link
if ($this->_properties['always_show_navigation'] || $this->_properties['total_pages'] > $this->_properties['selectable_pages']) {
// CSS classes to be applied to the list item, if any
$css_classes = isset($this->_properties['css_classes']['list_item']) && $this->_properties['css_classes']['list_item'] != '' ? array(trim($this->_properties['css_classes']['list_item'])) : array();
// if we're on the last page, the link is disabled
if ($this->_properties['page'] >= $this->_properties['total_pages']) {
$css_classes[] = 'disabled';
}
// generate markup
$output = '<li' .
// add CSS classes to the list item, if necessary
(!empty($css_classes) ? ' class="' . implode(' ', $css_classes) . '"' : '') . '><a href="' .
// the href is different if we're on the last page