Pagination Tags

When using perch_content_custom() to paginate the returned data you must also add some markup to your template to display the paging. This markup makes use of a number of special id values to display pagination.


In this example I place my pagination code between perch:after tags in order that it only displays after results have been shown and use the special id values:

The perch:content tags using these special id values are all given a type of hidden, in order that they do not show up in the Control Panel when this content is edited.

  <perch:if exists="paging">
    <div class="paging">
      Page <perch:content id="current_page" type="hidden"> 
        of <perch:content id="number_of_pages" type="hidden">
      <perch:if exists="not_first_page">
        <a href="<perch:content id="prev_url" type="hidden" encode="false">">Previous</a>
      <perch:content id="page_links" encode="false">
      <perch:if exists="not_last_page">
        <a href="<perch:content id="next_url" type="hidden" encode="false">">Next</a>

Pagination template variables

ID Purpose
paging Set if paging is present. Can be testing for with a perch:if tag.
total The total number of items in the result set.
number_of_pages The number of pages the result set is split into.
total_pages Same as number_of_pages. (Compatibility)
per_page Number of results per page.
current_page The current page in the result set.
lower_bound The first record index on this page.
upper_bound The last record index on this page.
prev_url The URL of the previous page. Empty for the first page.
next_url The URL of the next page. Empty for the last page.
prev_page_number The page number of the previous page. Empty for the first page.
next_page_number The page number for the next page. Empty for the last page.
not_first_page Present and set if the current page is not the first page in the set.
not_last_page Present and set if the current page is not the last page in the set.
page_links The HTML output of the page links template, if enabled.
perch_index_in_set An integer storing the position of this item in the result set, indexed from 1
perch_zero_index_in_set An integer storing the position of this item in the result set, indexed from 0
perch_first_in_set Will be true if this is the first item in the set
perch_last_in_set Will be true if this is the last item in the set

Using a subtemplate

Often, you’ll want to set up one pagination style for the whole of your site and reuse it when needed. You can do this with a sub template.

Perch includes an example, which often is a good starting point. Use it like this:

<perch:template path="pagination/default.html" rescope="parent">

Working with paged content

When paging content, some of the pagination variables help you to control how the content is displayed in addition to generating the pagination itself.

For example, a common pattern is to output a list of items, but use a different template for the first item in the set. Subsequent pages do not show the featured item. We can do this by checking to see if our item is perch_first_in_set. Then using the appropriate template tags, or included template.

<perch:if exists="perch_first_in_set">
    <perch:template path="content/special-item.html">
    <perch:template path="content/item.html">

You can use perch_index_in_set to look for the first n items and either add a different class, or use a different template as above. In the below example I am testing to see if perch_index_in_set is equal to or less than 3, and if it is applying a special class.

<div class="box<perch:if id="perch_index_in_set" match="lte" value="3"> special</perch:if>">

Pagination options

For all page functions that provide pagination (not just perch_content_custom) you can set an number of options to configure how the pagination behaves.

Pagination Options

Option Values
paginate True or false. Whether to use pagination.
count Integer. (When used with paginate) The number of items to show per page if pagination is being used.
pagination-var The URL query string parameter name to use for the page number. Defaults to page.
page-links True or false. Create numbered page links as well as previous and next links.
page-link-template The template to use (if not the default) to generate the page links.
page-link-style shortened or all. By default a shortened set of page links are generated. If you want a link for every page, set to all.