docs/pagination.txt

   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 Required arguments
  66 ------------------
  67
  68 ``object_list``
  69     A list, tuple, Django ``QuerySet``, or other sliceable object with a
  70     ``count()`` or ``__len__()`` method.
  71
  72 ``per_page``
  73     The maximum number of items to include on a page, not including orphans
  74     (see the ``orphans`` optional argument below).
  75
  76 Optional arguments
  77 ------------------
  78
  79 ``orphans``
  80     The minimum number of items allowed on the last page, defaults to zero.
  81     Use this when you don't want to have a last page with very few items.
  82     If the last page would normally have a number of items less than or equal
  83     to ``orphans``, then those items will be added to the previous page (which
  84     becomes the last page) instead of leaving the items on a page by
  85     themselves. For example, with 23 items, ``per_page=10``, and
  86     ``orphans=3``, there will be two pages; the first page with 10 items and
  87     the  second (and last) page with 13 items.
  88
  89 ``allow_empty_first_page``
  90     Whether or not the first page is allowed to be empty.  If ``False`` and
  91     ``object_list`` is  empty, then a ``EmptyPage`` error will be raised.
  92
  93 Methods
  94 -------
  95
  96 ``page(number)``
  97     Returns a ``Page`` object with the given 1-based index. Raises
  98     ``InvalidPage`` if the given page number doesn't exist.
  99
 100 Attributes
 101 ----------
 102
 103 In addition to the arguments above, which get stored as attributes, a
 104 ``Paginator`` object also has the following attributes:
 105
 106 ``count``
 107     The total number of objects, across all pages.
 108
 109     **Note**: When determining the number of objects contained in
 110     ``object_list``, ``Paginator`` will first try calling
 111     ``object_list.count()``. If ``object_list`` has no ``count()`` method, then
 112     ``Paginator`` will fallback to using ``object_list.__len__()``. This allows
 113     objects, such as Django's ``QuerySet``, to use a more efficient ``count()``
 114     method when available.
 115
 116 ``num_pages``
 117     The total number of pages.
 118
 119 ``page_range``
 120     A 1-based range of page numbers, e.g., ``[1, 2, 3, 4]``.
 121
 122 ``InvalidPage`` exceptions
 123 ==========================
 124
 125 The ``page()`` method raises ``InvalidPage`` if the requested page is invalid
 126 (i.e., not an integer) or contains no objects. Generally, it's enough to trap
 127 the ``InvalidPage`` exception, but if you'd like more granularity, you can trap
 128 either of the following exceptions:
 129
 130 ``PageNotAnInteger``
 131     Raised when ``page()`` is given a value that isn't an integer.
 132
 133 ``EmptyPage``
 134     Raised when ``page()`` is given a valid value but no objects exist on that
 135     page.
 136
 137 Both of the exceptions are subclasses of ``InvalidPage``, so you can handle
 138 them both with a simple ``except InvalidPage``.
 139
 140 ``Page`` objects
 141 ================
 142
 143 Methods
 144 -------
 145
 146 ``has_next()``
 147     Returns ``True`` if there's a next page.
 148
 149 ``has_previous()``
 150     Returns ``True`` if there's a previous page.
 151
 152 ``has_other_pages()``
 153     Returns ``True`` if there's a next *or* previous page.
 154
 155 ``next_page_number()``
 156     Returns the next page number. Note that this is "dumb" and will return the
 157     next page number regardless of whether a subsequent page exists.
 158
 159 ``previous_page_number()``
 160     Returns the previous page number. Note that this is "dumb" and will return
 161     the previous page number regardless of whether a previous page exists.
 162
 163 ``start_index()``
 164     Returns the 1-based index of the first object on the page, relative to all
 165     of the objects in the paginator's list. For example, when paginating a list
 166     of 5 objects with 2 objects per page, the second page's ``start_index()``
 167     would return ``3``.
 168
 169 ``end_index()``
 170     Returns the 1-based index of the last object on the page, relative to all
 171     of the objects in the paginator's list. For example, when paginating a list
 172     of 5 objects with 2 objects per page, the second page's ``end_index()``
 173     would return ``4``.
 174
 175 Attributes
 176 ----------
 177
 178 ``object_list``
 179     The list of objects on this page.
 180
 181 ``number``
 182     The 1-based page number for this page.
 183
 184 ``paginator``
 185     The associated ``Paginator`` object.