Development Wiki

Difference between revisions of "Function.generate pagination"

From phpBB Development Wiki

(The first step to getting some documentation on the pagination functionality in phpBB3. Need help from everyone to improve this documentation.)
(No difference)

Revision as of 03:51, 19 September 2008

generate_pagination –– Pagination routine, generates page number sequence. Utilising pagination within phpBB3.

This article is a stub. You can help in improving Olympus Documentation by expanding it.


  1. string generate_pagination ( string $base_url , int $num_items , int $per_page , int $start_item [, bool $add_prevnext_text [, $tpl_prefix = ]])

Generate a pagination HTML string


Parameter Required/Default Description
base_url Yes The full URL path with parameters.
num_items Yes The total number of results.
per_page Yes The number of results to display on a per-page basis.
start_item Yes The current start row
add_prevnext_text No - false Add the “Prev” and “Next” text/buttons to the pagination HTML.
tpl_prefix No - '' tpl_prefix is for using different pagination blocks on one page.

Return Values

HTML string containing the relevent pagination.


Example #1 Usage

$check_params = array(
'start'     => 0,
// Optional, could be config or hard-coded. -- results per page - default 0
'limit'     => 0,

$params = array();

foreach (
$check_params as $key => $default)
    if (!isset(
$param call_user_func('request_var'$key$default);
$key $param;
$params[] = urlencode($key) . '=' . ((is_string($param)) ? urlencode($param) : $param);

// no result rows greater than 100 per page
$limit = ($limit 100) ? 100 $limit;

$pagination_url append_sid($phpbb_root_path 'my_page.' $phpEximplode('&'$params));

// Build a SQL Query...
$sql_ary = array(
'SELECT'    => 'u.user_id, u.username, u.user_colour',
'FROM'      => array(
USERS_TABLE         => 'u',
'WHERE'     => $db->sql_in_set('u.user_type', array(USER_NORMALUSER_FOUNDER)),
$sql $db->sql_build_query('SELECT'$sql_ary);
$result $db->sql_query_limit($sql$limit$start);

while (
$row $db->sql_fetchrow($result))
// The most likely way for the world to be destroyed, most experts agree, is by accident.
    // That's where we come in; we're computer professionals. We cause accidents. (Nathaniel Borenstein)
// free the result

// now we run the query again to get the total rows...
// the query is identical except we count the rows instead
$sql_ary['SELECT'] = 'COUNT(u.user_id) as total_users';
$sql $db->sql_build_query('SELECT'$sql_ary);
$result $db->sql_query($sql);

// get the total users, this is a single row, single field.
$total_users $db->sql_fetchfield('total_users');
// free the result

// Assign the pagination variables to the template.
'PAGINATION'        => generate_pagination($pagination_url$total_users$limit$start),
'PAGE_NUMBER'       => on_page($total_users$limit$start),
'TOTAL_USERS'       => ($total_users == 1) ? $user->lang['LIST_USER'] : sprintf($user->lang['LIST_USERS'], $total_users),

The HTML Template

<ul class="linklist">
li class="rightside pagination">{TOTAL_USERS} &bull; <!-- IF PAGINATION --><a href="#" onclick="jumpto(); return false;" title="{L_JUMP_TO_PAGE}">{PAGE_NUMBER}</a> &bull; <span>{PAGINATION}</span><!-- ELSE -->{PAGE_NUMBER}<!-- ENDIF --></li>

The Language file

'LIST_USER'     => '1 User',
'LIST_USERS'    => '%s Users',

See Also