附录 D 通用视图参考

第９章介绍了通用视图，但没有介绍一些底层细节。这份附录描述了每个通用视图及其所有可选项。为了理解参考资料中的内容，一定要先阅读第 9 章的内容。你可能想回顾一下该章中定义的 Book 、 Publisher 和 Author 对象；下面的例子中将继续使用这些模型。

通用视图的常见参数

这些视图中的大多数有很多可以改变通用视图行为的参数。很多参数使用相同的方式来交叉形成很多视图。表 D-1 描述了每个参数；任何时候当你看到这些参数在通用视图的参数列表中，它将像下表中表述的那样工作

简易通用视图

django.views.generic.simple 模块包含了简单视图，用来处理一些公共的事情：在不需要视图逻辑的时候渲染一个模板和发出一个重定向。

渲染模板

视图函数 : django.views.generic.simple.direct_to_template

该视图渲染一给定模板，给其传递一个 {{ params }} 的模板变量，该变量是在 URL 中被获取的一个自典型参数

例子

给出下列 URLconf:

from django.conf.urls.defaults import *

from django.views.generic.simple import direct_to_template

urlpatterns = patterns('',

(r'^foo/$', direct_to_template, {'template': 'foo_index.html'}), (r'^foo/(?P<id>\d+)/$', direct_to_template, {'template': 'foo_detail.html'}),

)

请求 /foo/ 时就会渲染模板 foo_index.html ，而请求 /foo/15/ 就会附带一个值为 15 的

context 来渲染模板 foo_detail.html 。必要参数

• template ：模板的全名。

  重定向到另外一个 URL

  视图函数 ： django.views.generic.simple.redirect_to

  这个视图将源 URL 重定向到目的 URL，目的 URL 中可以带有字典风格的格式化字符串，在源

  URL 中被捕获的参数可以被格式化输出到目的 URL 中。

  如果目的 URL 是 None ，Django 会返回 HTTP 410（文件丢失）错误。例子

  这个 URLconf 将 /foo/<id>/ 重定向到 /bar/<id>/ ：

  from django.conf.urls.defaults import *

  from django.views.generic.simple import redirect_to

  urlpatterns = patterns('django.views.generic.simple', ('^foo/(?p<id>\d+)/$', redirect_to, {'url': '/bar/%(id)s/'}),

  )

  这个例子对 /bar/ 的请求返回文件丢失的错误：

  from django.views.generic.simple import redirect_to urlpatterns = patterns('django.views.generic.simple',

  ('^bar/$', redirect_to, {'url': None}),

  )

  必要参数

• url ：被重定向到的 URL，它是个字符串。如果是 None 的话，就返回 410（文件丢失）错误。

  列表/详细 通用视图

  列表/详细 通用视图(位于模块 django.views.generic.list_detail 中)处理了一种常见的应用，它在一个视图中显示一个项的列表，在另外一个视图中显示列表中某个具体项的细节。

  对象列表

  视图函数 : django.views.generic.list_detail.object_list使用这个视图来显示一个对象列表页面。

  例子

  拿第 5 章的 Author 对象来说，我们可以使用 object_list 视图来显示一个所有作者的简单列表，URLconf 的内容如下：

  from mysite.books.models import Author from django.conf.urls.defaults import *

  from django.views.generic import list_detail

  author_list_info = {

  'queryset' : Author.objects.all(), 'allow_empty': True,

  }

  urlpatterns = patterns('',

  (r'authors/$', list_detail.object_list, author_list_info)

  )

  必要参数

• queryset : 要列出的对象的 QuerySet (参见表 D-1).可选参数

• paginate_by : 一个整形数，用来制定每页显示多少条记录。如果指定了这个参数，那么视图将会把记录按照 paginate_by 的值来安排每页记录的数量。视图将会通过一个 page 的查询字符串参数传入一个以 0 开始的页号（通过 GET 来获取 page 的值），或者在配置 url 的时候指定一个 page 变量。详细请查看 Pagination 章节的说明。

  此外，这个视图也许会取得在 Table D-1 中描述的任何通用的参数

• 允许为空

• context_processors

• extra_context

• mimetype

• template_loader

• template_name

