1151 lines
46 KiB
Plaintext
1151 lines
46 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``.
|
|
|
|
* **New in Django development version:** ``template_object_name``:
|
|
Designates the name of the template variable to use in the template
|
|
context. By default, this is ``'latest'``.
|
|
|
|
**Template name:**
|
|
|
|
If ``template_name`` isn't specified, this view will use the template
|
|
``<app_label>/<model_name>_archive.html`` by default, where:
|
|
|
|
* ``<model_name>`` is your model's name in all lowercase. For a model
|
|
``StaffMember``, that'd be ``staffmember``.
|
|
|
|
* ``<app_label>`` is the right-most part of the full Python path to
|
|
your model's app. For example, if your model lives in
|
|
``apps/blog/models.py``, that'd be ``blog``.
|
|
|
|
**Template context:**
|
|
|
|
In addition to ``extra_context``, the template's context will be:
|
|
|
|
* ``date_list``: A 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 page number, as an integer. This is 1-based.
|
|
See `Notes on pagination`_ below.
|
|
|
|
* ``template_name``: The full name of a template to use in rendering the
|
|
page. This lets you override the default template name (see below).
|
|
|
|
* ``template_loader``: The template loader to use when loading the
|
|
template. By default, it's ``django.template.loader``.
|
|
|
|
* ``extra_context``: A dictionary of values to add to the template
|
|
context. By default, this is an empty dictionary. If a value in the
|
|
dictionary is callable, the generic view will call it
|
|
just before rendering the template.
|
|
|
|
* ``allow_empty``: A boolean specifying whether to display the page if no
|
|
objects are available. If this is ``False`` and no objects are available,
|
|
the view will raise a 404 instead of displaying an empty page. By
|
|
default, this is ``True``.
|
|
|
|
* ``context_processors``: A list of template-context processors to apply to
|
|
the view's template. 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:
|
|
|
|
* **New in Django development version:** ``paginator``: An instance of
|
|
``django.core.paginator.Paginator``.
|
|
|
|
* **New in Django development version:** ``page_obj``: An instance of
|
|
``django.core.paginator.Page``.
|
|
|
|
In older versions of Django, before ``paginator`` and ``page_obj`` were added
|
|
to this template's context, the template included several other variables
|
|
related to pagination. Note that you should *NOT* use these variables anymore;
|
|
use ``paginator`` and ``page_obj`` instead, because they let you do everything
|
|
these old variables let you do (and more!). But for legacy installations,
|
|
here's a list of those old template 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.
|
|
|
|
* ``last_on_page``: The number of the
|
|
last result on the current page. This is 1-based.
|
|
|
|
* ``first_on_page``: The number of the
|
|
first result on the current page. 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.
|
|
|
|
* ``page_range``: A list of the page numbers that are available. This is
|
|
1-based.
|
|
|
|
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``) is required.
|
|
|
|
If you provide ``object_id``, it should be the value of the primary-key
|
|
field for the object being displayed on this page.
|
|
|
|
Otherwise, ``slug`` should be the slug of the given object, and
|
|
``slug_field`` should be the name of the slug field in the ``QuerySet``'s
|
|
model. By default, ``slug_field`` is ``'slug'``.
|
|
|
|
**Optional arguments:**
|
|
|
|
* ``template_name``: The full name of a template to use in rendering the
|
|
page. This lets you override the default template name (see below).
|
|
|
|
* ``template_name_field``: The name of a field on the object whose value is
|
|
the template name to use. This lets you store template names in the data.
|
|
In other words, if your object has a field ``'the_template'`` that
|
|
contains a string ``'foo.html'``, and you set ``template_name_field`` to
|
|
``'the_template'``, then the generic view for this object will use the
|
|
template ``'foo.html'``.
|
|
|
|
It's a bit of a brain-bender, but it's useful in some cases.
|
|
|
|
* ``template_loader``: The template loader to use when loading the
|
|
template. By default, it's ``django.template.loader``.
|
|
|
|
* ``extra_context``: A dictionary of values to add to the template
|
|
context. By default, this is an empty dictionary. If a value in the
|
|
dictionary is callable, the generic view will call it
|
|
just before rendering the template.
|
|
|
|
* ``context_processors``: A list of template-context processors to apply to
|
|
the view's template. 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`` is required.
|
|
|
|
If you provide ``form_class``, it should be a
|
|
``django.forms.ModelForm`` subclass. Use this argument when you need
|
|
to customize the model's form. See the `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 the automatic manipulators that come with Django models.
|
|
|
|
**Required arguments:**
|
|
|
|
* Either ``form_class`` or ``model`` is required.
|
|
|
|
If you provide ``form_class``, it should be a
|
|
``django.forms.ModelForm`` subclass. Use this argument when you need
|
|
to customize the model's form. See the `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``) is required.
|
|
|
|
If you provide ``object_id``, it should be the value of the primary-key
|
|
field for the object being displayed on this page.
|
|
|
|
Otherwise, ``slug`` should be the slug of the given object, and
|
|
``slug_field`` should be the name of the slug field in the ``QuerySet``'s
|
|
model. By default, ``slug_field`` is ``'slug'``.
|
|
|
|
**Optional arguments:**
|
|
|
|
* ``post_save_redirect``: A URL to which the view will redirect after
|
|
saving the object. By default, it's ``object.get_absolute_url()``.
|
|
|
|
``post_save_redirect`` may contain dictionary string formatting, which
|
|
will be interpolated against the object's field attributes. For example,
|
|
you could use ``post_save_redirect="/polls/%(slug)s/"``.
|
|
|
|
* ``login_required``: A boolean that designates whether a user must be
|
|
logged in, in order to see the page and save changes. This hooks into the
|
|
Django `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``) is required.
|
|
|
|
If you provide ``object_id``, it should be the value of the primary-key
|
|
field for the object being displayed on this page.
|
|
|
|
Otherwise, ``slug`` should be the slug of the given object, and
|
|
``slug_field`` should be the name of the slug field in the ``QuerySet``'s
|
|
model. By default, ``slug_field`` is ``'slug'``.
|
|
|
|
* ``post_delete_redirect``: A URL to which the view will redirect after
|
|
deleting the object.
|
|
|
|
**Optional arguments:**
|
|
|
|
* ``login_required``: A boolean that designates whether a user must be
|
|
logged in, in order to see the page and save changes. This hooks into the
|
|
Django `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``.
|