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     * ``results_per_page``: The number of objects per page. (Same as the
 755       ``paginate_by`` parameter.)
 756
 757     * ``has_next``: A boolean representing whether there's a next page.
 758
 759     * ``has_previous``: A boolean representing whether there's a previous page.
 760
 761     * ``page``: The current page number, as an integer. This is 1-based.
 762
 763     * ``next``: The next page number, as an integer. If there's no next page,
 764       this will still be an integer representing the theoretical next-page
 765       number. This is 1-based.
 766
 767     * ``previous``: The previous page number, as an integer. This is 1-based.
 768
 769     * ``last_on_page``: The number of the
 770       last result on the current page. This is 1-based.
 771
 772     * ``first_on_page``: The number of the
 773       first result on the current page. This is 1-based.
 774
 775     * ``pages``: The total number of pages, as an integer.
 776
 777     * ``hits``: The total number of objects across *all* pages, not just this
 778       page.
 779
 780     * **New in Django development version:** ``page_range``: A list of the
 781       page numbers that are available. This is 1-based.
 782
 783 Notes on pagination
 784 ~~~~~~~~~~~~~~~~~~~
 785
 786 If ``paginate_by`` is specified, Django will paginate the results. You can
 787 specify the page number in the URL in one of two ways:
 788
 789     * Use the ``page`` parameter in the URLconf. For example, this is what
 790       your URLconf might look like::
 791
 792         (r'^objects/page(?P<page>[0-9]+)/$', 'object_list', dict(info_dict))
 793
 794     * Pass the page number via the ``page`` query-string parameter. For
 795       example, a URL would look like this::
 796
 797         /objects/?page=3
 798
 799     * To loop over all the available page numbers, use the ``page_range``
 800       variable. You can iterate over the list provided by ``page_range``
 801       to create a link to every page of results.
 802
 803 These values and lists are 1-based, not 0-based, so the first page would be
 804 represented as page ``1``.
 805
 806 An example of the use of pagination can be found in the `object pagination`_
 807 example model.
 808
 809 .. _`object pagination`: ../models/pagination/
 810
 811 **New in Django development version:**
 812
 813 As a special case, you are also permitted to use
 814 ``last`` as a value for ``page``::
 815
 816     /objects/?page=last
 817
 818 This allows you to access the final page of results without first having to
 819 determine how many pages there are.
 820
 821 Note that ``page`` *must* be either a valid page number or the value ``last``;
 822 any other value for ``page`` will result in a 404 error.
 823
 824 ``django.views.generic.list_detail.object_detail``
 825 --------------------------------------------------
 826
 827 A page representing an individual object.
 828
 829 **Description:**
 830
 831 A page representing an individual object.
 832
 833 **Required arguments:**
 834
 835     * ``queryset``: A ``QuerySet`` that contains the object.
 836
 837     * Either ``object_id`` or (``slug`` *and* ``slug_field``) is required.
 838
 839       If you provide ``object_id``, it should be the value of the primary-key
 840       field for the object being displayed on this page.
 841
 842       Otherwise, ``slug`` should be the slug of the given object, and
 843       ``slug_field`` should be the name of the slug field in the ``QuerySet``'s
 844       model. By default, ``slug_field`` is ``'slug'``.
 845
 846 **Optional arguments:**
 847
 848     * ``template_name``: The full name of a template to use in rendering the
 849       page. This lets you override the default template name (see below).
 850
 851     * ``template_name_field``: The name of a field on the object whose value is
 852       the template name to use. This lets you store template names in the data.
 853       In other words, if your object has a field ``'the_template'`` that
 854       contains a string ``'foo.html'``, and you set ``template_name_field`` to
 855       ``'the_template'``, then the generic view for this object will use the
 856       template ``'foo.html'``.
 857
 858       It's a bit of a brain-bender, but it's useful in some cases.
 859
 860     * ``template_loader``: The template loader to use when loading the
 861       template. By default, it's ``django.template.loader``.
 862
 863     * ``extra_context``: A dictionary of values to add to the template
 864       context. By default, this is an empty dictionary. If a value in the
 865       dictionary is callable, the generic view will call it
 866       just before rendering the template.
 867
 868     * ``context_processors``: A list of template-context processors to apply to
 869       the view's template. See the `RequestContext docs`_.
 870
 871     * ``template_object_name``:  Designates the name of the template variable
 872       to use in the template context. By default, this is ``'object'``.
 873
 874     * ``mimetype``: The MIME type to use for the resulting document. Defaults
 875       to the value of the ``DEFAULT_CONTENT_TYPE`` setting.
 876
 877 **Template name:**
 878
 879 If ``template_name`` isn't specified, this view will use the template
 880 ``<app_label>/<model_name>_detail.html`` by default.
 881
 882 **Template context:**
 883
 884 In addition to ``extra_context``, the template's context will be:
 885
 886     * ``object``: The object. This variable's name depends on the
 887       ``template_object_name`` parameter, which is ``'object'`` by default. If
 888       ``template_object_name`` is ``'foo'``, this variable's name will be
 889       ``foo``.
 890
 891 Create/update/delete generic views
 892 ==================================
 893
 894 The ``django.views.generic.create_update`` module contains a set of functions
 895 for creating, editing and deleting objects.
 896
 897 ``django.views.generic.create_update.create_object``
 898 ----------------------------------------------------
 899
 900 **Description:**
 901
 902 A page that displays a form for creating an object, redisplaying the form with
 903 validation errors (if there are any) and saving the object. This uses the
 904 automatic manipulators that come with Django models.
 905
 906 **Required arguments:**
 907
 908     * ``model``: The Django model class of the object that the form will
 909       create.
 910
 911 **Optional arguments:**
 912
 913     * ``post_save_redirect``: A URL to which the view will redirect after
 914       saving the object. By default, it's ``object.get_absolute_url()``.
 915
 916       ``post_save_redirect`` may contain dictionary string formatting, which
 917       will be interpolated against the object's field attributes. For example,
 918       you could use ``post_save_redirect="/polls/%(slug)s/"``.
 919
 920     * ``login_required``: A boolean that designates whether a user must be
 921       logged in, in order to see the page and save changes. This hooks into the
 922       Django `authentication system`_. By default, this is ``False``.
 923
 924       If this is ``True``, and a non-logged-in user attempts to visit this page
 925       or save the form, Django will redirect the request to ``/accounts/login/``.
 926
 927     * ``template_name``: The full name of a template to use in rendering the
 928       page. This lets you override the default template name (see below).
 929
 930     * ``template_loader``: The template loader to use when loading the
 931       template. By default, it's ``django.template.loader``.
 932
 933     * ``extra_context``: A dictionary of values to add to the template
 934       context. By default, this is an empty dictionary. If a value in the
 935       dictionary is callable, the generic view will call it
 936       just before rendering the template.
 937
 938     * ``context_processors``: A list of template-context processors to apply to
 939       the view's template. See the `RequestContext docs`_.
 940
 941 **Template name:**
 942
 943 If ``template_name`` isn't specified, this view will use the template
 944 ``<app_label>/<model_name>_form.html`` by default.
 945
 946 **Template context:**
 947
 948 In addition to ``extra_context``, the template's context will be:
 949
 950     * ``form``: A ``django.oldforms.FormWrapper`` instance representing the form
 951       for editing the object. This lets you refer to form fields easily in the
 952       template system.
 953
 954       For example, if ``model`` has two fields, ``name`` and ``address``::
 955
 956           <form action="" method="post">
 957           <p><label for="id_name">Name:</label> {{ form.name }}</p>
 958           <p><label for="id_address">Address:</label> {{ form.address }}</p>
 959           </form>
 960
 961       See the `manipulator and formfield documentation`_ for more information
 962       about using ``FormWrapper`` objects in templates.
 963
 964 .. _authentication system: ../authentication/
 965 .. _manipulator and formfield documentation: ../forms/
 966
 967 ``django.views.generic.create_update.update_object``
 968 ----------------------------------------------------
 969
 970 **Description:**
 971
 972 A page that displays a form for editing an existing object, redisplaying the
 973 form with validation errors (if there are any) and saving changes to the
 974 object. This uses the automatic manipulators that come with Django models.
 975
 976 **Required arguments:**
 977
 978     * ``model``: The Django model class of the object that the form will
 979       create.
 980
 981     * Either ``object_id`` or (``slug`` *and* ``slug_field``) is required.
 982
 983       If you provide ``object_id``, it should be the value of the primary-key
 984       field for the object being displayed on this page.
 985
 986       Otherwise, ``slug`` should be the slug of the given object, and
 987       ``slug_field`` should be the name of the slug field in the ``QuerySet``'s
 988       model. By default, ``slug_field`` is ``'slug'``.
 989
 990 **Optional arguments:**
 991
 992     * ``post_save_redirect``: A URL to which the view will redirect after
 993       saving the object. By default, it's ``object.get_absolute_url()``.
 994
 995       ``post_save_redirect`` may contain dictionary string formatting, which
 996       will be interpolated against the object's field attributes. For example,
 997       you could use ``post_save_redirect="/polls/%(slug)s/"``.
 998
 999     * ``login_required``: A boolean that designates whether a user must be
