Package: Zebra_Pagination

Class: Zebra_Pagination

source file: /Zebra_Pagination.php

A generic, Twitter Bootstrap compatible (both 3 and 4), 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 here

Author(s):

Version:

  • 2.3.1 (last revision: July 04, 2018)

Copyright:

  • (c) 2009 - 2018 Stefan Gabos

Class methods

constructor __construct() [line 90]

void __construct ( )

Constructor of the class.

Initializes the class and the default properties.

Tags:
access:   public
top

method always_show_navigation() [line 118]

void always_show_navigation ( [ boolean $show = true] )

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 selectable_pages.

  1. // show "previous page" / "next page" only if there are more pages
  2. // than there are selectable pages
  3. $pagination->always_show_navigation(false);
Tags:
since:   2.0
access:   public
Parameters:
boolean $show

(Optional) If set to FALSE, the "previous page" and "next page" links will only be shown if there are more pages than selectable_pages.

Default is TRUE.

top

method avoid_duplicate_content() [line 154]

void avoid_duplicate_content ( [ boolean $avoid_duplicate_content = true] )

When you first access a page with navigation you have the same content as you have when you access the first page from navigation. For example http://www.mywebsite.com/list will have the same content as http://www.mywebsite.com/list?page=1.

From a search engine's point of view these are 2 distinct URLs having the same content and your pages will be penalized for that.

