django/docs/ref/generic-views.txt

=============
Generic views
=============


.. versionchanged:: 1.3

.. note::

    From Django 1.3, function-based generic views have been deprecated in favor
    of a class-based approach, described in the class-based views :doc:`topic
    guide </topics/class-based-views>` and :doc:`detailed reference
    </ref/class-based-views>`.

Writing Web applications can be monotonous, because we repeat certain patterns
again and again. In Django, the most common of these patterns have been
abstracted into "generic views" that let you quickly provide common views of
an object without actually needing to write any Python code.

A general introduction to generic views can be found in the :doc:`topic guide
</topics/generic-views>`.

This reference contains details of Django's built-in generic views, along with
a list of all keyword arguments that a generic view expects. Remember that
arguments may either come from the URL pattern or from the ``extra_context``
additional-information dictionary.

Most generic views require the ``queryset`` key, which is a ``QuerySet``
instance; see :doc:`/topics/db/queries` for more information about ``QuerySet``
objects.

"Simple" generic views
======================

The ``django.views.generic.simple`` module contains simple views to handle a
couple of common cases: rendering a template when no view logic is needed,
and issuing a redirect.

``django.views.generic.simple.direct_to_template``
--------------------------------------------------

**Description:**

Renders a given template, passing it a ``{{ params }}`` template variable,
which is a dictionary of the parameters captured in the URL.

**Required arguments:**

    * ``template``: The full name of a template to use.

**Optional arguments:**

    * ``extra_context``: A dictionary of values to add to the template
      context. By default, this is an empty dictionary. If a value in the
      dictionary is callable, the generic view will call it
      just before rendering the template.

    * ``mimetype``: The MIME type to use for the resulting document. Defaults
      to the value of the ``DEFAULT_CONTENT_TYPE`` setting.

**Example:**

Given the following URL patterns::

    urlpatterns = patterns('django.views.generic.simple',
        (r'^foo/$',             'direct_to_template', {'template': 'foo_index.html'}),
        (r'^foo/(?P<id>\d+)/$', 'direct_to_template', {'template': 'foo_detail.html'}),
    )

... a request to ``/foo/`` would render the template ``foo_index.html``, and a
request to ``/foo/15/`` would render the ``foo_detail.html`` with a context
variable ``{{ params.id }}`` that is set to ``15``.

``django.views.generic.simple.redirect_to``
-------------------------------------------

**Description:**

Redirects to a given URL.

The given URL may contain dictionary-style string formatting, which will be
interpolated against the parameters captured in the URL. Because keyword
interpolation is *always* done (even if no arguments are passed in), any ``"%"``
characters in the URL must be written as ``"%%"`` so that Python will convert
them to a single percent sign on output.

If the given URL is ``None``, Django will return an ``HttpResponseGone`` (410).

**Required arguments:**

    * ``url``: The URL to redirect to, as a string. Or ``None`` to raise a 410
      (Gone) HTTP error.

**Optional arguments:**

    * ``permanent``: Whether the redirect should be permanent. The only
      difference here is the HTTP status code returned. If ``True``, then the
      redirect will use status code 301. If ``False``, then the redirect will
      use status code 302. By default, ``permanent`` is ``True``.

    * ``query_string``: Whether to pass along the GET query string to
      the new location. If ``True``, then the query string is appended
      to the URL. If ``False``, then the query string is discarded. By
      default, ``query_string`` is ``False``.

.. versionadded:: 1.3
    The ``query_string`` keyword argument is new in Django 1.3.

**Example:**

This example issues a permanent redirect (HTTP status code 301) from
``/foo/<id>/`` to ``/bar/<id>/``::

    urlpatterns = patterns('django.views.generic.simple',
        ('^foo/(?P<id>\d+)/$', 'redirect_to', {'url': '/bar/%(id)s/'}),
    )

This example issues a non-permanent redirect (HTTP status code 302) from
``/foo/<id>/`` to ``/bar/<id>/``::

    urlpatterns = patterns('django.views.generic.simple',
        ('^foo/(?P<id>\d+)/$', 'redirect_to', {'url': '/bar/%(id)s/', 'permanent': False}),
    )

This example returns a 410 HTTP error for requests to ``/bar/``::

    urlpatterns = patterns('django.views.generic.simple',
        ('^bar/$', 'redirect_to', {'url': None}),
    )

This example shows how ``"%"`` characters must be written in the URL in order
to avoid confusion with Python's string formatting markers. If the redirect
string is written as ``"%7Ejacob/"`` (with only a single ``%``), an exception would be raised::

    urlpatterns = patterns('django.views.generic.simple',
        ('^bar/$', 'redirect_to', {'url': '%%7Ejacob.'}),
    )

