New pagination options

In Perch 3.0.6, new ways to change the display of paged items based on their location

A common design pattern with paged listings is to do something different with the first item in the list, or perhaps the first few items. For example, your blog listing could show the first item with an image, and additional content.

You can achieve some of this using CSS. With CSS you can target items based on their position in the page using selectors such as first-child or nth-child however you can’t show an entirely different set of markup or content using this method. You also may not want your special feature display to happen on page two of the listing. To allow you to do this we have added the following Pagination Variables into the Perch template engine - making them available for any paged content, be it a Region, your Blog, Products in Shop or a Runway Collection.

Showing a different template for the first item

In the main template for the listing, check to see if the current item is the first in the paged set, then include your feature template if it is. The else would include your standard template.

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

You could add the template code directly into your template rather than using template includes, however this method does keep your templates easier to read and understand.

Adding a class to the first three items

Another use of these variables would be to add a class to the first items, in order to display them differently. This would only happen on the first page of the set, as opposed to targeting the first few in the list with CSS, which would happen on each page of the set.

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

These variables should open up a range of possibilities for displaying paginated listings in creative ways, we hope you find them useful.