1274 lines
44 KiB
Plaintext
1274 lines
44 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', info_dict),
|
|
(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.
|
|
|
|
``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.
|
|
|
|
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
|
|
``True``.
|
|
|
|
``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_object_name`` (**New in Django development version**)
|
|
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 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``.
|
|
|
|
**New in Django development version:** 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``.
|
|
|
|
.. _RequestContext docs: ../templates_python/#subclassing-context-requestcontext
|
|
|
|
``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 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 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. 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. 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'``.
|
|
|
|
``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 (1-based) page number, as an integer, or the string ``'last'``.
|
|
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. 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.
|
|
|
|
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`` (**New in Django development version**)
|
|
An instance of ``django.core.paginator.Paginator``.
|
|
|
|
``page_obj`` (**New in Django development version**)
|
|
An instance of ``django.core.paginator.Page``.
|
|
|
|
See the `pagination documentation`_ for more information on the ``Paginator``
|
|
and ``Page`` objects.
|
|
|
|
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 `pagination documentation`_.
|
|
|
|
.. _`pagination documentation`: ../pagination/
|
|
|
|
**New in Django development version:**
|
|
|
|
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``)
|
|
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. 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'``.
|
|
|
|
``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.
|
|
|
|
**Changed in Django development version:**
|
|
|
|
``django.views.generic.create_update.create_object`` and
|
|
``django.views.generic.create_update.update_object`` now use the new `forms
|
|
library`_ to build and display the form.
|
|
|
|
.. _forms library: ../forms/
|
|
|
|
``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``
|
|
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 `ModelForm docs`_ 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 `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.
|
|
|
|
``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.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 `forms documentation`_ for more information about using ``Form``
|
|
objects in templates.
|
|
|
|
.. _authentication system: ../authentication/
|
|
.. _ModelForm docs: ../modelforms/
|
|
.. _forms 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 a form automatically generated from the object's
|
|
model class.
|
|
|
|
Required arguments
|
|
~~~~~~~~~~~~~~~~~~
|
|
|
|
Either ``form_class`` or ``model``
|
|
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 `ModelForm docs`_ 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``)
|
|
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 `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.
|
|
|
|
``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.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 `forms documentation`_ 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 create.
|
|
|
|
Either ``object_id`` or (``slug`` *and* ``slug_field``)
|
|
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 `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.
|
|
|
|
``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``.
|