Date-based generic views
========================

Date-based generic views (in the module ``django.views.generic.date_based``)
are views for displaying drilldown pages for date-based data.

``django.views.generic.date_based.archive_index``
-------------------------------------------------

**Description:**

A top-level index page showing the "latest" objects, by date. Objects with
a date in the *future* are not included unless you set ``allow_future`` to
``True``.

**Required arguments:**

    * ``queryset``: A ``QuerySet`` of objects for which the archive serves.

    * ``date_field``: The name of the ``DateField`` or ``DateTimeField`` in
      the ``QuerySet``'s model that the date-based archive should use to
      determine the objects on the page.

**Optional arguments:**

    * ``num_latest``: The number of latest objects to send to the template
      context. By default, it's 15.

    * ``template_name``: The full name of a template to use in rendering the
      page. This lets you override the default template name (see below).

    * ``template_loader``: The template loader to use when loading the
      template. By default, it's ``django.template.loader``.

    * ``extra_context``: A dictionary of values to add to the template
      context. By default, this is an empty dictionary. If a value in the
      dictionary is callable, the generic view will call it
      just before rendering the template.

    * ``allow_empty``: A boolean specifying whether to display the page if no
      objects are available. If this is ``False`` and no objects are available,
      the view will raise a 404 instead of displaying an empty page. By
      default, this is ``True``.

    * ``context_processors``: A list of template-context processors to apply to
      the view's template.

    * ``mimetype``: The MIME type to use for the resulting document. Defaults
      to the value of the ``DEFAULT_CONTENT_TYPE`` setting.

    * ``allow_future``: A boolean specifying whether to include "future"
      objects on this page, where "future" means objects in which the field
      specified in ``date_field`` is greater than the current date/time. By
      default, this is ``False``.

    * ``template_object_name``: Designates the name of the template variable
      to use in the template context. By default, this is ``'latest'``.

**Template name:**

If ``template_name`` isn't specified, this view will use the template
``<app_label>/<model_name>_archive.html`` by default, where:

    * ``<model_name>`` is your model's name in all lowercase. For a model
      ``StaffMember``, that'd be ``staffmember``.

    * ``<app_label>`` is the right-most part of the full Python path to
      your model's app. For example, if your model lives in
      ``apps/blog/models.py``, that'd be ``blog``.

**Template context:**

In addition to ``extra_context``, the template's context will be:

    * ``date_list``: A ``DateQuerySet`` object containing all years that have
      have objects available according to ``queryset``, represented as
      ``datetime.datetime`` objects. These are ordered in reverse. This is
      equivalent to ``queryset.dates(date_field, 'year')[::-1]``.

    * ``latest``: The ``num_latest`` objects in the system, ordered descending
      by ``date_field``. For example, if ``num_latest`` is ``10``, then
      ``latest`` will be a list of the latest 10 objects in ``queryset``.

      This variable's name depends on the ``template_object_name`` parameter,
      which is ``'latest'`` by default. If ``template_object_name`` is
      ``'foo'``, this variable's name will be ``foo``.

``django.views.generic.date_based.archive_year``
------------------------------------------------

**Description:**

A yearly archive page showing all available months in a given year. Objects
with a date in the *future* are not displayed unless you set ``allow_future``
to ``True``.

**Required arguments:**

    * ``year``: The four-digit year for which the archive serves.

    * ``queryset``: A ``QuerySet`` of objects for which the archive serves.

    * ``date_field``: The name of the ``DateField`` or ``DateTimeField`` in
      the ``QuerySet``'s model that the date-based archive should use to
      determine the objects on the page.

**Optional arguments:**

    * ``template_name``: The full name of a template to use in rendering the
      page. This lets you override the default template name (see below).

    * ``template_loader``: The template loader to use when loading the
      template. By default, it's ``django.template.loader``.

    * ``extra_context``: A dictionary of values to add to the template
      context. By default, this is an empty dictionary. If a value in the
      dictionary is callable, the generic view will call it
      just before rendering the template.

    * ``allow_empty``: A boolean specifying whether to display the page if no
      objects are available. If this is ``False`` and no objects are available,
      the view will raise a 404 instead of displaying an empty page. By
      default, this is ``False``.

    * ``context_processors``: A list of template-context processors to apply to
      the view's template.

    * ``template_object_name``:  Designates the name of the template variable
      to use in the template context. By default, this is ``'object'``. The
      view will append ``'_list'`` to the value of this parameter in
      determining the variable's name.

    * ``make_object_list``: A boolean specifying whether to retrieve the full
      list of objects for this year and pass those to the template. If ``True``,
      this list of objects will be made available to the template as
      ``object_list``. (The name ``object_list`` may be different; see the docs
      for ``object_list`` in the "Template context" section below.) By default,
      this is ``False``.

    * ``mimetype``: The MIME type to use for the resulting document. Defaults
      to the value of the ``DEFAULT_CONTENT_TYPE`` setting.

    * ``allow_future``: A boolean specifying whether to include "future"
      objects on this page, where "future" means objects in which the field
      specified in ``date_field`` is greater than the current date/time. By
      default, this is ``False``.

