Pagination in Grails is both powerful and easy... if you know what your doing.  Pagination can often be a stumbling block to new Grails converts.  In this article, I hope to shine a light on some of the darker recesses of the pagination world and provide helpful examples.  Let's get started.

Pagination Defined

Pagination is a common UI pattern used to divide large sets of data into smaller, more digestible chunks.  If you've performed a Google search then you've used pagination.  The division of those millions of search results into pages, each populated with 10, 50, or 100 results is pagination on a massive scale.

Basic Pagination

The Grails reference documentation provides a good example of how to perform pagination in the simplest of scenarios.  Click here to view it.  This covers how pagination is performed when returning a list containing all of your domain objects.  But what do you do if you only want to return a subset of these domain objects?

Advanced Pagination

Lets look at the example where I have many books by many authors and I wish to return a paginated list for only one of the authors.  Thankfully, Hibernate provides great support for this.

Example Domain Class

The domain class is the same as in the basic pagination example

class Book {
     String title
     String author
}

Example Controller

The controller is responsible for the following tasks:

1. Specifying the author for whom books should be returned
2. Obtaining a list of the author's books from the BookService
3. Adding the author's total book count to params
4. Returning the book list and params to the view

class BookController {
    def list = {
        def author = "Author Name"
        def books = bookService.getBookList(author, params)
        params.totalBooks = books.totalCount
        [bookInstanceList: books, params: params]
    }
}

Example Service

The BookService class is where the magic happens with a little help from Grails' underlying support for Hibernate's criteria query.  The service does the following:

1. Sets the offset.  As user's click buttons provided by the paginate tag (see example below), an offset parameter is passed to the controller.  This is how we are able to determine which subset of the book list to return.
2. Sets the maximum number of books to return.  The max value defaults to 10 if no value is provided and allows for a maximum of value of 100 (you really don't want to see more than 100 books on the screen at once, do you?).
3. Sets the field to sort on.  In this case, we sort by the book title.
4. Sets the sort order.  The order can be ascending or descending.  In this example, we sort by the book's title in ascending order. 
5. Performs the criteria query, passing in the pagination specific information as well as the author for whom we'd like to retrieve books.

It's important to note that a "Book.createCriteria()" query is performed as opposed to "Book.withCriteria()".  This allows us to efficiently obtaining the total book count from the list when it is returned to the controller.

class BookService {
    def getBookList(author, params) {
        params.max = Math.min(params?.max?.toInteger() ?: 10, 100)
        params.offset = params?.offset?.toInteger() ?: 0
        params.sort = params?.sort ?: "title"
        params.order = params?.order ?: "asc"

        def books = Book.createCriteria().list(
                max: params.max,
                offset: params.offset,
                sort: params.sort, 
                order: params.order) {
            eq "author", author
        }
    }
}

Paginate Code

The paginate code is the same as in the basic example except for the inclusion of the totalBooks value. This is done because we want the totalBooks field to reflect the total book count for a particular author, not the total count of books for all authors in the database.

Summary

I hope this post helped to demystify some of the common issues surrounding pagination in Grails. Please feel free to post your comments, opinions and experiences pertaining to this subject. I'd love to hear them!