Package: Zebra_Pagination

Class: Zebra_Pagination

source file: /Zebra_Pagination.php

Class Overview


A generic 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.

Adheres to pagination best practices (provides large clickable areas, doesn't use underlines, the selected page is clearly highlighted, page links are spaced out, provides "previous page" and "next page" links, provides "first page" and "last page" links - as outlined in an article by Faruk Ates from 2007, which can now be found here), can generate links both in natural as well as in reverse order, can be easily, localized, supports different positions for next/previous page buttons, supports page propagation via GET or via URL rewriting, is SEO-friendly, and the appearance is easily customizable through CSS.

The library is compatible with Twitter Bootstrap.

Please note that this is a *generic* pagination script, meaning that it does not display any records and it does not have any dependencies on database connections or SQL queries, making it very flexible! It is up to the developer to fetch the actual data and display it based on the information returned by this pagination script. The advantage is that it can be used to paginate over records coming from any source like arrays or databases.

The code is heavily commented and generates no warnings/errors/notices when PHP's error reporting level is set to E_ALL.

Visit http://stefangabos.ro/php-libraries/zebra-pagination/ for more information.

For more resources visit http://stefangabos.ro/

Author(s):

Version:

  • 2.2.1 (last revision: February 19, 2016)

Copyright:

  • (c) 2009 - 2016 Stefan Gabos

Class methods

constructor __construct()

void __construct ( )

Constructor of the class.

Initializes the class and the default properties.

Top

method always_show_navigation()

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 set through 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 set through selectable_pages().

Default is TRUE.

Top

method avoid_duplicate_content()

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 (unpaginated) time.

If you want to disable this behaviour 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
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 (unpaginated) time.

Default is TRUE.

Top

method base_url()

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:

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 get_page()

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()

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()

void labels ( [ string $previous = '«'] , [ string $next = '»'] )

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()

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()

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
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()

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()

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.

The total number of pages is given by the fraction between the total number records (set through records()) and the number of records that are shown on a page (set through records_per_page()).

  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()

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: the total number of pages is given by the fraction between the total number of records and the number of records that are shown on one page.

  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()

void render ( [ boolean $return_output = false] )

Generates the output.

Make sure your script references the CSS file!

  1. //  generate output but don't echo it
  2. //  but 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()

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()

void selectable_pages ( integer $selectable_pages )

Sets the number of links to be displayed at once (besides the "previous page" and "next page" 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 the "previous page" and "next page" 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()

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.

The total number of pages is given by the fraction between the total number records (set through records()) and the number of records that are shown on one page (set through records_per_page()).

Top

method trailing_slash()

void trailing_slash ( boolean $enabled )

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

Read more on the subject on Google Webmasters'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()

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