**Template name:**

If ``template_name`` isn't specified, this view will use the template
``<app_label>/<model_name>_archive_year.html`` by default.

**Template context:**

In addition to ``extra_context``, the template's context will be:

    * ``date_list``: A ``DateQuerySet`` object containing all months that have
      have objects available according to ``queryset``, represented as
      ``datetime.datetime`` objects, in ascending order.

    * ``year``: The given year, as a four-character string.

    * ``object_list``: If the ``make_object_list`` parameter is ``True``, this
      will be set to a list of objects available for the given year, ordered by
      the date field. This variable's name depends on the
      ``template_object_name`` parameter, which is ``'object'`` by default. If
      ``template_object_name`` is ``'foo'``, this variable's name will be
      ``foo_list``.

      If ``make_object_list`` is ``False``, ``object_list`` will be passed to
      the template as an empty list.

``django.views.generic.date_based.archive_month``
-------------------------------------------------

**Description:**

A monthly archive page showing all objects in a given month. Objects with a
date in the *future* are not displayed unless you set ``allow_future`` to
``True``.

**Required arguments:**

    * ``year``: The four-digit year for which the archive serves (a string).

    * ``month``: The month for which the archive serves, formatted according to
      the ``month_format`` argument.

    * ``queryset``: A ``QuerySet`` of objects for which the archive serves.

    * ``date_field``: The name of the ``DateField`` or ``DateTimeField`` in
      the ``QuerySet``'s model that the date-based archive should use to
      determine the objects on the page.

**Optional arguments:**

    * ``month_format``: A format string that regulates what format the
      ``month`` parameter uses. This should be in the syntax accepted by
      Python's ``time.strftime``. (See the `strftime docs`_.) It's set to
      ``"%b"`` by default, which is a three-letter month abbreviation. To
      change it to use numbers, use ``"%m"``.

    * ``template_name``: The full name of a template to use in rendering the
      page. This lets you override the default template name (see below).

    * ``template_loader``: The template loader to use when loading the
      template. By default, it's ``django.template.loader``.

    * ``extra_context``: A dictionary of values to add to the template
      context. By default, this is an empty dictionary. If a value in the
      dictionary is callable, the generic view will call it
      just before rendering the template.

    * ``allow_empty``: A boolean specifying whether to display the page if no
      objects are available. If this is ``False`` and no objects are available,
      the view will raise a 404 instead of displaying an empty page. By
      default, this is ``False``.

    * ``context_processors``: A list of template-context processors to apply to
      the view's template.

    * ``template_object_name``:  Designates the name of the template variable
      to use in the template context. By default, this is ``'object'``. The
      view will append ``'_list'`` to the value of this parameter in
      determining the variable's name.

    * ``mimetype``: The MIME type to use for the resulting document. Defaults
      to the value of the ``DEFAULT_CONTENT_TYPE`` setting.

    * ``allow_future``: A boolean specifying whether to include "future"
      objects on this page, where "future" means objects in which the field
      specified in ``date_field`` is greater than the current date/time. By
      default, this is ``False``.

**Template name:**

If ``template_name`` isn't specified, this view will use the template
``<app_label>/<model_name>_archive_month.html`` by default.

**Template context:**

.. versionadded:: 1.2
   The inclusion of ``date_list`` in the template's context is new.

In addition to ``extra_context``, the template's context will be:

    * ``date_list``: A ``DateQuerySet`` object containing all days that have
      have objects available in the given month, according to ``queryset``,
      represented as ``datetime.datetime`` objects, in ascending order.

    * ``month``: A ``datetime.date`` object representing the given month.

    * ``next_month``: A ``datetime.date`` object representing the first day of
      the next month. If the next month is in the future, this will be
      ``None``.

    * ``previous_month``: A ``datetime.date`` object representing the first day
      of the previous month. Unlike ``next_month``, this will never be
      ``None``.

    * ``object_list``: A list of objects available for the given month. This
      variable's name depends on the ``template_object_name`` parameter, which
      is ``'object'`` by default. If ``template_object_name`` is ``'foo'``,
      this variable's name will be ``foo_list``.