1000       logged in, in order to see the page and save changes. This hooks into the
1001       Django `authentication system`_. By default, this is ``False``.
1002
1003       If this is ``True``, and a non-logged-in user attempts to visit this page
1004       or save the form, Django will redirect the request to ``/accounts/login/``.
1005
1006     * ``template_name``: The full name of a template to use in rendering the
1007       page. This lets you override the default template name (see below).
1008
1009     * ``template_loader``: The template loader to use when loading the
1010       template. By default, it's ``django.template.loader``.
1011
1012     * ``extra_context``: A dictionary of values to add to the template
1013       context. By default, this is an empty dictionary. If a value in the
1014       dictionary is callable, the generic view will call it
1015       just before rendering the template.
1016
1017     * ``context_processors``: A list of template-context processors to apply to
1018       the view's template. See the `RequestContext docs`_.
1019
1020     * ``template_object_name``:  Designates the name of the template variable
1021       to use in the template context. By default, this is ``'object'``.
1022
1023 **Template name:**
1024
1025 If ``template_name`` isn't specified, this view will use the template
1026 ``<app_label>/<model_name>_form.html`` by default.
1027
1028 **Template context:**
1029
1030 In addition to ``extra_context``, the template's context will be:
1031
1032     * ``form``: A ``django.oldforms.FormWrapper`` instance representing the form
1033       for editing the object. This lets you refer to form fields easily in the
1034       template system.
1035
1036       For example, if ``model`` has two fields, ``name`` and ``address``::
1037
1038           <form action="" method="post">
1039           <p><label for="id_name">Name:</label> {{ form.name }}</p>
1040           <p><label for="id_address">Address:</label> {{ form.address }}</p>
1041           </form>
1042
1043       See the `manipulator and formfield documentation`_ for more information
1044       about using ``FormWrapper`` objects in templates.
1045
1046     * ``object``: The original object being edited. This variable's name
1047       depends on the ``template_object_name`` parameter, which is ``'object'``
1048       by default. If ``template_object_name`` is ``'foo'``, this variable's
1049       name will be ``foo``.
1050
1051 ``django.views.generic.create_update.delete_object``
1052 ----------------------------------------------------
1053
1054 **Description:**
1055
1056 A view that displays a confirmation page and deletes an existing object. The
1057 given object will only be deleted if the request method is ``POST``. If this
1058 view is fetched via ``GET``, it will display a confirmation page that should
1059 contain a form that POSTs to the same URL.
1060
1061 **Required arguments:**
1062
1063     * ``model``: The Django model class of the object that the form will
1064       create.
1065
1066     * Either ``object_id`` or (``slug`` *and* ``slug_field``) is required.
1067
1068       If you provide ``object_id``, it should be the value of the primary-key
1069       field for the object being displayed on this page.
1070
1071       Otherwise, ``slug`` should be the slug of the given object, and
1072       ``slug_field`` should be the name of the slug field in the ``QuerySet``'s
1073       model. By default, ``slug_field`` is ``'slug'``.
1074
1075     * ``post_delete_redirect``: A URL to which the view will redirect after
1076       deleting the object.
1077
1078 **Optional arguments:**
1079
1080     * ``login_required``: A boolean that designates whether a user must be
1081       logged in, in order to see the page and save changes. This hooks into the
1082       Django `authentication system`_. By default, this is ``False``.
1083
1084       If this is ``True``, and a non-logged-in user attempts to visit this page
1085       or save the form, Django will redirect the request to ``/accounts/login/``.
1086
1087     * ``template_name``: The full name of a template to use in rendering the
1088       page. This lets you override the default template name (see below).
1089
1090     * ``template_loader``: The template loader to use when loading the
1091       template. By default, it's ``django.template.loader``.
1092
1093     * ``extra_context``: A dictionary of values to add to the template
1094       context. By default, this is an empty dictionary. If a value in the
1095       dictionary is callable, the generic view will call it
1096       just before rendering the template.
1097
1098     * ``context_processors``: A list of template-context processors to apply to
1099       the view's template. See the `RequestContext docs`_.
1100
1101     * ``template_object_name``:  Designates the name of the template variable
1102       to use in the template context. By default, this is ``'object'``.
1103
1104 **Template name:**
1105
1106 If ``template_name`` isn't specified, this view will use the template
1107 ``<app_label>/<model_name>_confirm_delete.html`` by default.
1108
1109 **Template context:**
1110
1111 In addition to ``extra_context``, the template's context will be:
1112
1113     * ``object``: The original object that's about to be deleted. This
1114       variable's name depends on the ``template_object_name`` parameter, which
1115       is ``'object'`` by default. If ``template_object_name`` is ``'foo'``,
1116       this variable's name will be ``foo``.