/docs/ref/generic-views.txt

   1=============
   2Generic views
   3=============
   4
   5
   6.. versionchanged:: 1.3
   7
   8.. note::
   9
  10    From Django 1.3, function-based generic views have been deprecated in favor
  11    of a class-based approach, described in the class-based views :doc:`topic
  12    guide </topics/class-based-views>` and :doc:`detailed reference
  13    </ref/class-based-views>`.
  14
  15Writing Web applications can be monotonous, because we repeat certain patterns
  16again and again. In Django, the most common of these patterns have been
  17abstracted into "generic views" that let you quickly provide common views of
  18an object without actually needing to write any Python code.
  19
  20A general introduction to generic views can be found in the :doc:`topic guide
  21</topics/generic-views>`.
  22
  23This reference contains details of Django's built-in generic views, along with
  24a list of all keyword arguments that a generic view expects. Remember that
  25arguments may either come from the URL pattern or from the ``extra_context``
  26additional-information dictionary.
  27
  28Most generic views require the ``queryset`` key, which is a ``QuerySet``
  29instance; see :doc:`/topics/db/queries` for more information about ``QuerySet``
  30objects.
  31
  32.. module:: django.views.generic.simple
  33
  34"Simple" generic views
  35======================
  36
  37The ``django.views.generic.simple`` module contains simple views to handle a
  38couple of common cases: rendering a template when no view logic is needed,
  39and issuing a redirect.
  40
  41``django.views.generic.simple.direct_to_template``
  42--------------------------------------------------
  43
  44**Description:**
  45
  46Renders a given template, passing it a ``{{ params }}`` template variable,
  47which is a dictionary of the parameters captured in the URL.
  48
  49**Required arguments:**
  50
  51    * ``template``: The full name of a template to use.
  52
  53**Optional arguments:**
  54
  55    * ``extra_context``: A dictionary of values to add to the template
  56      context. By default, this is an empty dictionary. If a value in the
  57      dictionary is callable, the generic view will call it
  58      just before rendering the template.
  59
  60    * ``mimetype``: The MIME type to use for the resulting document. Defaults
  61      to the value of the :setting:`DEFAULT_CONTENT_TYPE` setting.
  62
  63**Example:**
  64
  65Given the following URL patterns::
  66
  67    from django.views.generic.simple import direct_to_template
  68
  69    urlpatterns = patterns('',
  70        (r'^foo/$',             direct_to_template, {'template': 'foo_index.html'}),
  71        (r'^foo/(?P<id>\d+)/$', direct_to_template, {'template': 'foo_detail.html'}),
  72    )
  73
  74... a request to ``/foo/`` would render the template ``foo_index.html``, and a
  75request to ``/foo/15/`` would render the ``foo_detail.html`` with a context
  76variable ``{{ params.id }}`` that is set to ``15``.
  77
  78``django.views.generic.simple.redirect_to``
  79-------------------------------------------
  80
  81**Description:**
  82
  83Redirects to a given URL.
  84
  85The given URL may contain dictionary-style string formatting, which will be
  86interpolated against the parameters captured in the URL. Because keyword
  87interpolation is *always* done (even if no arguments are passed in), any ``"%"``
  88characters in the URL must be written as ``"%%"`` so that Python will convert
  89them to a single percent sign on output.
  90
  91If the given URL is ``None``, Django will return an ``HttpResponseGone`` (410).
  92
  93**Required arguments:**
  94
  95    * ``url``: The URL to redirect to, as a string. Or ``None`` to raise a 410
  96      (Gone) HTTP error.
  97
  98**Optional arguments:**
  99
 100    * ``permanent``: Whether the redirect should be permanent. The only
 101      difference here is the HTTP status code returned. If ``True``, then the
 102      redirect will use status code 301. If ``False``, then the redirect will
 103      use status code 302. By default, ``permanent`` is ``True``.
 104
 105    * ``query_string``: Whether to pass along the GET query string to
 106      the new location. If ``True``, then the query string is appended
 107      to the URL. If ``False``, then the query string is discarded. By
 108      default, ``query_string`` is ``False``.
 109
 110.. versionadded:: 1.3
 111    The ``query_string`` keyword argument is new in Django 1.3.
 112
 113**Example:**
 114
 115This example issues a permanent redirect (HTTP status code 301) from
 116``/foo/<id>/`` to ``/bar/<id>/``::
 117
 118    from django.views.generic.simple import redirect_to
 119
 120    urlpatterns = patterns('',
 121        ('^foo/(?P<id>\d+)/$', redirect_to, {'url': '/bar/%(id)s/'}),
 122    )
 123
 124This example issues a non-permanent redirect (HTTP status code 302) from
 125``/foo/<id>/`` to ``/bar/<id>/``::
 126
 127    from django.views.generic.simple import redirect_to
 128
 129    urlpatterns = patterns('',
 130        ('^foo/(?P<id>\d+)/$', redirect_to, {'url': '/bar/%(id)s/', 'permanent': False}),
 131    )
 132
 133This example returns a 410 HTTP error for requests to ``/bar/``::
 134
 135    from django.views.generic.simple import redirect_to
 136
 137    urlpatterns = patterns('',
 138        ('^bar/$', redirect_to, {'url': None}),
 139    )
 140
 141This example shows how ``"%"`` characters must be written in the URL in order
 142to avoid confusion with Python's string formatting markers. If the redirect
 143string is written as ``"%7Ejacob/"`` (with only a single ``%``), an exception would be raised::
 144
 145    from django.views.generic.simple import redirect_to
 146
 147    urlpatterns = patterns('',
 148        ('^bar/$', redirect_to, {'url': '%%7Ejacob.'}),
 149    )
 150
 151.. module:: django.views.generic.date_based
 152
 153Date-based generic views
 154========================
 155
 156Date-based generic views (in the module ``django.views.generic.date_based``)
 157are views for displaying drilldown pages for date-based data.
 158
 159``django.views.generic.date_based.archive_index``
 160-------------------------------------------------
 161
 162**Description:**
 163
 164A top-level index page showing the "latest" objects, by date. Objects with
 165a date in the *future* are not included unless you set ``allow_future`` to
 166``True``.
 167
 168**Required arguments:**
 169
 170    * ``queryset``: A ``QuerySet`` of objects for which the archive serves.
 171
 172    * ``date_field``: The name of the ``DateField`` or ``DateTimeField`` in
 173      the ``QuerySet``'s model that the date-based archive should use to
 174      determine the objects on the page.
 175
 176**Optional arguments:**
 177
 178    * ``num_latest``: The number of latest objects to send to the template
 179      context. By default, it's 15.
 180
 181    * ``template_name``: The full name of a template to use in rendering the
 182      page. This lets you override the default template name (see below).
 183
 184    * ``template_loader``: The template loader to use when loading the
 185      template. By default, it's ``django.template.loader``.
 186
 187    * ``extra_context``: A dictionary of values to add to the template
 188      context. By default, this is an empty dictionary. If a value in the
 189      dictionary is callable, the generic view will call it
 190      just before rendering the template.
 191
 192    * ``allow_empty``: A boolean specifying whether to display the page if no
 193      objects are available. If this is ``False`` and no objects are available,
 194      the view will raise a 404 instead of displaying an empty page. By
 195      default, this is ``True``.
 196
 197    * ``context_processors``: A list of template-context processors to apply to
 198      the view's template.
 199
 200    * ``mimetype``: The MIME type to use for the resulting document. Defaults
 201      to the value of the :setting:`DEFAULT_CONTENT_TYPE` setting.
 202
 203    * ``allow_future``: A boolean specifying whether to include "future"
 204      objects on this page, where "future" means objects in which the field
 205      specified in ``date_field`` is greater than the current date/time. By
 206      default, this is ``False``.
 207
 208    * ``template_object_name``: Designates the name of the template variable
 209      to use in the template context. By default, this is ``'latest'``.
 210
 211**Template name:**
 212
 213If ``template_name`` isn't specified, this view will use the template
 214``<app_label>/<model_name>_archive.html`` by default, where:
 215
 216    * ``<model_name>`` is your model's name in all lowercase. For a model
 217      ``StaffMember``, that'd be ``staffmember``.
 218
 219    * ``<app_label>`` is the right-most part of the full Python path to
 220      your model's app. For example, if your model lives in
 221      ``apps/blog/models.py``, that'd be ``blog``.
 222
 223**Template context:**
 224
 225In addition to ``extra_context``, the template's context will be:
 226
 227    * ``date_list``: A ``DateQuerySet`` object containing all years that have
 228      have objects available according to ``queryset``, represented as
 229      ``datetime.datetime`` objects. These are ordered in reverse. This is
 230      equivalent to ``queryset.dates(date_field, 'year')[::-1]``.
 231
 232    * ``latest``: The ``num_latest`` objects in the system, ordered descending
 233      by ``date_field``. For example, if ``num_latest`` is ``10``, then
 234      ``latest`` will be a list of the latest 10 objects in ``queryset``.
 235
 236      This variable's name depends on the ``template_object_name`` parameter,
 237      which is ``'latest'`` by default. If ``template_object_name`` is
 238      ``'foo'``, this variable's name will be ``foo``.
 239
 240``django.views.generic.date_based.archive_year``
 241------------------------------------------------
 242
 243**Description:**
 244
 245A yearly archive page showing all available months in a given year. Objects
 246with a date in the *future* are not displayed unless you set ``allow_future``
 247to ``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.
 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 :setting:`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
 302If ``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
 307In addition to ``extra_context``, the template's context will be:
 308
 309    * ``date_list``: A ``DateQuerySet`` object containing all months that have
 310      have objects available according to ``queryset``, represented as
 311      ``datetime.datetime`` objects, 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
 330A monthly archive page showing all objects in a given month. Objects with a
 331date 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.
 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 :setting:`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
 389If ``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.. versionadded:: 1.2
 395   The inclusion of ``date_list`` in the template's context is new.
 396
 397In addition to ``extra_context``, the template's context will be:
 398
 399    * ``date_list``: A ``DateQuerySet`` object containing all days that have
 400      have objects available in the given month, according to ``queryset``,
 401      represented as ``datetime.datetime`` objects, in ascending order.
 402
 403    * ``month``: A ``datetime.date`` object representing the given month.
 404
 405    * ``next_month``: A ``datetime.date`` object representing the first day of
 406      the next month. If the next month is in the future, this will be
 407      ``None``.
 408
 409    * ``previous_month``: A ``datetime.date`` object representing the first day
 410      of the previous month. Unlike ``next_month``, this will never be
 411      ``None``.
 412
 413    * ``object_list``: A list of objects available for the given month. This
 414      variable's name depends on the ``template_object_name`` parameter, which
 415      is ``'object'`` by default. If ``template_object_name`` is ``'foo'``,
 416      this variable's name will be ``foo_list``.
 417
 418.. _strftime docs: http://docs.python.org/library/time.html#time.strftime
 419
 420``django.views.generic.date_based.archive_week``
 421------------------------------------------------
 422
 423**Description:**
 424
 425A weekly archive page showing all objects in a given week. Objects with a date
 426in the *future* are not displayed unless you set ``allow_future`` to ``True``.
 427
 428**Required arguments:**
 429
 430    * ``year``: The four-digit year for which the archive serves (a string).
 431
 432    * ``week``: The week of the year for which the archive serves (a string).
 433      Weeks start with Sunday.
 434
 435    * ``queryset``: A ``QuerySet`` of objects for which the archive serves.
 436
 437    * ``date_field``: The name of the ``DateField`` or ``DateTimeField`` in
 438      the ``QuerySet``'s model that the date-based archive should use to
 439      determine the objects on the page.
 440
 441**Optional arguments:**
 442
 443    * ``template_name``: The full name of a template to use in rendering the
 444      page. This lets you override the default template name (see below).
 445
 446    * ``template_loader``: The template loader to use when loading the
 447      template. By default, it's ``django.template.loader``.
 448
 449    * ``extra_context``: A dictionary of values to add to the template
 450      context. By default, this is an empty dictionary. If a value in the
 451      dictionary is callable, the generic view will call it
 452      just before rendering the template.
 453
 454    * ``allow_empty``: A boolean specifying whether to display the page if no
 455      objects are available. If this is ``False`` and no objects are available,
 456      the view will raise a 404 instead of displaying an empty page. By
 457      default, this is ``True``.
 458
 459    * ``context_processors``: A list of template-context processors to apply to
 460      the view's template.
 461
 462    * ``template_object_name``:  Designates the name of the template variable
 463      to use in the template context. By default, this is ``'object'``. The
 464      view will append ``'_list'`` to the value of this parameter in
 465      determining the variable's name.
 466
 467    * ``mimetype``: The MIME type to use for the resulting document. Defaults
 468      to the value of the :setting:`DEFAULT_CONTENT_TYPE` setting.
 469
 470    * ``allow_future``: A boolean specifying whether to include "future"
 471      objects on this page, where "future" means objects in which the field
 472      specified in ``date_field`` is greater than the current date/time. By
 473      default, this is ``False``.
 474
 475**Template name:**
 476
 477If ``template_name`` isn't specified, this view will use the template
 478``<app_label>/<model_name>_archive_week.html`` by default.
 479
 480**Template context:**
 481
 482In addition to ``extra_context``, the template's context will be:
 483
 484    * ``week``: A ``datetime.date`` object representing the first day of the
 485      given week.
 486
 487    * ``object_list``: A list of objects available for the given week. This
 488      variable's name depends on the ``template_object_name`` parameter, which
 489      is ``'object'`` by default. If ``template_object_name`` is ``'foo'``,
 490      this variable's name will be ``foo_list``.
 491
 492``django.views.generic.date_based.archive_day``
 493-----------------------------------------------
 494
 495**Description:**
 496
 497A day archive page showing all objects in a given day. Days in the future throw
 498a 404 error, regardless of whether any objects exist for future days, unless
 499you set ``allow_future`` to ``True``.
 500
 501**Required arguments:**
 502
 503    * ``year``: The four-digit year for which the archive serves (a string).
 504
 505    * ``month``: The month for which the archive serves, formatted according to
 506      the ``month_format`` argument.
 507
 508    * ``day``: The day for which the archive serves, formatted according to the
 509      ``day_format`` argument.
 510
 511    * ``queryset``: A ``QuerySet`` of objects for which the archive serves.
 512
 513    * ``date_field``: The name of the ``DateField`` or ``DateTimeField`` in
 514      the ``QuerySet``'s model that the date-based archive should use to
 515      determine the objects on the page.
 516
 517**Optional arguments:**
 518
 519    * ``month_format``: A format string that regulates what format the
 520      ``month`` parameter uses. This should be in the syntax accepted by
 521      Python's ``time.strftime``. (See the `strftime docs`_.) It's set to
 522      ``"%b"`` by default, which is a three-letter month abbreviation. To
 523      change it to use numbers, use ``"%m"``.
 524
 525    * ``day_format``: Like ``month_format``, but for the ``day`` parameter.
 526      It defaults to ``"%d"`` (day of the month as a decimal number, 01-31).
 527
 528    * ``template_name``: The full name of a template to use in rendering the
 529      page. This lets you override the default template name (see below).
 530
 531    * ``template_loader``: The template loader to use when loading the
 532      template. By default, it's ``django.template.loader``.
 533
 534    * ``extra_context``: A dictionary of values to add to the template
 535      context. By default, this is an empty dictionary. If a value in the
 536      dictionary is callable, the generic view will call it
 537      just before rendering the template.
 538
 539    * ``allow_empty``: A boolean specifying whether to display the page if no
 540      objects are available. If this is ``False`` and no objects are available,
 541      the view will raise a 404 instead of displaying an empty page. By
 542      default, this is ``False``.
 543
 544    * ``context_processors``: A list of template-context processors to apply to
 545      the view's template.
 546
 547    * ``template_object_name``:  Designates the name of the template variable
 548      to use in the template context. By default, this is ``'object'``. The
 549      view will append ``'_list'`` to the value of this parameter in
 550      determining the variable's name.
 551
 552    * ``mimetype``: The MIME type to use for the resulting document. Defaults
 553      to the value of the :setting:`DEFAULT_CONTENT_TYPE` setting.
 554
 555    * ``allow_future``: A boolean specifying whether to include "future"
 556      objects on this page, where "future" means objects in which the field
 557      specified in ``date_field`` is greater than the current date/time. By
 558      default, this is ``False``.
 559
 560**Template name:**
 561
 562If ``template_name`` isn't specified, this view will use the template
 563``<app_label>/<model_name>_archive_day.html`` by default.
 564
 565**Template context:**
 566
 567In addition to ``extra_context``, the template's context will be:
 568
 569    * ``day``: A ``datetime.date`` object representing the given day.
 570
 571    * ``next_day``: A ``datetime.date`` object representing the next day. If
 572      the next day is in the future, this will be ``None``.
 573
 574    * ``previous_day``: A ``datetime.date`` object representing the previous day.
 575      Unlike ``next_day``, this will never be ``None``.
 576
 577    * ``object_list``: A list of objects available for the given day. This
 578      variable's name depends on the ``template_object_name`` parameter, which
 579      is ``'object'`` by default. If ``template_object_name`` is ``'foo'``,
 580      this variable's name will be ``foo_list``.
 581
 582``django.views.generic.date_based.archive_today``
 583-------------------------------------------------
 584
 585**Description:**
 586
 587A day archive page showing all objects for *today*. This is exactly the same as
 588``archive_day``, except the ``year``/``month``/``day`` arguments are not used,
 589and today's date is used instead.
 590
 591``django.views.generic.date_based.object_detail``
 592-------------------------------------------------
 593
 594**Description:**
 595
 596A page representing an individual object. If the object has a date value in the
 597future, the view will throw a 404 error by default, unless you set
 598``allow_future`` to ``True``.
 599
 600**Required arguments:**
 601
 602    * ``year``: The object's four-digit year (a string).
 603
 604    * ``month``: The object's month , formatted according to the
 605      ``month_format`` argument.
 606
 607    * ``day``: The object's day , formatted according to the ``day_format``
 608      argument.
 609
 610    * ``queryset``: A ``QuerySet`` that contains the object.
 611
 612    * ``date_field``: The name of the ``DateField`` or ``DateTimeField`` in
 613      the ``QuerySet``'s model that the generic view should use to look up the
 614      object according to ``year``, ``month`` and ``day``.
 615
 616    * Either ``object_id`` or (``slug`` *and* ``slug_field``) is required.
 617
 618      If you provide ``object_id``, it should be the value of the primary-key
 619      field for the object being displayed on this page.
 620
 621      Otherwise, ``slug`` should be the slug of the given object, and
 622      ``slug_field`` should be the name of the slug field in the ``QuerySet``'s
 623      model. By default, ``slug_field`` is ``'slug'``.
 624
 625**Optional arguments:**
 626
 627    * ``month_format``: A format string that regulates what format the
 628      ``month`` parameter uses. This should be in the syntax accepted by
 629      Python's ``time.strftime``. (See the `strftime docs`_.) It's set to
 630      ``"%b"`` by default, which is a three-letter month abbreviation. To
 631      change it to use numbers, use ``"%m"``.
 632
 633    * ``day_format``: Like ``month_format``, but for the ``day`` parameter.
 634      It defaults to ``"%d"`` (day of the month as a decimal number, 01-31).
 635
 636    * ``template_name``: The full name of a template to use in rendering the
 637      page. This lets you override the default template name (see below).
 638
 639    * ``template_name_field``: The name of a field on the object whose value is
 640      the template name to use. This lets you store template names in the data.
 641      In other words, if your object has a field ``'the_template'`` that
 642      contains a string ``'foo.html'``, and you set ``template_name_field`` to
 643      ``'the_template'``, then the generic view for this object will use the
 644      template ``'foo.html'``.
 645
 646      It's a bit of a brain-bender, but it's useful in some cases.
 647
 648    * ``template_loader``: The template loader to use when loading the
 649      template. By default, it's ``django.template.loader``.
 650
 651    * ``extra_context``: A dictionary of values to add to the template
 652      context. By default, this is an empty dictionary. If a value in the
 653      dictionary is callable, the generic view will call it
 654      just before rendering the template.
 655
 656    * ``context_processors``: A list of template-context processors to apply to
 657      the view's template.
 658
 659    * ``template_object_name``:  Designates the name of the template variable
 660      to use in the template context. By default, this is ``'object'``.
 661
 662    * ``mimetype``: The MIME type to use for the resulting document. Defaults
 663      to the value of the :setting:`DEFAULT_CONTENT_TYPE` setting.
 664
 665    * ``allow_future``: A boolean specifying whether to include "future"
 666      objects on this page, where "future" means objects in which the field
 667      specified in ``date_field`` is greater than the current date/time. By
 668      default, this is ``False``.
 669
 670**Template name:**
 671
 672If ``template_name`` isn't specified, this view will use the template
 673``<app_label>/<model_name>_detail.html`` by default.
 674
 675**Template context:**
 676
 677In addition to ``extra_context``, the template's context will be:
 678
 679    * ``object``: The object. This variable's name depends on the
 680      ``template_object_name`` parameter, which is ``'object'`` by default. If
 681      ``template_object_name`` is ``'foo'``, this variable's name will be
 682      ``foo``.
 683
 684.. module:: django.views.generic.list_detail
 685
 686List/detail generic views
 687=========================
 688
 689The list-detail generic-view framework (in the
 690``django.views.generic.list_detail`` module) is similar to the date-based one,
 691except the former simply has two views: a list of objects and an individual
 692object page.
 693
 694``django.views.generic.list_detail.object_list``
 695------------------------------------------------
 696
 697**Description:**
 698
 699A page representing a list of objects.
 700
 701**Required arguments:**
 702
 703    * ``queryset``: A ``QuerySet`` that represents the objects.
 704
 705**Optional arguments:**
 706
 707    * ``paginate_by``: An integer specifying how many objects should be
 708      displayed per page. If this is given, the view will paginate objects with
 709      ``paginate_by`` objects per page. The view will expect either a ``page``
 710      query string parameter (via ``GET``) or a ``page`` variable specified in
 711      the URLconf. See `Notes on pagination`_ below.
 712
 713    * ``page``: The current page number, as an integer, or the string
 714      ``'last'``. This is 1-based. See `Notes on pagination`_ below.
 715
 716    * ``template_name``: The full name of a template to use in rendering the
 717      page. This lets you override the default template name (see below).
 718
 719    * ``template_loader``: The template loader to use when loading the
 720      template. By default, it's ``django.template.loader``.
 721
 722    * ``extra_context``: A dictionary of values to add to the template
 723      context. By default, this is an empty dictionary. If a value in the
 724      dictionary is callable, the generic view will call it
 725      just before rendering the template.
 726
 727    * ``allow_empty``: A boolean specifying whether to display the page if no
 728      objects are available. If this is ``False`` and no objects are available,
 729      the view will raise a 404 instead of displaying an empty page. By
 730      default, this is ``True``.
 731
 732    * ``context_processors``: A list of template-context processors to apply to
 733      the view's template.
 734
 735    * ``template_object_name``:  Designates the name of the template variable
 736      to use in the template context. By default, this is ``'object'``. The
 737      view will append ``'_list'`` to the value of this parameter in
 738      determining the variable's name.
 739
 740    * ``mimetype``: The MIME type to use for the resulting document. Defaults
 741      to the value of the :setting:`DEFAULT_CONTENT_TYPE` setting.
 742
 743**Template name:**
 744
 745If ``template_name`` isn't specified, this view will use the template
 746``<app_label>/<model_name>_list.html`` by default.
 747
 748**Template context:**
 749
 750In addition to ``extra_context``, the template's context will be:
 751
 752    * ``object_list``: The list of objects. This variable's name depends on the
 753      ``template_object_name`` parameter, which is ``'object'`` by default. If
 754      ``template_object_name`` is ``'foo'``, this variable's name will be
 755      ``foo_list``.
 756
 757    * ``is_paginated``: A boolean representing whether the results are
 758      paginated. Specifically, this is set to ``False`` if the number of
 759      available objects is less than or equal to ``paginate_by``.
 760
 761If the results are paginated, the context will contain these extra variables:
 762
 763    * ``paginator``: An instance of ``django.core.paginator.Paginator``.
 764
 765    * ``page_obj``: An instance of ``django.core.paginator.Page``.
 766
 767Notes on pagination
 768~~~~~~~~~~~~~~~~~~~
 769
 770If ``paginate_by`` is specified, Django will paginate the results. You can
 771specify the page number in the URL in one of two ways:
 772
 773    * Use the ``page`` parameter in the URLconf. For example, this is what
 774      your URLconf might look like::
 775
 776        (r'^objects/page(?P<page>[0-9]+)/$', 'object_list', dict(info_dict))
 777
 778    * Pass the page number via the ``page`` query-string parameter. For
 779      example, a URL would look like this::
 780
 781        /objects/?page=3
 782
 783    * To loop over all the available page numbers, use the ``page_range``
 784      variable. You can iterate over the list provided by ``page_range``
 785      to create a link to every page of results.
 786
 787These values and lists are 1-based, not 0-based, so the first page would be
 788represented as page ``1``.
 789
 790For more on pagination, read the :doc:`pagination documentation
 791</topics/pagination>`.
 792
 793As a special case, you are also permitted to use ``last`` as a value for
 794``page``::
 795
 796    /objects/?page=last
 797
 798This allows you to access the final page of results without first having to
 799determine how many pages there are.
 800
 801Note that ``page`` *must* be either a valid page number or the value ``last``;
 802any other value for ``page`` will result in a 404 error.
 803
 804``django.views.generic.list_detail.object_detail``
 805--------------------------------------------------
 806
 807A page representing an individual object.
 808
 809**Description:**
 810
 811A page representing an individual object.
 812
 813**Required arguments:**
 814
 815    * ``queryset``: A ``QuerySet`` that contains the object.
 816
 817    * Either ``object_id`` or (``slug`` *and* ``slug_field``) is required.
 818
 819      If you provide ``object_id``, it should be the value of the primary-key
 820      field for the object being displayed on this page.
 821
 822      Otherwise, ``slug`` should be the slug of the given object, and
 823      ``slug_field`` should be the name of the slug field in the ``QuerySet``'s
 824      model. By default, ``slug_field`` is ``'slug'``.
 825
 826**Optional arguments:**
 827
 828    * ``template_name``: The full name of a template to use in rendering the
 829      page. This lets you override the default template name (see below).
 830
 831    * ``template_name_field``: The name of a field on the object whose value is
 832      the template name to use. This lets you store template names in the data.
 833      In other words, if your object has a field ``'the_template'`` that
 834      contains a string ``'foo.html'``, and you set ``template_name_field`` to
 835      ``'the_template'``, then the generic view for this object will use the
 836      template ``'foo.html'``.
 837
 838      It's a bit of a brain-bender, but it's useful in some cases.
 839
 840    * ``template_loader``: The template loader to use when loading the
 841      template. By default, it's ``django.template.loader``.
 842
 843    * ``extra_context``: A dictionary of values to add to the template
 844      context. By default, this is an empty dictionary. If a value in the
 845      dictionary is callable, the generic view will call it
 846      just before rendering the template.
 847
 848    * ``context_processors``: A list of template-context processors to apply to
 849      the view's template.
 850
 851    * ``template_object_name``:  Designates the name of the template variable
 852      to use in the template context. By default, this is ``'object'``.
 853
 854    * ``mimetype``: The MIME type to use for the resulting document. Defaults
 855      to the value of the :setting:`DEFAULT_CONTENT_TYPE` setting.
 856
 857**Template name:**
 858
 859If ``template_name`` isn't specified, this view will use the template
 860``<app_label>/<model_name>_detail.html`` by default.
 861
 862**Template context:**
 863
 864In addition to ``extra_context``, the template's context will be:
 865
 866    * ``object``: The object. This variable's name depends on the
 867      ``template_object_name`` parameter, which is ``'object'`` by default. If
 868      ``template_object_name`` is ``'foo'``, this variable's name will be
 869      ``foo``.
 870
 871.. module:: django.views.generic.create_update
 872
 873Create/update/delete generic views
 874==================================
 875
 876The ``django.views.generic.create_update`` module contains a set of functions
 877for creating, editing and deleting objects.
 878
 879``django.views.generic.create_update.create_object``
 880----------------------------------------------------
 881
 882**Description:**
 883
 884A page that displays a form for creating an object, redisplaying the form with
 885validation errors (if there are any) and saving the object.
 886
 887**Required arguments:**
 888
 889    * Either ``form_class`` or ``model`` is required.
 890
 891      If you provide ``form_class``, it should be a ``django.forms.ModelForm``
 892      subclass. Use this argument when you need to customize the model's form.
 893      See the :doc:`ModelForm docs </topics/forms/modelforms>` for more
 894      information.
 895
 896      Otherwise, ``model`` should be a Django model class and the form used
 897      will be a standard ``ModelForm`` for ``model``.
 898
 899**Optional arguments:**
 900
 901    * ``post_save_redirect``: A URL to which the view will redirect after
 902      saving the object. By default, it's ``object.get_absolute_url()``.
 903
 904      ``post_save_redirect`` may contain dictionary string formatting, which
 905      will be interpolated against the object's field attributes. For example,
 906      you could use ``post_save_redirect="/polls/%(slug)s/"``.
 907
 908    * ``login_required``: A boolean that designates whether a user must be
 909      logged in, in order to see the page and save changes. This hooks into the
 910      Django :doc:`authentication system </topics/auth>`. By default, this is
 911      ``False``.
 912
 913      If this is ``True``, and a non-logged-in user attempts to visit this page
 914      or save the form, Django will redirect the request to ``/accounts/login/``.
 915
 916    * ``template_name``: The full name of a template to use in rendering the
 917      page. This lets you override the default template name (see below).
 918
 919    * ``template_loader``: The template loader to use when loading the
 920      template. By default, it's ``django.template.loader``.
 921
 922    * ``extra_context``: A dictionary of values to add to the template
 923      context. By default, this is an empty dictionary. If a value in the
 924      dictionary is callable, the generic view will call it
 925      just before rendering the template.
 926
 927    * ``context_processors``: A list of template-context processors to apply to
 928      the view's template.
 929
 930**Template name:**
 931
 932If ``template_name`` isn't specified, this view will use the template
 933``<app_label>/<model_name>_form.html`` by default.
 934
 935**Template context:**
 936
 937In addition to ``extra_context``, the template's context will be:
 938
 939    * ``form``: A ``django.forms.ModelForm`` instance representing the form
 940      for creating the object. This lets you refer to form fields easily in the
 941      template system.
 942
 943      For example, if the model has two fields, ``name`` and ``address``::
 944
 945          <form action="" method="post">
 946          <p>{{ form.name.label_tag }} {{ form.name }}</p>
 947          <p>{{ form.address.label_tag }} {{ form.address }}</p>
 948          </form>
 949
 950      See the :doc:`forms documentation </topics/forms/index>` for more
 951      information about using ``Form`` objects in templates.
 952
 953``django.views.generic.create_update.update_object``
 954----------------------------------------------------
 955
 956**Description:**
 957
 958A page that displays a form for editing an existing object, redisplaying the
 959form with validation errors (if there are any) and saving changes to the
 960object. This uses a form automatically generated from the object's
 961model class.
 962
 963**Required arguments:**
 964
 965    * Either ``form_class`` or ``model`` is required.
 966
 967      If you provide ``form_class``, it should be a ``django.forms.ModelForm``
 968      subclass. Use this argument when you need to customize the model's form.
 969      See the :doc:`ModelForm docs </topics/forms/modelforms>` for more
 970      information.
 971
 972      Otherwise, ``model`` should be a Django model class and the form used
 973      will be a standard ``ModelForm`` for ``model``.
 974
 975    * Either ``object_id`` or (``slug`` *and* ``slug_field``) is required.
 976
 977      If you provide ``object_id``, it should be the value of the primary-key
 978      field for the object being displayed on this page.
 979
 980      Otherwise, ``slug`` should be the slug of the given object, and
 981      ``slug_field`` should be the name of the slug field in the ``QuerySet``'s
 982      model. By default, ``slug_field`` is ``'slug'``.
 983
 984**Optional arguments:**
 985
 986    * ``post_save_redirect``: A URL to which the view will redirect after
 987      saving the object. By default, it's ``object.get_absolute_url()``.
 988
 989      ``post_save_redirect`` may contain dictionary string formatting, which
 990      will be interpolated against the object's field attributes. For example,
 991      you could use ``post_save_redirect="/polls/%(slug)s/"``.
 992
 993    * ``login_required``: A boolean that designates whether a user must be
 994      logged in, in order to see the page and save changes. This hooks into the
 995      Django :doc:`authentication system </topics/auth>`. By default, this is
 996      ``False``.
 997
 998      If this is ``True``, and a non-logged-in user attempts to visit this page
 999      or save the form, Django will redirect to :setting:`LOGIN_URL` (which
1000      defaults to ``/accounts/login/``).
1001
1002    * ``template_name``: The full name of a template to use in rendering the
1003      page. This lets you override the default template name (see below).
1004
1005    * ``template_loader``: The template loader to use when loading the
1006      template. By default, it's ``django.template.loader``.
1007
1008    * ``extra_context``: A dictionary of values to add to the template
1009      context. By default, this is an empty dictionary. If a value in the
1010      dictionary is callable, the generic view will call it
1011      just before rendering the template.
1012
1013    * ``context_processors``: A list of template-context processors to apply to
1014      the view's template.
1015
1016    * ``template_object_name``:  Designates the name of the template variable
1017      to use in the template context. By default, this is ``'object'``.
1018
1019**Template name:**
1020
1021If ``template_name`` isn't specified, this view will use the template
1022``<app_label>/<model_name>_form.html`` by default.
1023
1024**Template context:**
1025
1026In addition to ``extra_context``, the template's context will be:
1027
1028    * ``form``: A ``django.forms.ModelForm`` instance representing the form
1029      for editing the object. This lets you refer to form fields easily in the
1030      template system.
1031
1032      For example, if the model has two fields, ``name`` and ``address``::
1033
1034          <form action="" method="post">
1035          <p>{{ form.name.label_tag }} {{ form.name }}</p>
1036          <p>{{ form.address.label_tag }} {{ form.address }}</p>
1037          </form>
1038
1039      See the :doc:`forms documentation </topics/forms/index>` for more
1040      information about using ``Form`` objects in templates.
1041
1042    * ``object``: The original object being edited. This variable's name
1043      depends on the ``template_object_name`` parameter, which is ``'object'``
1044      by default. If ``template_object_name`` is ``'foo'``, this variable's
1045      name will be ``foo``.
1046
1047``django.views.generic.create_update.delete_object``
1048----------------------------------------------------
1049
1050**Description:**
1051
1052A view that displays a confirmation page and deletes an existing object. The
1053given object will only be deleted if the request method is ``POST``. If this
1054view is fetched via ``GET``, it will display a confirmation page that should
1055contain a form that POSTs to the same URL.
1056
1057**Required arguments:**
1058
1059    * ``model``: The Django model class of the object that the form will
1060      delete.
1061
1062    * Either ``object_id`` or (``slug`` *and* ``slug_field``) is required.
1063
1064      If you provide ``object_id``, it should be the value of the primary-key
1065      field for the object being displayed on this page.
1066
1067      Otherwise, ``slug`` should be the slug of the given object, and
1068      ``slug_field`` should be the name of the slug field in the ``QuerySet``'s
1069      model. By default, ``slug_field`` is ``'slug'``.
1070
1071    * ``post_delete_redirect``: A URL to which the view will redirect after
1072      deleting the object.
1073
1074**Optional arguments:**
1075
1076    * ``login_required``: A boolean that designates whether a user must be
1077      logged in, in order to see the page and save changes. This hooks into the
1078      Django :doc:`authentication system </topics/auth>`. By default, this is
1079      ``False``.
1080
1081      If this is ``True``, and a non-logged-in user attempts to visit this page
1082      or save the form, Django will redirect to :setting:`LOGIN_URL` (which
1083      defaults to ``/accounts/login/``).
1084
1085    * ``template_name``: The full name of a template to use in rendering the
1086      page. This lets you override the default template name (see below).
1087
1088    * ``template_loader``: The template loader to use when loading the
1089      template. By default, it's ``django.template.loader``.
1090
1091    * ``extra_context``: A dictionary of values to add to the template
1092      context. By default, this is an empty dictionary. If a value in the
1093      dictionary is callable, the generic view will call it
1094      just before rendering the template.
1095
1096    * ``context_processors``: A list of template-context processors to apply to
1097      the view's template.
1098
1099    * ``template_object_name``:  Designates the name of the template variable
1100      to use in the template context. By default, this is ``'object'``.
1101
1102**Template name:**
1103
1104If ``template_name`` isn't specified, this view will use the template
1105``<app_label>/<model_name>_confirm_delete.html`` by default.
1106
1107**Template context:**
1108
1109In addition to ``extra_context``, the template's context will be:
1110
1111    * ``object``: The original object that's about to be deleted. This
1112      variable's name depends on the ``template_object_name`` parameter, which
1113      is ``'object'`` by default. If ``template_object_name`` is ``'foo'``,
1114      this variable's name will be ``foo``.