=============

Generic 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.

Django's generic views contain the following:

    * A set of views for doing list/detail interfaces (for example,

      Django's `documentation index`_ and `detail pages`_).

    * A set of views for year/month/day archive pages and associated

      detail and "latest" pages (for example, the Django weblog's year_,

      month_, day_, detail_, and latest_ pages).

    * A set of views for creating, editing, and deleting objects.

.. _`documentation index`: http://www.djangoproject.com/documentation/

.. _`detail pages`: http://www.djangoproject.com/documentation/faq/

.. _year: http://www.djangoproject.com/weblog/2005/

.. _month: http://www.djangoproject.com/weblog/2005/jul/

.. _day: http://www.djangoproject.com/weblog/2005/jul/20/

.. _detail: http://www.djangoproject.com/weblog/2005/jul/20/autoreload/

.. _latest: http://www.djangoproject.com/weblog/

All of these views are used by creating configuration dictionaries in

your URLconf files and passing those dictionaries as the third member of the

URLconf tuple for a given pattern. For example, here's the URLconf for the

simple weblog app that drives the blog on djangoproject.com::

    from django.conf.urls.defaults import *

    from django_website.apps.blog.models import Entry

    info_dict = {

        'queryset': Entry.objects.all(),

        'date_field': 'pub_date',

    }

    urlpatterns = patterns('django.views.generic.date_based',

       (r'^(?P<year>\d{4})/(?P<month>[a-z]{3})/(?P<day>\w{1,2})/(?P<slug>[-\w]+)/$', 'object_detail', dict(info_dict, slug_field='slug')),

       (r'^(?P<year>\d{4})/(?P<month>[a-z]{3})/(?P<day>\w{1,2})/$',               'archive_day',   info_dict),

       (r'^(?P<year>\d{4})/(?P<month>[a-z]{3})/$',                                'archive_month', info_dict),

       (r'^(?P<year>\d{4})/$',                                                    'archive_year',  info_dict),

       (r'^/?$',                                                                  'archive_index', info_dict),

    )

As you can see, this URLconf defines a few options in ``info_dict``.

``'queryset'`` gives the generic view a ``QuerySet`` of objects to use (in this

case, all of the ``Entry`` objects) and tells the generic view which model is

being used.

Documentation of each generic view follows, along with a list of all keyword

arguments that a generic view expects. Remember that as in the example above,

arguments may either come from the URL pattern (as ``month``, ``day``,

``year``, etc. do above) or from the additional-information dictionary (as for

``queryset``, ``date_field``, etc.).

Most generic views require the ``queryset`` key, which is a ``QuerySet``

instance; see the `database API docs`_ for more information about ``Queryset``

objects.

Most views also take an optional ``extra_context`` dictionary that you can use

to pass any auxiliary information you wish to the view. The values in the

``extra_context`` dictionary can be either functions (or other callables) or

other objects. Functions are evaluated just before they are passed to the

template. However, note that QuerySets retrieve and cache their data when they

are first evaluated, so if you want to pass in a QuerySet via

``extra_context`` that is always fresh you need to wrap it in a function or

lambda that returns the QuerySet.

.. _database API docs: ../db_api/

"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.

**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.

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.

**Example:**

This example redirects from ``/foo/<id>/`` to ``/bar/<id>/``::

    urlpatterns = patterns('django.views.generic.simple',

        ('^foo/(?P<id>\d+)/$', 'redirect_to', {'url': '/bar/%(id)s/'}),

    )

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

    urlpatterns = patterns('django.views.generic.simple',

        ('^bar/$', 'redirect_to', {'url': None}),

    )

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 ``False``.

    * ``context_processors``: A list of template-context processors to apply to

      the view's template. See the `RequestContext docs`_.

    * ``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.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 list of ``datetime.date`` objects representing all

      years that have objects available according to ``queryset``. 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``.

.. _RequestContext docs: ../templates_python/#subclassing-context-djangocontext

``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. See the `RequestContext docs`_.

    * ``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 list of ``datetime.date`` objects representing all

      months that have objects available in the given year, according to

      ``queryset``, 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. See the `RequestContext docs`_.

    * ``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:**

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

    * ``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://www.python.org/doc/current/lib/module-time.html#l2h-1941

``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. See the `RequestContext docs`_.

    * ``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. See the `RequestContext docs`_.

    * ``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