• template_object_name模板名称

  If template_name isnt specified, this view will use the template

  <app_label>/<model_name>_list.html by default. Both the application label and the model name are derived from the queryset parameter. The application label is the name of the application that the model is defined in, and the model name is the lowercased version of the name of the model class.

  在先前的例子中使用 Author.objects.all() 作为 queryset , 程序的标签将会是 books和模型的名字将是 author . 这意味着缺省的模板将是 books/author_list.html .

  模板上下文

  除了 extra_context , 模板上下文还包含:

• object_list : The list of objects. This variables name depends on the template_object_name parameter, which is 'object' by default. If template_object_name is 'foo' , this variables 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. (This is the same as the paginate_by parameter.)

• has_next : 一个布尔值表示是否有下一页.

• has_previous : 一个布尔值表示是否有上一页.

• page : 表示当前页的页码，是一个整数（如第 9 页），第一页是从 1 开始计算的。

• next : The next page number, as an integer. If theres 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.

A Note 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 .

Detail Views

View function : django.views.generic.list_detail.object_detail This view provides a detail view of a single object.

例子

Continuing the previous object_list example, we could add a detail view for a given author by modifying the URLconf:

from mysite.books.models import Author from django.conf.urls.defaults import *

from django.views.generic import list_detail

author_list_info = {

'queryset' : Author.objects.all(), 'allow_empty': True,

}

**author_detail_info = {**

**"queryset" : Author.objects.all(),**

**"template_object_name" : "author",**

**}**

urlpatterns = patterns('',

(r'authors/$', list_detail.object_list, author_list_info),

**(r'^authors/(?P<object_id>d+)/$', list_detail.object_detail, author_detail_info),**

)

必要参数

• queryset : A QuerySet that will be searched for the object (see Table D-1). and either

• object_id : The value of the primary-key field for the object.或者

• slug : The slug of the given object. If you pass this field, then the slug_field argument (see the following section) is also required.

  Optional Arguments

  slug_field : The name of the field on the object containing the slug. This is required if you are using the slug argument, but it must be absent if youre using the object_id argument.

  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 your 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' .

  If the template named by template_name_field doesnt exist, the one named by template_name is used instead. Its a bit of a brain-bender, but its useful in some cases.

  This view may also take these common arguments (see Table D-1):

• context_processors

• extra_context

• mimetype

• template_loader

• template_name

• template_object_name模板名

  如果``template_name`` 和 template_name_field 没有被指定, 这个视图将会使用

  <app_label>/<model_name>_detail.html 作为缺省模板.模板上下文

  根据 ``extra_context``，该模板上下文将如下：

  System Message: WARNING/2 (<string>, line 654); backlink

  Inline literal start-string without end-string.

• object : The object. This variables name depends on the template_object_name parameter, which is 'object' by default. If template_object_name is 'foo' , this variables name will be foo .

  基于日期的通用视图

  基于日期的通用视图通常用于提供为有日期的资料存档。想想一份报纸的 年/月/日 存档文件或一个典型的博客存档文件。

  提示：

  默认情况下，这种视图会忽略未来日期的对象。

  这意味着如果你想尝试访问一个未来的存档页，Django 将会自动显示一个404（找不到页面）错误。即使将会有对象在那天发布。

  因此，你可以发布事后日期对象。这个对象不会公然地的出现直到它们请求发布日期

  然而，对于不同类型的基于日期的对象，这么做又是不合理的（比如一个行程日历）。对于这些视图，设置``allow_future``选项为``True``就会显示未来对象（并允许用户访问未来的存档页）。

  存档索引

  视图函数 ： django.views.generic.date_based.archive_index 这个视图提供了一个最高层次的索引页用于按日期显示最近的对象。例子

  举个例子，图书发行商想要一个近期发行图书的页面。给某些“Book”对象一个

  “publication_date”域，我们可以使用“archive_index”视图来完成这个普通任务：

  from mysite.books.models import Book from django.conf.urls.defaults import *

  from django.views.generic import date_based

  book_info = {

  "queryset" : Book.objects.all(), "date_field" : "publication_date"

  }

  urlpatterns = patterns('',

  (r'^books/$', date_based.archive_index, book_info),

  )

  Required Arguments

• 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.

• queryset : A QuerySet of objects for which the archive serves.

  Optional Arguments

• allow_future : A Boolean specifying whether to include future objects on this page, as described in the previous note.

