Home » HTML » Pager_Sliding » Manual

Introduction

Introduction – Usage of Pager_Sliding

What is Pager_Sliding?

Pager_Sliding is a class to page an array of data. It is taken as input and it is paged according to various parameters. Pager_Sliding also builds links within a specified range, and allows complete customization of the output (it even works with mod_rewrite). It is compatible with PEAR::Pager's API

Deprecated

This package is deprecated in favour of the new Pager v.2.x.

Example 1

This simple example will page the array of alphabetical letters, giving back pages with 3 letters per page, and links to the previous two / next two pages:

<?php
require_once 'Pager/Sliding.php';
$params = array(
            'perPage'    => 3,
            'delta'      => 2,
            'itemData'   => array('a','b','c','d','e',[...omissis...],'z')
            );
$pager = & new Pager_Sliding($params);
$data  = $pager->getPageData();
$links = $pager->getLinks();
//$links is an ordered+associative array with 'back'/'pages'/'next'/'first'/'last'/'all' links.
//NB: $links['all'] is the same as $pager->links;

//echo links to other pages:
echo $links['all']

//Show data for current page:
echo 'PAGED DATA: ' ; print_r($data);

//Results from methods:
echo 'getCurrentPageID()...: '; var_dump($pager->getCurrentPageID());
echo 'getNextPageID()......: '; var_dump($pager->getNextPageID());
echo 'getPreviousPageID()..: '; var_dump($pager->getPreviousPageID());
echo 'numItems()...........: '; var_dump($pager->numItems());
echo 'numPages()...........: '; var_dump($pager->numPages());
echo 'isFirstPage()........: '; var_dump($pager->isFirstPage());
echo 'isLastPage().........: '; var_dump($pager->isLastPage());
echo 'isLastPageComplete().: '; var_dump($pager->isLastPageComplete());
echo '$pager->range........: '; var_dump($pager->range);
?>

In case you're wondering, $pager->range is a numeric array; its keys are the numbers of the pages in the current range, and the matching values are booleans (TRUE if its key represents currentPage, FALSE otherwise). This array can be useful to build the links manually, e.g. when using a template engine.

Example 2

This example shows how you can use this class with mod_rewite. Let's suppose we have a .htaccess like this:

It should transform an url like "/articles/march/art15.html" into "/article.php?num=15&month=march"

<?php
require_once 'Pager/Sliding.php';

$month = 'september';
$params = array(
            'append'    => false,
            'urlVar'    => 'num',
            'path'      => 'http://myserver.com/articles/' . $month,
            'fileName'  => 'art%d.html',  //Pager replaces "%d" with page number...
            'itemData'  => array('a','b','c',[...omissis...],'z'),
            'perPage'   => 3
            );
$pager = & new Pager_Sliding($params);

$data  = $pager->getPageData();
echo $pager->links;
echo 'Data for current page: '; print_r($data);
?>

More pagers in a single page

Using more than one pager in a single page is as simple as using a different urlVar for each pager:

<?php
require_once 'Pager/Sliding.php';

//first pager
$params1 = array(
            'perPage'    => 3,
            'urlVar'     => pageID_articles,  //1st identifier
            'itemData'   => $someArray
            );
$pager1 = & new Pager_Sliding($params1);
$data1  = $pager1->getPageData();
$links1 = $pager1->getLinks();

//second pager
$params2 = array(
            'perPage'    => 8,
            'urlVar'     => pageID_news,      //2nd identifier
            'itemData'   => $someOtherArray
            );
$pager2 = & new Pager_Sliding($params2);
$data2  = $pager2->getPageData();
$links2 = $pager2->getLinks();
?>

Pager (v.1.x) vs. Pager_Sliding

Pager (v.1.x) vs. Pager_Sliding – Feature comparison of the two classes

What are the differences with Pager?

While Pager v.1.x has a "jumping window" style, Pager_Sliding has a "sliding window" style. What does that mean? Let's see an example:

Pager v.1.x logic

Let's suppose that the data spans on 15 pages, and the window width is 5 page links. The links are built on "frames" of 5 pages each: [1-5] [6-10] [11-15] Pager v.1.x always shows the same 5 page links while you are on one of these pages. Here's a temporal succession of the links, starting from page 1 and moving forward. There are brakets around current page number to highlight this:

