--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/thirdparty/google_appengine/lib/django/docs/generic_views.txt Tue Aug 26 21:49:54 2008 +0000
@@ -0,0 +1,1076 @@
+=============
+Generic views
+=============
+
+Writing Web applications can be monotonous, because we repeat certain patterns
+again and again. In Django, the most common of these patterns have been
+abstracted into "generic views" that let you quickly provide common views of
+an object without actually needing to write any Python code.
+
+Django's generic views contain the following:
+
+ * A set of views for doing list/detail interfaces (for example,
+ Django's `documentation index`_ and `detail pages`_).
+
+ * A set of views for year/month/day archive pages and associated
+ detail and "latest" pages (for example, the Django weblog's year_,
+ month_, day_, detail_, and latest_ pages).
+
+ * A set of views for creating, editing, and deleting objects.
+
+.. _`documentation index`: http://www.djangoproject.com/documentation/
+.. _`detail pages`: http://www.djangoproject.com/documentation/faq/
+.. _year: http://www.djangoproject.com/weblog/2005/
+.. _month: http://www.djangoproject.com/weblog/2005/jul/
+.. _day: http://www.djangoproject.com/weblog/2005/jul/20/
+.. _detail: http://www.djangoproject.com/weblog/2005/jul/20/autoreload/
+.. _latest: http://www.djangoproject.com/weblog/
+
+All of these views are used by creating configuration dictionaries in
+your URLconf files and passing those dictionaries as the third member of the
+URLconf tuple for a given pattern. For example, here's the URLconf for the
+simple weblog app that drives the blog on djangoproject.com::
+
+ from django.conf.urls.defaults import *
+ from django_website.apps.blog.models import Entry
+
+ info_dict = {
+ 'queryset': Entry.objects.all(),
+ 'date_field': 'pub_date',
+ }
+
+ urlpatterns = patterns('django.views.generic.date_based',
+ (r'^(?P<year>\d{4})/(?P<month>[a-z]{3})/(?P<day>\w{1,2})/(?P<slug>[-\w]+)/$', 'object_detail', dict(info_dict, slug_field='slug')),
+ (r'^(?P<year>\d{4})/(?P<month>[a-z]{3})/(?P<day>\w{1,2})/$', 'archive_day', info_dict),
+ (r'^(?P<year>\d{4})/(?P<month>[a-z]{3})/$', 'archive_month', info_dict),
+ (r'^(?P<year>\d{4})/$', 'archive_year', info_dict),
+ (r'^/?$', 'archive_index', info_dict),
+ )
+
+As you can see, this URLconf defines a few options in ``info_dict``.
+``'queryset'`` gives the generic view a ``QuerySet`` of objects to use (in this
+case, all of the ``Entry`` objects) and tells the generic view which model is
+being used.
+
+Documentation of each generic view follows, along with a list of all keyword
+arguments that a generic view expects. Remember that as in the example above,
+arguments may either come from the URL pattern (as ``month``, ``day``,
+``year``, etc. do above) or from the additional-information dictionary (as for
+``queryset``, ``date_field``, etc.).
+
+Most generic views require the ``queryset`` key, which is a ``QuerySet``
+instance; see the `database API docs`_ for more information about ``Queryset``
+objects.
+
+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.
+
+**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 ``False``.
+
+ * ``context_processors``: A list of template-context processors to apply to
+ the view's template. See the `RequestContext docs`_.
+
+ * ``mimetype``: The MIME type to use for the resulting document. Defaults
+ to the value of the ``DEFAULT_CONTENT_TYPE`` setting.
+
+ * ``allow_future``: A boolean specifying whether to include "future"
+ objects on this page, where "future" means objects in which the field
+ specified in ``date_field`` is greater than the current date/time. By
+ default, this is ``False``.
+
+**Template name:**
+
+If ``template_name`` isn't specified, this view will use the template
+``<app_label>/<model_name>_archive.html`` by default, where:
+
+ * ``<model_name>`` is your model's name in all lowercase. For a model
+ ``StaffMember``, that'd be ``staffmember``.
+
+ * ``<app_label>`` is the right-most part of the full Python path to
+ your model's app. For example, if your model lives in
+ ``apps/blog/models.py``, that'd be ``blog``.
+
+**Template context:**
+
+In addition to ``extra_context``, the template's context will be:
+
+ * ``date_list``: A list of ``datetime.date`` objects representing all
+ years that have objects available according to ``queryset``. These are
+ ordered in reverse. This is equivalent to
+ ``queryset.dates(date_field, 'year')[::-1]``.
+ * ``latest``: The ``num_latest`` objects in the system, ordered descending
+ by ``date_field``. For example, if ``num_latest`` is ``10``, then
+ ``latest`` will be a list of the latest 10 objects in ``queryset``.
+
+.. _RequestContext docs: ../templates_python/#subclassing-context-djangocontext
+
+``django.views.generic.date_based.archive_year``
+------------------------------------------------
+
+**Description:**
+
+A yearly archive page showing all available months in a given year. Objects
+with a date in the *future* are not displayed 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.
+
+**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``) containing a 1-based page
+ number, or a ``page`` variable specified in the URLconf. 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 ``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.
+
+**Template name:**
+
+If ``template_name`` isn't specified, this view will use the template
+``<app_label>/<model_name>_list.html`` by default.
+
+**Template context:**
+
+In addition to ``extra_context``, the template's context will be:
+
+ * ``object_list``: The list of objects. This variable's name depends on the
+ ``template_object_name`` parameter, which is ``'object'`` by default. If
+ ``template_object_name`` is ``'foo'``, this variable's name will be
+ ``foo_list``.
+
+ * ``is_paginated``: A boolean representing whether the results are
+ paginated. Specifically, this is set to ``False`` if the number of
+ available objects is less than or equal to ``paginate_by``.
+
+If the results are paginated, the context will contain these extra variables:
+
+ * ``results_per_page``: The number of objects per page. (Same as the
+ ``paginate_by`` parameter.)
+
+ * ``has_next``: A boolean representing whether there's a next page.
+
+ * ``has_previous``: A boolean representing whether there's a previous page.
+
+ * ``page``: The current page number, as an integer. This is 1-based.
+
+ * ``next``: The next page number, as an integer. If there's no next page,
+ this will still be an integer representing the theoretical next-page
+ number. This is 1-based.
+
+ * ``previous``: The previous page number, as an integer. This is 1-based.
+
+ * `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.
+
+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
+
+In both cases, ``page`` is 1-based, not 0-based, so the first page would be
+represented as page ``1``.
+
+``django.views.generic.list_detail.object_detail``
+--------------------------------------------------
+
+A page representing an individual object.
+
+**Description:**
+
+A page representing an individual object.
+
+**Required arguments:**
+
+ * ``queryset``: A ``QuerySet`` that contains the object.
+
+ * Either ``object_id`` or (``slug`` *and* ``slug_field``) is required.
+
+ If you provide ``object_id``, it should be the value of the primary-key
+ field for the object being displayed on this page.
+
+ Otherwise, ``slug`` should be the slug of the given object, and
+ ``slug_field`` should be the name of the slug field in the ``QuerySet``'s
+ model.
+
+**Optional arguments:**
+
+ * ``template_name``: The full name of a template to use in rendering the
+ page. This lets you override the default template name (see below).
+
+ * ``template_name_field``: The name of a field on the object whose value is
+ the template name to use. This lets you store template names in the data.
+ In other words, if your object has a field ``'the_template'`` that
+ contains a string ``'foo.html'``, and you set ``template_name_field`` to
+ ``'the_template'``, then the generic view for this object will use the
+ template ``'foo.html'``.
+
+ It's a bit of a brain-bender, but it's useful in some cases.
+
+ * ``template_loader``: The template loader to use when loading the
+ template. By default, it's ``django.template.loader``.
+
+ * ``extra_context``: A dictionary of values to add to the template
+ context. By default, this is an empty dictionary. If a value in the
+ dictionary is callable, the generic view will call it
+ just before rendering the template.
+
+ * ``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.
+
+``django.views.generic.create_update.create_object``
+----------------------------------------------------
+
+**Description:**
+
+A page that displays a form for creating an object, redisplaying the form with
+validation errors (if there are any) and saving the object. This uses the
+automatic manipulators that come with Django models.
+
+**Required arguments:**
+
+ * ``model``: The Django model class of the object that the form will
+ create.
+
+**Optional arguments:**
+
+ * ``post_save_redirect``: A URL to which the view will redirect after
+ saving the object. By default, it's ``object.get_absolute_url()``.
+
+ ``post_save_redirect`` may contain dictionary string formatting, which
+ will be interpolated against the object's field attributes. For example,
+ you could use ``post_save_redirect="/polls/%(slug)s/"``.
+
+ * ``login_required``: A boolean that designates whether a user must be
+ logged in, in order to see the page and save changes. This hooks into the
+ Django `authentication system`_. By default, this is ``False``.
+
+ If this is ``True``, and a non-logged-in user attempts to visit this page
+ or save the form, Django will redirect the request to ``/accounts/login/``.
+
+ * ``template_name``: The full name of a template to use in rendering the
+ page. This lets you override the default template name (see below).
+
+ * ``template_loader``: The template loader to use when loading the
+ template. By default, it's ``django.template.loader``.
+
+ * ``extra_context``: A dictionary of values to add to the template
+ context. By default, this is an empty dictionary. If a value in the
+ dictionary is callable, the generic view will call it
+ just before rendering the template.
+
+ * ``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.oldforms.FormWrapper`` instance representing the form
+ for editing the object. This lets you refer to form fields easily in the
+ template system.
+
+ For example, if ``model`` has two fields, ``name`` and ``address``::
+
+ <form action="" method="post">
+ <p><label for="id_name">Name:</label> {{ form.name }}</p>
+ <p><label for="id_address">Address:</label> {{ form.address }}</p>
+ </form>
+
+ See the `manipulator and formfield documentation`_ for more information
+ about using ``FormWrapper`` objects in templates.
+
+.. _authentication system: ../authentication/
+.. _manipulator and formfield documentation: ../forms/
+
+``django.views.generic.create_update.update_object``
+----------------------------------------------------
+
+**Description:**
+
+A page that displays a form for editing an existing object, redisplaying the
+form with validation errors (if there are any) and saving changes to the
+object. This uses the automatic manipulators that come with Django models.
+
+**Required arguments:**
+
+ * ``model``: The Django model class of the object that the form will
+ create.
+
+ * Either ``object_id`` or (``slug`` *and* ``slug_field``) is required.
+
+ If you provide ``object_id``, it should be the value of the primary-key
+ field for the object being displayed on this page.
+
+ Otherwise, ``slug`` should be the slug of the given object, and
+ ``slug_field`` should be the name of the slug field in the ``QuerySet``'s
+ model.
+
+**Optional arguments:**
+
+ * ``post_save_redirect``: A URL to which the view will redirect after
+ saving the object. By default, it's ``object.get_absolute_url()``.
+
+ ``post_save_redirect`` may contain dictionary string formatting, which
+ will be interpolated against the object's field attributes. For example,
+ you could use ``post_save_redirect="/polls/%(slug)s/"``.
+
+ * ``login_required``: A boolean that designates whether a user must be
+ logged in, in order to see the page and save changes. This hooks into the
+ Django `authentication system`_. By default, this is ``False``.
+
+ If this is ``True``, and a non-logged-in user attempts to visit this page
+ or save the form, Django will redirect the request to ``/accounts/login/``.
+
+ * ``template_name``: The full name of a template to use in rendering the
+ page. This lets you override the default template name (see below).
+
+ * ``template_loader``: The template loader to use when loading the
+ template. By default, it's ``django.template.loader``.
+
+ * ``extra_context``: A dictionary of values to add to the template
+ context. By default, this is an empty dictionary. If a value in the
+ dictionary is callable, the generic view will call it
+ just before rendering the template.
+
+ * ``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.oldforms.FormWrapper`` instance representing the form
+ for editing the object. This lets you refer to form fields easily in the
+ template system.
+
+ For example, if ``model`` has two fields, ``name`` and ``address``::
+
+ <form action="" method="post">
+ <p><label for="id_name">Name:</label> {{ form.name }}</p>
+ <p><label for="id_address">Address:</label> {{ form.address }}</p>
+ </form>
+
+ See the `manipulator and formfield documentation`_ for more information
+ about using ``FormWrapper`` objects in templates.
+
+ * ``object``: The original object being edited. This variable's name
+ depends on the ``template_object_name`` parameter, which is ``'object'``
+ by default. If ``template_object_name`` is ``'foo'``, this variable's
+ name will be ``foo``.
+
+``django.views.generic.create_update.delete_object``
+----------------------------------------------------
+
+**Description:**
+
+A view that displays a confirmation page and deletes an existing object. The
+given object will only be deleted if the request method is ``POST``. If this
+view is fetched via ``GET``, it will display a confirmation page that should
+contain a form that POSTs to the same URL.
+
+**Required arguments:**
+
+ * ``model``: The Django model class of the object that the form will
+ create.
+
+ * Either ``object_id`` or (``slug`` *and* ``slug_field``) is required.
+
+ If you provide ``object_id``, it should be the value of the primary-key
+ field for the object being displayed on this page.
+
+ Otherwise, ``slug`` should be the slug of the given object, and
+ ``slug_field`` should be the name of the slug field in the ``QuerySet``'s
+ model.
+
+ * ``post_delete_redirect``: A URL to which the view will redirect after
+ deleting the object.
+
+**Optional arguments:**
+
+ * ``login_required``: A boolean that designates whether a user must be
+ logged in, in order to see the page and save changes. This hooks into the
+ Django `authentication system`_. By default, this is ``False``.
+
+ If this is ``True``, and a non-logged-in user attempts to visit this page
+ or save the form, Django will redirect the request to ``/accounts/login/``.
+
+ * ``template_name``: The full name of a template to use in rendering the
+ page. This lets you override the default template name (see below).
+
+ * ``template_loader``: The template loader to use when loading the
+ template. By default, it's ``django.template.loader``.
+
+ * ``extra_context``: A dictionary of values to add to the template
+ context. By default, this is an empty dictionary. If a value in the
+ dictionary is callable, the generic view will call it
+ just before rendering the template.
+
+ * ``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``.