Django Book 翻译

Appendix D: Generic View Reference
----------------------------------

附录D 通用视图参考
----------------------------------

Chapter 9 introduces generic views but leaves out some of the gory details. This appendix
describes each generic view along with all the options each view can take. Be sure to read
Chapter 9 before trying to understand the reference material that follows. You might want
to refer back to the ``Book`` , ``Publisher`` , and ``Author`` objects defined in that
chapter; the examples that follow use these models.

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

Common Arguments to Generic Views
`````````````````````````````````

通用视图的常见参数
`````````````````````````````````

Most of these views take a large number of arguments that can change the generic views
behavior. Many of these arguments work the same across a large number of views. Table D-1
describes each of these common arguments; anytime you see one of these arguments in a
generic views argument list, it will work as described in the table.

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

.. table:: Table D-1. Common Arguments to Generic Views

    +------------------------+---------------------------------------------------------------+
    |Argument                |Description                                                    |
    +========================+===============================================================+
    |``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 error instead of          |
    |                        |displaying an empty page. By default, this is ``False`` .      |
    +------------------------+---------------------------------------------------------------+
    |``context_processors``  |A list of additional template-context processors (besides the  |
    |                        |defaults) to apply to the views template. See Chapter 10 for   |
    |                        |information on template context processors.                    |
    +------------------------+---------------------------------------------------------------+
    |``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.                                 |
    +------------------------+---------------------------------------------------------------+
    |``mimetype``            |The MIME type to use for the resulting document. It defaults to|
    |                        |the value of the ``DEFAULT_MIME_TYPE`` setting, which is       |
    |                        |``text/html`` if you havent changed it.                        |
    +------------------------+---------------------------------------------------------------+
    |``queryset``            |A ``QuerySet`` (i.e., something like ``Author.objects.all()`` )|
    |                        |to read objects from. See Appendix C for more information about|
    |                        |``QuerySet`` objects. Most generic views require this argument.|
    +------------------------+---------------------------------------------------------------+
    |``template_loader``     |The template loader to use when loading the template. By       |
    |                        |default, its ``django.template.loader`` . See Chapter 10 for   |
    |                        |information on template loaders.                               |
    +------------------------+---------------------------------------------------------------+
    |``template_name``       |The full name of a template to use in rendering the page. This |
    |                        |lets you override the default template name derived from the   |
    |                        |``QuerySet`` .                                                 |
    +------------------------+---------------------------------------------------------------+
    |``template_object_name``|The name of the template variable to use in the template       |
    |                        |context. By default, this is ``'object'`` . Views that list    |
    |                        |more than one object (i.e., ``object_list`` views and various  |
    |                        |objects-for-date views) will append ``'_list'`` to the value of|
    |                        |this parameter.                                                |
    +------------------------+---------------------------------------------------------------+
    

.. table:: Table D-1. Common Arguments to Generic Views

    +------------------------+---------------------------------------------------------------+
    |参数                    |描述                                                           |
    +========================+===============================================================+
    |``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 error instead of          |
    |                        |displaying an empty page. By default, this is ``False`` .      |
    +------------------------+---------------------------------------------------------------+
    |``context_processors``  |A list of additional template-context processors (besides the  |
    |                        |defaults) to apply to the views template. See Chapter 10 for   |
    |                        |information on template context processors.                    |
    +------------------------+---------------------------------------------------------------+
    |``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.                                 |
    +------------------------+---------------------------------------------------------------+
    |``mimetype``            |The MIME type to use for the resulting document. It defaults to|
    |                        |the value of the ``DEFAULT_MIME_TYPE`` setting, which is       |
    |                        |``text/html`` if you havent changed it.                        |
    +------------------------+---------------------------------------------------------------+
    |``queryset``            |A ``QuerySet`` (i.e., something like ``Author.objects.all()`` )|
    |                        |to read objects from. See Appendix C for more information about|
    |                        |``QuerySet`` objects. Most generic views require this argument.|
    +------------------------+---------------------------------------------------------------+
    |``template_loader``     |The template loader to use when loading the template. By       |
    |                        |default, its ``django.template.loader`` . See Chapter 10 for   |
    |                        |information on template loaders.                               |
    +------------------------+---------------------------------------------------------------+
    |``template_name``       |The full name of a template to use in rendering the page. This |
    |                        |lets you override the default template name derived from the   |
    |                        |``QuerySet`` .                                                 |
    +------------------------+---------------------------------------------------------------+
    |``template_object_name``|The name of the template variable to use in the template       |
    |                        |context. By default, this is ``'object'`` . Views that list    |
    |                        |more than one object (i.e., ``object_list`` views and various  |
    |                        |objects-for-date views) will append ``'_list'`` to the value of|
    |                        |this parameter.                                                |
    +------------------------+---------------------------------------------------------------+
    

