The Django Book

Installing ReportLab

安装 ReportLab

Before you do any PDF generation, however, youll need to install ReportLab. Its usually pretty simple: just download and install the library from http://www.reportlab.org/downloads.html.

在生� PDF 文件之�，需�安装 ReportLab 库。这通常是个很简�的过程：从 http://www.reportlab.org/downloads.html 下载并且安装这个库��。

The user guide (naturally available only as a PDF file) at http://www.reportlab.org/rsrc/userguide.pdf has additional installation instructions.

使用手册（原始的�有 PDF 格�）�以从 http://www.reportlab.org/rsrc/userguide.pdf 下载，其中包�有一些其它的安装指�。

Note

注�

If youre using a modern Linux distribution, you might want to check your package management utility before installing ReportLab. Most package repositories have added ReportLab.

如果使用的是一些新的 Linux �行版，则在安装��以先检查包管�软件。多数软件包仓库中都加入了 ReportLab 。

For example, if youre using the (excellent) Ubuntu distribution, a simple apt-get install python-reportlab will do the trick nicely.

比如，如果使用（�出的） Ubuntu �行版，�需�简�的 apt-get install python-reportlab 一行命令��完�安装。

Test your installation by importing it in the Python interactive interpreter:

在 Python 交互环境中导入这个软件包以检查安装是��功。

>>> import reportlab

If that command doesnt raise any errors, the installation worked.

如果刚�那�命令没有出现任何错误，则表明安装�功。

Writing Your View

编写视图

Like CSV, generating PDFs dynamically with Django is easy because the ReportLab API acts on filelike objects.

和 CSV 类似，由 Django 动�生� PDF 文件很简�，因为 ReportLab API �样�以使用类似文件对象。

Heres a Hello World example:

下�是一个 Hello World 的示例：

from reportlab.pdfgen import canvas
from django.http import HttpResponse

def hello_pdf(request):
    # Create the HttpResponse object with the appropriate PDF headers.
    response = HttpResponse(mimetype='application/pdf')
    response['Content-Disposition'] = 'attachment; filename=hello.pdf'

    # Create the PDF object, using the response object as its "file."
    p = canvas.Canvas(response)

    # Draw things on the PDF. Here's where the PDF generation happens.
    # See the ReportLab documentation for the full list of functionality.
    p.drawString(100, 100, "Hello world.")

    # Close the PDF object cleanly, and we're done.
    p.showPage()
    p.save()
    return response

A few notes are in order:

需�注�以下几点：

• Here we use the application/pdf MIME type. This tells browsers that the document is a PDF file, rather than an HTML file. If you leave off this information, browsers will probably interpret the response as HTML, which will result in scary gobbledygook in the browser window.

• 这里我们使用的 MIME 类型是 application/pdf 。这会告诉æµ�览器这个文档是一个 PDF 文档，而ä¸�是 HTML 文档。如果忽略了这个å�‚数，æµ�览器å�¯èƒ½ä¼šæŠŠè¿™ä¸ªæ–‡ä»¶çœ‹æˆ� HTML 文档，这会使æµ�览器的窗å�£ä¸­å‡ºçŽ°å¾ˆå¥‡æ€ªçš„文字。

• Hooking into the ReportLab API is easy: just pass response as the first argument to canvas.Canvas . The Canvas class expects a filelike object, and HttpResponse objects fit the bill.

• 使用 ReportLab çš„ API 很简å�•ï¼šå�ªéœ€è¦�å°† response 对象作为 canvas.Canvas 的第一个å�‚数传入。 Canvas 类需è¦�一个类似文件的对象， HttpResponse 对象å�¯ä»¥æ»¡è¶³è¿™ä¸ªè¦�求。

• All subsequent PDF-generation methods are called on the PDF object (in this case, p ), not on response .

• 所有å�Žç»­çš„ PDF 生æˆ�方法需è¦�ç”± PDF 对象调用（在本例中是 p ），而ä¸�是 response 对象。

• Finally, its important to call showPage() and save() on the PDF file (or else youll end up with a corrupted PDF file).

• 最å�Žéœ€è¦�对 PDF 文件调用 showPage() å’Œ save() 方法（å�¦åˆ™ä½ ä¼šå¾—到一个æ�Ÿå��çš„ PDF 文件）。

Complex PDFs

��的 PDF 文件

If youre creating a complex PDF document (or any large data blob), consider using the cStringIO library as a temporary holding place for your PDF file. The cStringIO library provides a file-like object interface that is written in C for maximum efficiency.

