Pagination in TurboGears

Paginate Decorator

TurboGears provides a convenient paginate() decorator that you can combine with expose(). To use it, you simply have to pass it the name of a collection to paginate. In controller/root.py:

from tg.decorators import paginate

@expose("paginatesample.templates.movie_list_deco")
@paginate("movies", items_per_page=5)
def decolist(self):
    """
    List and paginate all movies in the database using the
    paginate() decorator.
    """

    movies = DBSession.query(Movie)
    return dict(movies=movies, page='paginatesample Movie list')

In your template, you can now use the collection direction since it will be trimed to only contain the current page. You will also have have a basic page navigation with ${tmpl_context.paginators.movies.pager()}:

<ol>
   <li py:for="movie in movies" py:content="movie">Movie title and year</li>
</ol>

<p class="pagelist">
  ${tmpl_context.paginators.movies.pager()}
</p>

Advanced Pagination

The pager method of the paginator supports various customization options to tune the look and feel of the paginator, make sure you take a look at tg.support.paginate.Page for more details:

${tmpl_context.paginators.movies.pager(format='~3~', page_param='page', show_if_single_page=True)}

Adding Parameters to Links

You can pass any number of arguments to the pager function and they will be used to create the links to the other pages.

For example with the following code:

${tmpl_context.paginators.movies.pager(param1='hi', param2='man')}

the resulting links will be:

• /list?page=1&param1=hi&param2=man
• /list?page=2&param1=hi&param2=man

and so on…

By default the url used to generate links will be the same of the page where the paginated data will be visible, this can be changed by passing the link argument to the pager function:

${tmpl_context.paginators.movies.pager(link='/otherlink', param1='hi', param2='man')}

and the resulting link will be generated by using the provided url:

• /otherlink?page=1&param1=hi&param2=man

Adding Previous And Next Links

Apart from providing the pager method the paginator Page object we receive inside our template context provides the previous_page and next_page properties which can be used to create previous/next links:

<p class="pagelist">
        <a class="prevPage" href="/list?page=${tmpl_context.paginators.movies.previous_page}">&lt;&lt;&lt;</a>
        ${tmpl_context.paginators.movies.pager(format='~3~', page_param='page', show_if_single_page=True)}
        <a class="nextPage" href="/list?page=${tmpl_context.paginators.movies.next_page}">&gt;&gt;&gt;</a>
</p>

Adding Some Arrow Images

Once you added your own previous/next page entities you can style them as you prefer, one common need is to display an image instead of the text:

a.prevPage {
        background: url("/images/icons/png/32x32/arrow-left.png") no-repeat;
        padding-left: 18px;
        padding-right: 18px;
        padding-top: 12px;
        padding-bottom: 15px;
        text-decoration: none;
        }

a.nextPage {
        background: url("/images/icons/png/32x32/arrow-right.png") no-repeat;
        padding-left: 18px;
        padding-right: 18px;
        padding-top: 12px;
        padding-bottom: 15px;
        text-decoration: none;
        }