Consistent Pagination in ExpressionEngine 2.8

Pagination is essential to most ExpressionEngine sites. We give you the flexibility to have as many Channel entries as you’d like, but then you need a reasonable way to show all of those entries.

Since ExpressionEngine 2.4.0, you’ve had the flexibility to style pagination in more ways than before. For example, you could style the first, last, next, and previous page links independently from each other and the numeric links.

{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} 

You also have the ability to call out the current page using a conditional.

{page}
    
<li><a href="{pagination_url}" class="page-{pagination_page_number} {if current_page}active{/if}">{pagination_page_number}</a></li>
{/page} 

However, those features were only available to the Channel module, the Comment module, and the Search module. Well, starting with ExpressionEngine 2.8.0, all template pagination code uses the exact same syntax. No longer do you have to look up specific pagination syntax for one module or another, they’re all the same. Yes, even the Wiki and Forum modules use the same pagination tags.

This is possible because all first-party code now uses the exact same pagination library. That has a secondary benefit as well: when adding new features to pagination, we only need to add them in one place. That’s allowed us to add two parameters to {pagination_links}: page_padding and always_show_first_last.

{pagination_links page_padding="2" always_show_first_last="yes"

  • page_padding allows you to specify the number of page links in the {page} loop surrounding the current page. For example, if you set page_padding to 3 (the default) and you were on page 5, you’d see pages 2, 3, 4, 5, 6, 7, 8.
  • always_show_first_last is tied to page_padding because we typically only show the first and last page links if those page links would not be shown in the {page} loop. By setting this to yes, you force pagination to always show the first and last page, even if you’re already on that page or if it wouldn’t be shown normally.

In addition, the library we’ve used to do all of this will be available to all third parties and will be documented in our developer documentation. This allows all third parties to use the exact same pagination syntax as all first party tags.

With this change, we’ve brought consistency to all pagination tags across ExpressionEngine, hopefully making your job just that little bit easier.

.(JavaScript must be enabled to view this email address) or share your feedback on this entry with @ellislab on Twitter.