如果您在创建一个��的 PDF 文档（或者任何较大的数��），请使用 cStringIO 库存放临时生�的 PDF 文件。 cStringIO �供了一个用 C 编写的类似文件对象的接�，从而�以使系统的效率最高。

Heres the previous Hello World example rewritten to use cStringIO :

下�是使用 cStringIO �写的 Hello World 例�：

from cStringIO import StringIO
from reportlab.pdfgen import canvas
from django.http import HttpResponse

def hello_pdf(request):
    # Create the HttpResponse object with the appropriate PDF headers.
    response = HttpResponse(mimetype='application/pdf')
    response['Content-Disposition'] = 'attachment; filename=hello.pdf'

    temp = StringIO()

    # Create the PDF object, using the StringIO object as its "file."
    p = canvas.Canvas(temp)

    # Draw things on the PDF. Here's where the PDF generation happens.
    # See the ReportLab documentation for the full list of functionality.
    p.drawString(100, 100, "Hello world.")

    # Close the PDF object cleanly.
    p.showPage()
    p.save()

    # Get the value of the StringIO buffer and write it to the response.
    response.write(temp.getvalue())
    return response

Initialization

�始化

To activate syndication feeds on your Django site, add this URLconf:

为了在您的Django站点中激活syndication feeds, 添加如下的 URLconf:

(r'^feeds/(?P<url>.*)/$',
 'django.contrib.syndication.views.feed',
 {'feed_dict': feeds}
),

This line tells Django to use the RSS framework to handle all URLs starting with "feeds/" . (You can change that "feeds/" prefix to fit your own needs.)

这一行告诉Django使用RSS框架处�所有的以 "feeds/" 开头的URL. ( 你�以修改 "feeds/" �缀以满足您自己的�求. )

This URLconf line has an extra argument: {'feed_dict': feeds} . Use this extra argument to pass the syndication framework the feeds that should be published under that URL.

URLConf里有一行å�‚数：``{‘feed_dict’: feeds}``，这个å�‚æ•°å�¯ä»¥æŠŠå¯¹åº”URL需è¦�å�‘布的feed内容传递给 syndication framework

Specifically, feed_dict should be a dictionary that maps a feeds slug (short URL label) to its Feed class. You can define the feed_dict in the URLconf itself. Heres a full example URLconf:

特别的，feed_dict应该是一个映射feed的slug(简短URL标签)到它的Feed类的字典 你�以在URL�置本身里定义feed_dict，这里是一个完整的例�

from django.conf.urls.defaults import *
from myproject.feeds import LatestEntries, LatestEntriesByCategory

feeds = {
    'latest': LatestEntries,
    'categories': LatestEntriesByCategory,
}

urlpatterns = patterns('',
    # ...
    (r'^feeds/(?P<url>.*)/$', 'django.contrib.syndication.views.feed',
        {'feed_dict': feeds}),
    # ...
)

The preceding example registers two feeds:

��的例�注册了两个feed:

• The feed represented by LatestEntries will live at feeds/latest/ .

• LatestEntries``表示的内容将对应到``feeds/latest/ .

• The feed represented by LatestEntriesByCategory will live at feeds/categories/ .

• LatestEntriesByCategory``的内容将对应到 ``feeds/categories/ .

Once thats set up, youll need to define the Feed classes themselves.

以上的设定完�之�，接下�需�自己定义 Feed 类

A Feed class is a simple Python class that represents a syndication feed. A feed can be simple (e.g., a site news feed, or a basic feed displaying the latest entries of a blog) or more complex (e.g., a feed displaying all the blog entries in a particular category, where the category is variable).

一个 Feed 类是一个简�的python类，用�表示一个syndication feed. 一个feed�能是简�的 (例如一个站点新闻feed，或者最基本的，显示一个blog的最新�目)，也�能更加��(例如一个显示blog�一类别下所有�目的feed。这里类别 category 是个��).

Feed classes must subclass django.contrib.syndication.feeds.Feed . They can live anywhere in your code tree.

Feed类必须继承django.contrib.syndication.feeds.Feed，它们�以在你的代�树的任何�置

A Simple Feed

一个简�的Feed

This simple example, taken from chicagocrime.org, describes a feed of the latest five news items:

例��自于chicagocrime.org，�述最近5项新闻�目的feed:

from django.contrib.syndication.feeds import Feed
from chicagocrime.models import NewsItem

