PageRenderTime 173ms CodeModel.GetById 25ms RepoModel.GetById 1ms app.codeStats 0ms

/docs/topics/pagination.txt

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