.. _strftime docs: http://docs.python.org/library/time.html#time.strftime

``django.views.generic.date_based.archive_week``
------------------------------------------------

**Description:**

A weekly archive page showing all objects in a given week. Objects with a date
in the *future* are not displayed unless you set ``allow_future`` to ``True``.

**Required arguments:**

    * ``year``: The four-digit year for which the archive serves (a string).

    * ``week``: The week of the year for which the archive serves (a string).
      Weeks start with Sunday.

    * ``queryset``: A ``QuerySet`` of objects for which the archive serves.

    * ``date_field``: The name of the ``DateField`` or ``DateTimeField`` in
      the ``QuerySet``'s model that the date-based archive should use to
      determine the objects on the page.

**Optional arguments:**

    * ``template_name``: The full name of a template to use in rendering the
      page. This lets you override the default template name (see below).

    * ``template_loader``: The template loader to use when loading the
      template. By default, it's ``django.template.loader``.

    * ``extra_context``: A dictionary of values to add to the template
      context. By default, this is an empty dictionary. If a value in the
      dictionary is callable, the generic view will call it
      just before rendering the template.

    * ``allow_empty``: A boolean specifying whether to display the page if no
      objects are available. If this is ``False`` and no objects are available,
      the view will raise a 404 instead of displaying an empty page. By
      default, this is ``True``.

    * ``context_processors``: A list of template-context processors to apply to
      the view's template.

    * ``template_object_name``:  Designates the name of the template variable
      to use in the template context. By default, this is ``'object'``. The
      view will append ``'_list'`` to the value of this parameter in
      determining the variable's name.

    * ``mimetype``: The MIME type to use for the resulting document. Defaults
      to the value of the ``DEFAULT_CONTENT_TYPE`` setting.

    * ``allow_future``: A boolean specifying whether to include "future"
      objects on this page, where "future" means objects in which the field
      specified in ``date_field`` is greater than the current date/time. By
      default, this is ``False``.

**Template name:**

If ``template_name`` isn't specified, this view will use the template
``<app_label>/<model_name>_archive_week.html`` by default.

**Template context:**

In addition to ``extra_context``, the template's context will be:

    * ``week``: A ``datetime.date`` object representing the first day of the
      given week.

    * ``object_list``: A list of objects available for the given week. This
      variable's name depends on the ``template_object_name`` parameter, which
      is ``'object'`` by default. If ``template_object_name`` is ``'foo'``,
      this variable's name will be ``foo_list``.

``django.views.generic.date_based.archive_day``
-----------------------------------------------

**Description:**

A day archive page showing all objects in a given day. Days in the future throw
a 404 error, regardless of whether any objects exist for future days, unless
you set ``allow_future`` to ``True``.

**Required arguments:**

    * ``year``: The four-digit year for which the archive serves (a string).

    * ``month``: The month for which the archive serves, formatted according to
      the ``month_format`` argument.

    * ``day``: The day for which the archive serves, formatted according to the
      ``day_format`` argument.

    * ``queryset``: A ``QuerySet`` of objects for which the archive serves.

    * ``date_field``: The name of the ``DateField`` or ``DateTimeField`` in
      the ``QuerySet``'s model that the date-based archive should use to
      determine the objects on the page.

**Optional arguments:**

    * ``month_format``: A format string that regulates what format the
      ``month`` parameter uses. This should be in the syntax accepted by
      Python's ``time.strftime``. (See the `strftime docs`_.) It's set to
      ``"%b"`` by default, which is a three-letter month abbreviation. To
      change it to use numbers, use ``"%m"``.

    * ``day_format``: Like ``month_format``, but for the ``day`` parameter.
      It defaults to ``"%d"`` (day of the month as a decimal number, 01-31).

    * ``template_name``: The full name of a template to use in rendering the
      page. This lets you override the default template name (see below).

    * ``template_loader``: The template loader to use when loading the
      template. By default, it's ``django.template.loader``.

    * ``extra_context``: A dictionary of values to add to the template
      context. By default, this is an empty dictionary. If a value in the
      dictionary is callable, the generic view will call it
      just before rendering the template.

    * ``allow_empty``: A boolean specifying whether to display the page if no
      objects are available. If this is ``False`` and no objects are available,
      the view will raise a 404 instead of displaying an empty page. By
      default, this is ``False``.

    * ``context_processors``: A list of template-context processors to apply to
      the view's template.

    * ``template_object_name``:  Designates the name of the template variable
      to use in the template context. By default, this is ``'object'``. The
      view will append ``'_list'`` to the value of this parameter in
      determining the variable's name.

    * ``mimetype``: The MIME type to use for the resulting document. Defaults
      to the value of the ``DEFAULT_CONTENT_TYPE`` setting.

    * ``allow_future``: A boolean specifying whether to include "future"
      objects on this page, where "future" means objects in which the field
      specified in ``date_field`` is greater than the current date/time. By
      default, this is ``False``.

