1096 lines
43 KiB
Plaintext
1096 lines
43 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.
|
|
|
|
A general introduction to generic views can be found in the :doc:`topic guide
|
|
</topics/http/generic-views>`.
|
|
|
|
This reference contains details of Django's built-in generic views, along with
|
|
a list of all keyword arguments that a generic view expects. Remember that
|
|
arguments may either come from the URL pattern or from the ``extra_context``
|
|
additional-information dictionary.
|
|
|
|
Most generic views require the ``queryset`` key, which is a ``QuerySet``
|
|
instance; see :doc:`/topics/db/queries` for more information about ``QuerySet``
|
|
objects.
|
|
|
|
"Simple" generic views
|
|
======================
|
|
|
|
The ``django.views.generic.simple`` module contains simple views to handle a
|
|
couple of common cases: rendering a template when no view logic is needed,
|
|
and issuing a redirect.
|
|
|
|
``django.views.generic.simple.direct_to_template``
|
|
--------------------------------------------------
|
|
|
|
**Description:**
|
|
|
|
Renders a given template, passing it a ``{{ params }}`` template variable,
|
|
which is a dictionary of the parameters captured in the URL.
|
|
|
|
**Required arguments:**
|
|
|
|
* ``template``: The full name of a template to use.
|
|
|
|
**Optional arguments:**
|
|
|
|
* ``extra_context``: A dictionary of values to add to the template
|
|
context. By default, this is an empty dictionary. If a value in the
|
|
dictionary is callable, the generic view will call it
|
|
just before rendering the template.
|
|
|
|
* ``mimetype``: The MIME type to use for the resulting document. Defaults
|
|
to the value of the ``DEFAULT_CONTENT_TYPE`` setting.
|
|
|
|
**Example:**
|
|
|
|
Given the following URL patterns::
|
|
|
|
urlpatterns = patterns('django.views.generic.simple',
|
|
(r'^foo/$', 'direct_to_template', {'template': 'foo_index.html'}),
|
|
(r'^foo/(?P<id>\d+)/$', 'direct_to_template', {'template': 'foo_detail.html'}),
|
|
)
|
|
|
|
... a request to ``/foo/`` would render the template ``foo_index.html``, and a
|
|
request to ``/foo/15/`` would render the ``foo_detail.html`` with a context
|
|
variable ``{{ params.id }}`` that is set to ``15``.
|
|
|
|
``django.views.generic.simple.redirect_to``
|
|
-------------------------------------------
|
|
|
|
**Description:**
|
|
|
|
Redirects to a given URL.
|
|
|
|
The given URL may contain dictionary-style string formatting, which will be
|
|
interpolated against the parameters captured in the URL. Because keyword
|
|
interpolation is *always* done (even if no arguments are passed in), any ``"%"``
|
|
characters in the URL must be written as ``"%%"`` so that Python will convert
|
|
them to a single percent sign on output.
|
|
|
|
If the given URL is ``None``, Django will return an ``HttpResponseGone`` (410).
|
|
|
|
**Required arguments:**
|
|
|
|
* ``url``: The URL to redirect to, as a string. Or ``None`` to raise a 410
|
|
(Gone) HTTP error.
|
|
|
|
**Optional arguments:**
|
|
|
|
* ``permanent``: Whether the redirect should be permanent. The only
|
|
difference here is the HTTP status code returned. If ``True``, then the
|
|
redirect will use status code 301. If ``False``, then the redirect will
|
|
use status code 302. By default, ``permanent`` is ``True``.
|
|
|
|
.. versionadded:: 1.1
|
|
The ``permanent`` keyword argument is new in Django 1.1.
|
|
|
|
**Example:**
|
|
|
|
This example issues a permanent redirect (HTTP status code 301) from
|
|
``/foo/<id>/`` to ``/bar/<id>/``::
|
|
|
|
urlpatterns = patterns('django.views.generic.simple',
|
|
('^foo/(?P<id>\d+)/$', 'redirect_to', {'url': '/bar/%(id)s/'}),
|
|
)
|
|
|
|
This example issues a non-permanent redirect (HTTP status code 302) from
|
|
``/foo/<id>/`` to ``/bar/<id>/``::
|
|
|
|
urlpatterns = patterns('django.views.generic.simple',
|
|
('^foo/(?P<id>\d+)/$', 'redirect_to', {'url': '/bar/%(id)s/', 'permanent': False}),
|
|
)
|
|
|
|
This example returns a 410 HTTP error for requests to ``/bar/``::
|
|
|
|
urlpatterns = patterns('django.views.generic.simple',
|
|
('^bar/$', 'redirect_to', {'url': None}),
|
|
)
|
|
|
|
This example shows how ``"%"`` characters must be written in the URL in order
|
|
to avoid confusion with Python's string formatting markers. If the redirect
|
|
string is written as ``"%7Ejacob/"`` (with only a single ``%``), an exception would be raised::
|
|
|
|
urlpatterns = patterns('django.views.generic.simple',
|
|
('^bar/$', 'redirect_to', {'url': '%%7Ejacob.'}),
|
|
)
|
|
|
|
Date-based generic views
|
|
========================
|
|
|
|
Date-based generic views (in the module ``django.views.generic.date_based``)
|
|
are views for displaying drilldown pages for date-based data.
|
|
|
|
``django.views.generic.date_based.archive_index``
|
|
-------------------------------------------------
|
|
|
|
**Description:**
|
|
|
|
A top-level index page showing the "latest" objects, by date. Objects with
|
|
a date in the *future* are not included unless you set ``allow_future`` to
|
|
``True``.
|
|
|
|
**Required arguments:**
|
|
|
|
* ``queryset``: A ``QuerySet`` of objects for which the archive serves.
|
|
|
|
* ``date_field``: The name of the ``DateField`` or ``DateTimeField`` in
|
|
the ``QuerySet``'s model that the date-based archive should use to
|
|
determine the objects on the page.
|
|
|
|
**Optional arguments:**
|
|
|
|
* ``num_latest``: The number of latest objects to send to the template
|
|
context. By default, it's 15.
|
|
|
|
* ``template_name``: The full name of a template to use in rendering the
|
|
page. This lets you override the default template name (see below).
|
|
|
|
* ``template_loader``: The template loader to use when loading the
|
|
template. By default, it's ``django.template.loader``.
|
|
|
|
* ``extra_context``: A dictionary of values to add to the template
|
|
context. By default, this is an empty dictionary. If a value in the
|
|
dictionary is callable, the generic view will call it
|
|
just before rendering the template.
|
|
|
|
* ``allow_empty``: A boolean specifying whether to display the page if no
|
|
objects are available. If this is ``False`` and no objects are available,
|
|
the view will raise a 404 instead of displaying an empty page. By
|
|
default, this is ``True``.
|
|
|
|
* ``context_processors``: A list of template-context processors to apply to
|
|
the view's template.
|
|
|
|
* ``mimetype``: The MIME type to use for the resulting document. Defaults
|
|
to the value of the ``DEFAULT_CONTENT_TYPE`` setting.
|
|
|
|
* ``allow_future``: A boolean specifying whether to include "future"
|
|
objects on this page, where "future" means objects in which the field
|
|
specified in ``date_field`` is greater than the current date/time. By
|
|
default, this is ``False``.
|
|
|
|
.. versionadded:: 1.0
|
|
|
|
* ``template_object_name``: Designates the name of the template variable
|
|
to use in the template context. By default, this is ``'latest'``.
|
|
|
|
**Template name:**
|
|
|
|
If ``template_name`` isn't specified, this view will use the template
|
|
``<app_label>/<model_name>_archive.html`` by default, where:
|
|
|
|
* ``<model_name>`` is your model's name in all lowercase. For a model
|
|
``StaffMember``, that'd be ``staffmember``.
|
|
|
|
* ``<app_label>`` is the right-most part of the full Python path to
|
|
your model's app. For example, if your model lives in
|
|
``apps/blog/models.py``, that'd be ``blog``.
|
|
|
|
**Template context:**
|
|
|
|
In addition to ``extra_context``, the template's context will be:
|
|
|
|
* ``date_list``: A ``DateQuerySet`` object containing all years that have
|
|
have objects available according to ``queryset``, represented as
|
|
``datetime.datetime`` objects. These are ordered in reverse. This is
|
|
equivalent to ``queryset.dates(date_field, 'year')[::-1]``.
|
|
|
|
.. versionchanged:: 1.0
|
|
The behaviour depending on ``template_object_name`` is new in this version.
|
|
|
|
* ``latest``: The ``num_latest`` objects in the system, ordered descending
|
|
by ``date_field``. For example, if ``num_latest`` is ``10``, then
|
|
``latest`` will be a list of the latest 10 objects in ``queryset``.
|
|
|
|
This variable's name depends on the ``template_object_name`` parameter,
|
|
which is ``'latest'`` by default. If ``template_object_name`` is
|
|
``'foo'``, this variable's name will be ``foo``.
|
|
|
|
``django.views.generic.date_based.archive_year``
|
|
------------------------------------------------
|
|
|
|
**Description:**
|
|
|
|
A yearly archive page showing all available months in a given year. Objects
|
|
with a date in the *future* are not displayed unless you set ``allow_future``
|
|
to ``True``.
|
|
|
|
**Required arguments:**
|
|
|
|
* ``year``: The four-digit year for which the archive serves.
|
|
|
|
* ``queryset``: A ``QuerySet`` of objects for which the archive serves.
|
|
|
|
* ``date_field``: The name of the ``DateField`` or ``DateTimeField`` in
|
|
the ``QuerySet``'s model that the date-based archive should use to
|
|
determine the objects on the page.
|
|
|
|
**Optional arguments:**
|
|
|
|
* ``template_name``: The full name of a template to use in rendering the
|
|
page. This lets you override the default template name (see below).
|
|
|
|
* ``template_loader``: The template loader to use when loading the
|
|
template. By default, it's ``django.template.loader``.
|
|
|
|
* ``extra_context``: A dictionary of values to add to the template
|
|
context. By default, this is an empty dictionary. If a value in the
|
|
dictionary is callable, the generic view will call it
|
|
just before rendering the template.
|
|
|
|
* ``allow_empty``: A boolean specifying whether to display the page if no
|
|
objects are available. If this is ``False`` and no objects are available,
|
|
the view will raise a 404 instead of displaying an empty page. By
|
|
default, this is ``False``.
|
|
|
|
* ``context_processors``: A list of template-context processors to apply to
|
|
the view's template.
|
|
|
|
* ``template_object_name``: Designates the name of the template variable
|
|
to use in the template context. By default, this is ``'object'``. The
|
|
view will append ``'_list'`` to the value of this parameter in
|
|
determining the variable's name.
|
|
|
|
* ``make_object_list``: A boolean specifying whether to retrieve the full
|
|
list of objects for this year and pass those to the template. If ``True``,
|
|
this list of objects will be made available to the template as
|
|
``object_list``. (The name ``object_list`` may be different; see the docs
|
|
for ``object_list`` in the "Template context" section below.) By default,
|
|
this is ``False``.
|
|
|
|
* ``mimetype``: The MIME type to use for the resulting document. Defaults
|
|
to the value of the ``DEFAULT_CONTENT_TYPE`` setting.
|
|
|
|
* ``allow_future``: A boolean specifying whether to include "future"
|
|
objects on this page, where "future" means objects in which the field
|
|
specified in ``date_field`` is greater than the current date/time. By
|
|
default, this is ``False``.
|
|
|
|
**Template name:**
|
|
|
|
If ``template_name`` isn't specified, this view will use the template
|
|
``<app_label>/<model_name>_archive_year.html`` by default.
|
|
|
|
**Template context:**
|
|
|
|
In addition to ``extra_context``, the template's context will be:
|
|
|
|
* ``date_list``: A ``DateQuerySet`` object containing all months that have
|
|
have objects available according to ``queryset``, represented as
|
|
``datetime.datetime`` objects, in ascending order.
|
|
|
|
* ``year``: The given year, as a four-character string.
|
|
|
|
* ``object_list``: If the ``make_object_list`` parameter is ``True``, this
|
|
will be set to a list of objects available for the given year, ordered by
|
|
the date field. This variable's name depends on the
|
|
``template_object_name`` parameter, which is ``'object'`` by default. If
|
|
``template_object_name`` is ``'foo'``, this variable's name will be
|
|
``foo_list``.
|
|
|
|
If ``make_object_list`` is ``False``, ``object_list`` will be passed to
|
|
the template as an empty list.
|
|
|
|
``django.views.generic.date_based.archive_month``
|
|
-------------------------------------------------
|
|
|
|
**Description:**
|
|
|
|
A monthly archive page showing all objects in a given month. Objects with a
|
|
date in the *future* are not displayed unless you set ``allow_future`` to
|
|
``True``.
|
|
|
|
**Required arguments:**
|
|
|
|
* ``year``: The four-digit year for which the archive serves (a string).
|
|
|
|
* ``month``: The month for which the archive serves, formatted according to
|
|
the ``month_format`` argument.
|
|
|
|
* ``queryset``: A ``QuerySet`` of objects for which the archive serves.
|
|
|
|
* ``date_field``: The name of the ``DateField`` or ``DateTimeField`` in
|
|
the ``QuerySet``'s model that the date-based archive should use to
|
|
determine the objects on the page.
|
|
|
|
**Optional arguments:**
|
|
|
|
* ``month_format``: A format string that regulates what format the
|
|
``month`` parameter uses. This should be in the syntax accepted by
|
|
Python's ``time.strftime``. (See the `strftime docs`_.) It's set to
|
|
``"%b"`` by default, which is a three-letter month abbreviation. To
|
|
change it to use numbers, use ``"%m"``.
|
|
|
|
* ``template_name``: The full name of a template to use in rendering the
|
|
page. This lets you override the default template name (see below).
|
|
|
|
* ``template_loader``: The template loader to use when loading the
|
|
template. By default, it's ``django.template.loader``.
|
|
|
|
* ``extra_context``: A dictionary of values to add to the template
|
|
context. By default, this is an empty dictionary. If a value in the
|
|
dictionary is callable, the generic view will call it
|
|
just before rendering the template.
|
|
|
|
* ``allow_empty``: A boolean specifying whether to display the page if no
|
|
objects are available. If this is ``False`` and no objects are available,
|
|
the view will raise a 404 instead of displaying an empty page. By
|
|
default, this is ``False``.
|
|
|
|
* ``context_processors``: A list of template-context processors to apply to
|
|
the view's template.
|
|
|
|
* ``template_object_name``: Designates the name of the template variable
|
|
to use in the template context. By default, this is ``'object'``. The
|
|
view will append ``'_list'`` to the value of this parameter in
|
|
determining the variable's name.
|
|
|
|
* ``mimetype``: The MIME type to use for the resulting document. Defaults
|
|
to the value of the ``DEFAULT_CONTENT_TYPE`` setting.
|
|
|
|
* ``allow_future``: A boolean specifying whether to include "future"
|
|
objects on this page, where "future" means objects in which the field
|
|
specified in ``date_field`` is greater than the current date/time. By
|
|
default, this is ``False``.
|
|
|
|
**Template name:**
|
|
|
|
If ``template_name`` isn't specified, this view will use the template
|
|
``<app_label>/<model_name>_archive_month.html`` by default.
|
|
|
|
**Template context:**
|
|
|
|
.. versionadded:: 1.2
|
|
The inclusion of ``date_list`` in the template's context is new.
|
|
|
|
In addition to ``extra_context``, the template's context will be:
|
|
|
|
* ``date_list``: A ``DateQuerySet`` object containing all days that have
|
|
have objects available in the given month, according to ``queryset``,
|
|
represented as ``datetime.datetime`` objects, in ascending order.
|
|
|
|
* ``month``: A ``datetime.date`` object representing the given month.
|
|
|
|
* ``next_month``: A ``datetime.date`` object representing the first day of
|
|
the next month. If the next month is in the future, this will be
|
|
``None``.
|
|
|
|
* ``previous_month``: A ``datetime.date`` object representing the first day
|
|
of the previous month. Unlike ``next_month``, this will never be
|
|
``None``.
|
|
|
|
* ``object_list``: A list of objects available for the given month. This
|
|
variable's name depends on the ``template_object_name`` parameter, which
|
|
is ``'object'`` by default. If ``template_object_name`` is ``'foo'``,
|
|
this variable's name will be ``foo_list``.
|
|
|
|
.. _strftime docs: http://docs.python.org/library/time.html#time.strftime
|
|
|
|
``django.views.generic.date_based.archive_week``
|
|
------------------------------------------------
|
|
|
|
**Description:**
|
|
|
|
A weekly archive page showing all objects in a given week. Objects with a date
|
|
in the *future* are not displayed unless you set ``allow_future`` to ``True``.
|
|
|
|
**Required arguments:**
|
|
|
|
* ``year``: The four-digit year for which the archive serves (a string).
|
|
|
|
* ``week``: The week of the year for which the archive serves (a string).
|
|
Weeks start with Sunday.
|
|
|
|
* ``queryset``: A ``QuerySet`` of objects for which the archive serves.
|
|
|
|
* ``date_field``: The name of the ``DateField`` or ``DateTimeField`` in
|
|
the ``QuerySet``'s model that the date-based archive should use to
|
|
determine the objects on the page.
|
|
|
|
**Optional arguments:**
|
|
|
|
* ``template_name``: The full name of a template to use in rendering the
|
|
page. This lets you override the default template name (see below).
|
|
|
|
* ``template_loader``: The template loader to use when loading the
|
|
template. By default, it's ``django.template.loader``.
|
|
|
|
* ``extra_context``: A dictionary of values to add to the template
|
|
context. By default, this is an empty dictionary. If a value in the
|
|
dictionary is callable, the generic view will call it
|
|
just before rendering the template.
|
|
|
|
* ``allow_empty``: A boolean specifying whether to display the page if no
|
|
objects are available. If this is ``False`` and no objects are available,
|
|
the view will raise a 404 instead of displaying an empty page. By
|
|
default, this is ``True``.
|
|
|
|
* ``context_processors``: A list of template-context processors to apply to
|
|
the view's template.
|
|
|
|
* ``template_object_name``: Designates the name of the template variable
|
|
to use in the template context. By default, this is ``'object'``. The
|
|
view will append ``'_list'`` to the value of this parameter in
|
|
determining the variable's name.
|
|
|
|
* ``mimetype``: The MIME type to use for the resulting document. Defaults
|
|
to the value of the ``DEFAULT_CONTENT_TYPE`` setting.
|
|
|
|
* ``allow_future``: A boolean specifying whether to include "future"
|
|
objects on this page, where "future" means objects in which the field
|
|
specified in ``date_field`` is greater than the current date/time. By
|
|
default, this is ``False``.
|
|
|
|
**Template name:**
|
|
|
|
If ``template_name`` isn't specified, this view will use the template
|
|
``<app_label>/<model_name>_archive_week.html`` by default.
|
|
|
|
**Template context:**
|
|
|
|
In addition to ``extra_context``, the template's context will be:
|
|
|
|
* ``week``: A ``datetime.date`` object representing the first day of the
|
|
given week.
|
|
|
|
* ``object_list``: A list of objects available for the given week. This
|
|
variable's name depends on the ``template_object_name`` parameter, which
|
|
is ``'object'`` by default. If ``template_object_name`` is ``'foo'``,
|
|
this variable's name will be ``foo_list``.
|
|
|
|
``django.views.generic.date_based.archive_day``
|
|
-----------------------------------------------
|
|
|
|
**Description:**
|
|
|
|
A day archive page showing all objects in a given day. Days in the future throw
|
|
a 404 error, regardless of whether any objects exist for future days, unless
|
|
you set ``allow_future`` to ``True``.
|
|
|
|
**Required arguments:**
|
|
|
|
* ``year``: The four-digit year for which the archive serves (a string).
|
|
|
|
* ``month``: The month for which the archive serves, formatted according to
|
|
the ``month_format`` argument.
|
|
|
|
* ``day``: The day for which the archive serves, formatted according to the
|
|
``day_format`` argument.
|
|
|
|
* ``queryset``: A ``QuerySet`` of objects for which the archive serves.
|
|
|
|
* ``date_field``: The name of the ``DateField`` or ``DateTimeField`` in
|
|
the ``QuerySet``'s model that the date-based archive should use to
|
|
determine the objects on the page.
|
|
|
|
**Optional arguments:**
|
|
|
|
* ``month_format``: A format string that regulates what format the
|
|
``month`` parameter uses. This should be in the syntax accepted by
|
|
Python's ``time.strftime``. (See the `strftime docs`_.) It's set to
|
|
``"%b"`` by default, which is a three-letter month abbreviation. To
|
|
change it to use numbers, use ``"%m"``.
|
|
|
|
* ``day_format``: Like ``month_format``, but for the ``day`` parameter.
|
|
It defaults to ``"%d"`` (day of the month as a decimal number, 01-31).
|
|
|
|
* ``template_name``: The full name of a template to use in rendering the
|
|
page. This lets you override the default template name (see below).
|
|
|
|
* ``template_loader``: The template loader to use when loading the
|
|
template. By default, it's ``django.template.loader``.
|
|
|
|
* ``extra_context``: A dictionary of values to add to the template
|
|
context. By default, this is an empty dictionary. If a value in the
|
|
dictionary is callable, the generic view will call it
|
|
just before rendering the template.
|
|
|
|
* ``allow_empty``: A boolean specifying whether to display the page if no
|
|
objects are available. If this is ``False`` and no objects are available,
|
|
the view will raise a 404 instead of displaying an empty page. By
|
|
default, this is ``False``.
|
|
|
|
* ``context_processors``: A list of template-context processors to apply to
|
|
the view's template.
|
|
|
|
* ``template_object_name``: Designates the name of the template variable
|
|
to use in the template context. By default, this is ``'object'``. The
|
|
view will append ``'_list'`` to the value of this parameter in
|
|
determining the variable's name.
|
|
|
|
* ``mimetype``: The MIME type to use for the resulting document. Defaults
|
|
to the value of the ``DEFAULT_CONTENT_TYPE`` setting.
|
|
|
|
* ``allow_future``: A boolean specifying whether to include "future"
|
|
objects on this page, where "future" means objects in which the field
|
|
specified in ``date_field`` is greater than the current date/time. By
|
|
default, this is ``False``.
|
|
|
|
**Template name:**
|
|
|
|
If ``template_name`` isn't specified, this view will use the template
|
|
``<app_label>/<model_name>_archive_day.html`` by default.
|
|
|
|
**Template context:**
|
|
|
|
In addition to ``extra_context``, the template's context will be:
|
|
|
|
* ``day``: A ``datetime.date`` object representing the given day.
|
|
|
|
* ``next_day``: A ``datetime.date`` object representing the next day. If
|
|
the next day is in the future, this will be ``None``.
|
|
|
|
* ``previous_day``: A ``datetime.date`` object representing the previous day.
|
|
Unlike ``next_day``, this will never be ``None``.
|
|
|
|
* ``object_list``: A list of objects available for the given day. This
|
|
variable's name depends on the ``template_object_name`` parameter, which
|
|
is ``'object'`` by default. If ``template_object_name`` is ``'foo'``,
|
|
this variable's name will be ``foo_list``.
|
|
|
|
``django.views.generic.date_based.archive_today``
|
|
-------------------------------------------------
|
|
|
|
**Description:**
|
|
|
|
A day archive page showing all objects for *today*. This is exactly the same as
|
|
``archive_day``, except the ``year``/``month``/``day`` arguments are not used,
|
|
and today's date is used instead.
|
|
|
|
``django.views.generic.date_based.object_detail``
|
|
-------------------------------------------------
|
|
|
|
**Description:**
|
|
|
|
A page representing an individual object. If the object has a date value in the
|
|
future, the view will throw a 404 error by default, unless you set
|
|
``allow_future`` to ``True``.
|
|
|
|
**Required arguments:**
|
|
|
|
* ``year``: The object's four-digit year (a string).
|
|
|
|
* ``month``: The object's month , formatted according to the
|
|
``month_format`` argument.
|
|
|
|
* ``day``: The object's day , formatted according to the ``day_format``
|
|
argument.
|
|
|
|
* ``queryset``: A ``QuerySet`` that contains the object.
|
|
|
|
* ``date_field``: The name of the ``DateField`` or ``DateTimeField`` in
|
|
the ``QuerySet``'s model that the generic view should use to look up the
|
|
object according to ``year``, ``month`` and ``day``.
|
|
|
|
* Either ``object_id`` or (``slug`` *and* ``slug_field``) is required.
|
|
|
|
If you provide ``object_id``, it should be the value of the primary-key
|
|
field for the object being displayed on this page.
|
|
|
|
Otherwise, ``slug`` should be the slug of the given object, and
|
|
``slug_field`` should be the name of the slug field in the ``QuerySet``'s
|
|
model. By default, ``slug_field`` is ``'slug'``.
|
|
|
|
**Optional arguments:**
|
|
|
|
* ``month_format``: A format string that regulates what format the
|
|
``month`` parameter uses. This should be in the syntax accepted by
|
|
Python's ``time.strftime``. (See the `strftime docs`_.) It's set to
|
|
``"%b"`` by default, which is a three-letter month abbreviation. To
|
|
change it to use numbers, use ``"%m"``.
|
|
|
|
* ``day_format``: Like ``month_format``, but for the ``day`` parameter.
|
|
It defaults to ``"%d"`` (day of the month as a decimal number, 01-31).
|
|
|
|
* ``template_name``: The full name of a template to use in rendering the
|
|
page. This lets you override the default template name (see below).
|
|
|
|
* ``template_name_field``: The name of a field on the object whose value is
|
|
the template name to use. This lets you store template names in the data.
|
|
In other words, if your object has a field ``'the_template'`` that
|
|
contains a string ``'foo.html'``, and you set ``template_name_field`` to
|
|
``'the_template'``, then the generic view for this object will use the
|
|
template ``'foo.html'``.
|
|
|
|
It's a bit of a brain-bender, but it's useful in some cases.
|
|
|
|
* ``template_loader``: The template loader to use when loading the
|
|
template. By default, it's ``django.template.loader``.
|
|
|
|
* ``extra_context``: A dictionary of values to add to the template
|
|
context. By default, this is an empty dictionary. If a value in the
|
|
dictionary is callable, the generic view will call it
|
|
just before rendering the template.
|
|
|
|
* ``context_processors``: A list of template-context processors to apply to
|
|
the view's template.
|
|
|
|
* ``template_object_name``: Designates the name of the template variable
|
|
to use in the template context. By default, this is ``'object'``.
|
|
|
|
* ``mimetype``: The MIME type to use for the resulting document. Defaults
|
|
to the value of the ``DEFAULT_CONTENT_TYPE`` setting.
|
|
|
|
* ``allow_future``: A boolean specifying whether to include "future"
|
|
objects on this page, where "future" means objects in which the field
|
|
specified in ``date_field`` is greater than the current date/time. By
|
|
default, this is ``False``.
|
|
|
|
**Template name:**
|
|
|
|
If ``template_name`` isn't specified, this view will use the template
|
|
``<app_label>/<model_name>_detail.html`` by default.
|
|
|
|
**Template context:**
|
|
|
|
In addition to ``extra_context``, the template's context will be:
|
|
|
|
* ``object``: The object. This variable's name depends on the
|
|
``template_object_name`` parameter, which is ``'object'`` by default. If
|
|
``template_object_name`` is ``'foo'``, this variable's name will be
|
|
``foo``.
|
|
|
|
List/detail generic views
|
|
=========================
|
|
|
|
The list-detail generic-view framework (in the
|
|
``django.views.generic.list_detail`` module) is similar to the date-based one,
|
|
except the former simply has two views: a list of objects and an individual
|
|
object page.
|
|
|
|
``django.views.generic.list_detail.object_list``
|
|
------------------------------------------------
|
|
|
|
**Description:**
|
|
|
|
A page representing a list of objects.
|
|
|
|
**Required arguments:**
|
|
|
|
* ``queryset``: A ``QuerySet`` that represents the objects.
|
|
|
|
**Optional arguments:**
|
|
|
|
* ``paginate_by``: An integer specifying how many objects should be
|
|
displayed per page. If this is given, the view will paginate objects with
|
|
``paginate_by`` objects per page. The view will expect either a ``page``
|
|
query string parameter (via ``GET``) or a ``page`` variable specified in
|
|
the URLconf. See `Notes on pagination`_ below.
|
|
|
|
* ``page``: The current page number, as an integer, or the string
|
|
``'last'``. This is 1-based. See `Notes on pagination`_ below.
|
|
|
|
* ``template_name``: The full name of a template to use in rendering the
|
|
page. This lets you override the default template name (see below).
|
|
|
|
* ``template_loader``: The template loader to use when loading the
|
|
template. By default, it's ``django.template.loader``.
|
|
|
|
* ``extra_context``: A dictionary of values to add to the template
|
|
context. By default, this is an empty dictionary. If a value in the
|
|
dictionary is callable, the generic view will call it
|
|
just before rendering the template.
|
|
|
|
* ``allow_empty``: A boolean specifying whether to display the page if no
|
|
objects are available. If this is ``False`` and no objects are available,
|
|
the view will raise a 404 instead of displaying an empty page. By
|
|
default, this is ``True``.
|
|
|
|
* ``context_processors``: A list of template-context processors to apply to
|
|
the view's template.
|
|
|
|
* ``template_object_name``: Designates the name of the template variable
|
|
to use in the template context. By default, this is ``'object'``. The
|
|
view will append ``'_list'`` to the value of this parameter in
|
|
determining the variable's name.
|
|
|
|
* ``mimetype``: The MIME type to use for the resulting document. Defaults
|
|
to the value of the ``DEFAULT_CONTENT_TYPE`` setting.
|
|
|
|
**Template name:**
|
|
|
|
If ``template_name`` isn't specified, this view will use the template
|
|
``<app_label>/<model_name>_list.html`` by default.
|
|
|
|
**Template context:**
|
|
|
|
.. versionadded:: 1.0
|
|
The ``paginator`` and ``page_obj`` context variables are new.
|
|
|
|
In addition to ``extra_context``, the template's context will be:
|
|
|
|
* ``object_list``: The list of objects. This variable's name depends on the
|
|
``template_object_name`` parameter, which is ``'object'`` by default. If
|
|
``template_object_name`` is ``'foo'``, this variable's name will be
|
|
``foo_list``.
|
|
|
|
* ``is_paginated``: A boolean representing whether the results are
|
|
paginated. Specifically, this is set to ``False`` if the number of
|
|
available objects is less than or equal to ``paginate_by``.
|
|
|
|
If the results are paginated, the context will contain these extra variables:
|
|
|
|
* ``paginator``: An instance of ``django.core.paginator.Paginator``.
|
|
|
|
* ``page_obj``: An instance of ``django.core.paginator.Page``.
|
|
|
|
Notes on pagination
|
|
~~~~~~~~~~~~~~~~~~~
|
|
|
|
If ``paginate_by`` is specified, Django will paginate the results. You can
|
|
specify the page number in the URL in one of two ways:
|
|
|
|
* Use the ``page`` parameter in the URLconf. For example, this is what
|
|
your URLconf might look like::
|
|
|
|
(r'^objects/page(?P<page>[0-9]+)/$', 'object_list', dict(info_dict))
|
|
|
|
* Pass the page number via the ``page`` query-string parameter. For
|
|
example, a URL would look like this::
|
|
|
|
/objects/?page=3
|
|
|
|
* To loop over all the available page numbers, use the ``page_range``
|
|
variable. You can iterate over the list provided by ``page_range``
|
|
to create a link to every page of results.
|
|
|
|
These values and lists are 1-based, not 0-based, so the first page would be
|
|
represented as page ``1``.
|
|
|
|
For more on pagination, read the :doc:`pagination documentation
|
|
</topics/pagination>`.
|
|
|
|
.. versionadded:: 1.0
|
|
|
|
As a special case, you are also permitted to use ``last`` as a value for
|
|
``page``::
|
|
|
|
/objects/?page=last
|
|
|
|
This allows you to access the final page of results without first having to
|
|
determine how many pages there are.
|
|
|
|
Note that ``page`` *must* be either a valid page number or the value ``last``;
|
|
any other value for ``page`` will result in a 404 error.
|
|
|
|
``django.views.generic.list_detail.object_detail``
|
|
--------------------------------------------------
|
|
|
|
A page representing an individual object.
|
|
|
|
**Description:**
|
|
|
|
A page representing an individual object.
|
|
|
|
**Required arguments:**
|
|
|
|
* ``queryset``: A ``QuerySet`` that contains the object.
|
|
|
|
* Either ``object_id`` or (``slug`` *and* ``slug_field``) is required.
|
|
|
|
If you provide ``object_id``, it should be the value of the primary-key
|
|
field for the object being displayed on this page.
|
|
|
|
Otherwise, ``slug`` should be the slug of the given object, and
|
|
``slug_field`` should be the name of the slug field in the ``QuerySet``'s
|
|
model. By default, ``slug_field`` is ``'slug'``.
|
|
|
|
**Optional arguments:**
|
|
|
|
* ``template_name``: The full name of a template to use in rendering the
|
|
page. This lets you override the default template name (see below).
|
|
|
|
* ``template_name_field``: The name of a field on the object whose value is
|
|
the template name to use. This lets you store template names in the data.
|
|
In other words, if your object has a field ``'the_template'`` that
|
|
contains a string ``'foo.html'``, and you set ``template_name_field`` to
|
|
``'the_template'``, then the generic view for this object will use the
|
|
template ``'foo.html'``.
|
|
|
|
It's a bit of a brain-bender, but it's useful in some cases.
|
|
|
|
* ``template_loader``: The template loader to use when loading the
|
|
template. By default, it's ``django.template.loader``.
|
|
|
|
* ``extra_context``: A dictionary of values to add to the template
|
|
context. By default, this is an empty dictionary. If a value in the
|
|
dictionary is callable, the generic view will call it
|
|
just before rendering the template.
|
|
|
|
* ``context_processors``: A list of template-context processors to apply to
|
|
the view's template.
|
|
|
|
* ``template_object_name``: Designates the name of the template variable
|
|
to use in the template context. By default, this is ``'object'``.
|
|
|
|
* ``mimetype``: The MIME type to use for the resulting document. Defaults
|
|
to the value of the ``DEFAULT_CONTENT_TYPE`` setting.
|
|
|
|
**Template name:**
|
|
|
|
If ``template_name`` isn't specified, this view will use the template
|
|
``<app_label>/<model_name>_detail.html`` by default.
|
|
|
|
**Template context:**
|
|
|
|
In addition to ``extra_context``, the template's context will be:
|
|
|
|
* ``object``: The object. This variable's name depends on the
|
|
``template_object_name`` parameter, which is ``'object'`` by default. If
|
|
``template_object_name`` is ``'foo'``, this variable's name will be
|
|
``foo``.
|
|
|
|
Create/update/delete generic views
|
|
==================================
|
|
|
|
The ``django.views.generic.create_update`` module contains a set of functions
|
|
for creating, editing and deleting objects.
|
|
|
|
.. versionchanged:: 1.0
|
|
|
|
``django.views.generic.create_update.create_object`` and
|
|
``django.views.generic.create_update.update_object`` now use the new :doc:`forms
|
|
library </topics/forms/index>` to build and display the form.
|
|
|
|
``django.views.generic.create_update.create_object``
|
|
----------------------------------------------------
|
|
|
|
**Description:**
|
|
|
|
A page that displays a form for creating an object, redisplaying the form with
|
|
validation errors (if there are any) and saving the object.
|
|
|
|
**Required arguments:**
|
|
|
|
* Either ``form_class`` or ``model`` is required.
|
|
|
|
If you provide ``form_class``, it should be a ``django.forms.ModelForm``
|
|
subclass. Use this argument when you need to customize the model's form.
|
|
See the :doc:`ModelForm docs </topics/forms/modelforms>` for more
|
|
information.
|
|
|
|
Otherwise, ``model`` should be a Django model class and the form used
|
|
will be a standard ``ModelForm`` for ``model``.
|
|
|
|
**Optional arguments:**
|
|
|
|
* ``post_save_redirect``: A URL to which the view will redirect after
|
|
saving the object. By default, it's ``object.get_absolute_url()``.
|
|
|
|
``post_save_redirect`` may contain dictionary string formatting, which
|
|
will be interpolated against the object's field attributes. For example,
|
|
you could use ``post_save_redirect="/polls/%(slug)s/"``.
|
|
|
|
* ``login_required``: A boolean that designates whether a user must be
|
|
logged in, in order to see the page and save changes. This hooks into the
|
|
Django :doc:`authentication system </topics/auth>`. By default, this is
|
|
``False``.
|
|
|
|
If this is ``True``, and a non-logged-in user attempts to visit this page
|
|
or save the form, Django will redirect the request to ``/accounts/login/``.
|
|
|
|
* ``template_name``: The full name of a template to use in rendering the
|
|
page. This lets you override the default template name (see below).
|
|
|
|
* ``template_loader``: The template loader to use when loading the
|
|
template. By default, it's ``django.template.loader``.
|
|
|
|
* ``extra_context``: A dictionary of values to add to the template
|
|
context. By default, this is an empty dictionary. If a value in the
|
|
dictionary is callable, the generic view will call it
|
|
just before rendering the template.
|
|
|
|
* ``context_processors``: A list of template-context processors to apply to
|
|
the view's template.
|
|
|
|
**Template name:**
|
|
|
|
If ``template_name`` isn't specified, this view will use the template
|
|
``<app_label>/<model_name>_form.html`` by default.
|
|
|
|
**Template context:**
|
|
|
|
In addition to ``extra_context``, the template's context will be:
|
|
|
|
* ``form``: A ``django.forms.ModelForm`` instance representing the form
|
|
for creating the object. This lets you refer to form fields easily in the
|
|
template system.
|
|
|
|
For example, if the model has two fields, ``name`` and ``address``::
|
|
|
|
<form action="" method="post">
|
|
<p>{{ form.name.label_tag }} {{ form.name }}</p>
|
|
<p>{{ form.address.label_tag }} {{ form.address }}</p>
|
|
</form>
|
|
|
|
See the :doc:`forms documentation </topics/forms/index>` for more
|
|
information about using ``Form`` objects in templates.
|
|
|
|
``django.views.generic.create_update.update_object``
|
|
----------------------------------------------------
|
|
|
|
**Description:**
|
|
|
|
A page that displays a form for editing an existing object, redisplaying the
|
|
form with validation errors (if there are any) and saving changes to the
|
|
object. This uses a form automatically generated from the object's
|
|
model class.
|
|
|
|
**Required arguments:**
|
|
|
|
* Either ``form_class`` or ``model`` is required.
|
|
|
|
If you provide ``form_class``, it should be a ``django.forms.ModelForm``
|
|
subclass. Use this argument when you need to customize the model's form.
|
|
See the :doc:`ModelForm docs </topics/forms/modelforms>` for more
|
|
information.
|
|
|
|
Otherwise, ``model`` should be a Django model class and the form used
|
|
will be a standard ``ModelForm`` for ``model``.
|
|
|
|
* Either ``object_id`` or (``slug`` *and* ``slug_field``) is required.
|
|
|
|
If you provide ``object_id``, it should be the value of the primary-key
|
|
field for the object being displayed on this page.
|
|
|
|
Otherwise, ``slug`` should be the slug of the given object, and
|
|
``slug_field`` should be the name of the slug field in the ``QuerySet``'s
|
|
model. By default, ``slug_field`` is ``'slug'``.
|
|
|
|
**Optional arguments:**
|
|
|
|
* ``post_save_redirect``: A URL to which the view will redirect after
|
|
saving the object. By default, it's ``object.get_absolute_url()``.
|
|
|
|
``post_save_redirect`` may contain dictionary string formatting, which
|
|
will be interpolated against the object's field attributes. For example,
|
|
you could use ``post_save_redirect="/polls/%(slug)s/"``.
|
|
|
|
* ``login_required``: A boolean that designates whether a user must be
|
|
logged in, in order to see the page and save changes. This hooks into the
|
|
Django :doc:`authentication system </topics/auth>`. By default, this is
|
|
``False``.
|
|
|
|
If this is ``True``, and a non-logged-in user attempts to visit this page
|
|
or save the form, Django will redirect the request to ``/accounts/login/``.
|
|
|
|
* ``template_name``: The full name of a template to use in rendering the
|
|
page. This lets you override the default template name (see below).
|
|
|
|
* ``template_loader``: The template loader to use when loading the
|
|
template. By default, it's ``django.template.loader``.
|
|
|
|
* ``extra_context``: A dictionary of values to add to the template
|
|
context. By default, this is an empty dictionary. If a value in the
|
|
dictionary is callable, the generic view will call it
|
|
just before rendering the template.
|
|
|
|
* ``context_processors``: A list of template-context processors to apply to
|
|
the view's template.
|
|
|
|
* ``template_object_name``: Designates the name of the template variable
|
|
to use in the template context. By default, this is ``'object'``.
|
|
|
|
**Template name:**
|
|
|
|
If ``template_name`` isn't specified, this view will use the template
|
|
``<app_label>/<model_name>_form.html`` by default.
|
|
|
|
**Template context:**
|
|
|
|
In addition to ``extra_context``, the template's context will be:
|
|
|
|
* ``form``: A ``django.forms.ModelForm`` instance representing the form
|
|
for editing the object. This lets you refer to form fields easily in the
|
|
template system.
|
|
|
|
For example, if the model has two fields, ``name`` and ``address``::
|
|
|
|
<form action="" method="post">
|
|
<p>{{ form.name.label_tag }} {{ form.name }}</p>
|
|
<p>{{ form.address.label_tag }} {{ form.address }}</p>
|
|
</form>
|
|
|
|
See the :doc:`forms documentation </topics/forms/index>` for more
|
|
information about using ``Form`` objects in templates.
|
|
|
|
* ``object``: The original object being edited. This variable's name
|
|
depends on the ``template_object_name`` parameter, which is ``'object'``
|
|
by default. If ``template_object_name`` is ``'foo'``, this variable's
|
|
name will be ``foo``.
|
|
|
|
``django.views.generic.create_update.delete_object``
|
|
----------------------------------------------------
|
|
|
|
**Description:**
|
|
|
|
A view that displays a confirmation page and deletes an existing object. The
|
|
given object will only be deleted if the request method is ``POST``. If this
|
|
view is fetched via ``GET``, it will display a confirmation page that should
|
|
contain a form that POSTs to the same URL.
|
|
|
|
**Required arguments:**
|
|
|
|
* ``model``: The Django model class of the object that the form will
|
|
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 :doc:`authentication system </topics/auth>`. By default, this is
|
|
``False``.
|
|
|
|
If this is ``True``, and a non-logged-in user attempts to visit this page
|
|
or save the form, Django will redirect the request to ``/accounts/login/``.
|
|
|
|
* ``template_name``: The full name of a template to use in rendering the
|
|
page. This lets you override the default template name (see below).
|
|
|
|
* ``template_loader``: The template loader to use when loading the
|
|
template. By default, it's ``django.template.loader``.
|
|
|
|
* ``extra_context``: A dictionary of values to add to the template
|
|
context. By default, this is an empty dictionary. If a value in the
|
|
dictionary is callable, the generic view will call it
|
|
just before rendering the template.
|
|
|
|
* ``context_processors``: A list of template-context processors to apply to
|
|
the view's template.
|
|
|
|
* ``template_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``.
|