| 1 |
========== |
| 2 |
Pagination |
| 3 |
========== |
| 4 |
|
| 5 |
Django provides high-level and low-level ways to help you manage paginated data |
| 6 |
-- that is, data that's split across several pages, with "Previous/Next" links. |
| 7 |
|
| 8 |
The ``Paginator`` class |
| 9 |
======================= |
| 10 |
|
| 11 |
Under the hood, all methods of pagination use the |
| 12 |
:class:`~django.core.paginator.Paginator` class. It does all the heavy lifting |
| 13 |
of actually splitting a ``QuerySet`` into :class:`~django.core.paginator.Page` |
| 14 |
objects. |
| 15 |
|
| 16 |
Example |
| 17 |
======= |
| 18 |
|
| 19 |
Give :class:`~django.core.paginator.Paginator` a list of objects, plus the |
| 20 |
number of items you'd like to have on each page, and it gives you methods for |
| 21 |
accessing the items for each page: |
| 22 |
|
| 23 |
.. code-block:: pycon |
| 24 |
|
| 25 |
>>> from django.core.paginator import Paginator |
| 26 |
>>> objects = ["john", "paul", "george", "ringo"] |
| 27 |
>>> p = Paginator(objects, 2) |
| 28 |
|
| 29 |
>>> p.count |
| 30 |
4 |
| 31 |
>>> p.num_pages |
| 32 |
2 |
| 33 |
>>> type(p.page_range) |
| 34 |
<class 'range'> |
| 35 |
>>> p.page_range |
| 36 |
range(1, 3) |
| 37 |
|
| 38 |
>>> page1 = p.page(1) |
| 39 |
>>> page1 |
| 40 |
<Page 1 of 2> |
| 41 |
>>> page1.object_list |
| 42 |
['john', 'paul'] |
| 43 |
|
| 44 |
>>> page2 = p.page(2) |
| 45 |
>>> page2.object_list |
| 46 |
['george', 'ringo'] |
| 47 |
>>> page2.has_next() |
| 48 |
False |
| 49 |
>>> page2.has_previous() |
| 50 |
True |
| 51 |
>>> page2.has_other_pages() |
| 52 |
True |
| 53 |
>>> page2.next_page_number() |
| 54 |
Traceback (most recent call last): |
| 55 |
... |
| 56 |
EmptyPage: That page contains no results |
| 57 |
>>> page2.previous_page_number() |
| 58 |
1 |
| 59 |
>>> page2.start_index() # The 1-based index of the first item on this page |
| 60 |
3 |
| 61 |
>>> page2.end_index() # The 1-based index of the last item on this page |
| 62 |
4 |
| 63 |
|
| 64 |
>>> p.page(0) |
| 65 |
Traceback (most recent call last): |
| 66 |
... |
| 67 |
EmptyPage: That page number is less than 1 |
| 68 |
>>> p.page(3) |
| 69 |
Traceback (most recent call last): |
| 70 |
... |
| 71 |
EmptyPage: That page contains no results |
| 72 |
|
| 73 |
.. note:: |
| 74 |
|
| 75 |
Note that you can give ``Paginator`` a list/tuple, a Django ``QuerySet``, |
| 76 |
or any other object with a ``count()`` or ``__len__()`` method. When |
| 77 |
determining the number of objects contained in the passed object, |
| 78 |
``Paginator`` will first try calling ``count()``, then fallback to using |
| 79 |
``len()`` if the passed object has no ``count()`` method. This allows |
| 80 |
objects such as Django's ``QuerySet`` to use a more efficient ``count()`` |
| 81 |
method when available. |
| 82 |
|
| 83 |
.. _paginating-a-list-view: |
| 84 |
|
| 85 |
Paginating a ``ListView`` |
| 86 |
========================= |
| 87 |
|
| 88 |
:class:`django.views.generic.list.ListView` provides a builtin way to paginate |
| 89 |
the displayed list. You can do this by adding a |
| 90 |
:attr:`~django.views.generic.list.MultipleObjectMixin.paginate_by` attribute to |
| 91 |
your view class, for example:: |
| 92 |
|
| 93 |
from django.views.generic import ListView |
| 94 |
|
| 95 |
from myapp.models import Contact |
| 96 |
|
| 97 |
|
| 98 |
class ContactListView(ListView): |
| 99 |
paginate_by = 2 |
| 100 |
model = Contact |
| 101 |
|
| 102 |
This limits the number of objects per page and adds a ``paginator`` and |
| 103 |
``page_obj`` to the ``context``. To allow your users to navigate between pages, |
| 104 |
add links to the next and previous page, in your template like this: |
| 105 |
|
| 106 |
.. code-block:: html+django |
| 107 |
|
| 108 |
{% for contact in page_obj %} |
| 109 |
{# Each "contact" is a Contact model object. #} |
| 110 |
{{ contact.full_name|upper }}<br> |
| 111 |
... |
| 112 |
{% endfor %} |
| 113 |
|
| 114 |
<div class="pagination"> |
| 115 |
<span class="step-links"> |
| 116 |
{% if page_obj.has_previous %} |
| 117 |
<a href="?page=1">« first</a> |
| 118 |
<a href="?page={{ page_obj.previous_page_number }}">previous</a> |
| 119 |
{% endif %} |
| 120 |
|
| 121 |
<span class="current"> |
| 122 |
Page {{ page_obj.number }} of {{ page_obj.paginator.num_pages }}. |
| 123 |
</span> |
| 124 |
|
| 125 |
{% if page_obj.has_next %} |
| 126 |
<a href="?page={{ page_obj.next_page_number }}">next</a> |
| 127 |
<a href="?page={{ page_obj.paginator.num_pages }}">last »</a> |
| 128 |
{% endif %} |
| 129 |
</span> |
| 130 |
</div> |
| 131 |
|
| 132 |
.. _using-paginator-in-view: |
| 133 |
|
| 134 |
Using ``Paginator`` in a view function |
| 135 |
====================================== |
| 136 |
|
| 137 |
Here's an example using :class:`~django.core.paginator.Paginator` in a view |
| 138 |
function to paginate a queryset:: |
| 139 |
|
| 140 |
from django.core.paginator import Paginator |
| 141 |
from django.shortcuts import render |
| 142 |
|
| 143 |
from myapp.models import Contact |
| 144 |
|
| 145 |
|
| 146 |
def listing(request): |
| 147 |
contact_list = Contact.objects.all() |
| 148 |
paginator = Paginator(contact_list, 25) # Show 25 contacts per page. |
| 149 |
|
| 150 |
page_number = request.GET.get("page") |
| 151 |
page_obj = paginator.get_page(page_number) |
| 152 |
return render(request, "list.html", {"page_obj": page_obj}) |
| 153 |
|
| 154 |
In the template :file:`list.html`, you can include navigation between pages in |
| 155 |
the same way as in the template for the ``ListView`` above. |