**Template name:**

If ``template_name`` isn't specified, this view will use the template
``<app_label>/<model_name>_archive_day.html`` by default.

**Template context:**

In addition to ``extra_context``, the template's context will be:

    * ``day``: A ``datetime.date`` object representing the given day.

    * ``next_day``: A ``datetime.date`` object representing the next day. If
      the next day is in the future, this will be ``None``.

    * ``previous_day``: A ``datetime.date`` object representing the previous day.
      Unlike ``next_day``, this will never be ``None``.

    * ``object_list``: A list of objects available for the given day. This
      variable's name depends on the ``template_object_name`` parameter, which
      is ``'object'`` by default. If ``template_object_name`` is ``'foo'``,
      this variable's name will be ``foo_list``.

``django.views.generic.date_based.archive_today``
-------------------------------------------------

**Description:**

A day archive page showing all objects for *today*. This is exactly the same as
``archive_day``, except the ``year``/``month``/``day`` arguments are not used,
and today's date is used instead.

``django.views.generic.date_based.object_detail``
-------------------------------------------------

**Description:**

A page representing an individual object. If the object has a date value in the
future, the view will throw a 404 error by default, unless you set
``allow_future`` to ``True``.

**Required arguments:**

    * ``year``: The object's four-digit year (a string).

    * ``month``: The object's month , formatted according to the
      ``month_format`` argument.

    * ``day``: The object's day , formatted according to the ``day_format``
      argument.

    * ``queryset``: A ``QuerySet`` that contains the object.

    * ``date_field``: The name of the ``DateField`` or ``DateTimeField`` in
      the ``QuerySet``'s model that the generic view should use to look up the
      object according to ``year``, ``month`` and ``day``.

    * Either ``object_id`` or (``slug`` *and* ``slug_field``) is required.

      If you provide ``object_id``, it should be the value of the primary-key
      field for the object being displayed on this page.

      Otherwise, ``slug`` should be the slug of the given object, and
      ``slug_field`` should be the name of the slug field in the ``QuerySet``'s
      model. By default, ``slug_field`` is ``'slug'``.

**Optional arguments:**

    * ``month_format``: A format string that regulates what format the
      ``month`` parameter uses. This should be in the syntax accepted by
      Python's ``time.strftime``. (See the `strftime docs`_.) It's set to
      ``"%b"`` by default, which is a three-letter month abbreviation. To
      change it to use numbers, use ``"%m"``.

    * ``day_format``: Like ``month_format``, but for the ``day`` parameter.
      It defaults to ``"%d"`` (day of the month as a decimal number, 01-31).

    * ``template_name``: The full name of a template to use in rendering the
      page. This lets you override the default template name (see below).

    * ``template_name_field``: The name of a field on the object whose value is
      the template name to use. This lets you store template names in the data.
      In other words, if your object has a field ``'the_template'`` that
      contains a string ``'foo.html'``, and you set ``template_name_field`` to
      ``'the_template'``, then the generic view for this object will use the
      template ``'foo.html'``.

      It's a bit of a brain-bender, but it's useful in some cases.

    * ``template_loader``: The template loader to use when loading the
      template. By default, it's ``django.template.loader``.

    * ``extra_context``: A dictionary of values to add to the template
      context. By default, this is an empty dictionary. If a value in the
      dictionary is callable, the generic view will call it
      just before rendering the template.

    * ``context_processors``: A list of template-context processors to apply to
      the view's template.

    * ``template_object_name``:  Designates the name of the template variable
      to use in the template context. By default, this is ``'object'``.

    * ``mimetype``: The MIME type to use for the resulting document. Defaults
      to the value of the ``DEFAULT_CONTENT_TYPE`` setting.

    * ``allow_future``: A boolean specifying whether to include "future"
      objects on this page, where "future" means objects in which the field
      specified in ``date_field`` is greater than the current date/time. By
      default, this is ``False``.

**Template name:**

If ``template_name`` isn't specified, this view will use the template
``<app_label>/<model_name>_detail.html`` by default.

**Template context:**

In addition to ``extra_context``, the template's context will be:

    * ``object``: The object. This variable's name depends on the
      ``template_object_name`` parameter, which is ``'object'`` by default. If
      ``template_object_name`` is ``'foo'``, this variable's name will be
      ``foo``.

List/detail generic views
=========================