<?php
a)    {1} 2  3  4  5  =>   // first frame: [1-5]
b) <=  1 {2} 3  4  5  =>
c) <=  1  2 {3} 4  5  =>
d) <=  1  2  3 {4} 5  =>
e) <=  1  2  3  4 {5} =>   // HERE IT JUMPS TO THE NEXT FRAME
f) <= {6} 7  8  9 10  =>   // second frame: [6-10]
g) <=  6 {7} 8  9 10  =>
h) <=  6  7 {8} 9 10  =>
?>

and so on. See what a "jumping window" frame is? When you reach a limit (in the example, you go from page 5 to page 6), it "jumps" to next frame (links from page 6 to 10).

Pager_Sliding logic

Instead of jumping from one frame to the other, with Pager_Sliding the change is done smoothly, and the current page is always shown at the center of the "window" (except of course for the first and the last pages):

<?php
a)       {1} 2  3  4  5  => [15]
b) [1] <= 1 {2} 3  4  5  => [15]
c) [1] <= 1  2 {3} 4  5  => [15]  // HERE IT's STARTING WORKING AS DESIGNED
d) [1] <= 2  3 {4} 5  6  => [15]  // see: current page number is at the center of the window
e) [1] <= 3  4 {5} 6  7  => [15]  // and it stays there...
f) [1] <= 4  5 {6} 7  8  => [15]
g) [1] <= 5  6 {7} 8  9  => [15]
h) [1] <= 6  7 {8} 9 10  => [15]
?>

and so on.

Other differences

Apart from the different "philosophy", Pager_Sliding is also designed to be highly customizable.

UPDATE: since Pager 2.x release, every option once only available in Pager_Sliding is now fully implemented in Pager too, and more. As stated in the Intro, Pager_Sliding is now deprecated in favour of the new Pager v.2.x. You can have both behaviours ("Jumping" and "Sliding") in Pager v.2.x, just change the mode. Please refer to Pager docs for more details.

• There are *many* options to change the look and feel of the links in your page. They are explained in the constructor docs.
• It can work with Apache mod_rewrite module too, see the examples for that.
• It is "template"-friendly, i.e. you can assign the processed links and page numbers to your custom vars and use them to draw your link bar according to your page layout, without worrying about the underlying logic.
• You can easily extend the class; this is useful if you plan to use the class in many different pages and you don't want to set the same options everytime: just set your preferred default values in your extending class and you're done!

Pager_Sliding::getCurrentPageID

Pager_Sliding::getCurrentPageID() – Returns current page number

Synopsis

integer getCurrentPageID ( )

Return value

integer - Current page number.

Pager_Sliding::getLinks

Pager_Sliding::getLinks() – Returns back/next/first/last and page links, both as ordered and associative array.

Synopsis

array Pager_Sliding::getLinks ( integer $pageID = null )

Parameter

• integer $pageID - Optional pageID. If specified, linksfor that page are provided instead of current one.

Return value

return back/pages/next/first/last/all links, both as numeric and associative array.

Pager_Sliding::getNextPageID

Pager_Sliding::getNextPageID() – Returns next page number.

Synopsis

mixed Pager_Sliding::getNextPageID ( )

Description

If current page is last page this function returns FALSE, otherwise returns next page number.

Return value

return Next page number or FALSE

Pager_Sliding::getOffsetByPageId

Pager_Sliding::getOffsetByPageId() – Returns offsets for given pageID.

Synopsis

array Pager_Sliding::getOffsetByPageId ( integer $pageid = null )

Description

Eg, if you pass it pageID = 5 and your delta is 2 it will return you 3 and 7. PageID of 6 would give you 4 and 8

NB: The behaviour of this function could be misleading: it was left only for compatibility with PEAR::Pager. It could raise some confusion when pageID is within delta positions from an extreme: in fact this method returns also the extremes, while $this->_getPageLinks leaves them out. Pager_Sliding works this way: if pageID is NOT an extreme, show first and last page within brackets: [1] << 5 | _6_ | 7 >> [15] So when dealing with pageID within delta positions from an extreme, this method would return the extreme as well, while $this->_getPageLinks would return (for instance) 2 | _3_ | 4 | 5 even if pageID is 3 and delta is 2. Consider this method deprecated and/or subject to changes.

Parameter

• integer $pageid - PageID to get offsets for

Return value

return array with first and last offsets

Deprecated

deprecated

Pager_Sliding::getPageData

Pager_Sliding::getPageData() – Returns an array of current pages data