Simple Generic Views
````````````````````

简易通用视图
````````````````````

The module``django.views.generic.simple`` contains simple views that handle a couple of
common cases: rendering a template when no view logic is needed and issuing a redirect.

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

Rendering a Template
''''''''''''''''''''

渲染模板
''''''''''''''''''''

*View function* : ``django.views.generic.simple.direct_to_template``

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

This view renders a given template, passing it a ``{{ params }}`` template variable, which
is a dictionary of the parameters captured in the URL.

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

Example
.......

例子
.......

Given the following URLconf:

给出下列URLconf:

a request to ``/foo/`` would render the template ``foo_index.html`` , and a request to
``/foo/15/`` would render ``foo_detail.html`` with a context variable ``{{ params.id }}``
that is set to ``15`` .

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

Required Arguments
..................

必要参数

*   ``template`` : The full name of a template to use.

*   ``template`` ：模板的全名。

Redirecting to Another URL
''''''''''''''''''''''''''

重定向到另外一个URL
''''''''''''''''''''''''''

*View function* : ``django.views.generic.simple.redirect_to``

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

This view redirects to another URL. The given URL may contain dictionary-style string
formatting, which will be interpolated against the parameters captured in the URL.

这个视图将源URL重定向到目的URL，目的URL中可以带有字典风格的格式化字符串，在源URL中被捕获的参数可以被格式化输出到目的URL中。

If the given URL is ``None`` , Django will return an HTTP 410 (Gone) message.

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

Example
.......

例子
.......

This URLconf redirects from ``/foo/<id>/`` to ``/bar/<id>/`` :

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

This example returns a Gone response for requests to ``/bar/`` :

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

Required Arguments
..................

必要参数
..................

*   ``url`` : The URL to redirect to, as a string. Or ``None`` to return a 410 (Gone) HTTP
    response.

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

List/Detail Generic Views
`````````````````````````

列表/详细 通用视图
`````````````````````````

The list/detail generic views (in the module ``django.views.generic.list_detail`` ) handle
the common case of displaying a list of items at one view and individual detail views of
those items at another.

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

Lists of Objects
''''''''''''''''

对象列表
''''''''''''''''

*View function* : ``django.views.generic.list_detail.object_list``

*视图函数* : ``django.views.generic.list_detail.object_list``

Use this view to display a page representing a list of objects.

使用这个视图来显示一个对象列表页面。

Example
.......

例子
.......

Given the ``Author`` object from Chapter 5, we can use the ``object_list`` view to show a
simple list of all authors given the following URLconf snippet:

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

Required Arguments
..................

必要参数
..................

*   ``queryset`` : A ``QuerySet`` of objects to list (see Table D-1).

*   ``queryset`` : 要列出的对象的 ``QuerySet`` (参见表 D-1).

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 the following Notes on Pagination section.

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

Additionally, this view may take any of these common arguments described in Table D-1:

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

*   ``allow_empty``

*   ``allow_empty``

*   ``context_processors``

*   ``context_processors``

*   ``extra_context``

*   ``extra_context``

*   ``mimetype``

*   ``mimetype``

*   ``template_loader``

*   ``template_loader``

*   ``template_name``

*   ``template_name``

*   ``template_object_name``

*   ``template_object_name``

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

如果 ``template_name`` 没有被指定, 这个视图将采用
``<app_label>/<model_name>_list.html`` 做为默认模板. 程序标签和模型名都继承自 ``queryset`` 参数. 程序标签是定义模型的程序的名称,模型名是模型类的名称的小写.

