← Back to branch summary

~ubuntu-branches/ubuntu/jaunty/python-django/jaunty-backports

« back to all changes in this revision

Viewing changes to docs/topics/pagination.txt

  • Committer: Bazaar Package Importer
  • Author(s): Scott James Remnant
  • Date: 2008-11-15 19:15:33 UTC
  • mfrom: (1.1.6 upstream)
  • Revision ID: james.westby@ubuntu.com-20081115191533-xbt1ut2xf4fvwtvc
Tags: 1.0.1-0ubuntu1
* New upstream release:
  - Bug fixes.

* The tests/ sub-directory appaers to have been dropped upstream, so pull
  our patch to workaround the tests and modify the rules.

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/topics/pagination.txt
75
75
    objects such as Django's ``QuerySet`` to use a more efficient ``count()``
76
76
    method when available.
77
77
 
 
78
 
 
79
Using ``Paginator`` in a view
 
80
==============================
 
81
 
 
82
Here's a slightly more complex example using :class:`Paginator` in a view to
 
83
paginate a queryset. We give both the view and the accompanying template to
 
84
show how you can display the results. This example assumes you have a
 
85
``Contacts`` model that has already been imported.
 
86
 
 
87
The view function looks like this::
 
88
 
 
89
    from django.core.paginator import Paginator, InvalidPage, EmptyPage
 
90
 
 
91
    def listing(request):
 
92
        contact_list = Contacts.objects.all()
 
93
        paginator = Paginator(contact_list, 25) # Show 25 contacts per page
 
94
 
 
95
        # Make sure page request is an int. If not, deliver first page.
 
96
        try:
 
97
            page = int(request.GET.get('page', '1'))
 
98
        except ValueError:
 
99
            page = 1
 
100
 
 
101
        # If page request (9999) is out of range, deliver last page of results.
 
102
        try:
 
103
            contacts = paginator.page(page)
 
104
        except (EmptyPage, InvalidPage):
 
105
            contacts = paginator.page(paginator.num_pages)
 
106
 
 
107
        return render_to_response('list.html', {"contacts": contacts})
 
108
 
 
109
In the template :file:`list.html`, you'll want to include navigation between
 
110
pages along with any interesting information from the objects themselves::
 
111
 
 
112
    {% for contact in contacts.object_list %}
 
113
        {# Each "contact" is a Contact model object. #}
 
114
        {{ contact.full_name|upper }}<br />
 
115
        ...
 
116
    {% endfor %}
 
117
 
 
118
    <div class="pagination">
 
119
        <span class="step-links">
 
120
            {% if contacts.has_previous %}
 
121
                <a href="?page={{ contacts.previous_page_number }}">previous</a>
 
122
            {% endif %}
 
123
 
 
124
            <span class="current">
 
125
                Page {{ contacts.number }} of {{ contacts.paginator.num_pages }}.
 
126
            </span>
 
127
 
 
128
            {% if contacts.has_next %}
 
129
                <a href="?page={{ contacts.next_page_number }}">next</a>
 
130
            {% endif %}
 
131
        </span>
 
132
    </div>
 
133
 
 
134
 
78
135
``Paginator`` objects
79
136
=====================
80
137
 
114
171
-------
115
172
 
116
173
.. method:: Paginator.page(number)
117
 
    
 
174
 
118
175
    Returns a :class:`Page` object with the given 1-based index. Raises
119
176
    :exc:`InvalidPage` if the given page number doesn't exist.
120
177
 
122
179
----------
123
180
 
124
181
.. attribute:: Paginator.count
125
 
    
 
182
 
126
183
    The total number of objects, across all pages.
127
 
    
128
 
    .. note:: 
 
184
 
 
185
    .. note::
129
186
 
130
187
        When determining the number of objects contained in ``object_list``,
131
188
        ``Paginator`` will first try calling ``object_list.count()``. If
133
190
        fallback to using ``object_list.__len__()``. This allows objects, such
134
191
        as Django's ``QuerySet``, to use a more efficient ``count()`` method
135
192
        when available.
136
 
        
 
193
 
137
194
.. attribute:: Paginator.num_pages
138
 
    
 
195
 
139
196
    The total number of pages.
140
 
    
 
197
 
141
198
.. attribute:: Paginator.page_range
142
 
    
 
199
 
143
200
    A 1-based range of page numbers, e.g., ``[1, 2, 3, 4]``.
144
201
 
145
202
``InvalidPage`` exceptions
174
231
-------
175
232
 
176
233
.. method:: Page.has_next()
177
 
    
 
234
 
178
235
    Returns ``True`` if there's a next page.
179
 
    
 
236
 
180
237
.. method:: Page.has_previous()
181
 
    
 
238
 
182
239
    Returns ``True`` if there's a previous page.
183
 
    
 
240
 
184
241
.. method:: Page.has_other_pages()
185
 
    
 
242
 
186
243
    Returns ``True`` if there's a next *or* previous page.
187
 
    
 
244
 
188
245
.. method:: Page.next_page_number()
189
 
    
 
246
 
190
247
    Returns the next page number. Note that this is "dumb" and will return the
191
248
    next page number regardless of whether a subsequent page exists.
192
 
    
 
249
 
193
250
.. method:: Page.previous_page_number()
194
 
    
 
251
 
195
252
    Returns the previous page number. Note that this is "dumb" and will return
196
253
    the previous page number regardless of whether a previous page exists.
197
 
    
 
254
 
198
255
.. method:: Page.start_index()
199
 
    
 
256
 
200
257
    Returns the 1-based index of the first object on the page, relative to all
201
258
    of the objects in the paginator's list. For example, when paginating a list
202
259
    of 5 objects with 2 objects per page, the second page's :meth:`~Page.start_index`
203
260
    would return ``3``.
204
 
    
 
261
 
205
262
.. method:: Page.end_index()
206
 
    
 
263
 
207
264
    Returns the 1-based index of the last object on the page, relative to all of
208
265
    the objects in the paginator's list. For example, when paginating a list of
209
266
    5 objects with 2 objects per page, the second page's :meth:`~Page.end_index`
213
270
----------
214
271
 
215
272
.. attribute:: Page.object_list
216
 
    
 
273
 
217
274
    The list of objects on this page.
218
 
    
 
275
 
219
276
.. attribute:: Page.number
220
 
    
 
277
 
221
278
    The 1-based page number for this page.
222
 
    
 
279
 
223
280
.. attribute:: Page.paginator
224
 
    
 
281
 
225
282
    The associated :class:`Paginator` object.
226
283