Legacy Documentation
You are using the documentation for version 4.3.8. Go here for the latest version.
Pagination¶
Pagination works identically across all first-party modules and allows you to display a limited number of entries and then automatically link to the next set. That way you can, for example, show comments 1-10 on the first page and automatically link to pages that display 11-20, 21-30, etc.
You have two choices as to the style of the navigation element. The first method would look something like this:
Page 27 of 344 pages « First < 11 12 13 14 15 > Last »
The second method is a more traditional “next page” / “previous page” output:
Previous Page | Next Page
Pagination will also automatically restrict itself to any category you’re currently viewing. So if you have a category specified in your channel entries tag or you are viewing the entries of a category, then the pagination links will automatically restrict themselves to only entries in that category.
Example Code¶
Here are two basic code examples, one for each of the methods mentioned above. Information about the variables and parameters are covered later.
{exp:channel:entries channel="news" orderby="date" sort="desc" limit="1" paginate="bottom"}
<h2>{title}</h2>
{summary}
{body}
{paginate}
<p>Page {current_page} of {total_pages} pages {pagination_links}</p>
{/paginate}
{/exp:channel:entries}
Note
It does not matter where you put your {paginate} code
within the channel entries tag. The HTML markup within the
{paginate} tag pair will be placed in the appropriate location
according to what you specify with the paginate= parameter
(detailed below).
And for the “next/previous” method:
{exp:comment:entries channel="news" sort="desc" limit="1" paginate="bottom"}
{comment}
<p>By {name} on {comment_date format="%Y %m %d"}</p>
{paginate}
{if previous_page}
<a href="{auto_path}">Previous Page</a>
{/if}
{if next_page}
<a href="{auto_path}">Next Page</a>
{/if}
{/paginate}
{/exp:comment:entries}
Note
You can have multiple {paginate} blocks with different
content, but you’ll need to use paginate=inline.
Parameters¶
Pagination tag pair parameters should be used in the enclosing tag. For example:
{exp:comment:entries limit="1" paginate="bottom"}
paginate=¶
This parameter determines where the pagination code will appear:
paginate="top" paginate="bottom" paginate="both" paginate="inline" paginate="hidden"
top: The navigation text and links will appear above your list of entries.bottom: The navigation text and links will appear below your list of entries.both: The navigation text and links will appear both above and below your list of entries.inline: The navigation text and links will appear within the list of entries for each entry.hidden: The navigation text and links will not appear, but your entries will be paginated. (This is useful for things like JSON.)
If no parameter is specified, the navigation block will default to the “bottom” behavior.
paginate_base=¶
paginate_base="site/index"
This tells ExpressionEngine to override the normal pagination link locations and point instead to the explicitly stated template group and template.
Variable Pairs¶
paginate¶
The opening and closing tags for pagination. This can to be used in conjunction with the paginate= parameter to determine where the contents of this tag will appear. See below for the available variables for use inside this tag. This tag is wrapped around either the single variables (see below) or the next/previous variable pairs.
{paginate} {/paginate}
pagination_links¶
This variable shows the current page you are on as well as “surrounding” pages in addition to links for next/previous pages and first/last pages.
You can use {pagination_links} in two ways. It can be used as a
single variable:
{paginate}
{pagination_links}
{/paginate}
And the output looks like this:
« First < 11 12 13 14 15 > Last »
When used as a pair, you have a lot more flexibility with the markup:
{paginate}
{pagination_links}
<ul>
{first_page}
<li><a href="{pagination_url}" class="page-first">First Page</a></li>
{/first_page}
{previous_page}
<li><a href="{pagination_url}" class="page-previous">Previous Page</a></li>
{/previous_page}
{page}
<li><a href="{pagination_url}" class="page-{pagination_page_number} {if current_page}active{/if}">{pagination_page_number}</a></li>
{/page}
{next_page}
<li><a href="{pagination_url}" class="page-next">Next Page</a></li>
{/next_page}
{last_page}
<li><a href="{pagination_url}" class="page-last">Last Page</a></li>
{/last_page}
</ul>
{/pagination_links}
{/paginate}
There are one parameter, two variables, five variable pairs, and one conditional variable available when using the {pagination_links} pair.
Parameters¶
page_padding¶
{pagination_links page_padding="2"}
page_padding defaults to 2 if left unset. page_padding will
allow you to determine how many pages are shown on either side of the
current page.
Note
If you’re paginating over 10 items and showing 1 item per page, if you’re on the first page, you’d normally see this:
*1* 2 3 Next Page Last Page
If you changed page_padding to another value, say 5, you’d see
more page numbers:
*1* 2 3 4 5 6 Next Page Last Page
If you later changed to page 4, you’d see this:
Previous Page 1 2 3 *4* 5 6 7 8 9 Next Page Last Page
always_show_first_last¶
{pagination_links always_show_first_last="yes"}
Set this parameter to yes if you always want to see the links for
the first and last pages.
Note
If left unset or set to no, first and last links will only
be shown if the first and/or last page’s number isn’t shown.
For example, if you have 5 pages and pagination_links is set at 2
and you’re currently on the 3rd page you won’t see a first or last
page link because all five pages are shown:
Previous Page 1 2 *3* 4 5 Next Page
If you changed pagination_links to 1, then you’d see both first
and last links because the page numbers are not shown:
First Page Previous Page 2 *3* 4 Next Page Last Page
Variables¶
pagination_page_number¶
{pagination_page_number}
Outputs the page number associated with the current page in the {pagination_links} tag pair.
pagination_url¶
{pagination_url}
Outputs the URL associated with the current page in the {pagination_links} tag pair.
Variable Pairs¶
These four variable pairs can be used to display specific pages within the pagination:
Note
The markup within the first_page and last_page
variable pairs will only display when there are at least 4 pages of
content.
{first_page}
<li><a href="{pagination_url}" class="page-first">First Page</a></li>
{/first_page}
{previous_page}
<li><a href="{pagination_url}" class="page-previous">Previous Page</a></li>
{/previous_page}
{next_page}
<li><a href="{pagination_url}" class="page-next">Next Page</a></li>
{/next_page}
{last_page}
<li><a href="{pagination_url}" class="page-last">Last Page</a></li>
{/last_page}
The {page} variable pair can be used to display standard pagination
links:
{page}
<li><a href="{pagination_url}" class="page-{pagination_page_number}">{pagination_page_number}</a></li>
{/page}
Conditional Variables¶
Check and see if the current {page} link is the current page.
{if current_page}class="current"{/if}
if next_page¶
This tag will conditionally display the code inside the tag if there is a “next” page. If there is no next page then the content simply will not be displayed.
{if next_page} {/if}
if previous_page¶
This tag will conditionally display the code inside the tag if there is a “previous” page. If there is no previous page then the content simply will not be displayed.
{if previous_page} {/if}
Variables¶
These individual variables are for use inside the {paginate} tag pair.
auto_path¶
The {auto_path} variable is used inside of the {if next_page} and {if previous_page} variable pairs. It is dynamically replaced with the correct path to the next/previous page. Unlike other “path” variables, this variable does not require the Template_Group/Template to be specified.
{auto_path}
current_page¶
This variable is replaced by the page number of the current page you are viewing.
{current_page}