Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

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
Adrian Holovaty authored March 18, 2008

Showing 1 changed file with 133 additions and 0 deletions. Show diff stats Hide diff stats

  1. 133  docs/pagination.txt
133  docs/pagination.txt
... ...
@@ -0,0 +1,133 @@
  1
+==========
  2
+Pagination
  3
+==========
  4
+
  5
+**New in Django development version**
  6
+
  7
+Django provides a few classes that help you manage paginated data -- that is,
  8
+data that's split across several pages, with "Previous/Next" links. These
  9
+classes live in the module ``django/core/paginator.py``.
  10
+
  11
+Example
  12
+=======
  13
+
  14
+Give ``Paginator`` a list of objects, plus the number of items you'd like to
  15
+have on each page, and it gives you methods for accessing the items for each
  16
+page::
  17
+
  18
+    >>> from django.core.paginator import Paginator
  19
+    >>> objects = ['john', 'paul', 'george', 'ringo']
  20
+    >>> p = Paginator(objects, 2)
  21
+
  22
+    >>> p.count
  23
+    4
  24
+    >>> p.num_pages
  25
+    2
  26
+    >>> p.page_range
  27
+    [1, 2]
  28
+
  29
+    >>> page1 = p.page(1)
  30
+    >>> page1
  31
+    <Page 1 of 2>
  32
+    >>> page1.object_list
  33
+    ['john', 'paul']
  34
+
  35
+    >>> page2 = p.page(2)
  36
+    >>> page2.object_list
  37
+    ['george', 'ringo']
  38
+    >>> page2.has_next()
  39
+    False
  40
+    >>> page2.has_previous()
  41
+    True
  42
+    >>> page2.has_other_pages()
  43
+    True
  44
+    >>> page2.next_page_number()
  45
+    3
  46
+    >>> page2.previous_page_number()
  47
+    1
  48
+    >>> page2.start_index() # The 1-based index of the first item on this page
  49
+    3
  50
+    >>> page2.end_index() # The 1-based index of the last item on this page
  51
+    4
  52
+
  53
+    >>> p.page(0)
  54
+    Traceback (most recent call last):
  55
+    ...
  56
+    InvalidPage
  57
+    >>> p.page(3)
  58
+    Traceback (most recent call last):
  59
+    ...
  60
+    InvalidPage
  61
+
  62
+``Paginator`` objects
  63
+=====================
  64
+
  65
+Methods
  66
+-------
  67
+
  68
+``page(number)`` -- Returns a ``Page`` object with the given 1-based index.
  69
+Raises ``InvalidPage`` if the given page number doesn't exist.
  70
+
  71
+Attributes
  72
+----------
  73
+
  74
+``count`` -- The total number of objects, across all pages.
  75
+
  76
+``num_pages`` -- The total number of pages.
  77
+
  78
+``page_range`` -- A 1-based range of page numbers, e.g., ``[1, 2, 3, 4]``.
  79
+
  80
+``Page`` objects
  81
+================
  82
+
  83
+Methods
  84
+-------
  85
+
  86
+``has_next()`` -- Returns ``True`` if there's a next page.
  87
+
  88
+``has_previous()`` -- Returns ``True`` if there's a previous page.
  89
+
  90
+``has_other_pages()`` -- Returns ``True`` if there's a next *or* previous page.
  91
+
  92
+``next_page_number()`` -- Returns the next page number. Note that this is
  93
+"dumb" and will return the next page number regardless of whether a subsequent
  94
+page exists.
  95
+
  96
+``previous_page_number()`` -- Returns the previous page number. Note that this
  97
+is "dumb" and will return the previous page number regardless of whether a
  98
+previous page exists.
  99
+
  100
+``start_index()`` -- Returns the 1-based index of the first object on the page,
  101
+relative to all of the objects in the paginator's list. For example, when
  102
+paginating a list of 5 objects with 2 objects per page, the second page's
  103
+``start_index()`` would return ``3``.
  104
+
  105
+``end_index()`` -- Returns the 1-based index of the last object on the page,
  106
+relative to all of the objects in the paginator's list. For example, when
  107
+paginating a list of 5 objects with 2 objects per page, the second page's
  108
+``end_index()`` would return ``4``.
  109
+
  110
+Attributes
  111
+----------
  112
+
  113
+``object_list`` -- The list of objects on this page.
  114
+
  115
+``number`` -- The 1-based page number for this page.
  116
+
  117
+``paginator`` -- The associated ``Paginator`` object.
  118
+
  119
+``QuerySetPaginator`` objects
  120
+=============================
  121
+
  122
+Use ``QuerySetPaginator`` instead of ``Paginator`` if you're paginating across
  123
+a ``QuerySet`` from Django's database API. This is slightly more efficient, and
  124
+there are no API differences between the two classes.
  125
+
  126
+The legacy ``ObjectPaginator`` class
  127
+====================================
  128
+
  129
+The ``Paginator`` and ``Page`` classes are new in the Django development
  130
+version, as of revision 7306. In previous versions, Django provided an
  131
+``ObjectPaginator`` class that offered similar functionality but wasn't as
  132
+convenient. This class still exists, for backwards compatibility, but Django
  133
+now issues a ``DeprecationWarning`` if you try to use it.

0 notes on commit edb3381

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