371144f134
git-svn-id: http://code.djangoproject.com/svn/django/trunk@304 bcc190cf-cafb-0310-a4f2-bffc1f526a37
301 lines
12 KiB
Plaintext
301 lines
12 KiB
Plaintext
===================
|
|
Using generic views
|
|
===================
|
|
|
|
Writing web applications can often be monotonous as 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 object without actually
|
|
needing to write any views.
|
|
|
|
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 urlconfig files and passing those dicts as the third member of the
|
|
urlconf tuple. For example, here's the urlconf for the simple weblog
|
|
app that drives the blog on djangoproject.com::
|
|
|
|
from django.conf.urls.defaults import *
|
|
|
|
info_dict = {
|
|
'app_label': 'blog',
|
|
'module_name': 'entries',
|
|
'date_field': 'pub_date',
|
|
}
|
|
|
|
urlpatterns = patterns('django.views.generic.date_based',
|
|
(r'^(?P<year>\d{4})/(?P<month>[a-z]{3})/(?P<day>\w{1,2})/(?P<slug>\w+)/$', 'object_detail', dict(info_dict, slug_field='slug')),
|
|
(r'^(?P<year>\d{4})/(?P<month>[a-z]{3})/(?P<day>\w{1,2})/$', 'archive_day', info_dict),
|
|
(r'^(?P<year>\d{4})/(?P<month>[a-z]{3})/$', 'archive_month', info_dict),
|
|
(r'^(?P<year>\d{4})/$', 'archive_year', info_dict),
|
|
(r'^/?$', 'archive_index', info_dict),
|
|
)
|
|
|
|
As you can see, this urlconf defines a few options in ``info_dict`` that tell
|
|
the generic view which model to use (``blog.entries`` in this case), as well as
|
|
some extra information.
|
|
|
|
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 dict (as for ``app_label``, ``module_name``, etc.).
|
|
|
|
All the generic views that follow require the ``app_label`` and ``module_name`` keys.
|
|
These values are easiest to explain through example::
|
|
|
|
>>> from django.models.blog import entries
|
|
|
|
In the above line, ``blog`` is the ``app_label`` (this is the name of the file that
|
|
holds all your model definitions) and ``entries`` is the ``module_name`` (this is
|
|
either a pluralized, lowercased version of the model class name or the value of
|
|
the ``module_name`` option of your model). In the docs below, these keys will not
|
|
be repeated, but each generic view requires them.
|
|
|
|
Using date-based generic views
|
|
==============================
|
|
|
|
Date-based generic views (in the module ``django.views.generic.date_based``)
|
|
export six functions for dealing with date-based data. Besides ``app_label``
|
|
and ``module_name``, all date-based generic views require that the ``date_field``
|
|
argument to passed to them; this is the name of the field that stores the date
|
|
the objects should key off of.
|
|
|
|
Additional, all date-based generic views have the following optional arguments:
|
|
|
|
======================= ==================================================
|
|
Argument Description
|
|
======================= ==================================================
|
|
``template_name`` Override the default template name used for the
|
|
view.
|
|
|
|
``extra_lookup_kwargs`` A dictionary of extra lookup parameters (see
|
|
the `database API docs`_).
|
|
|
|
``extra_context`` A dict of extra data to put into the template's
|
|
context.
|
|
======================= ==================================================
|
|
|
|
.. _`database API docs`: http://www.djangoproject.com/documentation/db_api/
|
|
|
|
The date-based generic functions are:
|
|
|
|
``archive_index``
|
|
A top-level index page showing the "latest" objects. Has an optional argument,
|
|
``num_latest`` which is the number of items to display on the page (defaults
|
|
to 15).
|
|
|
|
Uses the template ``app_label/module_name_archive`` by default.
|
|
|
|
Has the following template context:
|
|
|
|
``date_list``
|
|
List of years with objects
|
|
``latest``
|
|
Latest objects by date
|
|
|
|
``archive_year``
|
|
Yearly archive. Requires that the ``year`` argument be present in the URL
|
|
pattern.
|
|
|
|
Uses the template ``app_label/module_name__archive_year`` by default.
|
|
|
|
Has the following template context:
|
|
|
|
``date_list``
|
|
List of months in this year with objects
|
|
``year``
|
|
This year
|
|
|
|
``archive_month``
|
|
Monthly archive; requires that ``year`` and ``month`` arguments be given.
|
|
|
|
Uses the template ``app_label/module_name__archive_month`` by default.
|
|
|
|
Has the following template context:
|
|
|
|
``month``
|
|
(datetime object) this month
|
|
``object_list``
|
|
list of objects published in the given month
|
|
|
|
``archive_day``
|
|
Daily archive; requires that ``year``, ``month``, and ``day`` arguments
|
|
be given.
|
|
|
|
Uses the template ``app_label/module_name__archive_day`` by default.
|
|
|
|
Has the following template context:
|
|
|
|
``object_list``
|
|
list of objects published this day
|
|
``day``
|
|
(datetime) the day
|
|
``previous_day``
|
|
(datetime) the previous day
|
|
``next_day``
|
|
(datetime) the next day, or None if the current day is today
|
|
|
|
|
|
``archive_today``
|
|
List of objects for today; exactly the same as ``archive_day``, except
|
|
that the year/month/day arguments are not given and today's date is
|
|
used instead.
|
|
|
|
``object_detail``
|
|
Individual object page; requires ``year``/``month``/``day`` arguments like
|
|
``archive_day``. This function can be used with two types of URLs: either
|
|
``/year/month/day/slug/`` or ``/year/month/day/object_id/``.
|
|
|
|
If you're using the slug-style URLs, you'll need to have a ``slug`` item in
|
|
your urlconf, and you'll need to pass a ``slug_field`` key in your info
|
|
dict to indicate the name of the slug field.
|
|
|
|
If your using the object_id-style URLs, you'll just need to have the URL
|
|
pattern have an ``object_id`` field.
|
|
|
|
You can also pass the ``template_name_field`` argument to indicate that the
|
|
the object stores the name of its template in a field on the object itself.
|
|
|
|
Using list/detail generic views
|
|
===============================
|
|
|
|
The list-detail generic views (in the ``django.views.generic.list_detail`` module)
|
|
are similar to the data-based ones, except the list-detail views simply have two
|
|
views: a list of objects, and an individual object page.
|
|
|
|
All these views take the same three optional arguments as the date-based ones do
|
|
(and they obviously do not accept or require the date field argument).
|
|
|
|
Individual views are:
|
|
|
|
``object_list``
|
|
List of objects.
|
|
|
|
Takes the following optional arguments:
|
|
|
|
======================= =================================================
|
|
Argument Description
|
|
======================= =================================================
|
|
``paginate_by`` If set to an integer, the view will paginate
|
|
objects with ``paginate_by`` objects per page.
|
|
The view will expect a ``page`` GET param with
|
|
the (zero-indexed) page number.
|
|
|
|
``allow_empty`` If ``False`` and there are no objects to display
|
|
the view will raise a 404 instead of displaying
|
|
an empty index page.
|
|
======================= =================================================
|
|
|
|
Uses the template ``app_label/module_name__list`` by default.
|
|
|
|
Has the following template context:
|
|
|
|
``object_list``
|
|
list of objects
|
|
``is_paginated``
|
|
are the results paginated?
|
|
|
|
If the results are paginated, the context will have some extra variables:
|
|
|
|
``results_per_page``
|
|
number of objects per page
|
|
``has_next``
|
|
is there a next page?
|
|
``has_previous``
|
|
is there a prev page?
|
|
``page``
|
|
the current page
|
|
``next``
|
|
the next page
|
|
``previous``
|
|
the previous page
|
|
``pages``
|
|
number of pages, total
|
|
|
|
``object_detail``
|
|
Object detail page. This works like and takes the same arguments as
|
|
the date-based ``object_detail`` above, except this one obviously
|
|
does not take the year/month/day arguments.
|
|
|
|
Using create/update/delete generic views
|
|
========================================
|
|
|
|
The ``django.views.generic.create_update`` module contains a set of functions
|
|
for creating, editing, and deleting objects. These views take the same global
|
|
arguments as the above sets of generic views; they also have a
|
|
``login_required`` argument which, if ``True``, requires the user to be logged
|
|
in to have access to the page (``login_required`` defaults to ``False``).
|
|
|
|
The create/update/delete views are:
|
|
|
|
``create_object``
|
|
Create a new object. Has an extra optional argument, ``post_save_redirect``,
|
|
which is a URL that the view will redirect to after saving the object
|
|
(defaults to ``object.get_absolute_url()``).
|
|
|
|
``post_save_redirect`` may contain dictionary string formatting which will
|
|
be interpolated against the object's dict (so you could use
|
|
``post_save_redirect="/polls/%(slug)s/"``, for example).
|
|
|
|
Uses the template ``app_label/module_name__form`` by default (this is the
|
|
same template as the ``update_object`` view below; your template can tell
|
|
the different by the presence or absence of ``{{ object }}`` in the context.
|
|
|
|
Has the following template context:
|
|
|
|
form
|
|
the form wrapper for the object
|
|
|
|
.. admonition:: Note
|
|
|
|
See the `manipulator and formfield documentation`_ for more information
|
|
about using form wrappers in templates.
|
|
|
|
.. _`manipulator and formfield documentation`: http://www.djangoproject.com/documentation/forms/
|
|
|
|
``update_object``
|
|
Edit an existing object. Has the same extra slug/ID parameters as
|
|
``list_detail.object_detail`` does (see above), and the same ``post_save_redirect``
|
|
as ``create_object`` does.
|
|
|
|
Uses the template ``app_label/module_name__form`` by default.
|
|
|
|
Has the following template context:
|
|
|
|
form
|
|
the form wrapper for the object
|
|
object
|
|
the original object being edited
|
|
|
|
``delete_object``
|
|
Delete an existing object. The given object will only actually be deleted if
|
|
the request method is POST; if this view is fetched with GET it will display
|
|
a confirmation page that should contain a form that POSTs to the same URL.
|
|
|
|
You must provide the ``post_delete_redirect`` argument to this function so
|
|
that the view knows where to go after the object is deleted.
|
|
|
|
If fetched with GET, uses the template
|
|
``app_label/module_name_s_confirm_delete`` by default (uses no template if
|
|
POSTed; simply deletes the object).
|
|
|
|
Has the following template context:
|
|
|
|
object
|
|
the object about to be deleted |