Pagination

October CMS includes pagination features out of the box, it integrates with standard templates and offers complete flexibility for custom markup. Paginated records are integrated closely with model pagination queries and the pager() Twig function.

# Paginating Data

A paginated set of data can come from Component logic, inside the page or layout PHP section, or from a Tailor component. The following is an example of a page requesting paginated data from a Tailor component, stepping through the records at 10 per page.

url = "/blog"

[collection]
handle = "Blog\Post"

___TWIG0___

Now the posts variable is available. We can loop through each record and display the pagination links.

<div>
    ___TWIG0___
        <h2>___TWIG1___</h2>
    ___TWIG2___
</div>

<nav>
    ___TWIG3___
</nav>

# Multiple Pagination Instances

By default the pagination will take the current page number from the ?page query string, so the same page number will be used when displaying two or more sets of paginated data. To solve this problem, use the paginateCustom method and specify a unique parameter name.

url = "/blog"

[collection blog]
handle = "Blog\Post"

[collection category]
handle = "Blog\Category"

___TWIG0___

___TWIG1___

Set the withQuery option to preserve the page number for other pagination instances (optional).

___TWIG0___

This results in the query string containing both page numbers, for example,
?postPage=1&commentPage=2.

# Using Custom Pagination Markup

To use custom pagination markup, start with the file locations below and copy the contents to a partial inside your theme.

Then render as a partial by passing the partial option to the pager.

___TWIG0___

# AJAX Pagination

Use the ajaxPager() Twig function to update paginated records dynamically using AJAX. The partial should display the records and include the pager inside, for example, a partial named latest-posts.htm with the following contents.

<div>
    ___TWIG0___
        <h2>___TWIG1___</h2>
    ___TWIG2___
</div>

<nav>
    ___TWIG3___
</nav>

Then render the partial on the page using the {% ajaxPartial %} Twig tag.

url = "/blog"

[collection blog]
handle = "Blog\Post"

___TWIG0___

<h3>Latest Posts</h3>
___TWIG1___

Alternatively, you can encapsulate all the logic inside the partial to make it completely portable.

[collection blog]
handle = "Blog\Post"

___TWIG0___

<div>
    ___TWIG1___
        <h2>___TWIG2___</h2>
    ___TWIG3___
</div>

<nav>
    ___TWIG4___
</nav>

The partial can then be rendered anywhere on a page or layout without any additional configuration.

url = "/blog"

___TWIG0___

# Load More Pagination

A load more button, sometimes called an infinite loader, is a method of displaying records in a stack instead of across multiple pages.

This approach uses an AJAX partial to append the new content along with a self-destructing button. For example, a partial named load-more-posts.htm with the following contents.

___TWIG0___

<div>
    ___TWIG1___
        <h2>___TWIG2___</h2>
    ___TWIG3___
</div>

___TWIG4___
    <button
        data-request="onAjax"
        data-request-update="{ _self: '@' }"
        data-request-success="this.remove()"
        data-request-data="{ page: ___TWIG5___ }"
        data-attach-loading>
        Load More
    </button>
___TWIG6___

The button element leverages a combination of AJAX data attributes to perform a self-update in append mode, passing the next page number as data and removing itself upon completion.

The partial should be rendered using {% ajaxPartial %} Twig tag.

url = "/blog"

___TWIG0___

# See Also