Generic views
This covers Django version 0.95 and the development version. Old docs: 0.90, 0.91
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.
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.
"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. (This is new in the Django development version.)
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.
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.
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 zero-indexed 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.
- 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.forms.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.
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.forms.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.
Comments
Max July 25, 2005 at 2:13 a.m.
There are a lot of references to slugs here, but is there any documentation about that "slug-style-url"? In fact, what is a slug?
Edgars July 25, 2005 at 3:22 a.m.
Max, for example http://myserver/2005/jul/25/my_test_post... - my_test_post is a slug.
sway July 25, 2005 at 2:03 p.m.
It seems like generic.viewDispatcher would be more accurate to what's really happening here.
xtian July 26, 2005 at 7:32 a.m.
Man, you guys needed to document this bit earlier - this is the stuff that really makes this a RAD-style framework. Although I guess it would all be a bit academic without the DB api and the templating language.
Looks brilliant - I'm looking forward to having a bit more of a play with this.
Randy July 30, 2005 at 1:55 p.m.
I would like to see more examples, of how to use these generic views. Like xtian mentioned above, this is very powerful stuff. I think it merits more explanation and examples.
Grzegorz July 31, 2005 at 8:37 a.m.
hello i think to there should be more examples about generic view, this looks very interesting. The good example will be e.g. how it was used on the pages that runs on django (i mean lawrence.com...)
maurycy July 31, 2005 at 5:55 p.m.
Grzegorz, take a look at djangoproject.com sources. They're freely available in the subversion repository.
ianm August 17, 2005 at 11:08 a.m.
Matt Croydon posted a nice tutorial on his blog:
http://www.postneo.com/2005/08/17/django...
pedro August 25, 2005 at 12:17 p.m.
Is there a way to use this login_required argument to lock the entire site (views and CRUD)?
Luke September 16, 2005 at 6:32 p.m.
You don't have to use URLconf to use generic views. You can also write your own (very short) view functions which do something with the request first, then call the generic view function directly. This allows the parameters that generic views accept to be generated dynamically.
Scott Pierce September 19, 2005 at 11:58 p.m.
for detail/list generic views, you might want to throw in the fact that these views have more optional keyword arguments than shown above:
paginate_by, allow_empty, template_name, extra_lookup_kwargs, extra_context. An example of extra_lookup_kwargs would likely be helpful.
Rube December 6, 2005 at 10:05 a.m.
Is anybody else having trouble with SlugFields whose values include a hyphen? I can't get the generic-views' URL to find them. It always returns a 404 when there's a hyphen in it.
Matt Moriarity January 5, 2006 at 8:30 a.m.
I'm pleasantly surprised at how well Django's generic views handle relationships. It's really easy.
Scum January 10, 2006 at 2:42 p.m.
You can extend the generic views very easily. Here's a quick example on how to extend the list view.
1) In urls.py, direct the link to your own view. You dont need to pass any variables.
Eg: (r'^/table/?$', 'tableView')
2) In the new view, import the generic modules. From here you can add your own custom functions and return the data to the same template using the following code.
def table(request):
from django.views.generic.list_detail import object_list, object_detail
## Add custom code here
## You can pass any variable to the template using the extra_context dictionary.
return object_list(
request, app_label="phonebook", module_name="people",
paginate_by=20, extra_lookup_kwargs = { "order_by":["firstName"]},
extra_context = {"yourCustomVarsYouWantToAccessInYourTemplate":"Howdy!"}
)
Luke Skibinski Holt January 21, 2006 at 8:29 a.m.
Extending generic views like the above post by Scum also lets you add authentication to a generic view, see the authentication docs
http://www.djangoproject.com/documentati...
DJP February 8, 2006 at 10:59 p.m.
For Rube above and anyone else who's wondering: the problem with slugs containing hyphens is with the pattern shown in the example: (?P<slug>\w+) "\w+" only matches alphanumerics plus underscore, not hyphens.
To get the intended functionality you'll need a pattern that matches on any character except the standard URL separators (i.e. "\" "&" and "?". In a pinch you can drop in \S+ in place of \w+ in the above example but bear in mind this matches any nonwhitespace character, including the aforementioned URL separators, so beware side effects.
pa-ching April 7, 2006 at 7:53 p.m.
What's wrong with (?P<slug>[\w-]+)?
mrmachine April 12, 2006 at 11:40 a.m.
it seems that the object_detail generic view does not support allow_empty, as it says it should above (i think).
akaihola May 3, 2006 at 12:52 a.m.
Beware of the 404 trap: if the queryset for object_list is empty, Django will render a 404 error page instead of your template. Use allow_empty=True to override this behavior.
See also http://code.djangoproject.com/ticket/685...
davel May 13, 2006 at 2:56 p.m.
In the redirect_to example, the "p" in the regular expression should be a capital "P" rather than lowercase.
bram May 15, 2006 at 2:31 a.m.
( someone should edit the CSS and make the template-names a tad bigger. This page is rather confusing like this as it's easy to miss the view-names... )
Michael H. June 13, 2006 at 4:10 a.m.
The update generic view documentation should include some info on getting the supporting javascript (seen in the admin interface) to work in a generic page. Some info on the CSS might be a good idea as well. Seems like the generic forms/lists need to be evolved to be more like GUI components.
And, yes, the title font for templates doesn't stand out very well.
Scum June 15, 2006 at 11:31 a.m.
If you are creating a generic form with an ImageField or FileField, you may get stumped when the upload field does not show up on your page when you write the standard {{form.fieldname}}. You have to use the following grammer when using an upload field: {{form.fieldname}}{{form.fieldname_file}}. The first field is a hidden type that contains the path. The second is the physical upload field.
(Another gotcha is to make sure you have the form enctype set to "multipart/form-data" in these situations. You file won't upload without it. )
Simon Sapin July 9, 2006 at 12:26 p.m.
The HTTP RFC says that the Location header is an *absolute* URI.
It would be nice if django.views.generic.simple.redirect_to could handle relative URI, while putting an absolute one in the Location header.
Example :
urlpatterns = patterns('',
(r'(^|/)index.html$', 'django.views.generic.simple.redirect_to', {'url': './'}),
)
Hitting http://example.net/myapp/index.html should redirect with Location: http://example.net/myapp/ (calculated from the Host header and the request path of the first request)
The current behaviour (Location: ./) seems to work with some browsers, but isn't standard-compliant.
Gustavo September 22, 2006 at 9:30 a.m.
The object provided by django.views.generic.create_update.update_object seems to be broken... I can acess the related fields with the form object, but if I change it to object, nothing is rendered by the template.
Dave Abrahams November 26, 2006 at 8:15 a.m.
The whole "slug" thing is mighty vague in these docs. Notwithstanding the example shown in the comments above, a definition for "slug" that explains where the term came from would still be very much appreciated. I've learned at least this (which could also be explained in the docs): slug_field must correspond to a real database field in the model, or there will be no way for the generic view to construct the query that brings up the page. So for example, despite the presence of the django.template.defaultfilters.slugify function, if you use it to add a slug property (not a DB field) to your model that is just a slugified version of some real field in the database, your DB record won't be found.
Perhaps this is a question for the models section of the docs: I am working on a model that has a human-readable Title field, and I'd love to have the slug field be always a slugified version of the title. However, now I have a database full of records with no slug field. If I do an updatedb, the best I can hope for is a bunch of empty slugs that I have to fill in by hand, or I could write a special script to fill in the slug fields. It would be great to have a kind of field that is always automatically calculated from other fields, even when the field is initially created.