class LatestEntries(Feed):
    title = "Chicagocrime.org site news"
    link = "/sitenews/"
    description = "Updates on changes and additions to chicagocrime.org."

    def items(self):
        return NewsItem.objects.order_by('-pub_date')[:5]

The important things to notice here are as follows:

�注�的��的事情如下所示:

The class subclasses django.contrib.syndication.feeds.Feed .

�类 django.contrib.syndication.feeds.Feed .

title , link , and description correspond to the standard RSS <title> , <link> , and <description> elements, respectively.

title , link , 和 description 对应一个标准 RSS 里的 <title> , <link> , 和 <description> 标签.

items() is simply a method that returns a list of objects that should be included in the feed as <item> elements. Although this example returns NewsItem objects using Djangos database API, items() doesnt have to return model instances.

items() 是一个方法，返回一个用以包�在包�在feed的 <item> 元素里的 list 虽然例�里用Djangos database API返回的 NewsItem 对象, items() �一定必须返回 model的实例

You do get a few bits of functionality for free by using Django models, but items() can return any type of object you want.

你�以利用 Django models�费实现一定功能，但是 items() �以返回你想�的任�类型的对象.

Theres just one more step. In an RSS feed, each <item> has a <title> , <link> , and <description> . We need to tell the framework what data to put into those elements.

还有一个步骤，在一个RSS feed里，�个(item)有一个(title)，(link)和(description)，我们需�告诉框架 把数�放到这些元素中

To specify the contents of <title> and <description> , create Django templates (see Chapter 4) called feeds/latest_title.html and feeds/latest_description.html , where latest is the slug specified in the URLconf for the given feed. Note that the .html extension is required.

如果�指定 <title> 和 <description> ，�以建立一个Django模�（�Chapter 4）�字� feeds/latest_title.html 和 feeds/latest_description.html ，�者是URLConf里为对应feed指定的 slug 。注� .html �缀是必须的。

The RSS system renders that template for each item, passing it two template context variables:

RSS系统模�渲染�一个�目，需�给传递2个�数给模�上下文��：

• obj : The current object (one of whichever objects you returned in items() ).

• obj : 当å‰�对象 ( 返回到 items() ä»»æ„�对象之一 )。

• site : A django.models.core.sites.Site object representing the current site. This is useful for {{ site.domain }} or {{ site.name }} .

• site : 一个表示当å‰�站点的 django.models.core.sites.Site 对象。 这对于 {{ site.domain }} 或者 {{ site.name }} 很有用。

If you dont create a template for either the title or description, the framework will use the template "{{ obj }}" by default that is, the normal string representation of the object.

如果你在创建模�的时候，没有指明标题或者�述信�，框架会默认使用 "{{ obj }}" ，对象的字符串表示。

You can also change the names of these two templates by specifying title_template and description_template as attributes of your Feed class.

你也�以通过修改 Feed 类中的两个属性 title_template 和 description_template �改�这两个模�的�字。

To specify the contents of <link> , you have two options. For each item in items() , Django first tries executing a get_absolute_url() method on that object. If that method doesnt exist, it tries calling a method item_link() in the Feed class, passing it a single parameter, item , which is the object itself.

你有两�方法�指定 <link> 的内容。 Django 首先执行 items() 中�一项的 get_absolute_url() 方法。 如果该方法�存在，就会�试执行 Feed 类中的 item_link() 方法，并将自身作为 item �数传递进去。

Both get_absolute_url() and item_link() should return the items URL as a normal Python string.

get_absolute_url() 和 item_link() 都应该以Python字符串形�返回URL。

For the previous LatestEntries example, we could have very simple feed templates. latest_title.html contains:

对于���到的 LatestEntries 例�，我们�以实现一个简�的feed模�。 latest_title.html 包括：

{{ obj.title }}

and latest_description.html contains:

并且 latest_description.html 包�:

{{ obj.description }}

Its almost too easy

这真是 太 简�了�

A More Complex Feed

一个更��的Feed

The framework also supports more complex feeds, via parameters.

框架通过�数支�更加��的feeds。

For example, chicagocrime.org offers an RSS feed of recent crimes for every police beat in Chicago. It would be silly to create a separate Feed class for each police beat; that would violate the Dont Repeat Yourself (DRY) principle and would couple data to programming logic.

举个例�，chicagocrime.org�供了一个RSS�以跟踪�一片区域的犯罪近况。如果为�一个�独的区域建立一个 Feed 类就显得很�明智。这样�就��了DRY原则了，程�逻辑也会和数�耦�在一起。