The list-detail generic-view framework (in the
``django.views.generic.list_detail`` module) is similar to the date-based one,
except the former simply has two views: a list of objects and an individual
object page.

``django.views.generic.list_detail.object_list``
------------------------------------------------

**Description:**

A page representing a list of objects.

**Required arguments:**

    * ``queryset``: A ``QuerySet`` that represents the objects.

**Optional arguments:**

    * ``paginate_by``: An integer specifying how many objects should be
      displayed per page. If this is given, the view will paginate objects with
      ``paginate_by`` objects per page. The view will expect either a ``page``
      query string parameter (via ``GET``) or a ``page`` variable specified in
      the URLconf. See `Notes on pagination`_ below.

    * ``page``: The current page number, as an integer, or the string
      ``'last'``. This is 1-based. See `Notes on pagination`_ below.

    * ``template_name``: The full name of a template to use in rendering the
      page. This lets you override the default template name (see below).

    * ``template_loader``: The template loader to use when loading the
      template. By default, it's ``django.template.loader``.

    * ``extra_context``: A dictionary of values to add to the template
      context. By default, this is an empty dictionary. If a value in the
      dictionary is callable, the generic view will call it
      just before rendering the template.

    * ``allow_empty``: A boolean specifying whether to display the page if no
      objects are available. If this is ``False`` and no objects are available,
      the view will raise a 404 instead of displaying an empty page. By
      default, this is ``True``.

    * ``context_processors``: A list of template-context processors to apply to
      the view's template.

    * ``template_object_name``:  Designates the name of the template variable
      to use in the template context. By default, this is ``'object'``. The
      view will append ``'_list'`` to the value of this parameter in
      determining the variable's name.

    * ``mimetype``: The MIME type to use for the resulting document. Defaults
      to the value of the ``DEFAULT_CONTENT_TYPE`` setting.

**Template name:**

If ``template_name`` isn't specified, this view will use the template
``<app_label>/<model_name>_list.html`` by default.

**Template context:**

In addition to ``extra_context``, the template's context will be:

    * ``object_list``: The list of objects. This variable's name depends on the
      ``template_object_name`` parameter, which is ``'object'`` by default. If
      ``template_object_name`` is ``'foo'``, this variable's name will be
      ``foo_list``.

    * ``is_paginated``: A boolean representing whether the results are
      paginated. Specifically, this is set to ``False`` if the number of
      available objects is less than or equal to ``paginate_by``.

If the results are paginated, the context will contain these extra variables:

    * ``paginator``: An instance of ``django.core.paginator.Paginator``.

    * ``page_obj``: An instance of ``django.core.paginator.Page``.

Notes on pagination
~~~~~~~~~~~~~~~~~~~

If ``paginate_by`` is specified, Django will paginate the results. You can
specify the page number in the URL in one of two ways:

    * Use the ``page`` parameter in the URLconf. For example, this is what
      your URLconf might look like::

        (r'^objects/page(?P<page>[0-9]+)/$', 'object_list', dict(info_dict))

    * Pass the page number via the ``page`` query-string parameter. For
      example, a URL would look like this::

        /objects/?page=3

    * To loop over all the available page numbers, use the ``page_range``
      variable. You can iterate over the list provided by ``page_range``
      to create a link to every page of results.

These values and lists are 1-based, not 0-based, so the first page would be
represented as page ``1``.

For more on pagination, read the :doc:`pagination documentation
</topics/pagination>`.

As a special case, you are also permitted to use ``last`` as a value for
``page``::

    /objects/?page=last

This allows you to access the final page of results without first having to
determine how many pages there are.

Note that ``page`` *must* be either a valid page number or the value ``last``;
any other value for ``page`` will result in a 404 error.

``django.views.generic.list_detail.object_detail``
--------------------------------------------------

A page representing an individual object.

**Description:**

A page representing an individual object.

**Required arguments:**

    * ``queryset``: A ``QuerySet`` that contains the object.

    * Either ``object_id`` or (``slug`` *and* ``slug_field``) is required.

      If you provide ``object_id``, it should be the value of the primary-key
      field for the object being displayed on this page.

      Otherwise, ``slug`` should be the slug of the given object, and
      ``slug_field`` should be the name of the slug field in the ``QuerySet``'s
      model. By default, ``slug_field`` is ``'slug'``.

