Introduction

When you retrieve a large amount of rows from a database consultation, you might want to display your result in several pages instead of having everything listed on a very long page. The paginator component might help the programmer to minimize the impact of transforming a simple data display into a complex multipage management display.

What it looks like

Many sites, including Google, use paginators to display search results in multiple pages. Some can be very stily and very well designed. In our case, we will focus on the programmatic aspect of the question. Our paginator might look like this:

<< < 1 2 3 > >>

Example:

Where:

Additionaly, the user will only be able to click the pages available. He won't be allowed to click on the current page number, and for instance, if he is seeing the first page, he won't be able to go to the previous page.

Defining the role of the component

Normaly when you want to display the result of a consultation to a database into a webpage, you just have to fetch each row corresponding to the result of the query and display the resulting array. When the returned resultset is big and you want to break into several pieces, managing the navigation between each result page, is not so easy. The paginator component will cut on this work.

The component will receive the query to send to the database and several layout parameters used for the paginator to be displayed.
The component will output a set of rows corresponding to that page and the number of lines for each page.
Addictionaly, the component had to be Search Engine frendly, which means that every page of results, accessible from the paginator should be spider browsable. I could achieve this only by using an access to each page by passing a querystring like www.mypage.com/results.php?page=325
Also the component should respect the previous existance of a querystring. If the page where the paginator is located is accessed by www.mypage.com/results.php?param=a¶m2=b, then the access to page 325 should complete the existing querystring without damaging it: www.mypage.com/results.php?param=a¶m2=b&page=325 The paginator should also be able to be generated several time on the same page, therefore a paginator id property has been created in order to manage different page numbers whithin the same web page.

How to call the component

Input properties

1 - $paginatorid (mandatory): Allows the user to use several paginator on the same page, with different id.

2 - $paginatorquerystring (mandatory): The same query string you would have submited to retrieve the result set. The component will manage what information to retrieve according to other the number of line per page and the number of rows retrieved by the query.

3 - $paginatorbigjumps (optional, by default 'auto'): .

4 - $paginatorcurrentpage (optional by default 1): The page the user is trying to display.

5 - $paginatornumberoflines (optional, by default 20): This is the number of line you want to display on a page.

6 - $paginatordepth (optional, by default 4): The maximum number of pages that will be shown on the paginator bar on each side.

7 - $paginatorstyle (optional, by default ""): The CSS style used to display the paginator bar.

Output properties

1 - $paginatorresult: is built when getresults is executed. It is a bidimentional array containing each row of the result set for the current page.

2 - $paginatornumberofrows: is the number of rows given by the query.

Functions of the component

1 - getresults($db): Fill both output variables $paginatorresult and $paginatornumberofrows, by completing the original query with limits.

2 - drawpaginator(): Draws the paginator bar, after the results are fetched.

3 - rebuildquerystring(): Private function, used in drawpaginator only. Recreates the querystring with the new value for the selected page. This function respects the existing querystring and add to it, or modifies the value for the current page associated to the resultset.

Getting the code

The class paginator can be seen below:

Using the class can be as simple as the following:

Sample

Check this link out.

History

2008-10-06: First version