The Django Book

Example

例子

Given the following URLconf:

给出下列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'}),
)

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 ：模板的全名。

Example

例子

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

这个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/'}),
)

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

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

from django.views.generic.simple import redirect_to

urlpatterns = patterns('django.views.generic.simple',
    ('^bar/$', redirect_to, {'url': None}),
)

Required Arguments

必要参数

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

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

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的内容如下：

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

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 看起来像这样:

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

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

/objects/?page=3

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 .

Example

例子

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

继续上一个 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,
}
**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),**
)

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 .

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”视图来完成这个普通任务：

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

模板名

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 .

Example

例子

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

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.

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

模板名称

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 .

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

模板名

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 .

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

这个视图也许会带来一些常见的争论 (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 .

Example

例子

urlpatterns = patterns('',
    # ...
    **(r'^books/today/$', date_based.archive_today, book_info),**
)

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

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

Example

例子

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

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

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.

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