python/lib/django_1_4/docs/topics/pagination.txt

   1 ==========
   2 Pagination
   3 ==========
   4
   5 .. module:: django.core.paginator
   6    :synopsis: Classes to help you easily manage paginated data.
   7
   8 Django provides a few classes that help you manage paginated data -- that is,
   9 data that's split across several pages, with "Previous/Next" links. These
  10 classes live in :file:`django/core/paginator.py`.
  11
  12 Example
  13 =======
  14
  15 Give :class:`Paginator` a list of objects, plus the number of items you'd like to
  16 have on each page, and it gives you methods for accessing the items for each
  17 page::
  18
  19     >>> from django.core.paginator import Paginator
  20     >>> objects = ['john', 'paul', 'george', 'ringo']
  21     >>> p = Paginator(objects, 2)
  22
  23     >>> p.count
  24     4
  25     >>> p.num_pages
  26     2
  27     >>> p.page_range
  28     [1, 2]
  29
  30     >>> page1 = p.page(1)
  31     >>> page1
  32     <Page 1 of 2>
  33     >>> page1.object_list
  34     ['john', 'paul']
  35
  36     >>> page2 = p.page(2)
  37     >>> page2.object_list
  38     ['george', 'ringo']
  39     >>> page2.has_next()
  40     False
  41     >>> page2.has_previous()
  42     True
  43     >>> page2.has_other_pages()
  44     True
  45     >>> page2.next_page_number()
  46     3
  47     >>> page2.previous_page_number()
  48     1
  49     >>> page2.start_index() # The 1-based index of the first item on this page
  50     3
  51     >>> page2.end_index() # The 1-based index of the last item on this page
  52     4
  53
  54     >>> p.page(0)
  55     Traceback (most recent call last):
  56     ...
  57     EmptyPage: That page number is less than 1
  58     >>> p.page(3)
  59     Traceback (most recent call last):
  60     ...
  61     EmptyPage: That page contains no results
  62
  63 .. note::
  64
  65     Note that you can give ``Paginator`` a list/tuple, a Django ``QuerySet``,
  66     or any other object with a ``count()`` or ``__len__()`` method. When
  67     determining the number of objects contained in the passed object,
  68     ``Paginator`` will first try calling ``count()``, then fallback to using
  69     ``len()`` if the passed object has no ``count()`` method. This allows
  70     objects such as Django's ``QuerySet`` to use a more efficient ``count()``
  71     method when available.
  72
  73
  74 Using ``Paginator`` in a view
  75 ==============================
  76
  77 Here's a slightly more complex example using :class:`Paginator` in a view to
  78 paginate a queryset. We give both the view and the accompanying template to
  79 show how you can display the results. This example assumes you have a
  80 ``Contacts`` model that has already been imported.
  81
  82 The view function looks like this::
  83
  84     from django.core.paginator import Paginator, EmptyPage, PageNotAnInteger
  85
  86     def listing(request):
  87         contact_list = Contacts.objects.all()
  88         paginator = Paginator(contact_list, 25) # Show 25 contacts per page
  89
  90         page = request.GET.get('page')
  91         try:
  92             contacts = paginator.page(page)
  93         except PageNotAnInteger:
  94             # If page is not an integer, deliver first page.
  95             contacts = paginator.page(1)
  96         except EmptyPage:
  97             # If page is out of range (e.g. 9999), deliver last page of results.
  98             contacts = paginator.page(paginator.num_pages)
  99
 100         return render_to_response('list.html', {"contacts": contacts})
 101
 102 In the template :file:`list.html`, you'll want to include navigation between
 103 pages along with any interesting information from the objects themselves::
 104
 105     {% for contact in contacts %}
 106         {# Each "contact" is a Contact model object. #}
 107         {{ contact.full_name|upper }}<br />
 108         ...
 109     {% endfor %}
 110
 111     <div class="pagination">
 112         <span class="step-links">
 113             {% if contacts.has_previous %}
 114                 <a href="?page={{ contacts.previous_page_number }}">previous</a>
 115             {% endif %}
 116
 117             <span class="current">
 118                 Page {{ contacts.number }} of {{ contacts.paginator.num_pages }}.
 119             </span>
 120
 121             {% if contacts.has_next %}
 122                 <a href="?page={{ contacts.next_page_number }}">next</a>
 123             {% endif %}
 124         </span>
 125     </div>
 126
 127 .. versionchanged:: 1.4
 128     Previously, you would need to use
 129     ``{% for contact in contacts.object_list %}``, since the ``Page``
 130     object was not iterable.
 131
 132
 133 ``Paginator`` objects
 134 =====================
 135
 136 The :class:`Paginator` class has this constructor:
 137
 138 .. class:: Paginator(object_list, per_page, orphans=0, allow_empty_first_page=True)
 139
 140 Required arguments
 141 ------------------
 142
 143 ``object_list``
 144     A list, tuple, Django ``QuerySet``, or other sliceable object with a
 145     ``count()`` or ``__len__()`` method.
 146
 147 ``per_page``
 148     The maximum number of items to include on a page, not including orphans
 149     (see the ``orphans`` optional argument below).
 150
 151 Optional arguments
 152 ------------------
 153
 154 ``orphans``
 155     The minimum number of items allowed on the last page, defaults to zero.
 156     Use this when you don't want to have a last page with very few items.
 157     If the last page would normally have a number of items less than or equal
 158     to ``orphans``, then those items will be added to the previous page (which
 159     becomes the last page) instead of leaving the items on a page by
 160     themselves. For example, with 23 items, ``per_page=10``, and
 161     ``orphans=3``, there will be two pages; the first page with 10 items and
 162     the  second (and last) page with 13 items.
 163
 164 ``allow_empty_first_page``
 165     Whether or not the first page is allowed to be empty.  If ``False`` and
 166     ``object_list`` is  empty, then an ``EmptyPage`` error will be raised.
 167
 168 Methods
 169 -------
 170
 171 .. method:: Paginator.page(number)
 172
 173     Returns a :class:`Page` object with the given 1-based index. Raises
 174     :exc:`InvalidPage` if the given page number doesn't exist.
 175
 176 Attributes
 177 ----------
 178
 179 .. attribute:: Paginator.count
 180
 181     The total number of objects, across all pages.
 182
 183     .. note::
 184
 185         When determining the number of objects contained in ``object_list``,
 186         ``Paginator`` will first try calling ``object_list.count()``. If
 187         ``object_list`` has no ``count()`` method, then ``Paginator`` will
 188         fallback to using ``len(object_list)``. This allows objects, such as
 189         Django's ``QuerySet``, to use a more efficient ``count()`` method when
 190         available.
 191
 192 .. attribute:: Paginator.num_pages
 193
 194     The total number of pages.
 195
 196 .. attribute:: Paginator.page_range
 197
 198     A 1-based range of page numbers, e.g., ``[1, 2, 3, 4]``.
 199
 200
 201 ``InvalidPage`` exceptions
 202 ==========================
 203
 204 .. exception:: InvalidPage
 205
 206         A base class for exceptions raised when a paginator is passed an invalid
 207         page number.
 208
 209 The :meth:`Paginator.page` method raises an exception if the requested page is
 210 invalid (i.e., not an integer) or contains no objects. Generally, it's enough
 211 to trap the ``InvalidPage`` exception, but if you'd like more granularity, you
 212 can trap either of the following exceptions:
 213
 214 .. exception:: PageNotAnInteger
 215
 216     Raised when ``page()`` is given a value that isn't an integer.
 217
 218 .. exception:: EmptyPage
 219
 220     Raised when ``page()`` is given a valid value but no objects exist on that
 221     page.
 222
 223 Both of the exceptions are subclasses of :exc:`InvalidPage`, so you can handle
 224 them both with a simple ``except InvalidPage``.
 225
 226
 227 ``Page`` objects
 228 ================
 229
 230 You usually won't construct ``Page`` objects by hand -- you'll get them
 231 using :meth:`Paginator.page`.
 232
 233 .. class:: Page(object_list, number, paginator)
 234
 235 .. versionadded:: 1.4
 236     A page acts like a sequence of :attr:`Page.object_list` when using
 237     ``len()`` or iterating it directly.
 238
 239 Methods
 240 -------
 241
 242 .. method:: Page.has_next()
 243
 244     Returns ``True`` if there's a next page.
 245
 246 .. method:: Page.has_previous()
 247
 248     Returns ``True`` if there's a previous page.
 249
 250 .. method:: Page.has_other_pages()
 251
 252     Returns ``True`` if there's a next *or* previous page.
 253
 254 .. method:: Page.next_page_number()
 255
 256     Returns the next page number. Note that this is "dumb" and will return the
 257     next page number regardless of whether a subsequent page exists.
 258
 259 .. method:: Page.previous_page_number()
 260
 261     Returns the previous page number. Note that this is "dumb" and will return
 262     the previous page number regardless of whether a previous page exists.
 263
 264 .. method:: Page.start_index()
 265
 266     Returns the 1-based index of the first object on the page, relative to all
 267     of the objects in the paginator's list. For example, when paginating a list
 268     of 5 objects with 2 objects per page, the second page's
 269     :meth:`~Page.start_index` would return ``3``.
 270
 271 .. method:: Page.end_index()
 272
 273     Returns the 1-based index of the last object on the page, relative to all
 274     of the objects in the paginator's list. For example, when paginating a list
 275     of 5 objects with 2 objects per page, the second page's
 276     :meth:`~Page.end_index` would return ``4``.
 277
 278 Attributes
 279 ----------
 280
 281 .. attribute:: Page.object_list
 282
 283     The list of objects on this page.
 284
 285 .. attribute:: Page.number
 286
 287     The 1-based page number for this page.
 288
 289 .. attribute:: Page.paginator
 290
 291     The associated :class:`Paginator` object.