• num_latest : The number of latest objects to send to the template context. By default, its 15.

  This view may also take these common arguments (see Table D-1):

• allow_empty

• context_processors

• extra_context

• mimetype

• template_loader

• template_name模板名

  如果 template_name 没有指定，视图会默认使用模板

  <app_label>/<model_name>_archive.html 。模板上下文

  除了 extra_context ，模板上下文将如下所示：

  date_list : A list of datetime.date objects representing all years that have objects available according to queryset . These are ordered in reverse.

  For example, if you have blog entries from 2003 through 2006, this list will contain four datetime.date objects: one for each of those years.

  latest : The num_latest objects in the system, in descending order by date_field . For example, if num_latest is 10 , then latest will be a list of the latest ten objects in queryset .

  Year Archives

  View function : django.views.generic.date_based.archive_year

  年存档使用这个视图。这些页面有一个对象存在的月份的列表，并且可选的显示所有在本年内发行的对象。

  例子

  Extending the archive_index example from earlier, well add a way to view all the books published in a given year:

  from mysite.books.models import Book from django.conf.urls.defaults import *

  from django.views.generic import date_based

  book_info = {

  "queryset" : Book.objects.all(), "date_field" : "publication_date"

  }

  urlpatterns = patterns('',

  (r'^books/$', date_based.archive_index, book_info),

  **(r'^books/(?P<year>d{4})/?$', date_based.archive_year, book_info),**

  )

  Required Arguments

• date_field : As for archive_index (see the previous section).

• queryset : A QuerySet of objects for which the archive serves.

• year : The four-digit year for which the archive serves (as in our example, this is usually taken from a URL parameter).

  Optional Arguments

• 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 information about object_list in the following Template Context section.) By default, this is False .

• allow_future : A Boolean specifying whether to include future objects on this page.

  This view may also take these common arguments (see Table D-1):

• allow_empty

• context_processors

• extra_context

• mimetype

• template_loader

• template_name

• template_object_name Template Name

  如果”template_name”没有被指定，这个视图将使

  用”<app_label>/<model_name>_archive_year.html”做为默认模板。 Template Context

  In addition to extra_context , the templates context will be as follows:

  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 variables name depends on the template_object_name parameter, which is 'object' by default. If template_object_name is 'foo' , this variables name will be foo_list .

  If make_object_list is False , object_list will be passed to the template as an empty list.

  Month Archives

  View function : django.views.generic.date_based.archive_month

  This view provides monthly archive pages showing all objects for a given month. Example

  Continuing with our example, adding month views should look familiar:

  urlpatterns = patterns('',

  (r'^books/$', date_based.archive_index, book_info), (r'^books/(?P<year>d{4})/?$', date_based.archive_year, book_info),

  **(**

  **r'^(?P<year>d{4})/(?P<month>[a-z]{3})/$',**

  **date_based.archive_month,**

  **book_info**

  **),**

  )

  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 Pythons time.strftime . (See Pythons strftime documentation at http://www.djangoproject.com/r/python/strftime/.) Its set to "%b" by default, which is a three-letter month abbreviation (i.e., jan, feb, etc.). To change it to use numbers, use "%m" .

• allow_future : A Boolean specifying whether to include future objects on this page, as described in the previous note.

  This view may also take these common arguments (see Table D-1):

• allow_empty

• context_processors

• extra_context

• mimetype

• template_loader

• template_name

• template_object_name Template Name

  如果”template_name”没有被指定，这个视图将使

  用”<app_label>/<model_name>_archive_month.html”做为默认模板。 Template Context

  In addition to extra_context , the templates context will be as follows:

• 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 variables name depends on the template_object_name parameter, which is 'object' by default. If template_object_name is 'foo' , this variables name will be foo_list .

  Week Archives

  View function : django.views.generic.date_based.archive_week这个视图显示给定星期内的所有对象。

  注记

  为了保持和 Python 内置日期/时间处理方法的一致性，Django 也把星期天当做一周的第一天。 Example

  urlpatterns = patterns('',

  # ...

  **(**

  **r'^(?P<year>d{4})/(?P<week>d{2})/$',**

  **date_based.archive_week,**

  **book_info**

  **),**

  )

  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).

• 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

