Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

Added docs/pagination.txt

git-svn-id: http://code.djangoproject.com/svn/django/trunk@7311 bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
commit edb3381c7a938e0a20cc09cb68f40cd40da778d3 1 parent c016352
@adrianholovaty adrianholovaty authored
Showing with 133 additions and 0 deletions.
  1. +133 −0 docs/pagination.txt
View
133 docs/pagination.txt
@@ -0,0 +1,133 @@
+==========
+Pagination
+==========
+
+**New in Django development version**
+
+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 the module ``django/core/paginator.py``.
+
+Example
+=======
+
+Give ``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):
+ ...
+ InvalidPage
+ >>> p.page(3)
+ Traceback (most recent call last):
+ ...
+ InvalidPage
+
+``Paginator`` objects
+=====================
+
+Methods
+-------
+
+``page(number)`` -- Returns a ``Page`` object with the given 1-based index.
+Raises ``InvalidPage`` if the given page number doesn't exist.
+
+Attributes
+----------
+
+``count`` -- The total number of objects, across all pages.
+
+``num_pages`` -- The total number of pages.
+
+``page_range`` -- A 1-based range of page numbers, e.g., ``[1, 2, 3, 4]``.
+
+``Page`` objects
+================
+
+Methods
+-------
+
+``has_next()`` -- Returns ``True`` if there's a next page.
+
+``has_previous()`` -- Returns ``True`` if there's a previous page.
+
+``has_other_pages()`` -- Returns ``True`` if there's a next *or* previous 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.
+
+``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.
+
+``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
+``start_index()`` would return ``3``.
+
+``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
+``end_index()`` would return ``4``.
+
+Attributes
+----------
+
+``object_list`` -- The list of objects on this page.
+
+``number`` -- The 1-based page number for this page.
+
+``paginator`` -- The associated ``Paginator`` object.
+
+``QuerySetPaginator`` objects
+=============================
+
+Use ``QuerySetPaginator`` instead of ``Paginator`` if you're paginating across
+a ``QuerySet`` from Django's database API. This is slightly more efficient, and
+there are no API differences between the two classes.
+
+The legacy ``ObjectPaginator`` class
+====================================
+
+The ``Paginator`` and ``Page`` classes are new in the Django development
+version, as of revision 7306. In previous versions, Django provided an
+``ObjectPaginator`` class that offered similar functionality but wasn't as
+convenient. This class still exists, for backwards compatibility, but Django
+now issues a ``DeprecationWarning`` if you try to use it.

0 comments on commit edb3381

Please sign in to comment.
Something went wrong with that request. Please try again.