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