• allow_future : A Boolean specifying whether to include future objects on this page, as described in the previous note.

  This view may also take these common arguments (see Table D-1):

• allow_empty

• context_processors

• extra_context

• mimetype

• template_loader

• template_name

• template_object_name模板名

  如果``template_name``标识被指定，这个视图会默认使用

  ``<app_label>/<model_name>_archive_week.html`` 模板。模板内容

  In addition to extra_context , the templates context will be as follows:

• 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 variables name depends on the template_object_name parameter, which is 'object' by default. If template_object_name is 'foo' , this variables name will be foo_list .

  Day Archives

  View function : django.views.generic.date_based.archive_day This view generates all objects in a given day.

  Example

  urlpatterns = patterns('',

  # ...

  **(**

  **r'^(?P<year>d{4})/(?P<month>[a-z]{3})/(?P<day>d{2})/$',**

  **date_based.archive_day,**

  **book_info**

  **),**

  )

  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. See the detailed explanation in the Month Archives section, above.

• day_format : Like month_format , but for the day parameter. It defaults to "%d" (the day of the month as a decimal number, 01-31).

• allow_future : A Boolean specifying whether to include future objects on this page, as described in the previous note.

  This view may also take these common arguments (see Table D-1):

• allow_empty

• context_processors

• extra_context

• mimetype

• template_loader

• template_name

• template_object_name Template Name

  如果”template_name”没有被指定，这个视图将使

  用”<app_label>/<model_name>_archive_day.html”做为默认模板。 Template Context

  In addition to extra_context , the templates context will be as follows:

• 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 variables name depends on the template_object_name parameter, which is 'object' by default. If template_object_name is 'foo' , this variables name will be foo_list .

  Archive for Today

  The django.views.generic.date_based.archive_today view shows all objects for today . This is exactly the same as archive_day , except the year /month /day arguments are not used, and todays date is used instead.

  Example

  urlpatterns = patterns('',

  # ...

  **(r'^books/today/$', date_based.archive_today, book_info),**

  )

  Date-Based Detail Pages

  View function : django.views.generic.date_based.object_detail Use this view for a page representing an individual object.

  This has a different URL from the object_detail view; the object_detail view uses URLs like /entries/<slug>/ , while this one uses URLs like

  /entries/2006/aug/27/<slug>/ . Note

  If youre using date-based detail pages with slugs in the URLs, you probably also want to use the unique_for_date option on the slug field to validate that slugs arent duplicated in a single day. See Appendix B for details on unique_for_date .

  Example

  This one differs (slightly) from all the other date-based examples in that we need to provide either an object ID or a slug so that Django can look up the object in question.

  Since the object were using doesnt have a slug field, well use ID-based URLs. Its considered a best practice to use a slug field, but in the interest of simplicity well let it go.

  urlpatterns = patterns('',

  # ...

  **(**

  **r'^(?P<year>d{4})/(?P<month>[a-z]{3})/(?P<day>d{2})/(?P<object_id>[w-]+)/$',**

  **date_based.object_detail,**

  **book_info**

  **),**

  )

  Required Arguments

• year : The objects four-digit year (a string).

• month : The objects month, formatted according to the month_format argument.

• day : The objects 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 .

  Youll also need either:

• object_id : The value of the primary-key field for the object. or:

• slug : The slug of the given object. If you pass this field, then the slug_field argument (described in the following section) is also required.

  Optional Arguments

• allow_future : A Boolean specifying whether to include future objects on this page, as described in the previous note.

• day_format : Like month_format , but for the day parameter. It defaults to "%d" (the day of the month as a decimal number, 01-31).

• month_format : A format string that regulates what format the month parameter uses. See the detailed explanation in the Month Archives section, above.

• slug_field : The name of the field on the object containing the slug. This is required if you are using the slug argument, but it must be absent if youre using the object_id argument.

• 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' .

  This view may also take these common arguments (see Table D-1):

• context_processors

• extra_context

• mimetype

• template_loader

• template_name

• template_object_name Template Name

  If template_name and template_name_field arent specified, this view will use the template <app_label>/<model_name>_detail.html by default.

  Template Context

  In addition to extra_context , the templates context will be as follows:

