docs/generic_views.txt

   1 =============
   2 Generic views
   3 =============
   4
   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.
   9
  10 Django's generic views contain the following:
  11
  12     * A set of views for doing list/detail interfaces (for example,
  13       Django's `documentation index`_ and `detail pages`_).
  14
  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).
  18
  19     * A set of views for creating, editing, and deleting objects.
  20
  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/
  28
  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::
  33
  34     from django.conf.urls.defaults import *
  35     from django_website.apps.blog.models import Entry
  36
  37     info_dict = {
  38         'queryset': Entry.objects.all(),
  39         'date_field': 'pub_date',
  40     }
  41
  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', info_dict),
  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),
  48     )
  49
  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
  53 being used.
  54
  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.).
  60
  61 Most generic views require the ``queryset`` key, which is a ``QuerySet``
  62 instance; see the `database API docs`_ for more information about ``Queryset``
  63 objects.
  64
  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.
  73
  74 .. _database API docs: ../db-api/
  75
  76 "Simple" generic views
  77 ======================
  78
  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.
  82
  83 ``django.views.generic.simple.direct_to_template``
  84 --------------------------------------------------
  85
  86 **Description:**
  87
  88 Renders a given template, passing it a ``{{ params }}`` template variable,
  89 which is a dictionary of the parameters captured in the URL.
  90
  91 **Required arguments:**
  92
  93     * ``template``: The full name of a template to use.
  94
  95 **Optional arguments:**
  96
  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.
 101
 102     * ``mimetype``: The MIME type to use for the resulting document. Defaults
 103       to the value of the ``DEFAULT_CONTENT_TYPE`` setting.
 104
 105 **Example:**
 106
 107 Given the following URL patterns::
 108
 109     urlpatterns = patterns('django.views.generic.simple',
 110         (r'^foo/$',             'direct_to_template', {'template': 'foo_index.html'}),
 111         (r'^foo/(?P<id>\d+)/$', 'direct_to_template', {'template': 'foo_detail.html'}),
 112     )
 113
 114 ... a request to ``/foo/`` would render the template ``foo_index.html``, and a
 115 request to ``/foo/15/`` would render the ``foo_detail.html`` with a context
 116 variable ``{{ params.id }}`` that is set to ``15``.
 117
 118 ``django.views.generic.simple.redirect_to``
 119 -------------------------------------------
 120
 121 **Description:**
 122
 123 Redirects to a given URL.
 124
 125 The given URL may contain dictionary-style string formatting, which will be
 126 interpolated against the parameters captured in the URL.
 127
 128 If the given URL is ``None``, Django will return an ``HttpResponseGone`` (410).
 129
 130 **Required arguments:**
 131
 132     * ``url``: The URL to redirect to, as a string. Or ``None`` to raise a 410
 133       (Gone) HTTP error.
 134
 135 **Example:**
 136
 137 This example redirects from ``/foo/<id>/`` to ``/bar/<id>/``::
 138
 139     urlpatterns = patterns('django.views.generic.simple',
 140         ('^foo/(?P<id>\d+)/$', 'redirect_to', {'url': '/bar/%(id)s/'}),
 141     )
 142
 143 This example returns a 410 HTTP error for requests to ``/bar/``::
 144
 145     urlpatterns = patterns('django.views.generic.simple',
 146         ('^bar/$', 'redirect_to', {'url': None}),
 147     )
 148
 149 Date-based generic views
 150 ========================
 151
 152 Date-based generic views (in the module ``django.views.generic.date_based``)
 153 are views for displaying drilldown pages for date-based data.
 154
 155 ``django.views.generic.date_based.archive_index``
 156 -------------------------------------------------
 157
 158 **Description:**
 159
 160 A top-level index page showing the "latest" objects, by date. Objects with
 161 a date in the *future* are not included unless you set ``allow_future`` to
 162 ``True``.
 163
 164 **Required arguments:**
 165
 166     * ``queryset``: A ``QuerySet`` of objects for which the archive serves.
 167
 168     * ``date_field``: The name of the ``DateField`` or ``DateTimeField`` in
 169       the ``QuerySet``'s model that the date-based archive should use to
 170       determine the objects on the page.
 171
 172 **Optional arguments:**
 173
 174     * ``num_latest``: The number of latest objects to send to the template
 175       context. By default, it's 15.
 176
 177     * ``template_name``: The full name of a template to use in rendering the
 178       page. This lets you override the default template name (see below).
 179
 180     * ``template_loader``: The template loader to use when loading the
 181       template. By default, it's ``django.template.loader``.
 182
 183     * ``extra_context``: A dictionary of values to add to the template
 184       context. By default, this is an empty dictionary. If a value in the
 185       dictionary is callable, the generic view will call it
 186       just before rendering the template.
 187
 188     * ``allow_empty``: A boolean specifying whether to display the page if no
 189       objects are available. If this is ``False`` and no objects are available,
 190       the view will raise a 404 instead of displaying an empty page. By
 191       default, this is ``True``.
 192
 193     * ``context_processors``: A list of template-context processors to apply to
 194       the view's template. See the `RequestContext docs`_.
 195
 196     * ``mimetype``: The MIME type to use for the resulting document. Defaults
 197       to the value of the ``DEFAULT_CONTENT_TYPE`` setting.
 198
 199     * ``allow_future``: A boolean specifying whether to include "future"
 200       objects on this page, where "future" means objects in which the field
 201       specified in ``date_field`` is greater than the current date/time. By
 202       default, this is ``False``.
 203
 204     * **New in Django development version:** ``template_object_name``:
 205       Designates the name of the template variable to use in the template
 206       context. By default, this is ``'latest'``.
 207
 208 **Template name:**
 209
 210 If ``template_name`` isn't specified, this view will use the template
 211 ``<app_label>/<model_name>_archive.html`` by default, where:
 212
 213     * ``<model_name>`` is your model's name in all lowercase. For a model
 214       ``StaffMember``, that'd be ``staffmember``.
 215
 216     * ``<app_label>`` is the right-most part of the full Python path to
 217       your model's app. For example, if your model lives in
 218       ``apps/blog/models.py``, that'd be ``blog``.
 219
 220 **Template context:**
 221
 222 In addition to ``extra_context``, the template's context will be:
 223
 224     * ``date_list``: A list of ``datetime.date`` objects representing all
 225       years that have objects available according to ``queryset``. These are
 226       ordered in reverse. This is equivalent to
 227       ``queryset.dates(date_field, 'year')[::-1]``.
 228
 229     * ``latest``: The ``num_latest`` objects in the system, ordered descending
 230       by ``date_field``. For example, if ``num_latest`` is ``10``, then
 231       ``latest`` will be a list of the latest 10 objects in ``queryset``.
 232
 233       **New in Django development version:** This variable's name depends on
 234       the ``template_object_name`` parameter, which is ``'latest'`` by default.
 235       If ``template_object_name`` is ``'foo'``, this variable's name will be
 236       ``foo``.
 237
 238 .. _RequestContext docs: ../templates_python/#subclassing-context-requestcontext
 239
 240 ``django.views.generic.date_based.archive_year``
 241 ------------------------------------------------
 242
 243 **Description:**
 244
 245 A yearly archive page showing all available months in a given year. Objects
 246 with a date in the *future* are not displayed unless you set ``allow_future``
 247 to ``True``.
 248
 249 **Required arguments:**
 250
 251     * ``year``: The four-digit year for which the archive serves.
 252
 253     * ``queryset``: A ``QuerySet`` of objects for which the archive serves.
 254
 255     * ``date_field``: The name of the ``DateField`` or ``DateTimeField`` in
 256       the ``QuerySet``'s model that the date-based archive should use to
 257       determine the objects on the page.
 258
 259 **Optional arguments:**
 260
 261     * ``template_name``: The full name of a template to use in rendering the
 262       page. This lets you override the default template name (see below).
 263
 264     * ``template_loader``: The template loader to use when loading the
 265       template. By default, it's ``django.template.loader``.
 266
 267     * ``extra_context``: A dictionary of values to add to the template
 268       context. By default, this is an empty dictionary. If a value in the
 269       dictionary is callable, the generic view will call it
 270       just before rendering the template.
 271
 272     * ``allow_empty``: A boolean specifying whether to display the page if no
 273       objects are available. If this is ``False`` and no objects are available,
 274       the view will raise a 404 instead of displaying an empty page. By
 275       default, this is ``False``.
 276
 277     * ``context_processors``: A list of template-context processors to apply to
 278       the view's template. See the `RequestContext docs`_.
 279
 280     * ``template_object_name``:  Designates the name of the template variable
 281       to use in the template context. By default, this is ``'object'``. The
 282       view will append ``'_list'`` to the value of this parameter in
 283       determining the variable's name.
 284
 285     * ``make_object_list``: A boolean specifying whether to retrieve the full
 286       list of objects for this year and pass those to the template. If ``True``,
 287       this list of objects will be made available to the template as
 288       ``object_list``. (The name ``object_list`` may be different; see the docs
 289       for ``object_list`` in the "Template context" section below.) By default,
 290       this is ``False``.
 291
 292     * ``mimetype``: The MIME type to use for the resulting document. Defaults
 293       to the value of the ``DEFAULT_CONTENT_TYPE`` setting.
 294
 295     * ``allow_future``: A boolean specifying whether to include "future"
 296       objects on this page, where "future" means objects in which the field
 297       specified in ``date_field`` is greater than the current date/time. By
 298       default, this is ``False``.
 299
 300 **Template name:**
 301
 302 If ``template_name`` isn't specified, this view will use the template
 303 ``<app_label>/<model_name>_archive_year.html`` by default.
 304
 305 **Template context:**
 306
 307 In addition to ``extra_context``, the template's context will be:
 308
 309     * ``date_list``: A list of ``datetime.date`` objects representing all
 310       months that have objects available in the given year, according to
 311       ``queryset``, in ascending order.
 312
 313     * ``year``: The given year, as a four-character string.
 314
 315     * ``object_list``: If the ``make_object_list`` parameter is ``True``, this
 316       will be set to a list of objects available for the given year, ordered by
 317       the date field. This variable's name depends on the
 318       ``template_object_name`` parameter, which is ``'object'`` by default. If
 319       ``template_object_name`` is ``'foo'``, this variable's name will be
 320       ``foo_list``.
 321
 322       If ``make_object_list`` is ``False``, ``object_list`` will be passed to
 323       the template as an empty list.
 324
 325 ``django.views.generic.date_based.archive_month``
 326 -------------------------------------------------
 327
 328 **Description:**
 329
 330 A monthly archive page showing all objects in a given month. Objects with a
 331 date in the *future* are not displayed unless you set ``allow_future`` to
 332 ``True``.
 333
 334 **Required arguments:**
 335
 336     * ``year``: The four-digit year for which the archive serves (a string).
 337
 338     * ``month``: The month for which the archive serves, formatted according to
 339       the ``month_format`` argument.
 340
 341     * ``queryset``: A ``QuerySet`` of objects for which the archive serves.
 342
 343     * ``date_field``: The name of the ``DateField`` or ``DateTimeField`` in
 344       the ``QuerySet``'s model that the date-based archive should use to
 345       determine the objects on the page.
 346
 347 **Optional arguments:**
 348
 349     * ``month_format``: A format string that regulates what format the
 350       ``month`` parameter uses. This should be in the syntax accepted by
 351       Python's ``time.strftime``. (See the `strftime docs`_.) It's set to
 352       ``"%b"`` by default, which is a three-letter month abbreviation. To
 353       change it to use numbers, use ``"%m"``.
 354
 355     * ``template_name``: The full name of a template to use in rendering the
 356       page. This lets you override the default template name (see below).
 357
 358     * ``template_loader``: The template loader to use when loading the
 359       template. By default, it's ``django.template.loader``.
 360
 361     * ``extra_context``: A dictionary of values to add to the template
 362       context. By default, this is an empty dictionary. If a value in the
 363       dictionary is callable, the generic view will call it
 364       just before rendering the template.
 365
 366     * ``allow_empty``: A boolean specifying whether to display the page if no
 367       objects are available. If this is ``False`` and no objects are available,
 368       the view will raise a 404 instead of displaying an empty page. By
 369       default, this is ``False``.
 370
 371     * ``context_processors``: A list of template-context processors to apply to
 372       the view's template. See the `RequestContext docs`_.
 373
 374     * ``template_object_name``:  Designates the name of the template variable
 375       to use in the template context. By default, this is ``'object'``. The
 376       view will append ``'_list'`` to the value of this parameter in
 377       determining the variable's name.
 378
 379     * ``mimetype``: The MIME type to use for the resulting document. Defaults
 380       to the value of the ``DEFAULT_CONTENT_TYPE`` setting.
 381
 382     * ``allow_future``: A boolean specifying whether to include "future"
 383       objects on this page, where "future" means objects in which the field
 384       specified in ``date_field`` is greater than the current date/time. By
 385       default, this is ``False``.
 386
 387 **Template name:**
 388
 389 If ``template_name`` isn't specified, this view will use the template
 390 ``<app_label>/<model_name>_archive_month.html`` by default.
 391
 392 **Template context:**
 393
 394 In addition to ``extra_context``, the template's context will be:
 395
 396     * ``month``: A ``datetime.date`` object representing the given month.
 397
 398     * ``next_month``: A ``datetime.date`` object representing the first day of
 399       the next month. If the next month is in the future, this will be
 400       ``None``.
 401
 402     * ``previous_month``: A ``datetime.date`` object representing the first day
 403       of the previous month. Unlike ``next_month``, this will never be
 404       ``None``.
 405
 406     * ``object_list``: A list of objects available for the given month. This
 407       variable's name depends on the ``template_object_name`` parameter, which
 408       is ``'object'`` by default. If ``template_object_name`` is ``'foo'``,
 409       this variable's name will be ``foo_list``.
 410
 411 .. _strftime docs: http://www.python.org/doc/current/lib/module-time.html#l2h-1941
 412
 413 ``django.views.generic.date_based.archive_week``
 414 ------------------------------------------------
 415
 416 **Description:**
 417
 418 A weekly archive page showing all objects in a given week. Objects with a date
 419 in the *future* are not displayed unless you set ``allow_future`` to ``True``.
 420
 421 **Required arguments:**
 422
 423     * ``year``: The four-digit year for which the archive serves (a string).
 424
 425     * ``week``: The week of the year for which the archive serves (a string).
 426       Weeks start with Sunday.
 427
 428     * ``queryset``: A ``QuerySet`` of objects for which the archive serves.
 429
 430     * ``date_field``: The name of the ``DateField`` or ``DateTimeField`` in
 431       the ``QuerySet``'s model that the date-based archive should use to
 432       determine the objects on the page.
 433
 434 **Optional arguments:**
 435
 436     * ``template_name``: The full name of a template to use in rendering the
 437       page. This lets you override the default template name (see below).
 438
 439     * ``template_loader``: The template loader to use when loading the
 440       template. By default, it's ``django.template.loader``.
 441
 442     * ``extra_context``: A dictionary of values to add to the template
 443       context. By default, this is an empty dictionary. If a value in the
 444       dictionary is callable, the generic view will call it
 445       just before rendering the template.
 446
 447     * ``allow_empty``: A boolean specifying whether to display the page if no
 448       objects are available. If this is ``False`` and no objects are available,
 449       the view will raise a 404 instead of displaying an empty page. By
 450       default, this is ``True``.
 451
 452     * ``context_processors``: A list of template-context processors to apply to
 453       the view's template. See the `RequestContext docs`_.
 454
 455     * ``template_object_name``:  Designates the name of the template variable
 456       to use in the template context. By default, this is ``'object'``. The
 457       view will append ``'_list'`` to the value of this parameter in
 458       determining the variable's name.
 459
 460     * ``mimetype``: The MIME type to use for the resulting document. Defaults
 461       to the value of the ``DEFAULT_CONTENT_TYPE`` setting.
 462
 463     * ``allow_future``: A boolean specifying whether to include "future"
 464       objects on this page, where "future" means objects in which the field
 465       specified in ``date_field`` is greater than the current date/time. By
 466       default, this is ``False``.
 467
 468 **Template name:**
 469
 470 If ``template_name`` isn't specified, this view will use the template
 471 ``<app_label>/<model_name>_archive_week.html`` by default.
 472
 473 **Template context:**
 474
 475 In addition to ``extra_context``, the template's context will be:
 476
 477     * ``week``: A ``datetime.date`` object representing the first day of the
 478       given week.
 479
 480     * ``object_list``: A list of objects available for the given week. This
 481       variable's name depends on the ``template_object_name`` parameter, which
 482       is ``'object'`` by default. If ``template_object_name`` is ``'foo'``,
 483       this variable's name will be ``foo_list``.
 484
 485 ``django.views.generic.date_based.archive_day``
 486 -----------------------------------------------
 487
 488 **Description:**
 489
 490 A day archive page showing all objects in a given day. Days in the future throw
 491 a 404 error, regardless of whether any objects exist for future days, unless
 492 you set ``allow_future`` to ``True``.
 493
 494 **Required arguments:**
 495
 496     * ``year``: The four-digit year for which the archive serves (a string).
 497
 498     * ``month``: The month for which the archive serves, formatted according to
 499       the ``month_format`` argument.
 500
 501     * ``day``: The day for which the archive serves, formatted according to the
 502       ``day_format`` argument.
 503
 504     * ``queryset``: A ``QuerySet`` of objects for which the archive serves.
 505
 506     * ``date_field``: The name of the ``DateField`` or ``DateTimeField`` in
 507       the ``QuerySet``'s model that the date-based archive should use to
 508       determine the objects on the page.
 509
 510 **Optional arguments:**
 511
 512     * ``month_format``: A format string that regulates what format the
 513       ``month`` parameter uses. This should be in the syntax accepted by
 514       Python's ``time.strftime``. (See the `strftime docs`_.) It's set to
 515       ``"%b"`` by default, which is a three-letter month abbreviation. To
 516       change it to use numbers, use ``"%m"``.
 517
 518     * ``day_format``: Like ``month_format``, but for the ``day`` parameter.
 519       It defaults to ``"%d"`` (day of the month as a decimal number, 01-31).
 520
 521     * ``template_name``: The full name of a template to use in rendering the
 522       page. This lets you override the default template name (see below).
 523
 524     * ``template_loader``: The template loader to use when loading the
 525       template. By default, it's ``django.template.loader``.
 526
 527     * ``extra_context``: A dictionary of values to add to the template
 528       context. By default, this is an empty dictionary. If a value in the
 529       dictionary is callable, the generic view will call it
 530       just before rendering the template.
 531
 532     * ``allow_empty``: A boolean specifying whether to display the page if no
 533       objects are available. If this is ``False`` and no objects are available,
 534       the view will raise a 404 instead of displaying an empty page. By
 535       default, this is ``False``.
 536
 537     * ``context_processors``: A list of template-context processors to apply to
 538       the view's template. See the `RequestContext docs`_.
 539
 540     * ``template_object_name``:  Designates the name of the template variable
 541       to use in the template context. By default, this is ``'object'``. The
 542       view will append ``'_list'`` to the value of this parameter in
 543       determining the variable's name.
 544
 545     * ``mimetype``: The MIME type to use for the resulting document. Defaults
 546       to the value of the ``DEFAULT_CONTENT_TYPE`` setting.
 547
 548     * ``allow_future``: A boolean specifying whether to include "future"
 549       objects on this page, where "future" means objects in which the field
 550       specified in ``date_field`` is greater than the current date/time. By
 551       default, this is ``False``.
 552
 553 **Template name:**
 554
 555 If ``template_name`` isn't specified, this view will use the template
 556 ``<app_label>/<model_name>_archive_day.html`` by default.
 557
 558 **Template context:**
 559
 560 In addition to ``extra_context``, the template's context will be:
 561
 562     * ``day``: A ``datetime.date`` object representing the given day.
 563
 564     * ``next_day``: A ``datetime.date`` object representing the next day. If
 565       the next day is in the future, this will be ``None``.
 566
 567     * ``previous_day``: A ``datetime.date`` object representing the given day.
 568       Unlike ``next_day``, this will never be ``None``.
 569
 570     * ``object_list``: A list of objects available for the given day. This
 571       variable's name depends on the ``template_object_name`` parameter, which
 572       is ``'object'`` by default. If ``template_object_name`` is ``'foo'``,
 573       this variable's name will be ``foo_list``.
 574
 575 ``django.views.generic.date_based.archive_today``
 576 -------------------------------------------------
 577
 578 **Description:**
 579
 580 A day archive page showing all objects for *today*. This is exactly the same as
 581 ``archive_day``, except the ``year``/``month``/``day`` arguments are not used,
 582 and today's date is used instead.
 583
 584 ``django.views.generic.date_based.object_detail``
 585 -------------------------------------------------
 586
 587 **Description:**
 588
 589 A page representing an individual object. If the object has a date value in the
 590 future, the view will throw a 404 error by default, unless you set
 591 ``allow_future`` to ``True``.
 592
 593 **Required arguments:**
 594
 595     * ``year``: The object's four-digit year (a string).
 596
 597     * ``month``: The object's month , formatted according to the
 598       ``month_format`` argument.
 599
 600     * ``day``: The object's day , formatted according to the ``day_format``
 601       argument.
 602
 603     * ``queryset``: A ``QuerySet`` that contains the object.
 604
 605     * ``date_field``: The name of the ``DateField`` or ``DateTimeField`` in
 606       the ``QuerySet``'s model that the generic view should use to look up the
 607       object according to ``year``, ``month`` and ``day``.
 608
 609     * Either ``object_id`` or (``slug`` *and* ``slug_field``) is required.
 610
 611       If you provide ``object_id``, it should be the value of the primary-key
 612       field for the object being displayed on this page.
 613
 614       Otherwise, ``slug`` should be the slug of the given object, and
 615       ``slug_field`` should be the name of the slug field in the ``QuerySet``'s
 616       model. By default, ``slug_field`` is ``'slug'``.
 617
 618 **Optional arguments:**
 619
 620     * ``month_format``: A format string that regulates what format the
 621       ``month`` parameter uses. This should be in the syntax accepted by
 622       Python's ``time.strftime``. (See the `strftime docs`_.) It's set to
 623       ``"%b"`` by default, which is a three-letter month abbreviation. To
 624       change it to use numbers, use ``"%m"``.
 625
 626     * ``day_format``: Like ``month_format``, but for the ``day`` parameter.
 627       It defaults to ``"%d"`` (day of the month as a decimal number, 01-31).
 628
 629     * ``template_name``: The full name of a template to use in rendering the
 630       page. This lets you override the default template name (see below).
 631
 632     * ``template_name_field``: The name of a field on the object whose value is
 633       the template name to use. This lets you store template names in the data.
 634       In other words, if your object has a field ``'the_template'`` that
 635       contains a string ``'foo.html'``, and you set ``template_name_field`` to
 636       ``'the_template'``, then the generic view for this object will use the
 637       template ``'foo.html'``.
 638
 639       It's a bit of a brain-bender, but it's useful in some cases.
 640
 641     * ``template_loader``: The template loader to use when loading the
 642       template. By default, it's ``django.template.loader``.
 643
 644     * ``extra_context``: A dictionary of values to add to the template
 645       context. By default, this is an empty dictionary. If a value in the
 646       dictionary is callable, the generic view will call it
 647       just before rendering the template.
 648
 649     * ``context_processors``: A list of template-context processors to apply to
 650       the view's template. See the `RequestContext docs`_.
 651
 652     * ``template_object_name``:  Designates the name of the template variable
 653       to use in the template context. By default, this is ``'object'``.
 654
 655     * ``mimetype``: The MIME type to use for the resulting document. Defaults
 656       to the value of the ``DEFAULT_CONTENT_TYPE`` setting.
 657
 658     * ``allow_future``: A boolean specifying whether to include "future"
 659       objects on this page, where "future" means objects in which the field
 660       specified in ``date_field`` is greater than the current date/time. By
 661       default, this is ``False``.
 662
 663 **Template name:**
 664
 665 If ``template_name`` isn't specified, this view will use the template
 666 ``<app_label>/<model_name>_detail.html`` by default.
 667
 668 **Template context:**
 669
 670 In addition to ``extra_context``, the template's context will be:
 671
 672     * ``object``: The object. This variable's name depends on the
 673       ``template_object_name`` parameter, which is ``'object'`` by default. If
 674       ``template_object_name`` is ``'foo'``, this variable's name will be
 675       ``foo``.
 676
 677 List/detail generic views
 678 =========================
 679
 680 The list-detail generic-view framework (in the
 681 ``django.views.generic.list_detail`` module) is similar to the date-based one,
 682 except the former simply has two views: a list of objects and an individual
 683 object page.
 684
 685 ``django.views.generic.list_detail.object_list``
 686 ------------------------------------------------
 687
 688 **Description:**
 689
 690 A page representing a list of objects.
 691
 692 **Required arguments:**
 693
 694     * ``queryset``: A ``QuerySet`` that represents the objects.
 695
 696 **Optional arguments:**
 697
 698     * ``paginate_by``: An integer specifying how many objects should be
 699       displayed per page. If this is given, the view will paginate objects with
 700       ``paginate_by`` objects per page. The view will expect either a ``page``
 701       query string parameter (via ``GET``) or a ``page`` variable specified in
 702       the URLconf. See `Notes on pagination`_ below.
 703
 704     * ``page``: The current page number, as an integer. This is 1-based.
 705       See `Notes on pagination`_ below.
 706
 707     * ``template_name``: The full name of a template to use in rendering the
 708       page. This lets you override the default template name (see below).
 709
 710     * ``template_loader``: The template loader to use when loading the
 711       template. By default, it's ``django.template.loader``.
 712
 713     * ``extra_context``: A dictionary of values to add to the template
 714       context. By default, this is an empty dictionary. If a value in the
 715       dictionary is callable, the generic view will call it
 716       just before rendering the template.
 717
 718     * ``allow_empty``: A boolean specifying whether to display the page if no
 719       objects are available. If this is ``False`` and no objects are available,
 720       the view will raise a 404 instead of displaying an empty page. By
 721       default, this is ``True``.
 722
 723     * ``context_processors``: A list of template-context processors to apply to
 724       the view's template. See the `RequestContext docs`_.
 725
 726     * ``template_object_name``:  Designates the name of the template variable
 727       to use in the template context. By default, this is ``'object'``. The
 728       view will append ``'_list'`` to the value of this parameter in
 729       determining the variable's name.
 730
 731     * ``mimetype``: The MIME type to use for the resulting document. Defaults
 732       to the value of the ``DEFAULT_CONTENT_TYPE`` setting.
 733
 734 **Template name:**
 735
 736 If ``template_name`` isn't specified, this view will use the template
 737 ``<app_label>/<model_name>_list.html`` by default.
 738
 739 **Template context:**
 740
 741 In addition to ``extra_context``, the template's context will be:
 742
 743     * ``object_list``: The list of objects. This variable's name depends on the
 744       ``template_object_name`` parameter, which is ``'object'`` by default. If
 745       ``template_object_name`` is ``'foo'``, this variable's name will be
 746       ``foo_list``.
 747
 748     * ``is_paginated``: A boolean representing whether the results are
 749       paginated. Specifically, this is set to ``False`` if the number of
 750       available objects is less than or equal to ``paginate_by``.
 751
 752 If the results are paginated, the context will contain these extra variables:
 753
 754     * **New in Django development version:** ``paginator``: An instance of
 755       ``django.core.paginator.Paginator``.
 756
 757     * **New in Django development version:** ``page_obj``: An instance of
 758       ``django.core.paginator.Page``.
 759
 760 In older versions of Django, before ``paginator`` and ``page_obj`` were added
 761 to this template's context, the template included several other variables
 762 related to pagination. Note that you should *NOT* use these variables anymore;
 763 use ``paginator`` and ``page_obj`` instead, because they let you do everything
 764 these old variables let you do (and more!). But for legacy installations,
 765 here's a list of those old template variables:
 766
 767     * ``results_per_page``: The number of objects per page. (Same as the
 768       ``paginate_by`` parameter.)
 769
 770     * ``has_next``: A boolean representing whether there's a next page.
 771
 772     * ``has_previous``: A boolean representing whether there's a previous page.
 773
 774     * ``page``: The current page number, as an integer. This is 1-based.
 775
 776     * ``next``: The next page number, as an integer. If there's no next page,
 777       this will still be an integer representing the theoretical next-page
 778       number. This is 1-based.
 779
 780     * ``previous``: The previous page number, as an integer. This is 1-based.
 781
 782     * ``last_on_page``: The number of the
 783       last result on the current page. This is 1-based.
 784
 785     * ``first_on_page``: The number of the
 786       first result on the current page. This is 1-based.
 787
 788     * ``pages``: The total number of pages, as an integer.
 789
 790     * ``hits``: The total number of objects across *all* pages, not just this
 791       page.
 792
 793     * ``page_range``: A list of the page numbers that are available. This is
 794       1-based.
 795
 796 Notes on pagination
 797 ~~~~~~~~~~~~~~~~~~~
 798
 799 If ``paginate_by`` is specified, Django will paginate the results. You can
 800 specify the page number in the URL in one of two ways:
 801
 802     * Use the ``page`` parameter in the URLconf. For example, this is what
 803       your URLconf might look like::
 804
 805         (r'^objects/page(?P<page>[0-9]+)/$', 'object_list', dict(info_dict))
 806
 807     * Pass the page number via the ``page`` query-string parameter. For
 808       example, a URL would look like this::
 809
 810         /objects/?page=3
 811
 812     * To loop over all the available page numbers, use the ``page_range``
 813       variable. You can iterate over the list provided by ``page_range``
 814       to create a link to every page of results.
 815
 816 These values and lists are 1-based, not 0-based, so the first page would be
 817 represented as page ``1``.
 818
 819 An example of the use of pagination can be found in the `object pagination`_
 820 example model.
 821
 822 .. _`object pagination`: ../models/pagination/
 823
 824 **New in Django development version:**
 825
 826 As a special case, you are also permitted to use
 827 ``last`` as a value for ``page``::
 828
 829     /objects/?page=last
 830
 831 This allows you to access the final page of results without first having to
 832 determine how many pages there are.
 833
 834 Note that ``page`` *must* be either a valid page number or the value ``last``;
 835 any other value for ``page`` will result in a 404 error.
 836
 837 ``django.views.generic.list_detail.object_detail``
 838 --------------------------------------------------
 839
 840 A page representing an individual object.
 841
 842 **Description:**
 843
 844 A page representing an individual object.
 845
 846 **Required arguments:**
 847
 848     * ``queryset``: A ``QuerySet`` that contains the object.
 849
 850     * Either ``object_id`` or (``slug`` *and* ``slug_field``) is required.
 851
 852       If you provide ``object_id``, it should be the value of the primary-key
 853       field for the object being displayed on this page.
 854
 855       Otherwise, ``slug`` should be the slug of the given object, and
 856       ``slug_field`` should be the name of the slug field in the ``QuerySet``'s
 857       model. By default, ``slug_field`` is ``'slug'``.
 858
 859 **Optional arguments:**
 860
 861     * ``template_name``: The full name of a template to use in rendering the
 862       page. This lets you override the default template name (see below).
 863
 864     * ``template_name_field``: The name of a field on the object whose value is
 865       the template name to use. This lets you store template names in the data.
 866       In other words, if your object has a field ``'the_template'`` that
 867       contains a string ``'foo.html'``, and you set ``template_name_field`` to
 868       ``'the_template'``, then the generic view for this object will use the
 869       template ``'foo.html'``.
 870
 871       It's a bit of a brain-bender, but it's useful in some cases.
 872
 873     * ``template_loader``: The template loader to use when loading the
 874       template. By default, it's ``django.template.loader``.
 875
 876     * ``extra_context``: A dictionary of values to add to the template
 877       context. By default, this is an empty dictionary. If a value in the
 878       dictionary is callable, the generic view will call it
 879       just before rendering the template.
 880
 881     * ``context_processors``: A list of template-context processors to apply to
 882       the view's template. See the `RequestContext docs`_.
 883
 884     * ``template_object_name``:  Designates the name of the template variable
 885       to use in the template context. By default, this is ``'object'``.
 886
 887     * ``mimetype``: The MIME type to use for the resulting document. Defaults
 888       to the value of the ``DEFAULT_CONTENT_TYPE`` setting.
 889
 890 **Template name:**
 891
 892 If ``template_name`` isn't specified, this view will use the template
 893 ``<app_label>/<model_name>_detail.html`` by default.
 894
 895 **Template context:**
 896
 897 In addition to ``extra_context``, the template's context will be:
 898
 899     * ``object``: The object. This variable's name depends on the
 900       ``template_object_name`` parameter, which is ``'object'`` by default. If
 901       ``template_object_name`` is ``'foo'``, this variable's name will be
 902       ``foo``.
 903
 904 Create/update/delete generic views
 905 ==================================
 906
 907 The ``django.views.generic.create_update`` module contains a set of functions
 908 for creating, editing and deleting objects.
 909
 910 ``django.views.generic.create_update.create_object``
 911 ----------------------------------------------------
 912
 913 **Description:**
 914
 915 A page that displays a form for creating an object, redisplaying the form with
 916 validation errors (if there are any) and saving the object. This uses the
 917 automatic manipulators that come with Django models.
 918
 919 **Required arguments:**
 920
 921     * ``model``: The Django model class of the object that the form will
 922       create.
 923
 924 **Optional arguments:**
 925
 926     * ``post_save_redirect``: A URL to which the view will redirect after
 927       saving the object. By default, it's ``object.get_absolute_url()``.
 928
 929       ``post_save_redirect`` may contain dictionary string formatting, which
 930       will be interpolated against the object's field attributes. For example,
 931       you could use ``post_save_redirect="/polls/%(slug)s/"``.
 932
 933     * ``login_required``: A boolean that designates whether a user must be
 934       logged in, in order to see the page and save changes. This hooks into the
 935       Django `authentication system`_. By default, this is ``False``.
 936
 937       If this is ``True``, and a non-logged-in user attempts to visit this page
 938       or save the form, Django will redirect the request to ``/accounts/login/``.
 939
 940     * ``template_name``: The full name of a template to use in rendering the
 941       page. This lets you override the default template name (see below).
 942
 943     * ``template_loader``: The template loader to use when loading the
 944       template. By default, it's ``django.template.loader``.
 945
 946     * ``extra_context``: A dictionary of values to add to the template
 947       context. By default, this is an empty dictionary. If a value in the
 948       dictionary is callable, the generic view will call it
 949       just before rendering the template.
 950
 951     * ``context_processors``: A list of template-context processors to apply to
 952       the view's template. See the `RequestContext docs`_.
 953
 954 **Template name:**
 955
 956 If ``template_name`` isn't specified, this view will use the template
 957 ``<app_label>/<model_name>_form.html`` by default.
 958
 959 **Template context:**
 960
 961 In addition to ``extra_context``, the template's context will be:
 962
 963     * ``form``: A ``django.oldforms.FormWrapper`` instance representing the form
 964       for editing the object. This lets you refer to form fields easily in the
 965       template system.
 966
 967       For example, if ``model`` has two fields, ``name`` and ``address``::
 968
 969           <form action="" method="post">
 970           <p><label for="id_name">Name:</label> {{ form.name }}</p>
 971           <p><label for="id_address">Address:</label> {{ form.address }}</p>
 972           </form>
 973
 974       See the `manipulator and formfield documentation`_ for more information
 975       about using ``FormWrapper`` objects in templates.
 976
 977 .. _authentication system: ../authentication/
 978 .. _manipulator and formfield documentation: ../forms/
 979
 980 ``django.views.generic.create_update.update_object``
 981 ----------------------------------------------------
 982
 983 **Description:**
 984
 985 A page that displays a form for editing an existing object, redisplaying the
 986 form with validation errors (if there are any) and saving changes to the
 987 object. This uses the automatic manipulators that come with Django models.
 988
 989 **Required arguments:**
 990
 991     * ``model``: The Django model class of the object that the form will
 992       create.
 993
 994     * Either ``object_id`` or (``slug`` *and* ``slug_field``) is required.
 995
 996       If you provide ``object_id``, it should be the value of the primary-key
 997       field for the object being displayed on this page.
 998
 999       Otherwise, ``slug`` should be the slug of the given object, and
