Adding Pagination to a phpBB Page

As you probably know, phpBB has the ability to display information across many different pages. Forums, topics, search results and the member list are all capable of this when needed. Sometimes it is useful to add this pagination feature to other pages that display a great deal of information. With a little bit of work, you can do this on any phpBB enabled page. If your page is not phpBB enabled, have a look at AJ Quick's Dynamic Sites with phpBB Tutorial.

To add phpBB's pagination to a page, there are four major steps we must complete.

  1. Setting Up Basic Variables
  2. Editing an Existing SQL Query
  3. Adding Pagination Output Code
  4. Adding Pagination Output to a Template File

Setting Up Basic Variables

In this step, we will add some setup variables for pagination near the top of the page's code. It is important that we do this to prevent dangerous security problems that could put your site at risk. To begin, open the .php file for your page in your favorite text or code editing program. Look in your file for the following code: 

//
// End session management
//

We will add the code for new setup variables, as shown below, after this code. Some of this code may already be in your file; if so, go ahead and add the code here anyway. Adding the code a second time won't hurt anything, usually. 

$start = ( isset($HTTP_GET_VARS['start']) ) ? intval($HTTP_GET_VARS['start']) : 0; 
 
$pagination = ' ';
$total_pag_items = 1;

Editing an Existing SQL Query

Somewhere in the code for your page there is an SQL query that is used to get all the data displayed on the page from the database. You need to find this query and edit it to limit the amount of data displayed on the page. The query will look different on every page, but you should be able to find it by searching for the word "SELECT" in the code.

Here is a general SQL query that phpBB might use to get the settings of all users other than guests. I will show you how to limit this query for use with pagination, and you can adapt those changes to the SQL query in your page. 

$sql = 'SELECT *
	FROM ' . USERS_TABLE . '
	WHERE user_id <> ' . ANONYMOUS;

To prevent the page from displaying all the data retrieved from the query (all the forum's members, in this example), we'll add a LIMIT command to the end of the query. The query, with this LIMIT command added, is displayed below. The added code is in blue. Using $start tells the query to get data beginning at the end of the last page, while $board_config['topics_per_page'] stops the query from going beyond the number set in the "Topics Per Page" configuration of the forum. 

$sql = 'SELECT *
	FROM ' . USERS_TABLE . '
	WHERE user_id <> ' . ANONYMOUS . '
	LIMIT ' . $start . ', ' . $board_config['topics_per_page'];

Here is another example, which might get the text of posts on your forum. It is followed by the limited query. 

$sql = 'SELECT *
	FROM ' . POSTS_TEXT_TABLE;


$sql = 'SELECT *
	FROM ' . POSTS_TEXT_TABLE . '
	LIMIT ' . $start . ', ' . $board_config['topics_per_page'];

Adding Pagination Output Code

Now, we will add the code that actually creates the page number text and links. There are several areas where you can place this code, but for the sake of simplicity, it is often best to place the code near the end of the .php file. Most phpBB .php files have a line like the one below near the end; place the code before this line. 

$template->pparse('body');

You'll need to edit some parts of the new code, but we'll get to that in a moment. Here is the new code: 

$sql = 'SELECT count(*) AS total 
	FROM ' . USERS_TABLE . '
	WHERE user_id <> ' . ANONYMOUS;
 
if ( !$result = $db->sql_query($sql) ) 
{
	message_die(GENERAL_ERROR, 'Error getting total', '', __LINE__, __FILE__, $sql);
}
 
if ( $total = $db->sql_fetchrow($result) )
{
	$total_pag_items = $total['total'];
	$page_url = "memberlist.php?mode=$mode&amp;order=$sort_order";
	$pagination = generate_pagination($page_url,
					$total_pag_items,
					$board_config['topics_per_page'],
					$start);
	$pagination .= '&nbsp;';
}
 
$current_page = floor( $start / $board_config['topics_per_page'] ) + 1;
$total_pages = ceil( $total_pag_items / $board_config['topics_per_page'] );
$template->assign_vars(array(
	'PAGINATION' => $pagination,
	'PAGE_NUMBER' => sprintf($lang['Page_of'], $current_page, $total_pages)
));

Now, as mentioned before, you need to edit some of that code block. Let's look at the SQL query in this code. Notice that everything between USERS_TABLE and the semi-colon at the end of the line is in red. You need to replace this part of the original query with the corresponding part of the SQL query you edited in Step 2. 

$sql = 'SELECT count(*) AS total
	FROM ' . USERS_TABLE . '
	WHERE user_id <> ' . ANONYMOUS;

Also in this block of code, you need to edit the URL passed to the pagination function, shown in blue below. This should be changed to the URL of your page. The page number details will be added to this URL automatically later. 

$page_url = "memberlist.php?mode=$mode&amp;order=$sort_order";

Adding Pagination Output to a Template File

In the final step, we'll add the output into your page's template. Open the *.tpl file for your page and find the place you'd like the pagination details to appear. You can add the HTML shown in this example to that location. {PAGE_NUMBER} will be replaced with the text "Page 1 of 3," while {PAGINATION} will be replaced with the links to other pages. 

<table width="100%" cellspacing="0" cellpadding="0" border="0">
  <tr> 
	<td>{PAGE_NUMBER}</td>
	<td align="right">{PAGINATION}</td>
  </tr>
</table>

If you're not using a template on your page, you can also use lines similar to the ones below to print out the same information. 

$current_page = floor( $start / $board_config['topics_per_page'] ) + 1;
$total_pages = ceil( $total_pag_items / $board_config['topics_per_page'] );
echo sprintf($lang['Page_of'], $current_page, $total_pages);
echo $pagination;

You should now have pagination links in your page. Enjoy! :D