vBulletin LTS

[HOW TO - vB4] Paginating Results

by cellarius 24 Aug 2009

Rating:

(3 votes - 3.67 average)

Introduction

Not very much has changed regarding how pagination works since vB 3.8, but quite enough to warrant an update of Revan's great tutorial, dating from 2006. Kudos to Revan.

As Revan I assume you know your way around php and can understand at least roughfly what each bit of the code does. There'll be explanations, of course, but this is for coders and mod developers.

The main work for pagination has to be done in the PHP-code, still no surprise there.

Cleaning URL parameters

We start off by cleaning the URL parameters that will tell our paginator how many entries to show per page and on which page of the resultset we're actually on

PHP Code:


 $vbulletin->input->clean_array_gpc('r', array(
    'perpage'    => TYPE_UINT,
    'pagenumber' => TYPE_UINT,
));

.
Counting results

The next step is to count the number of resuts that our actual database query will return (this query we will meet later on - it's an example that will throw all users with no posts).

PHP Code:


$cel_users = $db->query_first("
    SELECT COUNT('userid') AS users_count
    FROM " . TABLE_PREFIX . "user AS user
    WHERE user.posts = '0'
");

.
Settings & sanitizing

Next we're off to do some settings: The first argument is our counting result. The last two arguments are the maximum number of results per page (100) and the default number of results per page (20). Note how the first argument is the result of the count query above. You can replace those with settings from the AdminCP by inserting the corresponding variables obviously.

PHP Code:


sanitize_pageresults($cel_users['users_count'], $pagenumber, $perpage, 100, 20);

.
Orientation - where are we?

Now some stuff to determine on which page we're on and which results to show. Note how you have to provide the results of our initial count query:

PHP Code:


if ($vbulletin->GPC['pagenumber'] < 1)
{
    $vbulletin->GPC['pagenumber'] = 1;
}
else if ($vbulletin->GPC['pagenumber'] > ceil(($cel_users['users_count'] + 1) / $perpage))
{
    $vbulletin->GPC['pagenumber'] = ceil(($cel_users['users_count'] + 1) / $perpage);
}
$limitlower = ($vbulletin->GPC['pagenumber'] - 1) * $perpage;
$limitupper = ($vbulletin->GPC['pagenumber']) * $perpage;

.
The main query

Now the query that throws all users with no posts - just an example, obviously. Note the LIMIT - this has to be added to the original query to delimit the resultset for the actual page

PHP Code:


$result = $db->query_read("
    SELECT user.username, user.userid
    FROM " . TABLE_PREFIX . "user as user
    WHERE user.posts = '0'
    ORDER BY username DESC
    LIMIT $limitlower, $perpage
");

.
Constructing pagenav

The last (but one) thing to do in the PHP code is to finally call the function to construct the actual page-nav and saving it's output to a variable for passing to the template.

Some explanation for the arguments that must/can be passed to this function are in the code.
Of course, the name of the file (yourfile.php) needs to be adapted to the file name your using the pagination on.
Only the first four arguments are mandatory. You can leave the rest away if not needed, I added them for documentation.
The ? that starts the parameters after myfile.php needs to be there, since atm the page parameter always is prefixed with an &. If there are no other parameters present as is the case in this example, the links will look like "yourfile.php?&page=2". This is, of course, wrong, but works; without the ? the link would be "yourfile.php&page=2", which is even more wrong, since it does not work. In vB 3 pagination handled this correctly. I filed this as a bug in vB4 beta 3. Maybe I'm missing something, or this will be resolved - I'll keep you posted.

PHP Code:


$pagenav = construct_page_nav(
    $vbulletin->GPC['pagenumber'],
    $perpage,
    $cel_users['users_count'],
    'yourfile.php?' . $vbulletin->session->vars['sessionurl'], // the pagenav-link
    '', // to pass a second portion or the pagenav-link, gets directly appended to above
    '', // to pass an anchor
    '', // SEO-Link for thread, forum, member... pages - make the pagenav-links seo'ed if you use the paginator on one of those
    '', // Array to pass linkinfo for SEO-Link-Method
    ''  // Array to pass additional Info for SEO-Link-Method
);

.
Registering pagenav for templates

As with all variables in vB4, the newly created $pagenav has to be registered to be used inside the template:

PHP Code:


$templater = vB_Template::create('cel_test_pagination');
    $templater->register_page_templates();
    $templater->register('navbar', $navbar);
// Need to add for pagenav
    $templater->register('pagenav', $pagenav);
    $templater->register('pagenumber', $pagenumber);
    $templater->register('perpage', $perpage);
    $templater->register('output', $output);
print_output($templater->render());

.
Template code

Now you just have to put the pagenav-code into your template, and we're done. Note that the id of the surrounding div should be changed to "pagination_bottom" or "pagination_top" accordingly.

Code:

<vb:if condition="$pagenav">
     <div id="pagination_top">
          {vb:raw pagenav}
     </div>
</vb:if>

Have fun!

-c
As of now (beta 3), there are still some issues that need to be resolved regarding pagination. They are minor and there should not be substantial changes, but be aware of that. For example, the setting of results shown per page does not work yet - 20 is hardcoded into the sanitizing function.

vblts.ru supports vBulletin®, 2022-2024