Writing Web applications can be monotonous, because we repeat certain patterns again and again. In Django, the most common of these patterns have been abstracted into “generic views” that let you quickly provide common views of an object without actually needing to write any Python code.
A general introduction to generic views can be found in the topic guide.
This reference contains details of Django’s built-in generic views, along with a list of all keyword arguments that a generic view expects. Remember that arguments may either come from the URL pattern or from the extra_context additional-information dictionary.
Most generic views require the queryset key, which is a QuerySet instance; see Making queries for more information about QuerySet objects.
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.
Description:
Renders a given template, passing it a {{ params }} template variable, which is a dictionary of the parameters captured in the URL.
Required arguments:
Optional arguments:
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.
Description:
Redirects to a given URL.
The given URL may contain dictionary-style string formatting, which will be interpolated against the parameters captured in the URL. Because keyword interpolation is always done (even if no arguments are passed in), any "%" characters in the URL must be written as "%%" so that Python will convert them to a single percent sign on output.
If the given URL is None, Django will return an HttpResponseGone (410).
Required arguments:
Optional arguments:
Example:
This example issues a permanent redirect (HTTP status code 301) from /foo/<id>/ to /bar/<id>/:
urlpatterns = patterns('django.views.generic.simple',
('^foo/(?P<id>\d+)/$', 'redirect_to', {'url': '/bar/%(id)s/'}),
)
This example issues a non-permanent redirect (HTTP status code 302) from /foo/<id>/ to /bar/<id>/:
urlpatterns = patterns('django.views.generic.simple',
('^foo/(?P<id>\d+)/$', 'redirect_to', {'url': '/bar/%(id)s/', 'permanent': False}),
)
This example returns a 410 HTTP error for requests to /bar/:
urlpatterns = patterns('django.views.generic.simple',
('^bar/$', 'redirect_to', {'url': None}),
)
This example shows how "%" characters must be written in the URL in order to avoid confusion with Python's string formatting markers. If the redirect string is written as "%7Ejacob/" (with only a single %), an exception would be raised:
urlpatterns = patterns('django.views.generic.simple',
('^bar/$', 'redirect_to', {'url': '%%7Ejacob.'}),
)
Date-based generic views (in the module django.views.generic.date_based) are views for displaying drilldown pages for date-based data.
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:
Optional arguments:
- num_latest: The number of latest objects to send to the template context. By default, it's 15.
- template_name: The full name of a template to use in rendering the page. This lets you override the default template name (see below).
- template_loader: The template loader to use when loading the template. By default, it's django.template.loader.
- extra_context: A dictionary of values to add to the template context. By default, this is an empty dictionary. If a value in the dictionary is callable, the generic view will call it just before rendering the template.
- allow_empty: A boolean specifying whether to display the page if no objects are available. If this is False and no objects are available, the view will raise a 404 instead of displaying an empty page. By default, this is True.
- context_processors: A list of template-context processors to apply to the view's template.
- mimetype: The MIME type to use for the resulting document. Defaults to the value of the DEFAULT_CONTENT_TYPE setting.
- allow_future: A boolean specifying whether to include "future" objects on this page, where "future" means objects in which the field specified in date_field is greater than the current date/time. By default, this is False.
New in Django 1.0: Please, see the release notes
- template_object_name: Designates the name of the template variable to use in the template context. By default, this is 'latest'.
Template name:
If template_name isn't specified, this view will use the template <app_label>/<model_name>_archive.html by default, where:
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].
Changed in Django 1.0: The behaviour depending on template_object_name is new in this version.
latest: The num_latest objects in the system, ordered descending by date_field. For example, if num_latest is 10, then latest will be a list of the latest 10 objects in queryset.
This variable's name depends on the template_object_name parameter, which is 'latest' by default. If template_object_name is 'foo', this variable's name will be foo.
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:
Optional arguments:
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.
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:
Optional arguments:
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:
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:
Optional arguments:
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:
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:
Optional arguments:
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:
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.
Description:
A page representing an individual object. If the object has a date value in the future, the view will throw a 404 error by default, unless you set allow_future to True.
Required arguments:
year: The object's four-digit year (a string).
month: The object's month , formatted according to the month_format argument.
day: The object's day , formatted according to the day_format argument.
queryset: A QuerySet that contains the object.
date_field: The name of the DateField or DateTimeField in the QuerySet's model that the generic view should use to look up the object according to year, month and day.
Either object_id or (slug and slug_field) is required.
If you provide object_id, it should be the value of the primary-key field for the object being displayed on this page.
Otherwise, slug should be the slug of the given object, and slug_field should be the name of the slug field in the QuerySet's model. By default, slug_field is 'slug'.
Optional arguments:
month_format: A format string that regulates what format the month parameter uses. This should be in the syntax accepted by Python's time.strftime. (See the strftime docs.) It's set to "%b" by default, which is a three-letter month abbreviation. To change it to use numbers, use "%m".
day_format: Like month_format, but for the day parameter. It defaults to "%d" (day of the month as a decimal number, 01-31).
template_name: The full name of a template to use in rendering the page. This lets you override the default template name (see below).
template_name_field: The name of a field on the object whose value is the template name to use. This lets you store template names in the data. In other words, if your object has a field 'the_template' that contains a string 'foo.html', and you set template_name_field to 'the_template', then the generic view for this object will use the template 'foo.html'.
It's a bit of a brain-bender, but it's useful in some cases.
template_loader: The template loader to use when loading the template. By default, it's django.template.loader.
extra_context: A dictionary of values to add to the template context. By default, this is an empty dictionary. If a value in the dictionary is callable, the generic view will call it just before rendering the template.
context_processors: A list of template-context processors to apply to the view's template.
template_object_name: Designates the name of the template variable to use in the template context. By default, this is 'object'.
mimetype: The MIME type to use for the resulting document. Defaults to the value of the DEFAULT_CONTENT_TYPE setting.
allow_future: A boolean specifying whether to include "future" objects on this page, where "future" means objects in which the field specified in date_field is greater than the current date/time. By default, this is False.
Template name:
If template_name isn't specified, this view will use the template <app_label>/<model_name>_detail.html by default.
Template context:
In addition to extra_context, the template's context will be:
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.
Description:
A page representing a list of objects.
Required arguments:
Optional arguments:
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:
If the results are paginated, the context will contain these extra variables:
If paginate_by is specified, Django will paginate the results. You can specify the page number in the URL in one of two ways:
Use the page parameter in the URLconf. For example, this is what your URLconf might look like:
(r'^objects/page(?P<page>[0-9]+)/$', 'object_list', dict(info_dict))
Pass the page number via the page query-string parameter. For example, a URL would look like this:
/objects/?page=3
To loop over all the available page numbers, use the page_range variable. You can iterate over the list provided by page_range to create a link to every page of results.
These values and lists are 1-based, not 0-based, so the first page would be represented as page 1.
For more on pagination, read the pagination documentation.
As a special case, you are also permitted to use last as a value for page:
/objects/?page=last
This allows you to access the final page of results without first having to determine how many pages there are.
Note that page must be either a valid page number or the value last; any other value for page will result in a 404 error.
A page representing an individual object.
Description:
A page representing an individual object.
Required arguments:
queryset: A QuerySet that contains the object.
Either object_id or (slug and slug_field) is required.
If you provide object_id, it should be the value of the primary-key field for the object being displayed on this page.
Otherwise, slug should be the slug of the given object, and slug_field should be the name of the slug field in the QuerySet's model. By default, slug_field is 'slug'.
Optional arguments:
template_name: The full name of a template to use in rendering the page. This lets you override the default template name (see below).
template_name_field: The name of a field on the object whose value is the template name to use. This lets you store template names in the data. In other words, if your object has a field 'the_template' that contains a string 'foo.html', and you set template_name_field to 'the_template', then the generic view for this object will use the template 'foo.html'.
It's a bit of a brain-bender, but it's useful in some cases.
template_loader: The template loader to use when loading the template. By default, it's django.template.loader.
extra_context: A dictionary of values to add to the template context. By default, this is an empty dictionary. If a value in the dictionary is callable, the generic view will call it just before rendering the template.
context_processors: A list of template-context processors to apply to the view's template.
template_object_name: Designates the name of the template variable to use in the template context. By default, this is 'object'.
mimetype: The MIME type to use for the resulting document. Defaults to the value of the DEFAULT_CONTENT_TYPE setting.
Template name:
If template_name isn't specified, this view will use the template <app_label>/<model_name>_detail.html by default.
Template context:
In addition to extra_context, the template's context will be:
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 and django.views.generic.create_update.update_object now use the new forms library to build and display the form.
Description:
A page that displays a form for creating an object, redisplaying the form with validation errors (if there are any) and saving the object.
Required arguments:
Either form_class or model is required.
If you provide form_class, it should be a django.forms.ModelForm subclass. Use this argument when you need to customize the model's form. See the ModelForm docs for more information.
Otherwise, model should be a Django model class and the form used will be a standard ModelForm for model.
Optional arguments:
post_save_redirect: A URL to which the view will redirect after saving the object. By default, it's object.get_absolute_url().
post_save_redirect may contain dictionary string formatting, which will be interpolated against the object's field attributes. For example, you could use post_save_redirect="/polls/%(slug)s/".
login_required: A boolean that designates whether a user must be logged in, in order to see the page and save changes. This hooks into the Django authentication system. By default, this is False.
If this is True, and a non-logged-in user attempts to visit this page or save the form, Django will redirect the request to /accounts/login/.
template_name: The full name of a template to use in rendering the page. This lets you override the default template name (see below).
template_loader: The template loader to use when loading the template. By default, it's django.template.loader.
extra_context: A dictionary of values to add to the template context. By default, this is an empty dictionary. If a value in the dictionary is callable, the generic view will call it just before rendering the template.
context_processors: A list of template-context processors to apply to the view's template.
Template name:
If template_name isn't specified, this view will use the template <app_label>/<model_name>_form.html by default.
Template context:
In addition to extra_context, the template's context will be:
form: A django.forms.ModelForm instance representing the form for creating the object. This lets you refer to form fields easily in the template system.
For example, if the model has two fields, name and address:
<form action="" method="post">
<p>{{ form.name.label_tag }} {{ form.name }}</p>
<p>{{ form.address.label_tag }} {{ form.address }}</p>
</form>
See the forms documentation for more information about using Form objects in templates.
Description:
A page that displays a form for editing an existing object, redisplaying the form with validation errors (if there are any) and saving changes to the object. This uses a form automatically generated from the object's model class.
Required arguments:
Either form_class or model is required.
If you provide form_class, it should be a django.forms.ModelForm subclass. Use this argument when you need to customize the model's form. See the ModelForm docs for more information.
Otherwise, model should be a Django model class and the form used will be a standard ModelForm for model.
Either object_id or (slug and slug_field) is required.
If you provide object_id, it should be the value of the primary-key field for the object being displayed on this page.
Otherwise, slug should be the slug of the given object, and slug_field should be the name of the slug field in the QuerySet's model. By default, slug_field is 'slug'.
Optional arguments:
post_save_redirect: A URL to which the view will redirect after saving the object. By default, it's object.get_absolute_url().
post_save_redirect may contain dictionary string formatting, which will be interpolated against the object's field attributes. For example, you could use post_save_redirect="/polls/%(slug)s/".
login_required: A boolean that designates whether a user must be logged in, in order to see the page and save changes. This hooks into the Django authentication system. By default, this is False.
If this is True, and a non-logged-in user attempts to visit this page or save the form, Django will redirect the request to /accounts/login/.
template_name: The full name of a template to use in rendering the page. This lets you override the default template name (see below).
template_loader: The template loader to use when loading the template. By default, it's django.template.loader.
extra_context: A dictionary of values to add to the template context. By default, this is an empty dictionary. If a value in the dictionary is callable, the generic view will call it just before rendering the template.
context_processors: A list of template-context processors to apply to the view's template.
template_object_name: Designates the name of the template variable to use in the template context. By default, this is 'object'.
Template name:
If template_name isn't specified, this view will use the template <app_label>/<model_name>_form.html by default.
Template context:
In addition to extra_context, the template's context will be:
form: A django.forms.ModelForm instance representing the form for editing the object. This lets you refer to form fields easily in the template system.
For example, if the model has two fields, name and address:
<form action="" method="post">
<p>{{ form.name.label_tag }} {{ form.name }}</p>
<p>{{ form.address.label_tag }} {{ form.address }}</p>
</form>
See the forms documentation for more information about using Form objects in templates.
object: The original object being edited. This variable's name depends on the template_object_name parameter, which is 'object' by default. If template_object_name is 'foo', this variable's name will be foo.
Description:
A view that displays a confirmation page and deletes an existing object. The given object will only be deleted if the request method is POST. If this view is fetched via GET, it will display a confirmation page that should contain a form that POSTs to the same URL.
Required arguments:
model: The Django model class of the object that the form will create.
Either object_id or (slug and slug_field) is required.
If you provide object_id, it should be the value of the primary-key field for the object being displayed on this page.
Otherwise, slug should be the slug of the given object, and slug_field should be the name of the slug field in the QuerySet's model. By default, slug_field is 'slug'.
post_delete_redirect: A URL to which the view will redirect after deleting the object.
Optional arguments:
login_required: A boolean that designates whether a user must be logged in, in order to see the page and save changes. This hooks into the Django authentication system. By default, this is False.
If this is True, and a non-logged-in user attempts to visit this page or save the form, Django will redirect the request to /accounts/login/.
template_name: The full name of a template to use in rendering the page. This lets you override the default template name (see below).
template_loader: The template loader to use when loading the template. By default, it's django.template.loader.
extra_context: A dictionary of values to add to the template context. By default, this is an empty dictionary. If a value in the dictionary is callable, the generic view will call it just before rendering the template.
context_processors: A list of template-context processors to apply to the view's template.
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:
Sep 20, 2009