In the previous example using ``Author.objects.all()`` as the ``queryset`` , the
application label would be ``books`` and the model name would be ``author`` . This means
the default template would be ``books/author_list.html`` .

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

Template Context
................

模板上下文
................

In addition to ``extra_context`` , the templates context will contain the following:

除了 ``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`` .

*   ``object_list`` : 对象列表.这个变量名依赖于
    ``template_object_name`` 参数, 默认为 ``'object'`` . 如果
    ``template_object_name`` 为 ``'foo'`` , 则变量名为 ``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`` .

*   ``is_paginated`` : 一个布尔型来标示结果是否分页显示.
    然而,如果可用对象数小于或等于 ``paginate_by`` 的话,此参数将被自动设置为 ``False`` .

If the results are paginated, the context will contain these extra variables:

如果结果被分页, ``context `` 还将包含如下扩展变量:

*   ``results_per_page`` : The number of objects per page. (This is the same as the
    ``paginate_by`` parameter.)

*   ``results_per_page`` : 每页显示的对象数. (这个与参数
    ``paginate_by`` 相同.)

*   ``has_next`` : A Boolean representing whether theres a next page.

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

*   ``has_previous`` : A Boolean representing whether theres a previous page.

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

*   ``page`` : The current page number, as an integer. This is 1-based.

*   ``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.

*   ``next`` : 表示为下页的页数，是一个整数，如果下一页不存在的话，这个整数依然会显示为理论上下一页的页数。是基于1数起的。

*   ``previous`` : The previous page number, as an integer. This is 1-based.

*   ``previous`` : 表示为前一页的页数，是一个整数。是基于1数起的。

*   ``pages`` : The total number of pages, as an integer.

*   ``pages`` : 页数总数，是一个整数。

*   ``hits`` : The total number of objects across *all* pages, not just this page.

*   ``hits`` :对象传达所有页面的总数，而并非只是本页。

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:

如果 ``paginate_by`` 被设置, Django 将会对结果进行分页. 你可以用如下两种方法之一来设置页码:

    Use the ``page`` parameter in the URLconf. For example, this is what your URLconf
    might look like:

    在 ``URLconf`` 中使用 ``page`` 参数. 例如, 你的 ``URLconf`` 看起来像这样:

    Pass the page number via the ``page`` query-string parameter. For example, a URL would
    look like this:

    通过 ``page`` 查询字符串参数传递页码. 例如,  URL 看起来像这样:

In both cases, ``page`` is 1-based, not 0-based, so the first page would be represented as
page ``1`` .

在这两种情况下, ``page`` 从1起计数, 而非从0起计数, 所以第一页代表
page ``1`` .

Detail Views
''''''''''''

*View function* : ``django.views.generic.list_detail.object_detail``

*视图函数* : ``django.views.generic.list_detail.object_detail``

This view provides a detail view of a single object.

此视图提供单个对象的详细视图.

Example
.......

例子
.............

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

继续上一个 ``object_list`` 的例子,我们将通过修改 ``URLconf`` 来添加一个给定作者的详细视图:

Required Arguments
..................

必要参数
..................

*   ``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.

*   ``object_id`` : 对象主键的值.

or

或者

*   ``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.

    ``slug_field`` : 包含 slug 的对象的字段名. 如果你使用 slug 参数就必须设置此参数,而使用 ``object_id`` 则一定不能设置此参数.

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

    ``template_name_field`` : 在模板中使用的名字. 让我们在数据中设置模板名字.

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

    换句话说, 如果对象有一个内容是``'foo.html'``的字段：``'the_template'``, 并且你设置 ``template_name_field`` 到 ``'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``

``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_name`` 和 ``template_name_field`` 没有被指定, 这个视图将会使用
 ``<app_label>/<model_name>_detail.html`` 作为缺省模板.

Template Context
................

模板上下文
................

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

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

*   ``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`` .

*   ``object`` : 对象. 取决于 ``template_object_name``
    参数, 默认为 ``'object'`` . 如果 ``template_object_name`` 为 ``'foo'``
    , 此变量名则为 ``foo`` .

