Pagination
==========

This class provides the ability to do pagination on a web2py query. You can
easily generate a subset of results, and get next and previous links.

Supports

* Any valid Query
* Caching
* Orderby
* Display Count

The pagination works on the ``request.get_vars.p`` variable.

Usage::

    def list_dogs():
        # All dogs go to heaven
        query = db.dog.id > 0

        # Oldest dogs first
        orderby = ~db.dog.age

        # Define our cache type as ram, and 15 seconds to cache
        # If you do not specify a custom cache, the pagination
        # will default to Cache.ram with a 1500 second timeout
        pcache = (cache.ram, 15)

        # Instantiate the class
        # It will use ``request.vars.p`` to determine the page
        # it is on.
        paginate = web2py_utils.paginate.Pagination(db, query, orderby,
                                display_count=15, cache=pcache, r=request,
                                res=response)

        # Now we get our subset.
        dogs=paginate.get_set(set_links=True)

        return dict(dogs=dogs)

When you call ``set_links=True`` (which is the default) on ``get_set`` it will
place a variable containing the links in the response class.::

    response.paginate_links

This is a tuple containing the following.

========    ===========     =====
index       action          value
========    ===========     =====
0           backward        A Link to URL with p-=1
1           forward         A Link to URL with p+=1
2           location        Showing %d to %d out of %d records
========    ===========     =====

It is suggested to do the following in one of your views. This way you can
include the links with {{paginate()}} anywhere in your templates.

.. code-block:: html

    {{def paginate():}}
        {{if response.paginate_links:}}
                <div class="pagination">
                    <div class="paginate_back">
                        {{=response.paginate_links[0]}}
                    </div>
                    <div class="paginate_forw">
                        {{=response.paginate_links[1]}}
                    </div>
                    <div class="paginate_loc">
                        {{=response.paginate_links[2]}}
                    </div>
                </div>
        {{pass}}
    {{pass}}