ExpressionEngine

2.11.9 User Guide

Retired Documentation

You are using the documentation for version 2.11.9. Go here for the latest version or check here for your available upgrades to the latest version.

Pagination Class

Generating Pagination

class Pagination_object

The pagination library (and object) is a flexible way to create pagination for many different instances. More often then not, you will not be using all of it’s features and options, but they’re there because we’ve run into situations where they’re needed.

Your first step will be using ExpressionEngine’s pagination library to create a Pagination_object:

ee()->load->library('pagination');
$pagination = ee()->pagination->create();

This instance of a Pagination_object represents the various conditions, template, and parameters for a specific group of things, whether it’s channel entries, comments, files, forum threads, or otherwise.

Once you’ve created the object, you need to prepare the template.

Prepare the Template

Pagination_object::prepare($template)

prepare() determines if {paginate} is in the template data and if so, stores it in the object and removes it from the template. If you’re using field pagination (you most likely aren’t) then we also do some work to find additional tags needed for that kind of pagination:

ee()->TMPL->tagdata = $pagination->prepare(ee()->TMPL->tagdata);

The above line removes the pagination template from TMPL::$tagdata parses any parameters set on {pagination_links}. In addition, if you’re using inline pagination (using the Pagination_object::$position) we replace the pagination with a marker instead of removing it entirely.

Parameters:
  • $template (string) – The template data you want to prepare for pagination, typically TMPL::$tagdata.
Returns:

The prepared template, typically with it’s pagination tags removed.
Return type:

String

Build the Pagination

Pagination_object::build($total_items, $per_page)

The next step in the process is building the pagination. This is most of the heavy lifting in the process and consists of figuring out offsets, how many pages should exist given the $total_items and $per_page, the basepath and URLs, and then generates the necessary data to later render:

$total_items = $query->num_rows();
$per_page = ee()->TMPL->fetch_param('limit');
$pagination->build($total_items, $per_page);

It’s recommended that you don’t run this step if pagination isn’t necessary, so you can to see if $Pagination_object::$paginate is TRUE before running Pagination_object::build:

if ($pagination->paginate === TRUE)
{
  ...
  $pagination->build($total_items, $per_page);
}
Parameters:
  • $total_items (int) – The total number of items being paginated.
  • $per_page (int) – The number of items to show per page.
Returns:

TRUE if everything was successful, FALSE otherwise.
Return type:

Boolean

Render the Pagination

Pagination_object::render($return_data)

The last step is rendering the pagination into your template. Normally the pagination will be added to the top, bottom, or both top and bottom of your tag pair depending upon the Pagination_object::$position property:

$this->return_data = $pagination->render($this->return_data);

Note

Unless you’ve manually set Pagination_object::$position to hidden, you should always run Pagination_object::render. It will remove the unused pagination template and tags.

Parameters:
  • $return_data (string) – Template with all individual items parsed, about to be output.
Returns:

$return_data with pagination added back if required. If pagination was unnecessary, nothing is added and the inline template is removed if necessary.
Return type:

String

Properties

property Pagination_object::$paginate

This property is set once Pagination_object::prepare and is useful for checking whether subsequent pagination calls should run. It’s triggered by finding a {paginate} tag, so if you’re using something else, you’ll need to force the Pagination_object’s hand and set this to TRUE.

property Pagination_object::$current_page

The current page number, should be 1 through n.

property Pagination_object::$offset

The current offset, the number of items past the first. For example, if you’re showing 10 items per page and you’re on page 3, your offset should be 20.

property Pagination_object::$total_items

The total number of items being paginated.

property Pagination_object::$total_pages

The total number of pages being paginated.

property Pagination_object::$per_page

The number of items per page.

property Pagination_object::$basepath

The basepath URL for the pagination links. Normally this is automatically determined, but in some cases you will have to specify a basepath.

property Pagination_object::$prefix

The letter used to prefix the offset in pagination URLs (e.g. blog/archive/P30, P is the prefix and 30 is the offset). If changed, ensure this is fairly unique to URL segments.

property Pagination_object::$position

Can only be set, not retrieved. Manually set the position of the pagination. Only options are top, bottom, both, inline, or hidden.

property Pagination_object::$type

Can only be retrieved, not set. This is the name of the calling class and is useful for when using the pagination extension hooks so you can only run your hook for specific modules.

Field Pagination Specific

property Pagination_object::$field_pagination

This property is set once Pagination_object::prepare and is only TRUE in the case of field pagination, which will happen if {multi_field="..."} is found in $template.

property Pagination_object::$cfields

Only used with :attr:`Pagination_object::$field_pagination`. The custom fields that we’re potentially paginating over.

property Pagination_object::$field_pagiation_query

Only used with :attr:`Pagination_object::$field_pagination`. This is the query for the individual item that is being field paginated over.