Synopsis

array Pager_Sliding::getPageData ( integer $pageID = null )

Parameter

• integer $pageID - Desired page ID (optional)

Return value

return array of data for this page.

Pager_Sliding::getPageIdByOffset

Pager_Sliding::getPageIdByOffset() – Overload PEAR::Pager method. VOID.

Synopsis

array Pager_Sliding::getPageIdByOffset ( integer $index )

Parameter

• integer $index - Offset to get pageID for

Return value

return Page number for this offset

Deprecated

deprecated. It is only here for compatibility with PEAR::Pager.

Pager_Sliding::getPreviousPageID

Pager_Sliding::getPreviousPageID() – Returns previous page number.

Synopsis

mixed Pager_Sliding::getPreviousPageID ( )

Description

If current page is first page this function returns FALSE, otherwise returns previous page number.

Return value

return Previous page number or FALSE.

Pager_Sliding::isFirstPage

Pager_Sliding::isFirstPage() – Returns whether current page is first page

Synopsis

bool Pager_Sliding::isFirstPage ( )

Return value

return TRUE or FALSE, wrt it is the first page or not.

Pager_Sliding::isLastPage

Pager_Sliding::isLastPage() – Returns whether current page is last page

Synopsis

bool Pager_Sliding::isLastPage ( )

Return value

return TRUE or FALSE, wrt it is the last page or not.

Pager_Sliding::isLastPageComplete

Pager_Sliding::isLastPageComplete() – Returns whether last page is complete

Synopsis

bool Pager_Sliding::isLastPageComplete ( )

Return value

return TRUE or FALSE, wrt the last page is complete (i.e. it has perPage values in the array for the last page) or not.

Pager_Sliding::numItems

Pager_Sliding::numItems() – Returns number of items

Synopsis

int Pager_Sliding::numItems ( )

Return value

return integer - Number of items

Pager_Sliding::numPages

Pager_Sliding::numPages() – Returns number of pages

Synopsis

int Pager_Sliding::numPages ( )

Return value

return integer - Number of pages

Pager_Sliding::Sliding

Pager_Sliding::Sliding() – Creates a pager instance

Synopsis

object &Sliding ( array $options )

Parameter

Pager_Sliding constructor takes an associative array of parameters as input values. This is the complete list of these options:

• itemData [array] Array of items to page.
• totalItems [integer] Number of items to page (used only if itemData is not provided).
• perPage [integer] Number of items to display on each page.
• delta [integer] Number of page numbers to display before and after the current one.
• expanded [boolean] if TRUE, window size is always 2*delta+1
• linkClass [string] Name of CSS class used for link styling.
• urlVar [string] Name of URL var used to indicate the page number. Default value is "pageID".
• path [string] Complete path to the page (without the page name).
• fileName [string] name of the page, with a "%d" if append == TRUE.
• append [boolean] If TRUE pageID is appended as GET value to the URL. If FALSE it is embedded in the URL according to fileName specs.
• altPrev [string] Alt text to display for prev page, on prev link. Default value is "previous page";
• altNext [string] Alt text to display for next page, on next link. Default value is "next page";
• altPage [string] Alt text to display before the page number. Default value is "page ".
• prevImg [string] Something to display instead of "<<". It can be text such as "<< PREV" or an <img/> as well.
• nextImg [string] Something to display instead of ">>". It can be text such as "NEXT >>" or an <img/> as well.
• separator [string] What to use to separate numbers. It can be an <img/>, a comma, an hyphen, or whatever.
• spacesBeforeSeparator [integer] Number of spaces before the separator.
• spacesAfterSeparator [integer] Number of spaces after the separator.
• firstPagePre [string] String used before first page number. It can be an <img/>, a "{", an empty string, or whatever.
• firstPagePost [string] String used after first page number. It can be an <img/>, a "}", an empty string, or whatever.
• lastPagePre [string] Similar to firstPagePre, but used for last page number.
• lastPagePost [string] Similar to firstPagePost, but used for last page number.
• curPageLinkClassName [string] Name of CSS class used for current page link.
• lastPagePost [boolean] if there's only one page, don't display pager (returns an empty string).

REQUIRED options are:

• fileName IF append==FALSE (default is TRUE)
• itemData OR totalItems (if itemData is set, totalItems is overwritten)

Return value

object - a specific Pager_Sliding instance or a PEAR_Error object, if fails