**Optional arguments:**

    * ``template_name``: The full name of a template to use in rendering the
      page. This lets you override the default template name (see below).

    * ``template_name_field``: The name of a field on the object whose value is
      the template name to use. This lets you store template names in the data.
      In other words, if your object has a field ``'the_template'`` that
      contains a string ``'foo.html'``, and you set ``template_name_field`` to
      ``'the_template'``, then the generic view for this object will use the
      template ``'foo.html'``.

      It's a bit of a brain-bender, but it's useful in some cases.

    * ``template_loader``: The template loader to use when loading the
      template. By default, it's ``django.template.loader``.

    * ``extra_context``: A dictionary of values to add to the template
      context. By default, this is an empty dictionary. If a value in the
      dictionary is callable, the generic view will call it
      just before rendering the template.

    * ``context_processors``: A list of template-context processors to apply to
      the view's template.

    * ``template_object_name``:  Designates the name of the template variable
      to use in the template context. By default, this is ``'object'``.

    * ``mimetype``: The MIME type to use for the resulting document. Defaults
      to the value of the ``DEFAULT_CONTENT_TYPE`` setting.

**Template name:**

If ``template_name`` isn't specified, this view will use the template
``<app_label>/<model_name>_detail.html`` by default.

**Template context:**

In addition to ``extra_context``, the template's context will be:

    * ``object``: The object. This variable's name depends on the
      ``template_object_name`` parameter, which is ``'object'`` by default. If
      ``template_object_name`` is ``'foo'``, this variable's name will be
      ``foo``.

Create/update/delete generic views
==================================

The ``django.views.generic.create_update`` module contains a set of functions
for creating, editing and deleting objects.

``django.views.generic.create_update.create_object``
----------------------------------------------------

**Description:**

A page that displays a form for creating an object, redisplaying the form with
validation errors (if there are any) and saving the object.

**Required arguments:**

    * Either ``form_class`` or ``model`` is required.

      If you provide ``form_class``, it should be a ``django.forms.ModelForm``
      subclass. Use this argument when you need to customize the model's form.
      See the :doc:`ModelForm docs </topics/forms/modelforms>` for more
      information.

      Otherwise, ``model`` should be a Django model class and the form used
      will be a standard ``ModelForm`` for ``model``.

**Optional arguments:**

    * ``post_save_redirect``: A URL to which the view will redirect after
      saving the object. By default, it's ``object.get_absolute_url()``.

      ``post_save_redirect`` may contain dictionary string formatting, which
      will be interpolated against the object's field attributes. For example,
      you could use ``post_save_redirect="/polls/%(slug)s/"``.

    * ``login_required``: A boolean that designates whether a user must be
      logged in, in order to see the page and save changes. This hooks into the
      Django :doc:`authentication system </topics/auth>`. By default, this is
      ``False``.

      If this is ``True``, and a non-logged-in user attempts to visit this page
      or save the form, Django will redirect the request to ``/accounts/login/``.

    * ``template_name``: The full name of a template to use in rendering the
      page. This lets you override the default template name (see below).

    * ``template_loader``: The template loader to use when loading the
      template. By default, it's ``django.template.loader``.

    * ``extra_context``: A dictionary of values to add to the template
      context. By default, this is an empty dictionary. If a value in the
      dictionary is callable, the generic view will call it
      just before rendering the template.

    * ``context_processors``: A list of template-context processors to apply to
      the view's template.

**Template name:**

If ``template_name`` isn't specified, this view will use the template
``<app_label>/<model_name>_form.html`` by default.

**Template context:**

In addition to ``extra_context``, the template's context will be:

    * ``form``: A ``django.forms.ModelForm`` instance representing the form
      for creating the object. This lets you refer to form fields easily in the
      template system.

      For example, if the model has two fields, ``name`` and ``address``::

          <form action="" method="post">
          <p>{{ form.name.label_tag }} {{ form.name }}</p>
          <p>{{ form.address.label_tag }} {{ form.address }}</p>
          </form>

      See the :doc:`forms documentation </topics/forms/index>` for more
      information about using ``Form`` objects in templates.

``django.views.generic.create_update.update_object``
----------------------------------------------------

**Description:**

A page that displays a form for editing an existing object, redisplaying the
form with validation errors (if there are any) and saving changes to the
object. This uses a form automatically generated from the object's
model class.

**Required arguments:**

    * Either ``form_class`` or ``model`` is required.

      If you provide ``form_class``, it should be a ``django.forms.ModelForm``
      subclass. Use this argument when you need to customize the model's form.
      See the :doc:`ModelForm docs </topics/forms/modelforms>` for more
      information.

      Otherwise, ``model`` should be a Django model class and the form used
      will be a standard ``ModelForm`` for ``model``.

    * Either ``object_id`` or (``slug`` *and* ``slug_field``) is required.

      If you provide ``object_id``, it should be the value of the primary-key
      field for the object being displayed on this page.

      Otherwise, ``slug`` should be the slug of the given object, and
      ``slug_field`` should be the name of the slug field in the ``QuerySet``'s
      model. By default, ``slug_field`` is ``'slug'``.

