5
Writing Web applications can be monotonous, because we repeat certain patterns
6
again and again. In Django, the most common of these patterns have been
7
abstracted into "generic views" that let you quickly provide common views of
8
an object without actually needing to write any Python code.
10
Django's generic views contain the following:
12
* A set of views for doing list/detail interfaces (for example,
13
Django's `documentation index`_ and `detail pages`_).
15
* A set of views for year/month/day archive pages and associated
16
detail and "latest" pages (for example, the Django weblog's year_,
17
month_, day_, detail_, and latest_ pages).
19
* A set of views for creating, editing, and deleting objects.
21
.. _`documentation index`: http://www.djangoproject.com/documentation/
22
.. _`detail pages`: http://www.djangoproject.com/documentation/faq/
23
.. _year: http://www.djangoproject.com/weblog/2005/
24
.. _month: http://www.djangoproject.com/weblog/2005/jul/
25
.. _day: http://www.djangoproject.com/weblog/2005/jul/20/
26
.. _detail: http://www.djangoproject.com/weblog/2005/jul/20/autoreload/
27
.. _latest: http://www.djangoproject.com/weblog/
29
All of these views are used by creating configuration dictionaries in
30
your URLconf files and passing those dictionaries as the third member of the
31
URLconf tuple for a given pattern. For example, here's the URLconf for the
32
simple weblog app that drives the blog on djangoproject.com::
34
from django.conf.urls.defaults import *
35
from django_website.apps.blog.models import Entry
38
'queryset': Entry.objects.all(),
39
'date_field': 'pub_date',
42
urlpatterns = patterns('django.views.generic.date_based',
43
(r'^(?P<year>\d{4})/(?P<month>[a-z]{3})/(?P<day>\w{1,2})/(?P<slug>[-\w]+)/$', 'object_detail', dict(info_dict, slug_field='slug')),
44
(r'^(?P<year>\d{4})/(?P<month>[a-z]{3})/(?P<day>\w{1,2})/$', 'archive_day', info_dict),
45
(r'^(?P<year>\d{4})/(?P<month>[a-z]{3})/$', 'archive_month', info_dict),
46
(r'^(?P<year>\d{4})/$', 'archive_year', info_dict),
47
(r'^/?$', 'archive_index', info_dict),
50
As you can see, this URLconf defines a few options in ``info_dict``.
51
``'queryset'`` gives the generic view a ``QuerySet`` of objects to use (in this
52
case, all of the ``Entry`` objects) and tells the generic view which model is
55
Documentation of each generic view follows, along with a list of all keyword
56
arguments that a generic view expects. Remember that as in the example above,
57
arguments may either come from the URL pattern (as ``month``, ``day``,
58
``year``, etc. do above) or from the additional-information dictionary (as for
59
``queryset``, ``date_field``, etc.).
61
Most generic views require the ``queryset`` key, which is a ``QuerySet``
62
instance; see the `database API docs`_ for more information about ``Queryset``
65
Most views also take an optional ``extra_context`` dictionary that you can use
66
to pass any auxiliary information you wish to the view. The values in the
67
``extra_context`` dictionary can be either functions (or other callables) or
68
other objects. Functions are evaluated just before they are passed to the
69
template. However, note that QuerySets retrieve and cache their data when they
70
are first evaluated, so if you want to pass in a QuerySet via
71
``extra_context`` that is always fresh you need to wrap it in a function or
72
lambda that returns the QuerySet.
74
.. _database API docs: ../db_api/
76
"Simple" generic views
77
======================
79
The ``django.views.generic.simple`` module contains simple views to handle a
80
couple of common cases: rendering a template when no view logic is needed,
81
and issuing a redirect.
83
``django.views.generic.simple.direct_to_template``
84
--------------------------------------------------
88
Renders a given template, passing it a ``{{ params }}`` template variable,
89
which is a dictionary of the parameters captured in the URL.
91
**Required arguments:**
93
* ``template``: The full name of a template to use.
95
**Optional arguments:**
97
* ``extra_context``: A dictionary of values to add to the template
98
context. By default, this is an empty dictionary. If a value in the
99
dictionary is callable, the generic view will call it
100
just before rendering the template.
104
Given the following URL patterns::
106
urlpatterns = patterns('django.views.generic.simple',
107
(r'^foo/$', 'direct_to_template', {'template': 'foo_index.html'}),
108
(r'^foo/(?P<id>\d+)/$', 'direct_to_template', {'template': 'foo_detail.html'}),
111
... a request to ``/foo/`` would render the template ``foo_index.html``, and a
112
request to ``/foo/15/`` would render the ``foo_detail.html`` with a context
113
variable ``{{ params.id }}`` that is set to ``15``.
115
``django.views.generic.simple.redirect_to``
116
-------------------------------------------
120
Redirects to a given URL.
122
The given URL may contain dictionary-style string formatting, which will be
123
interpolated against the parameters captured in the URL.
125
If the given URL is ``None``, Django will return an ``HttpResponseGone`` (410).
127
**Required arguments:**
129
* ``url``: The URL to redirect to, as a string. Or ``None`` to raise a 410
134
This example redirects from ``/foo/<id>/`` to ``/bar/<id>/``::
136
urlpatterns = patterns('django.views.generic.simple',
137
('^foo/(?P<id>\d+)/$', 'redirect_to', {'url': '/bar/%(id)s/'}),
140
This example returns a 410 HTTP error for requests to ``/bar/``::
142
urlpatterns = patterns('django.views.generic.simple',
143
('^bar/$', 'redirect_to', {'url': None}),
146
Date-based generic views
147
========================
149
Date-based generic views (in the module ``django.views.generic.date_based``)
150
are views for displaying drilldown pages for date-based data.
152
``django.views.generic.date_based.archive_index``
153
-------------------------------------------------
157
A top-level index page showing the "latest" objects, by date. Objects with
158
a date in the *future* are not included unless you set ``allow_future`` to
161
**Required arguments:**
163
* ``queryset``: A ``QuerySet`` of objects for which the archive serves.
165
* ``date_field``: The name of the ``DateField`` or ``DateTimeField`` in
166
the ``QuerySet``'s model that the date-based archive should use to
167
determine the objects on the page.
169
**Optional arguments:**
171
* ``num_latest``: The number of latest objects to send to the template
172
context. By default, it's 15.
174
* ``template_name``: The full name of a template to use in rendering the
175
page. This lets you override the default template name (see below).
177
* ``template_loader``: The template loader to use when loading the
178
template. By default, it's ``django.template.loader``.
180
* ``extra_context``: A dictionary of values to add to the template
181
context. By default, this is an empty dictionary. If a value in the
182
dictionary is callable, the generic view will call it
183
just before rendering the template.
185
* ``allow_empty``: A boolean specifying whether to display the page if no
186
objects are available. If this is ``False`` and no objects are available,
187
the view will raise a 404 instead of displaying an empty page. By
188
default, this is ``False``.
190
* ``context_processors``: A list of template-context processors to apply to
191
the view's template. See the `RequestContext docs`_.
193
* ``mimetype``: The MIME type to use for the resulting document. Defaults
194
to the value of the ``DEFAULT_CONTENT_TYPE`` setting.
196
* ``allow_future``: A boolean specifying whether to include "future"
197
objects on this page, where "future" means objects in which the field
198
specified in ``date_field`` is greater than the current date/time. By
199
default, this is ``False``.
203
If ``template_name`` isn't specified, this view will use the template
204
``<app_label>/<model_name>_archive.html`` by default, where:
206
* ``<model_name>`` is your model's name in all lowercase. For a model
207
``StaffMember``, that'd be ``staffmember``.
209
* ``<app_label>`` is the right-most part of the full Python path to
210
your model's app. For example, if your model lives in
211
``apps/blog/models.py``, that'd be ``blog``.
213
**Template context:**
215
In addition to ``extra_context``, the template's context will be:
217
* ``date_list``: A list of ``datetime.date`` objects representing all
218
years that have objects available according to ``queryset``. These are
219
ordered in reverse. This is equivalent to
220
``queryset.dates(date_field, 'year')[::-1]``.
221
* ``latest``: The ``num_latest`` objects in the system, ordered descending
222
by ``date_field``. For example, if ``num_latest`` is ``10``, then
223
``latest`` will be a list of the latest 10 objects in ``queryset``.
225
.. _RequestContext docs: ../templates_python/#subclassing-context-djangocontext
227
``django.views.generic.date_based.archive_year``
228
------------------------------------------------
232
A yearly archive page showing all available months in a given year. Objects
233
with a date in the *future* are not displayed unless you set ``allow_future``
236
**Required arguments:**
238
* ``year``: The four-digit year for which the archive serves.
240
* ``queryset``: A ``QuerySet`` of objects for which the archive serves.
242
* ``date_field``: The name of the ``DateField`` or ``DateTimeField`` in
243
the ``QuerySet``'s model that the date-based archive should use to
244
determine the objects on the page.
246
**Optional arguments:**
248
* ``template_name``: The full name of a template to use in rendering the
249
page. This lets you override the default template name (see below).
251
* ``template_loader``: The template loader to use when loading the
252
template. By default, it's ``django.template.loader``.
254
* ``extra_context``: A dictionary of values to add to the template
255
context. By default, this is an empty dictionary. If a value in the
256
dictionary is callable, the generic view will call it
257
just before rendering the template.
259
* ``allow_empty``: A boolean specifying whether to display the page if no
260
objects are available. If this is ``False`` and no objects are available,
261
the view will raise a 404 instead of displaying an empty page. By
262
default, this is ``False``.
264
* ``context_processors``: A list of template-context processors to apply to
265
the view's template. See the `RequestContext docs`_.
267
* ``template_object_name``: Designates the name of the template variable
268
to use in the template context. By default, this is ``'object'``. The
269
view will append ``'_list'`` to the value of this parameter in
270
determining the variable's name.
272
* ``make_object_list``: A boolean specifying whether to retrieve the full
273
list of objects for this year and pass those to the template. If ``True``,
274
this list of objects will be made available to the template as
275
``object_list``. (The name ``object_list`` may be different; see the docs
276
for ``object_list`` in the "Template context" section below.) By default,
279
* ``mimetype``: The MIME type to use for the resulting document. Defaults
280
to the value of the ``DEFAULT_CONTENT_TYPE`` setting.
282
* ``allow_future``: A boolean specifying whether to include "future"
283
objects on this page, where "future" means objects in which the field
284
specified in ``date_field`` is greater than the current date/time. By
285
default, this is ``False``.
289
If ``template_name`` isn't specified, this view will use the template
290
``<app_label>/<model_name>_archive_year.html`` by default.
292
**Template context:**
294
In addition to ``extra_context``, the template's context will be:
296
* ``date_list``: A list of ``datetime.date`` objects representing all
297
months that have objects available in the given year, according to
298
``queryset``, in ascending order.
300
* ``year``: The given year, as a four-character string.
302
* ``object_list``: If the ``make_object_list`` parameter is ``True``, this
303
will be set to a list of objects available for the given year, ordered by
304
the date field. This variable's name depends on the
305
``template_object_name`` parameter, which is ``'object'`` by default. If
306
``template_object_name`` is ``'foo'``, this variable's name will be
309
If ``make_object_list`` is ``False``, ``object_list`` will be passed to
310
the template as an empty list.
312
``django.views.generic.date_based.archive_month``
313
-------------------------------------------------
317
A monthly archive page showing all objects in a given month. Objects with a
318
date in the *future* are not displayed unless you set ``allow_future`` to
321
**Required arguments:**
323
* ``year``: The four-digit year for which the archive serves (a string).
325
* ``month``: The month for which the archive serves, formatted according to
326
the ``month_format`` argument.
328
* ``queryset``: A ``QuerySet`` of objects for which the archive serves.
330
* ``date_field``: The name of the ``DateField`` or ``DateTimeField`` in
331
the ``QuerySet``'s model that the date-based archive should use to
332
determine the objects on the page.
334
**Optional arguments:**
336
* ``month_format``: A format string that regulates what format the
337
``month`` parameter uses. This should be in the syntax accepted by
338
Python's ``time.strftime``. (See the `strftime docs`_.) It's set to
339
``"%b"`` by default, which is a three-letter month abbreviation. To
340
change it to use numbers, use ``"%m"``.
342
* ``template_name``: The full name of a template to use in rendering the
343
page. This lets you override the default template name (see below).
345
* ``template_loader``: The template loader to use when loading the
346
template. By default, it's ``django.template.loader``.
348
* ``extra_context``: A dictionary of values to add to the template
349
context. By default, this is an empty dictionary. If a value in the
350
dictionary is callable, the generic view will call it
351
just before rendering the template.
353
* ``allow_empty``: A boolean specifying whether to display the page if no
354
objects are available. If this is ``False`` and no objects are available,
355
the view will raise a 404 instead of displaying an empty page. By
356
default, this is ``False``.
358
* ``context_processors``: A list of template-context processors to apply to
359
the view's template. See the `RequestContext docs`_.
361
* ``template_object_name``: Designates the name of the template variable
362
to use in the template context. By default, this is ``'object'``. The
363
view will append ``'_list'`` to the value of this parameter in
364
determining the variable's name.
366
* ``mimetype``: The MIME type to use for the resulting document. Defaults
367
to the value of the ``DEFAULT_CONTENT_TYPE`` setting.
369
* ``allow_future``: A boolean specifying whether to include "future"
370
objects on this page, where "future" means objects in which the field
371
specified in ``date_field`` is greater than the current date/time. By
372
default, this is ``False``.
376
If ``template_name`` isn't specified, this view will use the template
377
``<app_label>/<model_name>_archive_month.html`` by default.
379
**Template context:**
381
In addition to ``extra_context``, the template's context will be:
383
* ``month``: A ``datetime.date`` object representing the given month.
385
* ``next_month``: A ``datetime.date`` object representing the first day of
386
the next month. If the next month is in the future, this will be
389
* ``previous_month``: A ``datetime.date`` object representing the first day
390
of the previous month. Unlike ``next_month``, this will never be
393
* ``object_list``: A list of objects available for the given month. This
394
variable's name depends on the ``template_object_name`` parameter, which
395
is ``'object'`` by default. If ``template_object_name`` is ``'foo'``,
396
this variable's name will be ``foo_list``.
398
.. _strftime docs: http://www.python.org/doc/current/lib/module-time.html#l2h-1941
400
``django.views.generic.date_based.archive_week``
401
------------------------------------------------
405
A weekly archive page showing all objects in a given week. Objects with a date
406
in the *future* are not displayed unless you set ``allow_future`` to ``True``.
408
**Required arguments:**
410
* ``year``: The four-digit year for which the archive serves (a string).
412
* ``week``: The week of the year for which the archive serves (a string).
413
Weeks start with Sunday.
415
* ``queryset``: A ``QuerySet`` of objects for which the archive serves.
417
* ``date_field``: The name of the ``DateField`` or ``DateTimeField`` in
418
the ``QuerySet``'s model that the date-based archive should use to
419
determine the objects on the page.
421
**Optional arguments:**
423
* ``template_name``: The full name of a template to use in rendering the
424
page. This lets you override the default template name (see below).
426
* ``template_loader``: The template loader to use when loading the
427
template. By default, it's ``django.template.loader``.
429
* ``extra_context``: A dictionary of values to add to the template
430
context. By default, this is an empty dictionary. If a value in the
431
dictionary is callable, the generic view will call it
432
just before rendering the template.
434
* ``allow_empty``: A boolean specifying whether to display the page if no
435
objects are available. If this is ``False`` and no objects are available,
436
the view will raise a 404 instead of displaying an empty page. By
437
default, this is ``True``.
439
* ``context_processors``: A list of template-context processors to apply to
440
the view's template. See the `RequestContext docs`_.
442
* ``template_object_name``: Designates the name of the template variable
443
to use in the template context. By default, this is ``'object'``. The
444
view will append ``'_list'`` to the value of this parameter in
445
determining the variable's name.
447
* ``mimetype``: The MIME type to use for the resulting document. Defaults
448
to the value of the ``DEFAULT_CONTENT_TYPE`` setting.
450
* ``allow_future``: A boolean specifying whether to include "future"
451
objects on this page, where "future" means objects in which the field
452
specified in ``date_field`` is greater than the current date/time. By
453
default, this is ``False``.
457
If ``template_name`` isn't specified, this view will use the template
458
``<app_label>/<model_name>_archive_week.html`` by default.
460
**Template context:**
462
In addition to ``extra_context``, the template's context will be:
464
* ``week``: A ``datetime.date`` object representing the first day of the
467
* ``object_list``: A list of objects available for the given week. This
468
variable's name depends on the ``template_object_name`` parameter, which
469
is ``'object'`` by default. If ``template_object_name`` is ``'foo'``,
470
this variable's name will be ``foo_list``.
472
``django.views.generic.date_based.archive_day``
473
-----------------------------------------------
477
A day archive page showing all objects in a given day. Days in the future throw
478
a 404 error, regardless of whether any objects exist for future days, unless
479
you set ``allow_future`` to ``True``.
481
**Required arguments:**
483
* ``year``: The four-digit year for which the archive serves (a string).
485
* ``month``: The month for which the archive serves, formatted according to
486
the ``month_format`` argument.
488
* ``day``: The day for which the archive serves, formatted according to the
489
``day_format`` argument.
491
* ``queryset``: A ``QuerySet`` of objects for which the archive serves.
493
* ``date_field``: The name of the ``DateField`` or ``DateTimeField`` in
494
the ``QuerySet``'s model that the date-based archive should use to
495
determine the objects on the page.
497
**Optional arguments:**
499
* ``month_format``: A format string that regulates what format the
500
``month`` parameter uses. This should be in the syntax accepted by
501
Python's ``time.strftime``. (See the `strftime docs`_.) It's set to
502
``"%b"`` by default, which is a three-letter month abbreviation. To
503
change it to use numbers, use ``"%m"``.
505
* ``day_format``: Like ``month_format``, but for the ``day`` parameter.
506
It defaults to ``"%d"`` (day of the month as a decimal number, 01-31).
508
* ``template_name``: The full name of a template to use in rendering the
509
page. This lets you override the default template name (see below).
511
* ``template_loader``: The template loader to use when loading the
512
template. By default, it's ``django.template.loader``.
514
* ``extra_context``: A dictionary of values to add to the template
515
context. By default, this is an empty dictionary. If a value in the
516
dictionary is callable, the generic view will call it
517
just before rendering the template.
519
* ``allow_empty``: A boolean specifying whether to display the page if no
520
objects are available. If this is ``False`` and no objects are available,
521
the view will raise a 404 instead of displaying an empty page. By
522
default, this is ``False``.
524
* ``context_processors``: A list of template-context processors to apply to
525
the view's template. See the `RequestContext docs`_.
527
* ``template_object_name``: Designates the name of the template variable
528
to use in the template context. By default, this is ``'object'``. The
529
view will append ``'_list'`` to the value of this parameter in
530
determining the variable's name.
532
* ``mimetype``: The MIME type to use for the resulting document. Defaults
533
to the value of the ``DEFAULT_CONTENT_TYPE`` setting.
535
* ``allow_future``: A boolean specifying whether to include "future"
536
objects on this page, where "future" means objects in which the field
537
specified in ``date_field`` is greater than the current date/time. By
538
default, this is ``False``.
542
If ``template_name`` isn't specified, this view will use the template
543
``<app_label>/<model_name>_archive_day.html`` by default.
545
**Template context:**
547
In addition to ``extra_context``, the template's context will be:
549
* ``day``: A ``datetime.date`` object representing the given day.
551
* ``next_day``: A ``datetime.date`` object representing the next day. If
552
the next day is in the future, this will be ``None``.
554
* ``previous_day``: A ``datetime.date`` object representing the given day.
555
Unlike ``next_day``, this will never be ``None``.
557
* ``object_list``: A list of objects available for the given day. This
558
variable's name depends on the ``template_object_name`` parameter, which
559
is ``'object'`` by default. If ``template_object_name`` is ``'foo'``,
560
this variable's name will be ``foo_list``.
562
``django.views.generic.date_based.archive_today``
563
-------------------------------------------------
567
A day archive page showing all objects for *today*. This is exactly the same as
568
``archive_day``, except the ``year``/``month``/``day`` arguments are not used,
569
and today's date is used instead.
571
``django.views.generic.date_based.object_detail``
572
-------------------------------------------------
576
A page representing an individual object. If the object has a date value in the
577
future, the view will throw a 404 error by default, unless you set
578
``allow_future`` to ``True``.
580
**Required arguments:**
582
* ``year``: The object's four-digit year (a string).
584
* ``month``: The object's month , formatted according to the
585
``month_format`` argument.
587
* ``day``: The object's day , formatted according to the ``day_format``
590
* ``queryset``: A ``QuerySet`` that contains the object.
592
* ``date_field``: The name of the ``DateField`` or ``DateTimeField`` in
593
the ``QuerySet``'s model that the generic view should use to look up the
594
object according to ``year``, ``month`` and ``day``.
596
* Either ``object_id`` or (``slug`` *and* ``slug_field``) is required.
598
If you provide ``object_id``, it should be the value of the primary-key
599
field for the object being displayed on this page.
601
Otherwise, ``slug`` should be the slug of the given object, and
602
``slug_field`` should be the name of the slug field in the ``QuerySet``'s
605
**Optional arguments:**
607
* ``month_format``: A format string that regulates what format the
608
``month`` parameter uses. This should be in the syntax accepted by
609
Python's ``time.strftime``. (See the `strftime docs`_.) It's set to
610
``"%b"`` by default, which is a three-letter month abbreviation. To
611
change it to use numbers, use ``"%m"``.
613
* ``day_format``: Like ``month_format``, but for the ``day`` parameter.
614
It defaults to ``"%d"`` (day of the month as a decimal number, 01-31).
616
* ``template_name``: The full name of a template to use in rendering the
617
page. This lets you override the default template name (see below).
619
* ``template_name_field``: The name of a field on the object whose value is
620
the template name to use. This lets you store template names in the data.
621
In other words, if your object has a field ``'the_template'`` that
622
contains a string ``'foo.html'``, and you set ``template_name_field`` to
623
``'the_template'``, then the generic view for this object will use the
624
template ``'foo.html'``.
626
It's a bit of a brain-bender, but it's useful in some cases.
628
* ``template_loader``: The template loader to use when loading the
629
template. By default, it's ``django.template.loader``.
631
* ``extra_context``: A dictionary of values to add to the template
632
context. By default, this is an empty dictionary. If a value in the
633
dictionary is callable, the generic view will call it
634
just before rendering the template.
636
* ``context_processors``: A list of template-context processors to apply to
637
the view's template. See the `RequestContext docs`_.
639
* ``template_object_name``: Designates the name of the template variable
640
to use in the template context. By default, this is ``'object'``.
642
* ``mimetype``: The MIME type to use for the resulting document. Defaults
643
to the value of the ``DEFAULT_CONTENT_TYPE`` setting.
645
* ``allow_future``: A boolean specifying whether to include "future"
646
objects on this page, where "future" means objects in which the field
647
specified in ``date_field`` is greater than the current date/time. By
648
default, this is ``False``.
652
If ``template_name`` isn't specified, this view will use the template
653
``<app_label>/<model_name>_detail.html`` by default.
655
**Template context:**
657
In addition to ``extra_context``, the template's context will be:
659
* ``object``: The object. This variable's name depends on the
660
``template_object_name`` parameter, which is ``'object'`` by default. If
661
``template_object_name`` is ``'foo'``, this variable's name will be
664
List/detail generic views
665
=========================
667
The list-detail generic-view framework (in the
668
``django.views.generic.list_detail`` module) is similar to the date-based one,
669
except the former simply has two views: a list of objects and an individual
672
``django.views.generic.list_detail.object_list``
673
------------------------------------------------
677
A page representing a list of objects.
679
**Required arguments:**
681
* ``queryset``: A ``QuerySet`` that represents the objects.
683
**Optional arguments:**
685
* ``paginate_by``: An integer specifying how many objects should be
686
displayed per page. If this is given, the view will paginate objects with
687
``paginate_by`` objects per page. The view will expect either a ``page``
688
query string parameter (via ``GET``) containing a 1-based page
689
number, or a ``page`` variable specified in the URLconf. See
690
"Notes on pagination" below.
692
* ``template_name``: The full name of a template to use in rendering the
693
page. This lets you override the default template name (see below).
695
* ``template_loader``: The template loader to use when loading the
696
template. By default, it's ``django.template.loader``.
698
* ``extra_context``: A dictionary of values to add to the template
699
context. By default, this is an empty dictionary. If a value in the
700
dictionary is callable, the generic view will call it
701
just before rendering the template.
703
* ``allow_empty``: A boolean specifying whether to display the page if no
704
objects are available. If this is ``False`` and no objects are available,
705
the view will raise a 404 instead of displaying an empty page. By
706
default, this is ``False``.
708
* ``context_processors``: A list of template-context processors to apply to
709
the view's template. See the `RequestContext docs`_.
711
* ``template_object_name``: Designates the name of the template variable
712
to use in the template context. By default, this is ``'object'``. The
713
view will append ``'_list'`` to the value of this parameter in
714
determining the variable's name.
716
* ``mimetype``: The MIME type to use for the resulting document. Defaults
717
to the value of the ``DEFAULT_CONTENT_TYPE`` setting.
721
If ``template_name`` isn't specified, this view will use the template
722
``<app_label>/<model_name>_list.html`` by default.
724
**Template context:**
726
In addition to ``extra_context``, the template's context will be:
728
* ``object_list``: The list of objects. This variable's name depends on the
729
``template_object_name`` parameter, which is ``'object'`` by default. If
730
``template_object_name`` is ``'foo'``, this variable's name will be
733
* ``is_paginated``: A boolean representing whether the results are
734
paginated. Specifically, this is set to ``False`` if the number of
735
available objects is less than or equal to ``paginate_by``.
737
If the results are paginated, the context will contain these extra variables:
739
* ``results_per_page``: The number of objects per page. (Same as the
740
``paginate_by`` parameter.)
742
* ``has_next``: A boolean representing whether there's a next page.
744
* ``has_previous``: A boolean representing whether there's a previous page.
746
* ``page``: The current page number, as an integer. This is 1-based.
748
* ``next``: The next page number, as an integer. If there's no next page,
749
this will still be an integer representing the theoretical next-page
750
number. This is 1-based.
752
* ``previous``: The previous page number, as an integer. This is 1-based.
754
* `last_on_page`: The number of the
755
last result on the current page. This is 1-based.
757
* `first_on_page`: The number of the
758
first result on the current page. This is 1-based.
760
* ``pages``: The total number of pages, as an integer.
762
* ``hits``: The total number of objects across *all* pages, not just this
768
If ``paginate_by`` is specified, Django will paginate the results. You can
769
specify the page number in the URL in one of two ways:
771
* Use the ``page`` parameter in the URLconf. For example, this is what
772
your URLconf might look like::
774
(r'^objects/page(?P<page>[0-9]+)/$', 'object_list', dict(info_dict))
776
* Pass the page number via the ``page`` query-string parameter. For
777
example, a URL would look like this:
781
In both cases, ``page`` is 1-based, not 0-based, so the first page would be
782
represented as page ``1``.
784
``django.views.generic.list_detail.object_detail``
785
--------------------------------------------------
787
A page representing an individual object.
791
A page representing an individual object.
793
**Required arguments:**
795
* ``queryset``: A ``QuerySet`` that contains the object.
797
* Either ``object_id`` or (``slug`` *and* ``slug_field``) is required.
799
If you provide ``object_id``, it should be the value of the primary-key
800
field for the object being displayed on this page.
802
Otherwise, ``slug`` should be the slug of the given object, and
803
``slug_field`` should be the name of the slug field in the ``QuerySet``'s
806
**Optional arguments:**
808
* ``template_name``: The full name of a template to use in rendering the
809
page. This lets you override the default template name (see below).
811
* ``template_name_field``: The name of a field on the object whose value is
812
the template name to use. This lets you store template names in the data.
813
In other words, if your object has a field ``'the_template'`` that
814
contains a string ``'foo.html'``, and you set ``template_name_field`` to
815
``'the_template'``, then the generic view for this object will use the
816
template ``'foo.html'``.
818
It's a bit of a brain-bender, but it's useful in some cases.
820
* ``template_loader``: The template loader to use when loading the
821
template. By default, it's ``django.template.loader``.
823
* ``extra_context``: A dictionary of values to add to the template
824
context. By default, this is an empty dictionary. If a value in the
825
dictionary is callable, the generic view will call it
826
just before rendering the template.
828
* ``context_processors``: A list of template-context processors to apply to
829
the view's template. See the `RequestContext docs`_.
831
* ``template_object_name``: Designates the name of the template variable
832
to use in the template context. By default, this is ``'object'``.
834
* ``mimetype``: The MIME type to use for the resulting document. Defaults
835
to the value of the ``DEFAULT_CONTENT_TYPE`` setting.
839
If ``template_name`` isn't specified, this view will use the template
840
``<app_label>/<model_name>_detail.html`` by default.
842
**Template context:**
844
In addition to ``extra_context``, the template's context will be:
846
* ``object``: The object. This variable's name depends on the
847
``template_object_name`` parameter, which is ``'object'`` by default. If
848
``template_object_name`` is ``'foo'``, this variable's name will be
851
Create/update/delete generic views
852
==================================
854
The ``django.views.generic.create_update`` module contains a set of functions
855
for creating, editing and deleting objects.
857
``django.views.generic.create_update.create_object``
858
----------------------------------------------------
862
A page that displays a form for creating an object, redisplaying the form with
863
validation errors (if there are any) and saving the object. This uses the
864
automatic manipulators that come with Django models.
866
**Required arguments:**
868
* ``model``: The Django model class of the object that the form will
871
**Optional arguments:**
873
* ``post_save_redirect``: A URL to which the view will redirect after
874
saving the object. By default, it's ``object.get_absolute_url()``.
876
``post_save_redirect`` may contain dictionary string formatting, which
877
will be interpolated against the object's field attributes. For example,
878
you could use ``post_save_redirect="/polls/%(slug)s/"``.
880
* ``login_required``: A boolean that designates whether a user must be
881
logged in, in order to see the page and save changes. This hooks into the
882
Django `authentication system`_. By default, this is ``False``.
884
If this is ``True``, and a non-logged-in user attempts to visit this page
885
or save the form, Django will redirect the request to ``/accounts/login/``.
887
* ``template_name``: The full name of a template to use in rendering the
888
page. This lets you override the default template name (see below).
890
* ``template_loader``: The template loader to use when loading the
891
template. By default, it's ``django.template.loader``.
893
* ``extra_context``: A dictionary of values to add to the template
894
context. By default, this is an empty dictionary. If a value in the
895
dictionary is callable, the generic view will call it
896
just before rendering the template.
898
* ``context_processors``: A list of template-context processors to apply to
899
the view's template. See the `RequestContext docs`_.
903
If ``template_name`` isn't specified, this view will use the template
904
``<app_label>/<model_name>_form.html`` by default.
906
**Template context:**
908
In addition to ``extra_context``, the template's context will be:
910
* ``form``: A ``django.oldforms.FormWrapper`` instance representing the form
911
for editing the object. This lets you refer to form fields easily in the
914
For example, if ``model`` has two fields, ``name`` and ``address``::
916
<form action="" method="post">
917
<p><label for="id_name">Name:</label> {{ form.name }}</p>
918
<p><label for="id_address">Address:</label> {{ form.address }}</p>
921
See the `manipulator and formfield documentation`_ for more information
922
about using ``FormWrapper`` objects in templates.
924
.. _authentication system: ../authentication/
925
.. _manipulator and formfield documentation: ../forms/
927
``django.views.generic.create_update.update_object``
928
----------------------------------------------------
932
A page that displays a form for editing an existing object, redisplaying the
933
form with validation errors (if there are any) and saving changes to the
934
object. This uses the automatic manipulators that come with Django models.
936
**Required arguments:**
938
* ``model``: The Django model class of the object that the form will
941
* Either ``object_id`` or (``slug`` *and* ``slug_field``) is required.
943
If you provide ``object_id``, it should be the value of the primary-key
944
field for the object being displayed on this page.
946
Otherwise, ``slug`` should be the slug of the given object, and
947
``slug_field`` should be the name of the slug field in the ``QuerySet``'s
950
**Optional arguments:**
952
* ``post_save_redirect``: A URL to which the view will redirect after
953
saving the object. By default, it's ``object.get_absolute_url()``.
955
``post_save_redirect`` may contain dictionary string formatting, which
956
will be interpolated against the object's field attributes. For example,
957
you could use ``post_save_redirect="/polls/%(slug)s/"``.
959
* ``login_required``: A boolean that designates whether a user must be
960
logged in, in order to see the page and save changes. This hooks into the
961
Django `authentication system`_. By default, this is ``False``.
963
If this is ``True``, and a non-logged-in user attempts to visit this page
964
or save the form, Django will redirect the request to ``/accounts/login/``.
966
* ``template_name``: The full name of a template to use in rendering the
967
page. This lets you override the default template name (see below).
969
* ``template_loader``: The template loader to use when loading the
970
template. By default, it's ``django.template.loader``.
972
* ``extra_context``: A dictionary of values to add to the template
973
context. By default, this is an empty dictionary. If a value in the
974
dictionary is callable, the generic view will call it
975
just before rendering the template.
977
* ``context_processors``: A list of template-context processors to apply to
978
the view's template. See the `RequestContext docs`_.
980
* ``template_object_name``: Designates the name of the template variable
981
to use in the template context. By default, this is ``'object'``.
985
If ``template_name`` isn't specified, this view will use the template
986
``<app_label>/<model_name>_form.html`` by default.
988
**Template context:**
990
In addition to ``extra_context``, the template's context will be:
992
* ``form``: A ``django.oldforms.FormWrapper`` instance representing the form
993
for editing the object. This lets you refer to form fields easily in the
996
For example, if ``model`` has two fields, ``name`` and ``address``::
998
<form action="" method="post">
999
<p><label for="id_name">Name:</label> {{ form.name }}</p>
1000
<p><label for="id_address">Address:</label> {{ form.address }}</p>
1003
See the `manipulator and formfield documentation`_ for more information
1004
about using ``FormWrapper`` objects in templates.
1006
* ``object``: The original object being edited. This variable's name
1007
depends on the ``template_object_name`` parameter, which is ``'object'``
1008
by default. If ``template_object_name`` is ``'foo'``, this variable's
1009
name will be ``foo``.
1011
``django.views.generic.create_update.delete_object``
1012
----------------------------------------------------
1016
A view that displays a confirmation page and deletes an existing object. The
1017
given object will only be deleted if the request method is ``POST``. If this
1018
view is fetched via ``GET``, it will display a confirmation page that should
1019
contain a form that POSTs to the same URL.
1021
**Required arguments:**
1023
* ``model``: The Django model class of the object that the form will
1026
* Either ``object_id`` or (``slug`` *and* ``slug_field``) is required.
1028
If you provide ``object_id``, it should be the value of the primary-key
1029
field for the object being displayed on this page.
1031
Otherwise, ``slug`` should be the slug of the given object, and
1032
``slug_field`` should be the name of the slug field in the ``QuerySet``'s
1035
* ``post_delete_redirect``: A URL to which the view will redirect after
1036
deleting the object.
1038
**Optional arguments:**
1040
* ``login_required``: A boolean that designates whether a user must be
1041
logged in, in order to see the page and save changes. This hooks into the
1042
Django `authentication system`_. By default, this is ``False``.
1044
If this is ``True``, and a non-logged-in user attempts to visit this page
1045
or save the form, Django will redirect the request to ``/accounts/login/``.
1047
* ``template_name``: The full name of a template to use in rendering the
1048
page. This lets you override the default template name (see below).
1050
* ``template_loader``: The template loader to use when loading the
1051
template. By default, it's ``django.template.loader``.
1053
* ``extra_context``: A dictionary of values to add to the template
1054
context. By default, this is an empty dictionary. If a value in the
1055
dictionary is callable, the generic view will call it
1056
just before rendering the template.
1058
* ``context_processors``: A list of template-context processors to apply to
1059
the view's template. See the `RequestContext docs`_.
1061
* ``template_object_name``: Designates the name of the template variable
1062
to use in the template context. By default, this is ``'object'``.
1066
If ``template_name`` isn't specified, this view will use the template
1067
``<app_label>/<model_name>_confirm_delete.html`` by default.
1069
**Template context:**
1071
In addition to ``extra_context``, the template's context will be:
1073
* ``object``: The original object that's about to be deleted. This
1074
variable's name depends on the ``template_object_name`` parameter, which
1075
is ``'object'`` by default. If ``template_object_name`` is ``'foo'``,
1076
this variable's name will be ``foo``.
added
removed
docs/generic_views.txt