Instead, the syndication framework lets you make generic feeds that return items based on information in the feeds URL.

�而代之的方法是，使用��框架�产生一个通用的�，使其�以根�feeds URL返回相应的信�。

On chicagocrime.org, the police-beat feeds are accessible via URLs like this:

在chicagocrime这个例�中，区域信��以通过这样的URL方��访问:

• http://www.chicagocrime.org/rss/beats/0613/ : Returns recent crimes for beat 0613

• http://www.chicagocrime.org/rss/beats/0613/ ：返回0613å�·åœ°åŒºçš„犯罪数æ�®

• http://www.chicagocrime.org/rss/beats/1424/ : Returns recent crimes for beat 1424

• http://www.chicagocrime.org/rss/beats/1424/ ：返回1424å�·åœ°åŒºçš„犯罪数æ�®

The slug here is "beats" . The syndication framework sees the extra URL bits after the slug 0613 and 1424 and gives you a hook to tell it what those URL bits mean and how they should influence which items get published in the feed.

固定的那一部分是 "beats" （区域）。��框架看到了��的��之处 0613 和 1424 ，它会�供给你一个钩�函数��述这些URL的�义，以�会对feed中的项产生的影�。

An example makes this clear. Heres the code for these beat-specific feeds:

举个例�会澄清一切。下�是�个地区特定的feeds：

from django.core.exceptions import ObjectDoesNotExist

class BeatFeed(Feed):
    def get_object(self, bits):
        # In case of "/rss/beats/0613/foo/bar/baz/", or other such
        # clutter, check that bits has only one member.
        if len(bits) != 1:
            raise ObjectDoesNotExist
        return Beat.objects.get(beat__exact=bits[0])

    def title(self, obj):
        return "Chicagocrime.org: Crimes for beat %s" % obj.beat

    def link(self, obj):
        return obj.get_absolute_url()

    def description(self, obj):
        return "Crimes recently reported in police beat %s" % obj.beat

    def items(self, obj):
        crimes =  Crime.objects.filter(beat__id__exact=obj.id)
        return crimes.order_by('-crime_date')[:30]

Heres the basic algorithm the RSS framework, given this class and a request to the URL /rss/beats/0613/ :

以下是RSS框架的基本算法，我们�设通过URL /rss/beats/0613/ �访问这个类：

The framework gets the URL /rss/beats/0613/ and notices theres an extra bit of URL after the slug. It splits that remaining string by the slash character ("/" ) and calls the Feed classs get_object() method, passing it the bits.

框架获得了URL /rss/beats/0613/ 并且注�到URL中的slug部分���有更多的信�。它将斜�("/" )作为分隔符，把剩余的字符串分割开作为�数，调用 Feed 类的 get_object() 方法。

In this case, bits is ['0613'] . For a request to /rss/beats/0613/foo/bar/ , bits would be ['0613', 'foo', 'bar'] .

在这个例�中，添加的信�是 ['0613'] 。对于 /rss/beats/0613/foo/bar/ 的一个URL请求， 这些信�就是 ['0613', 'foo', 'bar'] 。

get_object() is responsible for retrieving the given beat, from the given bits .

get_object() 就根�给定的 bits 值�返回区域信�。

In this case, it uses the Django database API to retrieve the beat. Note that get_object() should raise django.core.exceptions.ObjectDoesNotExist if given invalid parameters. Theres no try /except around the Beat.objects.get() call, because its not necessary. That function raises Beat.DoesNotExist on failure, and Beat.DoesNotExist is a subclass of ObjectDoesNotExist . Raising ObjectDoesNotExist in get_object() tells Django to produce a 404 error for that request.

在这个例�中，它使用了Django的数�库API�获�信�。注�到如果给定的�数��法， get_object() 会抛出 django.core.exceptions.ObjectDoesNotExist 异常。在 Beat.objects.get() 调用中也没有出现 try /except 代��。函数在出错时抛出 Beat.DoesNotExist 异常，而 Beat.DoesNotExist 是 ObjectDoesNotExist 异常的一个�类型。 而在 get_object()

中抛出 ObjectDoesNotExist 异常�会使得Django引�404错误。

To generate the feeds <title> , <link> , and <description> , Django uses the title() , link() , and description() methods. In the previous example, they were simple string class attributes, but this example illustrates that they can be either strings or methods. For each of title , link , and description , Django follows this algorithm:

