Channel Entry and Comment Pagination¶
The pagination feature for both channel entries and comments works identically 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}
It is important to note that it does not matter where you put your {paginate} code within the channel entries tag. The pagination code will be “stripped out” of the regular output and 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}
Parameters¶
paginate=¶
paginate="top" paginate="bottom" paginate="both" paginate="inline"
This parameter determines where the pagination code will appear for your channel entries or comments:
- 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.
If no parameter is specified, the navigation block will default to the “bottom” behavior.
pagination_links¶
{pagination_links}
These show the current page you are on as well as “surrounding” pages in addition to links for nex/previous pages and first/last pages. You can use {pagination_links} in two ways. It can be used as a single variable or as a pair. When used as a single variable, the output looks a like this:
« First < 11 12 13 14 15 > Last »
When used as a pair, you have a bit more flexibility:
{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}
There are two variables, five variable pairs, and one conditional variable available when using the {pagination_links} pair.
Variables¶
{pagination_page_number}
Outputs the page number associated with the current page in the {pagination_links} tag pair.
{pagination_url}
Outputs the URL associated with the current page in the {pagination_links} tag pair.
Variable Pairs¶
{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}
These four variable pairs are used when displaying specific pages within the pagination: the first page link, the previous page link, the next page link, and the last page link.
{page}
<li><a href="{pagination_url}" class="page-{pagination_page_number}">{pagination_page_number}</a></li>
{/page}
The last variable pair is used for the standard pagination links.
Conditional Variables¶
{if current_page}class="current"{/if}
Check and see if the current {page} link is the current page.
Variable Pairs¶
paginate¶
{paginate} {/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.
if next_page¶
{if next_page} {/if}
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 previous_page¶
{if previous_page} {/if}
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.
Variables¶
These individual variables are for use inside the {paginate} tag pair.
auto_path¶
{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.
current_page¶
{current_page}
This variable is replaced by the page number of the current page you are viewing.
User Contributed Notes
Important note on {pagination_links}. Whether you are using the single or the tag pair version, it must be in between the {paginate} tag pair or they won’t work.
{paginate}{pagination_links}
{/paginate}
{paginate}{pagination_links}
Pagination details go here...
{/pagination_links}
{/paginate}
In response to the piping conditional above, I think it’s more semantically clean to just add classes to your previous and next anchors (or containing list items) like so:
{paginate}
{if previous_page}
<a class="prev" href="{auto_path}">Previous Page</a>
{/if}
{if {current_page} != '1' AND "{current_page}" != "{total_pages}" } | {/if}
{if next_page}
<a class="next" href="{auto_path}">Next Page</a>
{/if}
{/paginate}
...and then use the following CSS
.prev + .next {border-left: 1em;
margin-left: 1em;
padding-left: 1em;
}
Not as much fun with EE tags I realize, but given that it’s a presentational detail and not content or structure, it’s cleaner markup, and might even shave a fraction of a second off your load times as it’s one less conditional to check. I’ve used the above in basic next/prev pagination, and also ‘PREV | 1 2 3 4 5 | NEXT” style pagination as well. Just wrap the numeric page links in an element with the class=“center” and use .prev + .center, .center + .next rules accordingly.
When “pagination_links” is used as a single tag, here’s the simplest code:
{paginate}{pagination_links}{/paginate}Which outputs this:
<a href="URL">‹ First</a> <a href="URL/P20"><</a> <a href="URL/P10">2</a> <a href="URL/P20">3</a> <strong>4</strong> <a href="URL/P40">5</a> <a href="URL/P50">6</a> <a href="URL/P40">></a> <a href="URL/P60">Last ›</a>Which looks like this:
‹ First < 2 3 4 5 6 > Last ›
The “pagination_links” code pair can duplicate the output single tag, but it’s a lot more code. Here’s the code for the pair that generates the same output (with a DIV wrapped around it for extra fun):
{paginate}{if {total_pages} > 1}
<div class="pagination">
{pagination_links}
{first_page}<a href="{pagination_url}">‹ First</a> {/first_page}{previous_page}<a href="{pagination_url}"><</a>{/previous_page}{page}{if current_page}<strong>{pagination_page_number}</strong>{if:else}<a href="{pagination_url}">{pagination_page_number}</a>{/if} {/page}{next_page}<a href="{pagination_url}">></a>{/next_page}{last_page}<a href="{pagination_url}">Last ›</a>{/last_page}
{/pagination_links}
</div>
{/if}
{/paginate}
Please note the if… else for the current page—there’s no direct negation for current_page:
{if current_page}<strong>{pagination_page_number}</strong>
{if:else}
<a href="{pagination_url}">{pagination_page_number}</a>
{/if}
To clarify my previous comment—this only seems to be an issue when working with 3rd party addons such as AB Entry IDs.
If you find that pagination isn’t working, try adding the “paginate” parameter. The docs say it is optional and defaults to bottom, but I’ve found this is not necessarily the case.
Please note: You must have at least 4 pages for the first_page and last_page variables to display.
For example:
1 2 3 LastFirst 2 3 4If you want to conditionally display a separator between previous and next page links you can use this:
{paginate}
{if previous_page}
<a href="{auto_path}">Previous Page</a>
{/if}
{if {current_page} != '1' AND "{current_page}" != "{total_pages}" } | {/if}
{if next_page}
<a href="{auto_path}">Next Page</a>
{/if}
{/paginate}
via: John Henry Donovan on the forums
If you only want to display the contents of your {paginate} tag pair when there’s more than one page, surround your tag contents with this condition:
{paginate}{if {total_pages} > 1}...
{/if}{/paginate}
(Thanks to Pascal for the tip)
You must either have an EllisLab product license and have attained a forum rank of "Lab Assistant" (50 posts) to contribute notes to the User Guide