• object : The object. This variables name depends on the template_object_name parameter, which is 'object' by default. If template_object_name is 'foo' , this variables name will be foo .

  Create/Update/Delete Generic Views

  django.views.generic.create_update 视图包括了创建、编辑和删除对象所需的处理函数。注意

  当 Django 的 form 结构定下来的时候（书上使用的``django.newforms`` ，但是 1.0 已经改成``django.forms``了），这些视图可能会有一些变化。

  These views all present forms if accessed with GET and perform the requested action (create/update/delete) if accessed via POST .

  These views all have a very coarse idea of security. Although they take a login_required attribute, which if given will restrict access to logged-in users, thats as far as it goes. They wont, for example, check that the user editing an object is the same user who created it, nor will they validate any sort of permissions.

  Much of the time, however, those features can be accomplished by writing a small wrapper around the generic view; see Extending Generic Views in Chapter 9.

  Create Object View

  View function : django.views.generic.create_update.create_object

  This view displays a form for creating an object. When the form is submitted, this view redisplays the form with validation errors (if there are any) or saves the object.

  Example

  If we wanted to allow users to create new books in the database, we could do something like this:

  from mysite.books.models import Book from django.conf.urls.defaults import *

  from django.views.generic import date_based book_info = {'model' : Book}

  urlpatterns = patterns('',

  (r'^books/create/$', create_update.create_object, book_info),

  )

  Required Arguments

• model : The Django model of the object that the form will create.

  Note

  Notice that this view takes the model to be created, not a QuerySet (as all the list/detail/date-based views presented previously do).

  Optional Arguments

  post_save_redirect : A URL to which the view will redirect after saving the object. By default, its object.get_absolute_url() .

  post_save_redirect : May contain dictionary string formatting, which will be interpolated against the objects 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/ .

  This view may also take these common arguments (see Table D-1):

• context_processors

• extra_context

• template_loader

• template_name Template Name

  If template_name isnt specified, this view will use the template

  <app_label>/<model_name>_form.html by default. Template Context

  In addition to extra_context , the templates context will be as follows:

  form : A FormWrapper 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><label for="id_name">Name:</label> {{ form.name }}</p>

  <p><label for="id_address">Address:</label> {{ form.address }}</p>

  </form>

  Note that form is an oldforms FormWrapper, which is not covered in this book. See http://www.djangoproject.com/documentation/0.96/forms/ for details.

  Update Object View

  View function : django.views.generic.create_update.update_object

  This view is almost identical to the create object view. However, this one allows the editing of an existing object instead of the creation of a new one.

  Example

  Following the previous example, we could provide an edit interface for a single book with this URLconf snippet:

  from mysite.books.models import Book from django.conf.urls.defaults import *

  from django.views.generic. import date_based book_info = {'model' : Book}

  urlpatterns = patterns('',

  (r'^books/create/$', create_update.create_object, book_info),

  **(**

  **r'^books/edit/(?P<object_id>d+)/$',**

  **create_update.update_object,**

  **book_info**

  **),**

  )

  Required Arguments

• model : The Django model to edit. Again, this is the actual model itself, not a QuerySet .

  And either:

• object_id : The value of the primary-key field for the object. or:

• slug : The slug of the given object. If you pass this field, then the slug_field argument (below) is also required.

  Optional Arguments

• slug_field : The name of the field on the object containing the slug. This is required if you are using the slug argument, but it must be absent if youre using the object_id argument.

  Additionally, this view takes all same optional arguments as the creation view, plus the template_object_name common argument from Table D-1.

  Template Name

  This view uses the same default template name (<app_label>/<model_name>_form.html ) as the creation view.

  Template Context

  In addition to extra_context , the templates context will be as follows:

• form : A FormWrapper instance representing the form for editing the object. See the Create Object View section for more information about this value.

• object : The original object being edited (this variable may be named differently if youve provided the template_object_name argument).

  Delete Object View

  View function : django.views.generic.create_update.delete_object

  这个视图和另外两个创建/编辑视图非常相似。然而，这个视图允许删除对象。

  如果此视图是通过”GET”来取得数据，会显示一个确认画面（比如：你真的要删除这个对象吗？）。如果此视图是通过”POST”提交的话，对象将会不经过确认直接被删除。

  所有的参数同更新对象视图完全一样，做为上下文（context）；这个视图的模板为”<app_label>/<model_name>_confirm_delete.html”。