Debian Codegraph @

docs/topics/pagination.txt

raw
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">&laquo; 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 &raquo;</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.