diff options
Diffstat (limited to 'parts/django/docs/topics/pagination.txt')
| -rw-r--r-- | parts/django/docs/topics/pagination.txt | 281 |
1 files changed, 281 insertions, 0 deletions
diff --git a/parts/django/docs/topics/pagination.txt b/parts/django/docs/topics/pagination.txt new file mode 100644 index 0000000..ee8a433 --- /dev/null +++ b/parts/django/docs/topics/pagination.txt @@ -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. + |