This tutorial is brought to you by the kind folks at Stranger Studios. We encourage you to check out our other projects.

Digg-Style Pagination

READ FIRST: I've released a my own modularized version of the pagination code. If you just want to use the function and aren't interested in its implementation, use this code.

Download the PHP code for the function here: diggstyle_function.txt.

To use it make a function call like getPaginationString($page, $totalitems, $limit, $adjacents, $targetpage, $pagestring);.

$page is the current page number

$totalitems is the total number of items in the set. You usually get this from a SQL query.

$adjacents is the number of page links to put adjacent to the current page.

$targetpage is the URL you want to point to. e.g. index.php

$pagetext is the string used to append the page variable to the URL. e.g. ?page= or &p=

Use the stylesheet below.

You may still want to read everything below to understand how the algorithm works.

OTHER VERSIONS: Some awesome folks have created some great stuff based on this code.

A modularized PHP version, written by Victor de la Rocha at Mis-Algoritmos.com. This code will be much easier to use in your own application. People who just want to download and use some code should visit Victor's page (written in spanish, but you should be able to understand the code). Continue reading below if you are interested in how the algorithm works.

Also, Mis Algoritmos is at it again with a digg-style pagination plugin for Wordpress based on this code. (more styles)

A Perl version, written by Andrew. See his write up below.

A helper for the Zend PHP Framework, written by Rich Milns. See the code at pastie.org.

This page will explain how to build a pagination scheme similar to the one found at Digg.com. Flickr.com uses the same scheme. To be fair, I don't know who first introduced this style of pagination; I just noticed it at Digg first.

Please post any questions or comments at this blog post.

Example

This example is pulling items from our Stranger Studios portfolio. Two items are shown for each page. You can use the pagination object to browse through the pages.

Here is a demo just showing the pagination without any results.

To see a real world example, checkout this list of Oregonian wines at WineLog.net

How Do I Do That?

The main features of this pagination scheme are as follows:

The pagination object has a "previous" and "next" button which takes the user to the next page. The previous button is disabled on the first page. Similarly, the next button is disabled on the last page.
The pagination object will always display links to the first two pages and the last two pages of the set.
The pagination object will always display links to the first x ($adjacents in the code) pages before and after the current page.
The pagination object will only show at most 5+2x links (first two + prior x + current page + next x + last two). All links not shown will be replaced by ...

Ok, now that we have that out of the way. Let's build this thing. Our pagination scheme consists of two parts: the CSS and the code to draw the object.

CSS

Copy this code into your stylesheet or view source here (change extension to .css on your server).

The Code

This part is a little trickier. Below is an implementation in PHP. A good programmer should be able to transpose the code to any other language. If you do, let us know.

There is some potential to take advantage of redundancies, and a definite potential to abstract this into a class or function for general use. I've left these for future exercises.

If you have any trouble implementing the code, let me know and I will try to help out.

Copy the code below into your php file or view source here (change extension to .php to run on your server).

UPDATE: Or download this php code, which includes a function to make using this much easier. Instruction on how to use the function are at the top of the page.

