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

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.