1000       ``slug_field`` should be the name of the slug field in the ``QuerySet``'s
1001       model. By default, ``slug_field`` is ``'slug'``.
1002
1003 **Optional arguments:**
1004
1005     * ``post_save_redirect``: A URL to which the view will redirect after
1006       saving the object. By default, it's ``object.get_absolute_url()``.
1007
1008       ``post_save_redirect`` may contain dictionary string formatting, which
1009       will be interpolated against the object's field attributes. For example,
1010       you could use ``post_save_redirect="/polls/%(slug)s/"``.
1011
1012     * ``login_required``: A boolean that designates whether a user must be
1013       logged in, in order to see the page and save changes. This hooks into the
1014       Django `authentication system`_. By default, this is ``False``.
1015
1016       If this is ``True``, and a non-logged-in user attempts to visit this page
1017       or save the form, Django will redirect the request to ``/accounts/login/``.
1018
1019     * ``template_name``: The full name of a template to use in rendering the
1020       page. This lets you override the default template name (see below).
1021
1022     * ``template_loader``: The template loader to use when loading the
1023       template. By default, it's ``django.template.loader``.
1024
1025     * ``extra_context``: A dictionary of values to add to the template
1026       context. By default, this is an empty dictionary. If a value in the
1027       dictionary is callable, the generic view will call it
1028       just before rendering the template.
1029
1030     * ``context_processors``: A list of template-context processors to apply to
1031       the view's template. See the `RequestContext docs`_.
1032
1033     * ``template_object_name``:  Designates the name of the template variable
1034       to use in the template context. By default, this is ``'object'``.
1035
1036 **Template name:**
1037
1038 If ``template_name`` isn't specified, this view will use the template
1039 ``<app_label>/<model_name>_form.html`` by default.
1040
1041 **Template context:**
1042
1043 In addition to ``extra_context``, the template's context will be:
1044
1045     * ``form``: A ``django.oldforms.FormWrapper`` instance representing the form
1046       for editing the object. This lets you refer to form fields easily in the
1047       template system.
1048
1049       For example, if ``model`` has two fields, ``name`` and ``address``::
1050
1051           <form action="" method="post">
1052           <p><label for="id_name">Name:</label> {{ form.name }}</p>
1053           <p><label for="id_address">Address:</label> {{ form.address }}</p>
1054           </form>
1055
1056       See the `manipulator and formfield documentation`_ for more information
1057       about using ``FormWrapper`` objects in templates.
1058
1059     * ``object``: The original object being edited. This variable's name
1060       depends on the ``template_object_name`` parameter, which is ``'object'``
1061       by default. If ``template_object_name`` is ``'foo'``, this variable's
1062       name will be ``foo``.
1063
1064 ``django.views.generic.create_update.delete_object``
1065 ----------------------------------------------------
1066
1067 **Description:**
1068
1069 A view that displays a confirmation page and deletes an existing object. The
1070 given object will only be deleted if the request method is ``POST``. If this
1071 view is fetched via ``GET``, it will display a confirmation page that should
1072 contain a form that POSTs to the same URL.
1073
1074 **Required arguments:**
1075
1076     * ``model``: The Django model class of the object that the form will
1077       create.
1078
1079     * Either ``object_id`` or (``slug`` *and* ``slug_field``) is required.
1080
1081       If you provide ``object_id``, it should be the value of the primary-key
1082       field for the object being displayed on this page.
1083
1084       Otherwise, ``slug`` should be the slug of the given object, and
1085       ``slug_field`` should be the name of the slug field in the ``QuerySet``'s
1086       model. By default, ``slug_field`` is ``'slug'``.
1087
1088     * ``post_delete_redirect``: A URL to which the view will redirect after
1089       deleting the object.
1090
1091 **Optional arguments:**
1092
1093     * ``login_required``: A boolean that designates whether a user must be
1094       logged in, in order to see the page and save changes. This hooks into the
1095       Django `authentication system`_. By default, this is ``False``.
1096
1097       If this is ``True``, and a non-logged-in user attempts to visit this page
1098       or save the form, Django will redirect the request to ``/accounts/login/``.
1099
1100     * ``template_name``: The full name of a template to use in rendering the
1101       page. This lets you override the default template name (see below).
1102
1103     * ``template_loader``: The template loader to use when loading the
1104       template. By default, it's ``django.template.loader``.
1105
1106     * ``extra_context``: A dictionary of values to add to the template
1107       context. By default, this is an empty dictionary. If a value in the
1108       dictionary is callable, the generic view will call it
1109       just before rendering the template.
1110
1111     * ``context_processors``: A list of template-context processors to apply to
1112       the view's template. See the `RequestContext docs`_.
1113
1114     * ``template_object_name``:  Designates the name of the template variable
1115       to use in the template context. By default, this is ``'object'``.
1116
1117 **Template name:**
1118
1119 If ``template_name`` isn't specified, this view will use the template
1120 ``<app_label>/<model_name>_confirm_delete.html`` by default.
1121
1122 **Template context:**
1123
1124 In addition to ``extra_context``, the template's context will be:
1125
1126     * ``object``: The original object that's about to be deleted. This
1127       variable's name depends on the ``template_object_name`` parameter, which
1128       is ``'object'`` by default. If ``template_object_name`` is ``'foo'``,
1129       this variable's name will be ``foo``.