<?php
	/*
		Place code to connect to your DB here.
	*/
	
	// How many adjacent pages should be shown on each side?
	$adjacents = 3;
	
	/* 
	 First get total number of rows in data table. 
	 If you have a WHERE clause in your query, make sure you mirror it here.
	*/
	$query = "SELECT COUNT(*) as num FROM portfolio";
	$total_pages = mysql_fetch_array(mysql_query($query));
	$total_pages = $total_pages['num'];
	
	/* Setup vars for query. */
	$limit = 2; 								//how many items to show per page
	if($page) 
		$start = ($page - 1) * $limit; 			//first item to display on this page
	else
		$start = 0;								//if no page var is given, set start to 0
	
	/* Get data. */
	$query = "SELECT category, uname, title FROM portfolio LIMIT $start, $limit";
	$portfolio = mysql_query($query);
	
	/* Setup page vars for display. */
	if ($page == 0) $page = 1;					//if no page var is given, default to 1.
	$prev = $page - 1;							//previous page is page - 1
	$next = $page + 1;							//next page is page + 1
	$lastpage = ceil($total_pages/$limit);		//lastpage is = total pages / items per page, rounded up.
	$lpm1 = $lastpage - 1;						//last page minus 1
	
	/* 
		Now we apply our rules and draw the pagination object. 
		We're actually saving the code to a variable in case we want to draw it more than once.
	*/
	$pagination = "";
	if($lastpage > 1)
	{	
		$pagination .= "<div class=\"pagination\">";
		//previous button
		if ($page > 1) 
			$pagination.= "<a href=\"diggstyle.php?page=$prev\">« previous</a>";
		else
			$pagination.= "« previous";	
		
		//pages	
		if ($lastpage < 7 + ($adjacents * 2))	//not enough pages to bother breaking it up
		{	
			for ($counter = 1; $counter <= $lastpage; $counter++)
			{
				if ($counter == $page)
					$pagination.= "$counter";
				else
					$pagination.= "<a href=\"diggstyle.php?page=$counter\">$counter</a>";					
			}
		}
		elseif($lastpage > 5 + ($adjacents * 2))	//enough pages to hide some
		{
			//close to beginning; only hide later pages
			if($page < 1 + ($adjacents * 2))		
			{
				for ($counter = 1; $counter < 4 + ($adjacents * 2); $counter++)
				{
					if ($counter == $page)
						$pagination.= "$counter";
					else
						$pagination.= "<a href=\"diggstyle.php?page=$counter\">$counter</a>";					
				}
				$pagination.= "...";
				$pagination.= "<a href=\"diggstyle.php?page=$lpm1\">$lpm1</a>";
				$pagination.= "<a href=\"diggstyle.php?page=$lastpage\">$lastpage</a>";		
			}
			//in middle; hide some front and some back
			elseif($lastpage - ($adjacents * 2) > $page && $page > ($adjacents * 2))
			{
				$pagination.= "<a href=\"diggstyle.php?page=1\">1</a>";
				$pagination.= "<a href=\"diggstyle.php?page=2\">2</a>";
				$pagination.= "...";
				for ($counter = $page - $adjacents; $counter <= $page + $adjacents; $counter++)
				{
					if ($counter == $page)
						$pagination.= "$counter";
					else
						$pagination.= "<a href=\"diggstyle.php?page=$counter\">$counter</a>";					
				}
				$pagination.= "...";
				$pagination.= "<a href=\"diggstyle.php?page=$lpm1\">$lpm1</a>";
				$pagination.= "<a href=\"diggstyle.php?page=$lastpage\">$lastpage</a>";		
			}
			//close to end; only hide early pages
			else
			{
				$pagination.= "<a href=\"diggstyle.php?page=1\">1</a>";
				$pagination.= "<a href=\"diggstyle.php?page=2\">2</a>";
				$pagination.= "...";
				for ($counter = $lastpage - (2 + ($adjacents * 2)); $counter <= $lastpage; $counter++)
				{
					if ($counter == $page)
						$pagination.= "$counter";
					else
						$pagination.= "<a href=\"diggstyle.php?page=$counter\">$counter</a>";					
				}
			}
		}
		
		//next button
		if ($page < $counter - 1) 
			$pagination.= "<a href=\"diggstyle.php?page=$next\">next »</a>";
		else
			$pagination.= "next »";
		$pagination.= "</div>\n";		
	}
?>
<ul>
	<?php
		while($item = mysql_fetch_array($portfolio))
		{
	?>
		<li><a href="/portfolio/<?php echo $item['category']?>/<?php echo $item['uname'];?>"><?php echo $item['title']?></a></li>
	<?php
		}
	?>
</ul>
<?=$pagination?>

Help

Please post any questions or comments at our corresponding blog post. If you are interested in having Stranger Studios implement a pagination system for your project, contact us here.

A Perl Version by Andrew

Andrew sent me a Perl version of the pagination algorithm. This one is also modularized (how it should be, and how we do it at WineLog now). Below is the email and code Andrew sent me.

Hi Jason,

Thanks for posting your PHP pagination code! I translated it to Perl and modified it and it's very nice.

In my display loop, I show an element if:
($count > ($page - 1) * $numToShow && $count <= $page * $numToShow)

Then I call the modified pagination code:
$output = getPagination(2, $numToShow, $page, $count, $thisScript, '&m=an_extra_mode');

Here is the translated and modified code:

Copy the code below into your cgi script or view source here (change extension to .cgi, etc to run on your server).