为产生 <title> ， <link> ， 和 <description> 的feeds， Django使用 title() , link() , 和 description() 方法。 在上�的例�中，它们都是简�的字符串类型的类属性，而这个例�表明，它们既�以是字符串， 也�以是 方法。对于�一个 title ， link 和 description 的组�，Django使用以下的算法：

1. It tries to call a method, passing the obj argument, where obj is the object returned by get_object() .

1. 试图调用一个函数，并且以 get_object() 返回的对象作为�数传递给 obj �数。

2. Failing that, it tries to call a method with no arguments.

2. 如果没有�功，则�带�数调用一个方法。

3. Failing that, it uses the class attribute.

3. 还��功，则使用类属性。

Finally, note that items() in this example also takes the obj argument. The algorithm for items is the same as described in the previous step first, it tries items(obj) , then items() , and then finally an items class attribute (which should be a list).

最�，值得注�的是，这个例�中的 items() 使用 obj �数。对于 items 的算法就如�上�第一步所�述的那样，首先�试 items(obj) ， 然�是 items() ，最�是 items 类属性（必须是一个列表）。

Full documentation of all the methods and attributes of the Feed classes is always available from the official Django documentation (http://www.djangoproject.com/documentation/0.96/syndication_feeds/).

Feed 类所有方法和属性的完整文档，请�考官方的Django文档 (http://www.djangoproject.com/documentation/0.96/syndication_feeds/) 。

Specifying the Type of Feed

指定Feed的类型

By default, the syndication framework produces RSS 2.0. To change that, add a feed_type attribute to your Feed class:

默认情况下, ��框架生�RSS 2.0. �改�这样的情况, 在 Feed 类中添加一个 feed_type 属性.

from django.utils.feedgenerator import Atom1Feed

class MyFeed(Feed):
    feed_type = Atom1Feed

Note that you set feed_type to a class object, not an instance. Currently available feed types are shown in Table 11-1.

注�你把 feed_type 赋值�一个类对象，而�是类实例。目��法的Feed类型如表11-1所示。

Enclosures

闭包

To specify enclosures (i.e., media resources associated with a feed item such as MP3 podcast feeds), use the item_enclosure_url , item_enclosure_length , and item_enclosure_mime_type hooks, for example:

为了指定闭包（例如，与feed项比方说MP3 feeds相关�的媒体资�信�），使用 item_enclosure_url ， item_enclosure_length ， 以� item_enclosure_mime_type ，比如

from myproject.models import Song

class MyFeedWithEnclosures(Feed):
    title = "Example feed with enclosures"
    link = "/feeds/example-with-enclosures/"

    def items(self):
        return Song.objects.all()[:30]

    def item_enclosure_url(self, item):
        return item.song_url

    def item_enclosure_length(self, item):
        return item.song_length

    item_enclosure_mime_type = "audio/mpeg"

This assumes, of course, that youve created a Song object with song_url and song_length (i.e., the size in bytes) fields.

当然，你首先�创建一个包�有 song_url 和 song_length （比如按照字节计算的长度）域的 Song 对象。

Language

语言

Feeds created by the syndication framework automatically include the appropriate <language> tag (RSS 2.0) or xml:lang attribute (Atom). This comes directly from your LANGUAGE_CODE setting.

��框架自动创建的Feed包�适当的 <language> 标签(RSS 2.0) 或 xml:lang 属性(Atom). 他直接�自于您的 LANGUAGE_CODE 设置.

URLs

URLs

The link method/attribute can return either an absolute URL (e.g., "/blog/" ) or a URL with the fully qualified domain and protocol (e.g., "http://www.example.com/blog/" ). If link doesnt return the domain, the syndication framework will insert the domain of the current site, according to your SITE_ID setting.

link 方法/属性�以以�对URL的形�（例如， "/blog/" ）或者指定�议和域�的URL的形�返回（例如 "http://www.example.com/blog/" ）。如果 link 没有返回域�，��框架会根� SITE_ID 设置，自动的�入当�站点的域信�。

Atom feeds require a <link rel="self"> that defines the feeds current location. The syndication framework populates this automatically, using the domain of the current site according to the SITE_ID setting.

Atom feeds需� <link rel="self"> 指明feeds现在的�置。��框架根� SITE_ID 的设置，使用站点的域�自动完�这些功能。

Publishing Atom and RSS Feeds in Tandem

�时�布Atom and RSS

Some developers like to make available both Atom and RSS versions of their feeds. Thats easy to do with Django: just create a subclass of your feed class and set the feed_type to something different. Then update your URLconf to add the extra versions. Heres a full example:

一些开�人员想 �时 支�Atom和RSS。这在Django中很容易实现：�需创建一个你的 feed 类的�类，然�修改 feed_type ，并且更新URLconf内容。下�是一个完整的例�：

from django.contrib.syndication.feeds import Feed
from chicagocrime.models import NewsItem
from django.utils.feedgenerator import Atom1Feed

class RssSiteNewsFeed(Feed):
    title = "Chicagocrime.org site news"
    link = "/sitenews/"
    description = "Updates on changes and additions to chicagocrime.org."

    def items(self):
        return NewsItem.objects.order_by('-pub_date')[:5]

class AtomSiteNewsFeed(RssSiteNewsFeed):
    feed_type = Atom1Feed

And heres the accompanying URLconf:

这是与之相对应那个的URLconf：

from django.conf.urls.defaults import *
from myproject.feeds import RssSiteNewsFeed, AtomSiteNewsFeed

feeds = {
    'rss': RssSiteNewsFeed,
    'atom': AtomSiteNewsFeed,
}

urlpatterns = patterns('',
    # ...
    (r'^feeds/(?P<url>.*)/$', 'django.contrib.syndication.views.feed',
        {'feed_dict': feeds}),
    # ...
)

Installation

安装

To install the sitemap application, follow these steps:

�安装 sitemap 应用程�, 按下�的步骤进行:

1. Add 'django.contrib.sitemaps' to your INSTALLED_APPS setting.

1. 将 'django.contrib.sitemaps' 添加到您的 INSTALLED_APPS 设置中.

2. Make sure 'django.template.loaders.app_directories.load_template_source' is in your TEMPLATE_LOADERS setting. Its in there by default, so youll need to change this only if youve changed that setting.

2. 确� 'django.template.loaders.app_directories.load_template_source' 在您的 TEMPLATE_LOADERS 设置中。默认情况下它在那里, 所以, 如果你已�改�了那个设置的�, �需�改回���。

3. Make sure youve installed the sites framework (see Chapter 14).

3. 确定您已�安装了 sites 框架 (��第14章).

Note

备注

The sitemap application doesnt install any database tables. The only reason it needs to go into INSTALLED_APPS is so the load_template_source template loader can find the default templates.

sitemap 应用程�没有安装任何数�库表. 它需�加入到 INSTALLED_APPS 中的唯一原因是: 这样 load_template_source 模�加载器�以找到默认的模�.

Initialization

�始化

To activate sitemap generation on your Django site, add this line to your URLconf:

�在您的Django站点中激活sitemap生�, 请在您的 URLconf 中添加这一行:

(r'^sitemap.xml$', 'django.contrib.sitemaps.views.sitemap', {'sitemaps': sitemaps})

This line tells Django to build a sitemap when a client accesses /sitemap.xml .

这一行告诉 Django, 当客户访问 /sitemap.xml 的时候, 构建一个 sitemap.

The name of the sitemap file is not important, but the location is. Search engines will only index links in your sitemap for the current URL level and below. For instance, if sitemap.xml lives in your root directory, it may reference any URL in your site. However, if your sitemap lives at /content/sitemap.xml , it may only reference URLs that begin with /content/ .

sitemap文件的�字无关紧�，但是它在�务器上的�置�很��。�索引擎�索引你的sitemap中当�URL级别�其以下级别的链接。用一个实例�说，如果 sitemap.xml �于你的根目录，那么它将引用任何的URL。然而，如果你的sitemap�于 /content/sitemap.xml ，那么它�引用以 /content/ 打头的URL。

The sitemap view takes an extra, required argument: {'sitemaps': sitemaps} . sitemaps should be a dictionary that maps a short section label (e.g., blog or news ) to its Sitemap class (e.g., BlogSitemap or NewsSitemap ). It may also map to an instance of a Sitemap class (e.g., BlogSitemap(some_var) ).

sitemap视图需�一个�外的必须的�数： {'sitemaps': sitemaps} 。 sitemaps 应该是一个字典，它把一个短的�标签(例如, blog 或 news )映射到它的 Sitemap 类(例如， BlogSitemap 或 NewsSitemap )。它也�以映射到一个 Sitemap 类的实例(例如， BlogSitemap(some_var) )。

Sitemap Classes

Sitemap ç±»

A Sitemap class is a simple Python class that represents a section of entries in your sitemap. For example, one Sitemap class could represent all the entries of your Weblog, while another could represent all of the events in your events calendar.

Sitemap 类展示了一个进入地图站点简�的Python类片断.例如,一个 Sitemap 类能展现所有日志入�，而�外一个能够调度所有的日历事件。

In the simplest case, all these sections get lumped together into one sitemap.xml , but its also possible to use the framework to generate a sitemap index that references individual sitemap files, one per section (as described shortly).

在最简�的例�中，所有部分�以全部包�在一个 sitemap.xml 中，也�以使用框架�产生一个站点地图，为�一个独立的部分产生一个�独的站点文件。

Sitemap classes must subclass django.contrib.sitemaps.Sitemap . They can live anywhere in your code tree.

Sitemap 类必须是 django.contrib.sitemaps.Sitemap 的�类. 他们�以存在于您的代�树的任何地方。

For example, lets assume you have a blog system, with an Entry model, and you want your sitemap to include all the links to your individual blog entries. Heres how your Sitemap class might look:

例如�设你有一个blog系统，有一个 Entry 的model，并且你希望你的站点地图包�所有连到你的blog入�的超链接。你的 Sitemap 类很�能是这样的：

from django.contrib.sitemaps import Sitemap
from mysite.blog.models import Entry

class BlogSitemap(Sitemap):
    changefreq = "never"
    priority = 0.5

    def items(self):
        return Entry.objects.filter(is_draft=False)

    def lastmod(self, obj):
        return obj.pub_date

Declaring a Sitemap should look very similar to declaring a Feed ; thats by design.

声明一个 Sitemap 和声明一个 Feed 看起�很类似；这都是预先设计好的。

Like Feed classes, Sitemap members can be either methods or attributes. See the steps in the earlier A Complex Example section for more about how this works.

如� Feed 类一样， Sitemap �员也既�以是方法，也�以是属性。想�知�更详细的内容，请��上文 《一个��的例�》章节。

A Sitemap class can define the following methods/attributes:

一个 Sitemap 类�以定义如下 方法/属性:

items (required ): Provides list of objects. The framework doesnt care what type of objects they are; all that matters is that these objects get passed to the location() , lastmod() , changefreq() , and priority() methods.

items (必需 )：�供对象列表。框架并�关心对象的 类型 ；唯一关心的是这些对象会传递给 location() ， lastmod() ， changefreq() ，和 priority() 方法。

location (optional): Gives the absolute URL for a given object. Here, absolute URL means a URL that doesnt include the protocol or domain. Here are some examples:

location （�选）：给定对象的�对URL。�对URL�包��议�称和域�。下�是一些例�：

• Good: '/foo/bar/'

• 好的: '/foo/bar/'

• Bad: 'example.com/foo/bar/'

• 差的: 'example.com/foo/bar/'

• Bad: 'http://example.com/foo/bar/'

• 差的: 'http://example.com/foo/bar/'

If location isnt provided, the framework will call the get_absolute_url() method on each object as returned by items() .

如果没有�供 location , 框架将会在�个 items() 返回的对象上调用 get_absolute_url() 方法.

lastmod (optional): The objects last modification date, as a Python datetime object.

lastmod (�选): 对象的最�修改日期, 作为一个Python datetime 对象.

changefreq (optional): How often the object changes. Possible values (as given by the Sitemaps specification) are as follows:

changefreq （�选）：对象�更的频率。�选的值如下（详�Sitemaps文档）：

• 'always'

• 'always'

• 'hourly'

• 'hourly'

• 'daily'

• 'daily'

• 'weekly'

• 'weekly'

• 'monthly'

• 'monthly'

• 'yearly'

• 'yearly'

• 'never'

• 'never'

priority (optional): A suggested indexing priority between 0.0 and 1.0 . The default priority of a page is 0.5 ; see the http://sitemaps.org documentation for more about how priority works.

priority （�选）：�值范围在 0.0 and 1.0 之间，用�表明优先级。默认值为 0.5 ；请详� http://sitemaps.org 文档。

Shortcuts

快�方�

The sitemap framework provides a couple convenience classes for common cases. These are described in the sections that follow.

sitemap框架�供了一些常用的类。在下一部分中会看到。

from django.conf.urls.defaults import *
from django.contrib.sitemaps import FlatPageSitemap, GenericSitemap
from mysite.blog.models import Entry

info_dict = {
    'queryset': Entry.objects.all(),
    'date_field': 'pub_date',
}

sitemaps = {
    'flatpages': FlatPageSitemap,
    'blog': GenericSitemap(info_dict, priority=0.6),
}

urlpatterns = patterns('',
    # some generic view using info_dict
    # ...

    # the sitemap
    (r'^sitemap.xml$',
     'django.contrib.sitemaps.views.sitemap',
     {'sitemaps': sitemaps})
)

Creating a Sitemap Index

创建一个Sitemap索引

The sitemap framework also has the ability to create a sitemap index that references individual sitemap files, one per each section defined in your sitemaps dictionary. The only differences in usage are as follows:

sitemap框架�样�以根� sitemaps 字典中定义的�独的sitemap文件�建立索引。用法区别如下：

• You use two views in your URLconf: django.contrib.sitemaps.views.index and django.contrib.sitemaps.views.sitemap .

• 您在您的URLconf 中使用了两个视图: django.contrib.sitemaps.views.index å’Œ django.contrib.sitemaps.views.sitemap .

• The django.contrib.sitemaps.views.sitemap view should take a section keyword argument.

• django.contrib.sitemaps.views.sitemap 视图需è¦�带一个 section 关键字å�‚æ•°.

Here is what the relevant URLconf lines would look like for the previous example:

这里是��的例�的相关的 URLconf 行看起�的样�:

(r'^sitemap.xml$',
 'django.contrib.sitemaps.views.index',
 {'sitemaps': sitemaps}),

(r'^sitemap-(?P<section>.+).xml$',
 'django.contrib.sitemaps.views.sitemap',
 {'sitemaps': sitemaps})

This will automatically generate a sitemap.xml file that references both sitemap-flatpages.xml and sitemap-blog.xml . The Sitemap classes and the sitemaps dictionary dont change at all.

这将自动生�一个 sitemap.xml 文件, 它�时引用 sitemap-flatpages.xml 和 sitemap-blog.xml . Sitemap 类和 sitemaps 目录根本没有更改.

Pinging Google

通知Google

You may want to ping Google when your sitemap changes, to let it know to reindex your site. The framework provides a function to do just that: django.contrib.sitemaps.ping_google() .

当你的sitemap�化的时候，你会想通知Google，以便让它知�对你的站点进行�新索引。框架就�供了这样的一个函数： django.contrib.sitemaps.ping_google() 。

Note

备注

At the time this book was written, only Google responded to sitemap pings. However, its quite likely that Yahoo and/or MSN will soon support these pings as well.

在本书写�的时候, �有Google�以�应sitemap更新通知。然而，Yahoo和MSN�能很快也会支�这些通知。

At that time, well likely change the name of ping_google() to something like ping_search_engines() , so make sure to check the latest sitemap documentation at http://www.djangoproject.com/documentation/0.96/sitemaps/.

到那个时候，把“ping_google()�这个�字改�“ping_search_engines()�会比较好。所以还是到http://www.djangoproject.com/documentation/0.96/sitemaps/ 去检查一下最新的站点地图文档。

ping_google() takes an optional argument, sitemap_url , which should be the absolute URL of your sites sitemap (e.g., '/sitemap.xml' ). If this argument isnt provided, ping_google() will attempt to figure out your sitemap by performing a reverse lookup on your URLconf.

ping_google() 有一个�选的�数 sitemap_url ，它应该是你的站点地图的URL�对地�（例如： /sitemap.xml ）。如果��供该�数， ping_google() 将�试通过�查你的URLconf�找到你的站点地图。

ping_google() raises the exception django.contrib.sitemaps.SitemapNotFound if it cannot determine your sitemap URL.

如果�能够确定你的sitemap URL, ping_google() 会引� django.contrib.sitemaps.SitemapNotFound 异常。

One useful way to call ping_google() is from a models save() method:

我们�以通过模型中的 save() 方法�调用 ping_google() ：

from django.contrib.sitemaps import ping_google

class Entry(models.Model):
    # ...
    def save(self):
        super(Entry, self).save()
        try:
            ping_google()
        except Exception:
            # Bare 'except' because we could get a variety
            # of HTTP-related exceptions.
            pass

A more efficient solution, however, would be to call ping_google() from a cron script or some other scheduled task. The function makes an HTTP request to Googles servers, so you may not want to introduce that network overhead each time you call save() .

一个更有效的解决方案是用 cron 脚本或任务调度表�调用 ping_google() ，该方法使用Http直接请求Google�务器，从而�少�次调用 save() 时�用的网络带宽。