1
0
mirror of https://github.com/django/django.git synced 2024-12-24 18:16:19 +00:00
django/docs/generic_views.txt
Malcolm Tredinnick eb707d8c43 Clarified how extra_context values are evaluated and, in particular, how to
pass in a "live" QuerySet. Thanks to Jay Parlar for pointing out the potential
for confusion.


git-svn-id: http://code.djangoproject.com/svn/django/trunk@2931 bcc190cf-cafb-0310-a4f2-bffc1f526a37
2006-05-17 04:01:00 +00:00

995 lines
41 KiB
Plaintext

=============
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.
.. _database API docs: http://www.djangoproject.com/documentation/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.
**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.
**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. If it is not callable, it will be
evaluated once, at import time. Note that QuerySets are not callable, so
if you want to pass in a QuerySet in ``extra_context`` and have it
evaluated at render time, you need to wrap it in a function (that
returns the QuerySet).
* ``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 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: http://www.djangoproject.com/documentation/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.
**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. If it is not callable, it will be
evaluated once, at import time. Note that QuerySets are not callable, so
if you want to pass in a QuerySet in ``extra_context`` and have it
evaluated at render time, you need to wrap it in a function (that
returns the QuerySet).
* ``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 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.
``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.
**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. If it is not callable, it will be
evaluated once, at import time. Note that QuerySets are not callable, so
if you want to pass in a QuerySet in ``extra_context`` and have it
evaluated at render time, you need to wrap it in a function (that
returns the QuerySet).
* ``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.
**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.
**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. If it is not callable, it will be
evaluated once, at import time. Note that QuerySets are not callable, so
if you want to pass in a QuerySet in ``extra_context`` and have it
evaluated at render time, you need to wrap it in a function (that
returns the QuerySet).
* ``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.
**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.
**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. If it is not callable, it will be
evaluated once, at import time. Note that QuerySets are not callable, so
if you want to pass in a QuerySet in ``extra_context`` and have it
evaluated at render time, you need to wrap it in a function (that
returns the QuerySet).
* ``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.
**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 given 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.
**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.
**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. If it is not callable, it will be
evaluated once, at import time. Note that QuerySets are not callable, so
if you want to pass in a QuerySet in ``extra_context`` and have it
evaluated at render time, you need to wrap it in a function (that
returns the QuerySet).
* ``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'``.
**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 a ``page`` query
string (GET) parameter containing a zero-indexed page number.
* ``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. If it is not callable, it will be
evaluated once, at import time. Note that QuerySets are not callable, so
if you want to pass in a QuerySet in ``extra_context`` and have it
evaluated at render time, you need to wrap it in a function (that
returns the QuerySet).
* ``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.
**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:
* ``results_per_page``: The number of objects per page. (Same as the
``paginate_by`` parameter.)
* ``has_next``: A boolean representing whether there's a next page.
* ``has_previous``: A boolean representing whether there's a previous page.
* ``page``: The current page number, as an integer. This is 1-based.
* ``next``: The next page number, as an integer. If there's no next page,
this will still be an integer representing the theoretical next-page
number. This is 1-based.
* ``previous``: The previous page number, as an integer. This is 1-based.
* ``pages``: The total number of pages, as an integer.
* ``hits``: The total number of objects across *all* pages, not just this
page.
``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.
**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. If it is not callable, it will be
evaluated once, at import time. Note that QuerySets are not callable, so
if you want to pass in a QuerySet in ``extra_context`` and have it
evaluated at render time, you need to wrap it in a function (that
returns the QuerySet).
* ``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'``.
**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. This uses the
automatic manipulators that come with Django models.
**Required arguments:**
* ``model``: The Django model class of the object that the form will
create.
**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 `authentication system`_. 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. If it is not callable, it will be
evaluated once, at import time. Note that QuerySets are not callable, so
if you want to pass in a QuerySet in ``extra_context`` and have it
evaluated at render time, you need to wrap it in a function (that
returns the QuerySet).
* ``context_processors``: A list of template-context processors to apply to
the view's template. See the `RequestContext docs`_.
**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.FormWrapper`` instance representing the form
for editing the object. This lets you refer to form fields easily in the
template system.
For example, if ``model`` has two fields, ``name`` and ``address``::
<form action="" method="post">
<p><label for="id_name">Name:</label> {{ form.name }}</p>
<p><label for="id_address">Address:</label> {{ form.address }}</p>
</form>
See the `manipulator and formfield documentation`_ for more information
about using ``FormWrapper`` objects in templates.
.. _authentication system: http://www.djangoproject.com/documentation/authentication/
.. _manipulator and formfield documentation: http://www.djangoproject.com/documentation/forms/
``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 the automatic manipulators that come with Django models.
**Required arguments:**
* ``model``: The Django model class of the object that the form will
create.
* 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.
**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 `authentication system`_. 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. If it is not callable, it will be
evaluated once, at import time. Note that QuerySets are not callable, so
if you want to pass in a QuerySet in ``extra_context`` and have it
evaluated at render time, you need to wrap it in a function (that
returns the QuerySet).
* ``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'``.
**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.FormWrapper`` instance representing the form
for editing the object. This lets you refer to form fields easily in the
template system.
For example, if ``model`` has two fields, ``name`` and ``address``::
<form action="" method="post">
<p><label for="id_name">Name:</label> {{ form.name }}</p>
<p><label for="id_address">Address:</label> {{ form.address }}</p>
</form>
See the `manipulator and formfield documentation`_ for more information
about using ``FormWrapper`` 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
create.
* 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.
* ``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 `authentication system`_. 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. If it is not callable, it will be
evaluated once, at import time. Note that QuerySets are not callable, so
if you want to pass in a QuerySet in ``extra_context`` and have it
evaluated at render time, you need to wrap it in a function (that
returns the QuerySet).
* ``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'``.
**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``.