# PHP pagination code by Stranger Studios (http://www.strangerstudios.com/).
# Converted to Perl by Andrew, 2006.
sub getPagination {
	my ($adjacents, # How many adjacent pages should be shown on each side?
		$limit, # Number of items you will show per page.
		$page, # The current starting page.
		$total_items, # The total number of items you are paginating.
		$scriptName, # The name of the CGI script in <a href="$scriptName?page=...">.
		$extra # A string with any extra CGI params to include, of the form "&parm1=value1&parm2=value2&...".
		) = @_;
	
	$page = 1 if ($page == 0);		# if no page var is given, default to 1.
	my $prev = $page - 1;							# previous page is page - 1
	my $next = $page + 1;							# next page is page + 1
	my $lastpage = ceil($total_items/$limit);		# lastpage is = total pages / items per page, rounded up.
	my $lpm1 = $lastpage - 1;						# last page minus 1
			
	# Now we apply our rules and draw the pagination object. 
	# We're actually saving the HTML to a variable in case we want to draw it more than once.
	my $pagination = "";
	my $counter = 0;
	if ($lastpage > 1) {
		$pagination .= "<div class=\"pagination\">";
		# previous button
		if ($page > 1) {
			$pagination .= "<a href=\"$scriptName?page=$prev" . $extra . "\">« previous</a>";
		} else {
			$pagination .= "« previous";
		}
		
		# pages	
		if ($lastpage < 7 + ($adjacents * 2)) { # not enough pages to bother breaking it up
			for ($counter = 1; $counter <= $lastpage; $counter++) {
				if ($counter == $page) {
					$pagination .= "$counter";
				} else {
					$pagination .= "<a href=\"$scriptName?page=$counter" . $extra . "\">$counter</a>";					
				}
			}
		} elsif ($lastpage > 5 + ($adjacents * 2)) { # enough pages to hide some
			# close to beginning; only hide later pages
			if ($page < 1 + ($adjacents * 2)) {
				for ($counter = 1; $counter < 4 + ($adjacents * 2); $counter++) {
					if ($counter == $page) {
						$pagination .= "$counter";
					} else {
						$pagination .= "<a href=\"$scriptName?page=$counter" . $extra . "\">$counter</a>";
					}
				}
				$pagination .= "...";
				$pagination .= "<a href=\"$scriptName?page=$lpm1" . $extra . "\">$lpm1</a>";
				$pagination .= "<a href=\"$scriptName?page=$lastpage" . $extra . "\">$lastpage</a>";		
			} elsif ($lastpage - ($adjacents * 2) > $page && $page > ($adjacents * 2)) { # in middle; hide some front and some back
				$pagination .= "<a href=\"$scriptName?page=1" . $extra . "\">1</a>";
				$pagination .= "<a href=\"$scriptName?page=2" . $extra . "\">2</a>";
				$pagination .= "...";
				for ($counter = $page - $adjacents; $counter <= $page + $adjacents; $counter++) {
					if ($counter == $page) {
						$pagination .= "$counter";
					} else {
						$pagination .= "<a href=\"$scriptName?page=$counter" . $extra . "\">$counter</a>";
					}
				}
				$pagination .= "...";
				$pagination .= "<a href=\"$scriptName?page=$lpm1" . $extra . "\">$lpm1</a>";
				$pagination .= "<a href=\"$scriptName?page=$lastpage" . $extra . "\">$lastpage</a>";		
			} else { # close to end; only hide early pages
				$pagination .= "<a href=\"$scriptName?page=1" . $extra . "\">1</a>";
				$pagination .= "<a href=\"$scriptName?page=2" . $extra . "\">2</a>";
				$pagination .= "...";
				for ($counter = $lastpage - (2 + ($adjacents * 2)); $counter <= $lastpage; $counter++) {
					if ($counter == $page) {
						$pagination .= "$counter";
					} else {
						$pagination .= "<a href=\"$scriptName?page=$counter" . $extra . "\">$counter</a>";
					}
				}
			}
		}
				
		# next button
		if ($page < $counter - 1) {
			$pagination .= "<a href=\"$scriptName?page=$next" . $extra . "\">next »</a>";
		} else {
			$pagination .= "next »";
		}
		$pagination .= "</div>\n";
	}
	return $pagination;
}