--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/parts/django/docs/topics/pagination.txt Sat Jan 08 11:20:57 2011 +0530
@@ -0,0 +1,281 @@
+==========
+Pagination
+==========
+
+.. module:: django.core.paginator
+ :synopsis: Classes to help you easily manage paginated data.
+
+.. versionchanged:: 1.0
+ Pagination facilities have been almost fully reworked.
+
+Django provides a few classes that help you manage paginated data -- that is,
+data that's split across several pages, with "Previous/Next" links. These
+classes live in :file:`django/core/paginator.py`.
+
+Example
+=======
+
+Give :class:`Paginator` a list of objects, plus the number of items you'd like to
+have on each page, and it gives you methods for accessing the items for each
+page::
+
+ >>> from django.core.paginator import Paginator
+ >>> objects = ['john', 'paul', 'george', 'ringo']
+ >>> p = Paginator(objects, 2)
+
+ >>> p.count
+ 4
+ >>> p.num_pages
+ 2
+ >>> p.page_range
+ [1, 2]
+
+ >>> page1 = p.page(1)
+ >>> page1
+ <Page 1 of 2>
+ >>> page1.object_list
+ ['john', 'paul']
+
+ >>> page2 = p.page(2)
+ >>> page2.object_list
+ ['george', 'ringo']
+ >>> page2.has_next()
+ False
+ >>> page2.has_previous()
+ True
+ >>> page2.has_other_pages()
+ True
+ >>> page2.next_page_number()
+ 3
+ >>> page2.previous_page_number()
+ 1
+ >>> page2.start_index() # The 1-based index of the first item on this page
+ 3
+ >>> page2.end_index() # The 1-based index of the last item on this page
+ 4
+
+ >>> p.page(0)
+ Traceback (most recent call last):
+ ...
+ EmptyPage: That page number is less than 1
+ >>> p.page(3)
+ Traceback (most recent call last):
+ ...
+ EmptyPage: That page contains no results
+
+.. note::
+
+ Note that you can give ``Paginator`` a list/tuple, a Django ``QuerySet``, or
+ any other object with a ``count()`` or ``__len__()`` method. When
+ determining the number of objects contained in the passed object,
+ ``Paginator`` will first try calling ``count()``, then fallback to using
+ ``len()`` if the passed object has no ``count()`` method. This allows
+ objects such as Django's ``QuerySet`` to use a more efficient ``count()``
+ method when available.
+
+
+Using ``Paginator`` in a view
+==============================
+
+Here's a slightly more complex example using :class:`Paginator` in a view to
+paginate a queryset. We give both the view and the accompanying template to
+show how you can display the results. This example assumes you have a
+``Contacts`` model that has already been imported.
+
+The view function looks like this::
+
+ from django.core.paginator import Paginator, InvalidPage, EmptyPage
+
+ def listing(request):
+ contact_list = Contacts.objects.all()
+ paginator = Paginator(contact_list, 25) # Show 25 contacts per page
+
+ # Make sure page request is an int. If not, deliver first page.
+ try:
+ page = int(request.GET.get('page', '1'))
+ except ValueError:
+ page = 1
+
+ # If page request (9999) is out of range, deliver last page of results.
+ try:
+ contacts = paginator.page(page)
+ except (EmptyPage, InvalidPage):
+ contacts = paginator.page(paginator.num_pages)
+
+ return render_to_response('list.html', {"contacts": contacts})
+
+In the template :file:`list.html`, you'll want to include navigation between
+pages along with any interesting information from the objects themselves::
+
+ {% for contact in contacts.object_list %}
+ {# Each "contact" is a Contact model object. #}
+ {{ contact.full_name|upper }}<br />
+ ...
+ {% endfor %}
+
+ <div class="pagination">
+ <span class="step-links">
+ {% if contacts.has_previous %}
+ <a href="?page={{ contacts.previous_page_number }}">previous</a>
+ {% endif %}
+
+ <span class="current">
+ Page {{ contacts.number }} of {{ contacts.paginator.num_pages }}.
+ </span>
+
+ {% if contacts.has_next %}
+ <a href="?page={{ contacts.next_page_number }}">next</a>
+ {% endif %}
+ </span>
+ </div>
+
+
+``Paginator`` objects
+=====================
+
+The :class:`Paginator` class has this constructor:
+
+.. class:: Paginator(object_list, per_page, orphans=0, allow_empty_first_page=True)
+
+Required arguments
+------------------
+
+``object_list``
+ A list, tuple, Django ``QuerySet``, or other sliceable object with a
+ ``count()`` or ``__len__()`` method.
+
+``per_page``
+ The maximum number of items to include on a page, not including orphans
+ (see the ``orphans`` optional argument below).
+
+Optional arguments
+------------------
+
+``orphans``
+ The minimum number of items allowed on the last page, defaults to zero.
+ Use this when you don't want to have a last page with very few items.
+ If the last page would normally have a number of items less than or equal
+ to ``orphans``, then those items will be added to the previous page (which
+ becomes the last page) instead of leaving the items on a page by
+ themselves. For example, with 23 items, ``per_page=10``, and
+ ``orphans=3``, there will be two pages; the first page with 10 items and
+ the second (and last) page with 13 items.
+
+``allow_empty_first_page``
+ Whether or not the first page is allowed to be empty. If ``False`` and
+ ``object_list`` is empty, then an ``EmptyPage`` error will be raised.
+
+Methods
+-------
+
+.. method:: Paginator.page(number)
+
+ Returns a :class:`Page` object with the given 1-based index. Raises
+ :exc:`InvalidPage` if the given page number doesn't exist.
+
+Attributes
+----------
+
+.. attribute:: Paginator.count
+
+ The total number of objects, across all pages.
+
+ .. note::
+
+ When determining the number of objects contained in ``object_list``,
+ ``Paginator`` will first try calling ``object_list.count()``. If
+ ``object_list`` has no ``count()`` method, then ``Paginator`` will
+ fallback to using ``object_list.__len__()``. This allows objects, such
+ as Django's ``QuerySet``, to use a more efficient ``count()`` method
+ when available.
+
+.. attribute:: Paginator.num_pages
+
+ The total number of pages.
+
+.. attribute:: Paginator.page_range
+
+ A 1-based range of page numbers, e.g., ``[1, 2, 3, 4]``.
+
+``InvalidPage`` exceptions
+==========================
+
+The ``page()`` method raises ``InvalidPage`` if the requested page is invalid
+(i.e., not an integer) or contains no objects. Generally, it's enough to trap
+the ``InvalidPage`` exception, but if you'd like more granularity, you can trap
+either of the following exceptions:
+
+``PageNotAnInteger``
+ Raised when ``page()`` is given a value that isn't an integer.
+
+``EmptyPage``
+ Raised when ``page()`` is given a valid value but no objects exist on that
+ page.
+
+Both of the exceptions are subclasses of ``InvalidPage``, so you can handle
+them both with a simple ``except InvalidPage``.
+
+
+``Page`` objects
+================
+
+.. class:: Page(object_list, number, paginator)
+
+You usually won't construct :class:`Pages <Page>` by hand -- you'll get them
+using :meth:`Paginator.page`.
+
+
+Methods
+-------
+
+.. method:: Page.has_next()
+
+ Returns ``True`` if there's a next page.
+
+.. method:: Page.has_previous()
+
+ Returns ``True`` if there's a previous page.
+
+.. method:: Page.has_other_pages()
+
+ Returns ``True`` if there's a next *or* previous page.
+
+.. method:: Page.next_page_number()
+
+ Returns the next page number. Note that this is "dumb" and will return the
+ next page number regardless of whether a subsequent page exists.
+
+.. method:: Page.previous_page_number()
+
+ Returns the previous page number. Note that this is "dumb" and will return
+ the previous page number regardless of whether a previous page exists.
+
+.. method:: Page.start_index()
+
+ Returns the 1-based index of the first object on the page, relative to all
+ of the objects in the paginator's list. For example, when paginating a list
+ of 5 objects with 2 objects per page, the second page's :meth:`~Page.start_index`
+ would return ``3``.
+
+.. method:: Page.end_index()
+
+ Returns the 1-based index of the last object on the page, relative to all of
+ the objects in the paginator's list. For example, when paginating a list of
+ 5 objects with 2 objects per page, the second page's :meth:`~Page.end_index`
+ would return ``4``.
+
+Attributes
+----------
+
+.. attribute:: Page.object_list
+
+ The list of objects on this page.
+
+.. attribute:: Page.number
+
+ The 1-based page number for this page.
+
+.. attribute:: Page.paginator
+
+ The associated :class:`Paginator` object.
+