So, by default, in order to avoid this, the library will have for the first page (or last, if you are displaying links in 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.

  1. // don't avoid duplicate content
  2. $pagination->avoid_duplicate_content(false);
Tags:
since:   2.0
access:   public
Parameters:
boolean $avoid_duplicate_content

(Optional) If set to FALSE, the library will have for the first page (or last, if you are displaying links in 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.

top

method base_url() [line 208]

void base_url ( [ string $base_url = ''] , [ boolean $preserve_query_string = true] )

The base URL to be used when generating the navigation links.

This is helpful for the case when, for example, the URL where the records are paginated may have parameters that are needed only once and need to be removed for any subsequent requests generated by pagination.

For example, suppose some records are paginated at http://yourwebsite/mypage/. When a record from the list is updated, the URL could become something like http://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:

  • http://youwebsite/mypage/?action=updated&page=[page number] when method is "get" and variable_name is "page";
  • http://youwebsite/mypage/page[page number]/?action=updated when method is "url" and variable_name is "page").

Because of this, 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 http://youwebsite/mypage/ and in this way, regardless of however will the URL be changed, the pagination links will always be in the form of

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 want to preserve the hash in the URL, make sure you load the zebra_pagination.js file!

Tags:
access:   public
Parameters:
string $base_url

(Optional) The base URL to be used when generating the navigation links

Defaults is whatever returned by $_SERVER['REQUEST_URI']

boolean $preserve_query_string

(Optional) Indicates whether values in query strings, other than those set in $base_url, should be preserved

Default is TRUE

top

method css_classes() [line 301]

void css_classes ( array $css_classes )

Sets the CSS class names to be applied to the unorderd list, list item and anchors that make up the HTML markup of the pagination links.

Tags:
access:   public
Parameters:
array $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 unordered list (<ul>)
  • list_item, for setting the CSS class name to be used for the list item (<li>)
  • anchor, for setting the CSS class name to be used for the anchor (<a>)

The default generated HTML markup looks like below:

  1. <div class="Zebra_Pagination">
  2.     <ul class="pagination">
  3.         <li class="page-item">
  4.             <a href="path/to/first/page/" class="page-link">1</a>
  5.         </li>
  6.         <li class="page-item">
  7.             <a href="path/to/second/page/" class="page-link">2</a>
  8.         </li>
  9.         ...the other pages...
  10.     </ul>
  11. </div>

Calling this method with the following argument...

  1. $pagination->css_classes(array(
  2.     'list'      =>  'foo',
  3.     'list_item' =>  'bar',
  4.     'anchor'    =>  'baz',
  5. ));

...would result in the following markup:

  1. <div class="Zebra_Pagination">
  2.     <ul class="foo">
  3.         <li class="bar">
  4.             <a href="path/to/first/page/" class="baz">1</a>
  5.         </li>
  6.         <li class="bar">
  7.             <a href="path/to/second/page/" class="baz">2</a>
  8.         </li>
  9.         ...the other pages...
  10.     </ul>
  11. </div>

You can change only the CSS class names you want and the default CSS class names will be used for the other ones.

Default values are:

  1. $pagination->css_classes(array(
  2.     'list'      =>  'pagination',
  3.     'list_item' =>  'page-item',
  4.     'anchor'    =>  'page-link',
  5. ));

These values make the resulting markup to be compatible with both the older version 3 of Twitter Bootstrap as well as the new version 4.

top

method get_page() [line 324]

integer get_page ( )

Returns the current page's number.

  1. // echoes the current page
  2. echo $pagination->get_page();
Tags:
return:   Returns the current page's number
access:   public
top

method get_pages() [line 396]

integer get_pages ( )

Returns the total number of pages, based on the total number of records and the number of records to be shown per page.

  1. // get the total number of pages
  2. echo $pagination->get_pages();
Tags:
return:   Returns the total number of pages, based on the total number of records and the number of records to be shown per page.
since:   2.1
access:   public
top

method labels() [line 422]

void labels ( [ string $previous = '&laquo;'] , [ string $next = '&raquo;'] )

Change the labels for the "previous page" and "next page" links.

  1. // change the default labels
  2. $pagination->labels('Previous''Next');
Tags:
since:   2.0
access:   public
Parameters:
string $previous

(Optional) The label for the "previous page" link.

Default is "Previous page".

string $next

(Optional) The label for the "next page" link.

Default is "Next page".

top

method method() [line 463]

void method ( [ string $method = 'get'] )

Set the method to be used for page propagation.

  1. // set the method to the SEO friendly way
  2. $pagination->method('url');
Tags:
access:   public
Parameters:
string $method

(Optional) The method to be used for page propagation.

Values can be:

  • url - page propagation is done in a SEO friendly way;

This method requires the 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 http://youwebsite.com/yourpage/[variable name][page number]/ where [variable name] is set by 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 http://youwebsite.com/yourpage?[variable name]=[page number] where [variable name] is set by variable_name and [page number] represents the current page.

Default is "get".

top

method navigation_position() [line 487]

void navigation_position ( string $position )

By default, next/previous page links are shown on the outside of the links to individual pages.

These links can also be shown both on the left or on the right of the links to individual pages by setting the method's argument to "left" or "right" respectively.

Tags:
since:   2.1
access:   public
Parameters:
string $position

Setting this argument to "left" or "right" will instruct the script to show next/previous page links on the left or on the right of the links to individual pages.

Allowed values are "left", "right" and "outside".

Default is "outside".

top

method padding() [line 511]

void padding ( [ boolean $enabled = true] )

Sets whether page numbers should be prefixed by zeroes.

This is useful to keep the layout consistent by having the same number of characters for each page number.

  1. // disable padding numbers with zeroes
  2. $pagination->padding(false);
Tags:
access:   public
Parameters:
boolean $enabled

(Optional) Setting this property to FALSE will disable padding rather than enabling it.

Default is TRUE.

top

method records() [line 532]

void records ( integer $records )

Sets the total number of records that need to be paginated.

Based on this and on the value of records_per_page, the script will know how many pages there are.

  1. // tell the script that there are 100 total records
  2. $pagination->records(100);
Tags:
access:   public
Parameters:
integer $records The total number of records that need to be paginated
top

method records_per_page() [line 556]

void records_per_page ( integer $records_per_page )

Sets the number of records that are displayed on one page.

Based on this and on the value of records, the script will know how many pages there are.

  1. //  tell the class that there are 20 records displayed on one page
  2. $pagination->records_per_page(20);
Tags:
access:   public
Parameters:
integer $records_per_page

The number of records displayed on one page.

Default is 10.

top

method render() [line 582]

void render ( [ boolean $return_output = false] )

Generates the output.

Make sure your script references the CSS file unless you are using Twitter Bootstrap!

  1. //  generate output but don't echo it
  2. //  and return it instead
  3. $output $pagination->render(true);
Tags:
access:   public
Parameters:
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.

top

method reverse() [line 660]

void reverse ( [ boolean $reverse = false] )

By default, pagination links are shown in natural order, from 1 to the number of total pages.

Calling this method with the argument set to TRUE will generate links in reverse order, from the number of total pages to 1.

  1. // show pagination links in reverse order rather than in natural order
  2. $pagination->reverse(true);
Tags:
since:   2.0
access:   public
Parameters:
boolean $reverse

(Optional) Set it to TRUE to generate navigation links in reverse order.

Default is FALSE.

top

method selectable_pages() [line 685]

void selectable_pages ( integer $selectable_pages )

Sets the number of links to be displayed at once (besides "previous" and "next" links)

  1. // display links to 15 pages
  2. $pagination->selectable_pages(15);
Tags:
access:   public
Parameters:
integer $selectable_pages

The number of links to be displayed at once (besides "previous" and "next" links).

You should set this to an odd number so that the same number of links will be shown to the left and to the right of the current page.

Default is 11.

top

method set_page() [line 708]

void set_page ( integer $page )

Sets the current page.

  1. // sets the fifth page as the current page
  2. $pagination->set_page(5);
Tags:
access:   public
Parameters:
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.

top

method trailing_slash() [line 740]

void trailing_slash ( boolean $enabled )

Enables or disables trailing slash on the generated URLs when method is "url".

Read more on the subject on Google Webmaster's official blog.

  1. // disables trailing slashes on generated URLs
  2. $pagination->trailing_slash(false);
Tags:
access:   public
Parameters:
boolean $enabled

(Optional) Setting this property to FALSE will disable trailing slashes on generated URLs when method is "url".

Default is TRUE (trailing slashes are enabled by default).

top

method variable_name() [line 763]

void variable_name ( string $variable_name )

Sets the variable name to be used for page propagation.

  1. //  sets the variable name to "foo"
  2. //  now, in the URL, the current page will be passed either as "foo=[page number]" (if method is "get") or
  3. //  as "/foo[page number]" (if method is "url")
  4. $pagination->variable_name('foo');
Tags:
access:   public
Parameters:
string $variable_name

A string representing the variable name to be used for page propagation.

Default is "page".

top