**Optional arguments:**

    * ``post_save_redirect``: A URL to which the view will redirect after
      saving the object. By default, it's ``object.get_absolute_url()``.

      ``post_save_redirect`` may contain dictionary string formatting, which
      will be interpolated against the object's field attributes. For example,
      you could use ``post_save_redirect="/polls/%(slug)s/"``.

    * ``login_required``: A boolean that designates whether a user must be
      logged in, in order to see the page and save changes. This hooks into the
      Django :doc:`authentication system </topics/auth>`. By default, this is
      ``False``.

      If this is ``True``, and a non-logged-in user attempts to visit this page
      or save the form, Django will redirect to :setting:`LOGIN_URL` (which
      defaults to ``/accounts/login/``).

    * ``template_name``: The full name of a template to use in rendering the
      page. This lets you override the default template name (see below).

    * ``template_loader``: The template loader to use when loading the
      template. By default, it's ``django.template.loader``.

    * ``extra_context``: A dictionary of values to add to the template
      context. By default, this is an empty dictionary. If a value in the
      dictionary is callable, the generic view will call it
      just before rendering the template.

    * ``context_processors``: A list of template-context processors to apply to
      the view's template.

    * ``template_object_name``:  Designates the name of the template variable
      to use in the template context. By default, this is ``'object'``.

**Template name:**

If ``template_name`` isn't specified, this view will use the template
``<app_label>/<model_name>_form.html`` by default.

**Template context:**

In addition to ``extra_context``, the template's context will be:

    * ``form``: A ``django.forms.ModelForm`` instance representing the form
      for editing the object. This lets you refer to form fields easily in the
      template system.

      For example, if the model has two fields, ``name`` and ``address``::

          <form action="" method="post">
          <p>{{ form.name.label_tag }} {{ form.name }}</p>
          <p>{{ form.address.label_tag }} {{ form.address }}</p>
          </form>

      See the :doc:`forms documentation </topics/forms/index>` for more
      information about using ``Form`` objects in templates.

    * ``object``: The original object being edited. This variable's name
      depends on the ``template_object_name`` parameter, which is ``'object'``
      by default. If ``template_object_name`` is ``'foo'``, this variable's
      name will be ``foo``.

``django.views.generic.create_update.delete_object``
----------------------------------------------------

**Description:**

A view that displays a confirmation page and deletes an existing object. The
given object will only be deleted if the request method is ``POST``. If this
view is fetched via ``GET``, it will display a confirmation page that should
contain a form that POSTs to the same URL.

**Required arguments:**

    * ``model``: The Django model class of the object that the form will
      delete.

    * Either ``object_id`` or (``slug`` *and* ``slug_field``) is required.

      If you provide ``object_id``, it should be the value of the primary-key
      field for the object being displayed on this page.

      Otherwise, ``slug`` should be the slug of the given object, and
      ``slug_field`` should be the name of the slug field in the ``QuerySet``'s
      model. By default, ``slug_field`` is ``'slug'``.

    * ``post_delete_redirect``: A URL to which the view will redirect after
      deleting the object.

**Optional arguments:**

    * ``login_required``: A boolean that designates whether a user must be
      logged in, in order to see the page and save changes. This hooks into the
      Django :doc:`authentication system </topics/auth>`. By default, this is
      ``False``.

      If this is ``True``, and a non-logged-in user attempts to visit this page
      or save the form, Django will redirect to :setting:`LOGIN_URL` (which
      defaults to ``/accounts/login/``).

    * ``template_name``: The full name of a template to use in rendering the
      page. This lets you override the default template name (see below).

    * ``template_loader``: The template loader to use when loading the
      template. By default, it's ``django.template.loader``.

    * ``extra_context``: A dictionary of values to add to the template
      context. By default, this is an empty dictionary. If a value in the
      dictionary is callable, the generic view will call it
      just before rendering the template.

    * ``context_processors``: A list of template-context processors to apply to
      the view's template.

    * ``template_object_name``:  Designates the name of the template variable
      to use in the template context. By default, this is ``'object'``.

**Template name:**

If ``template_name`` isn't specified, this view will use the template
``<app_label>/<model_name>_confirm_delete.html`` by default.

**Template context:**

In addition to ``extra_context``, the template's context will be:

    * ``object``: The original object that's about to be deleted. This
      variable's name depends on the ``template_object_name`` parameter, which
      is ``'object'`` by default. If ``template_object_name`` is ``'foo'``,
      this variable's name will be ``foo``.