Date-Based Generic Views
````````````````````````

基于日期的通用视图
````````````````````````

Date-based generic views are generally used to provide a set of archive pages for dated
material. Think year/month/day archives for a newspaper, or a typical blog archive.

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

Tip:

提示：

By default, these views ignore objects with dates in the future.

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

This means that if you try to visit an archive page in the future, Django will
automatically show a 404 (Page not found) error, even if there are objects published that
day.

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

Thus, you can publish postdated objects that dont appear publicly until their desired
publication date.

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

However, for different types of date-based objects, this isnt appropriate (e.g., a
calendar of upcoming events). For these views, setting the ``allow_future`` option to
``True`` will make the future objects appear (and allow users to visit future archive
pages).

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

Archive Index
'''''''''''''

存档索引
'''''''''''''

*View function* : ``django.views.generic.date_based.archive_index``

*视图函数* ： ``django.views.generic.date_based.archive_index``

This view provides a top-level index page showing the latest (i.e., most recent) objects
by date.

这个视图提供了一个最高层次的索引页用于按日期显示最近的对象。

Example
.......

例子
.......

Say a typical book publisher wants a page of recently published books. Given some ``Book``
object with a ``publication_date`` field, we can use the ``archive_index`` view for this
common task:

举个例子，图书发行商想要一个近期发行图书的页面。给某些“Book”对象一个“publication_date”域，我们可以使用“archive_index”视图来完成这个普通任务：

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

模板名
.............

If ``template_name`` isnt specified, this view will use the template
``<app_label>/<model_name>_archive.html`` by default.

如果 ``template_name`` 没有指定，视图会默认使用模板 ``<app_label>/<model_name>_archive.html`` 。

Template Context
................

模板上下文
................

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

除了 ``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``

Use this view for yearly archive pages. These pages have a list of months in which objects
exists, and they can optionally display all the objects published in a given year.

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

Example
.......

例子
.......

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

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

If ``template_name`` isnt specified, this view will use the template
``<app_label>/<model_name>_archive_year.html`` by default.

如果"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:

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

模板名称

If ``template_name`` isnt specified, this view will use the template
``<app_label>/<model_name>_archive_month.html`` by default.

如果"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``

This view shows all objects in a given week.

这个视图显示给定星期内的所有对象。

Note

注记

For the sake of consistency with Pythons built-in date/time handling, Django assumes that
the first day of the week is Sunday.

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

Example
.......

例子

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

模板名
..............

If ``template_name`` isnt specified, this view will use the template
``<app_label>/<model_name>_archive_week.html`` by default.

如果``template_name``标识被指定，这个视图会默认使用``<app_label>/<model_name>_archive_week.html`` 模板。

Template Context
................

模板内容
................

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

例子

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

这个视图也许会带来一些常见的争论 (see Table D-1):

*   ``allow_empty``

*   ``context_processors``

*   ``extra_context``

*   ``mimetype``

*   ``template_loader``

*   ``template_name``

*   ``template_object_name``

Template Name
.............

模板名称

If ``template_name`` isnt specified, this view will use the template
``<app_label>/<model_name>_archive_day.html`` by default.

如果"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
.......

例子

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.

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

这个视图也适用这些通用参数（参见表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
``````````````````````````````````

The ``django.views.generic.create_update`` module contains a set of functions for
creating, editing, and deleting objects.

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

Note

注意

These views may change slightly when Djangos revised form architecture (currently under
development as ``django.newforms`` ) is finalized.

当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:

如果我们想允许用户在数据库建立新的books，我们可以做如下的范例

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`` :

    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:

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``

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

This view is very similar to the other two create/edit views. This view, however, allows
deletion of objects.

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

If this view is fetched with ``GET`` , it will display a confirmation page (i.e., Do you
really want to delete this object?). If the view is submitted with ``POST`` , the object
will be deleted without confirmation.

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

All the arguments are the same as for the update object view, as is the context; the
template name for this view is ``<app_label>/<model_name>_confirm_delete.html`` .

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