PageRenderTime 262ms CodeModel.GetById 201ms app.highlight 3ms RepoModel.GetById 38ms app.codeStats 0ms

/docs/ref/contrib/sitemaps.txt

https://code.google.com/p/mango-py/
Plain Text | 371 lines | 271 code | 100 blank | 0 comment | 0 complexity | 1a43d148993806072015c6f925106406 MD5 | raw file
  1=====================
  2The sitemap framework
  3=====================
  4
  5.. module:: django.contrib.sitemaps
  6   :synopsis: A framework for generating Google sitemap XML files.
  7
  8Django comes with a high-level sitemap-generating framework that makes
  9creating sitemap_ XML files easy.
 10
 11.. _sitemap: http://www.sitemaps.org/
 12
 13Overview
 14========
 15
 16A sitemap is an XML file on your Web site that tells search-engine indexers how
 17frequently your pages change and how "important" certain pages are in relation
 18to other pages on your site. This information helps search engines index your
 19site.
 20
 21The Django sitemap framework automates the creation of this XML file by letting
 22you express this information in Python code.
 23
 24It works much like Django's :doc:`syndication framework
 25</ref/contrib/syndication>`. To create a sitemap, just write a
 26:class:`~django.contrib.sitemaps.Sitemap` class and point to it in your
 27:doc:`URLconf </topics/http/urls>`.
 28
 29Installation
 30============
 31
 32To install the sitemap app, follow these steps:
 33
 34    1. Add ``'django.contrib.sitemaps'`` to your :setting:`INSTALLED_APPS`
 35       setting.
 36
 37    2. Make sure ``'django.template.loaders.app_directories.Loader'``
 38       is in your :setting:`TEMPLATE_LOADERS` setting. It's in there by default,
 39       so you'll only need to change this if you've changed that setting.
 40
 41    3. Make sure you've installed the
 42       :mod:`sites framework <django.contrib.sites>`.
 43
 44(Note: The sitemap application doesn't install any database tables. The only
 45reason it needs to go into :setting:`INSTALLED_APPS` is so that the
 46:func:`~django.template.loaders.app_directories.Loader` template
 47loader can find the default templates.)
 48
 49Initialization
 50==============
 51
 52To activate sitemap generation on your Django site, add this line to your
 53:doc:`URLconf </topics/http/urls>`::
 54
 55   (r'^sitemap\.xml$', 'django.contrib.sitemaps.views.sitemap', {'sitemaps': sitemaps})
 56
 57This tells Django to build a sitemap when a client accesses :file:`/sitemap.xml`.
 58
 59The name of the sitemap file is not important, but the location is. Search
 60engines will only index links in your sitemap for the current URL level and
 61below. For instance, if :file:`sitemap.xml` lives in your root directory, it may
 62reference any URL in your site. However, if your sitemap lives at
 63:file:`/content/sitemap.xml`, it may only reference URLs that begin with
 64:file:`/content/`.
 65
 66The sitemap view takes an extra, required argument: ``{'sitemaps': sitemaps}``.
 67``sitemaps`` should be a dictionary that maps a short section label (e.g.,
 68``blog`` or ``news``) to its :class:`~django.contrib.sitemaps.Sitemap` class
 69(e.g., ``BlogSitemap`` or ``NewsSitemap``). It may also map to an *instance* of
 70a :class:`~django.contrib.sitemaps.Sitemap` class (e.g.,
 71``BlogSitemap(some_var)``).
 72
 73Sitemap classes
 74===============
 75
 76A :class:`~django.contrib.sitemaps.Sitemap` class is a simple Python
 77class that represents a "section" of entries in your sitemap. For example,
 78one :class:`~django.contrib.sitemaps.Sitemap` class could represent
 79all the entries of your Weblog, while another could represent all of the
 80events in your events calendar.
 81
 82In the simplest case, all these sections get lumped together into one
 83:file:`sitemap.xml`, but it's also possible to use the framework to generate a
 84sitemap index that references individual sitemap files, one per section. (See
 85`Creating a sitemap index`_ below.)
 86
 87:class:`~django.contrib.sitemaps.Sitemap` classes must subclass
 88``django.contrib.sitemaps.Sitemap``. They can live anywhere in your codebase.
 89
 90A simple example
 91================
 92
 93Let's assume you have a blog system, with an ``Entry`` model, and you want your
 94sitemap to include all the links to your individual blog entries. Here's how
 95your sitemap class might look::
 96
 97    from django.contrib.sitemaps import Sitemap
 98    from blog.models import Entry
 99
100    class BlogSitemap(Sitemap):
101        changefreq = "never"
102        priority = 0.5
103
104        def items(self):
105            return Entry.objects.filter(is_draft=False)
106
107        def lastmod(self, obj):
108            return obj.pub_date
109
110Note:
111
112    * :attr:`~Sitemap.changefreq` and :attr:`~Sitemap.priority` are class
113      attributes corresponding to ``<changefreq>`` and ``<priority>`` elements,
114      respectively. They can be made callable as functions, as
115      :attr:`~Sitemap.lastmod` was in the example.
116    * :attr:`~Sitemap.items()` is simply a method that returns a list of
117      objects. The objects returned will get passed to any callable methods
118      corresponding to a sitemap property (:attr:`~Sitemap.location`,
119      :attr:`~Sitemap.lastmod`, :attr:`~Sitemap.changefreq`, and
120      :attr:`~Sitemap.priority`).
121    * :attr:`~Sitemap.lastmod` should return a Python ``datetime`` object.
122    * There is no :attr:`~Sitemap.location` method in this example, but you
123      can provide it in order to specify the URL for your object. By default,
124      :attr:`~Sitemap.location()` calls ``get_absolute_url()`` on each object
125      and returns the result.
126
127Sitemap class reference
128=======================
129
130.. class:: Sitemap
131
132    A ``Sitemap`` class can define the following methods/attributes:
133
134    .. attribute:: Sitemap.items
135
136        **Required.** A method that returns a list of objects. The framework
137        doesn't care what *type* of objects they are; all that matters is that
138        these objects get passed to the :attr:`~Sitemap.location()`,
139        :attr:`~Sitemap.lastmod()`, :attr:`~Sitemap.changefreq()` and
140        :attr:`~Sitemap.priority()` methods.
141
142    .. attribute:: Sitemap.location
143
144        **Optional.** Either a method or attribute.
145
146        If it's a method, it should return the absolute path for a given object
147        as returned by :attr:`~Sitemap.items()`.
148
149        If it's an attribute, its value should be a string representing an
150        absolute path to use for *every* object returned by
151        :attr:`~Sitemap.items()`.
152
153        In both cases, "absolute path" means a URL that doesn't include the
154        protocol or domain. Examples:
155
156            * Good: :file:`'/foo/bar/'`
157            * Bad: :file:`'example.com/foo/bar/'`
158            * Bad: :file:`'http://example.com/foo/bar/'`
159
160        If :attr:`~Sitemap.location` isn't provided, the framework will call
161        the ``get_absolute_url()`` method on each object as returned by
162        :attr:`~Sitemap.items()`.
163
164    .. attribute:: Sitemap.lastmod
165
166        **Optional.** Either a method or attribute.
167
168        If it's a method, it should take one argument -- an object as returned by
169        :attr:`~Sitemap.items()` -- and return that object's last-modified date/time, as a Python
170        ``datetime.datetime`` object.
171
172        If it's an attribute, its value should be a Python ``datetime.datetime`` object
173        representing the last-modified date/time for *every* object returned by
174        :attr:`~Sitemap.items()`.
175
176    .. attribute:: Sitemap.changefreq
177
178        **Optional.** Either a method or attribute.
179
180        If it's a method, it should take one argument -- an object as returned by
181        :attr:`~Sitemap.items()` -- and return that object's change frequency, as a Python string.
182
183        If it's an attribute, its value should be a string representing the change
184        frequency of *every* object returned by :attr:`~Sitemap.items()`.
185
186        Possible values for :attr:`~Sitemap.changefreq`, whether you use a method or attribute, are:
187
188            * ``'always'``
189            * ``'hourly'``
190            * ``'daily'``
191            * ``'weekly'``
192            * ``'monthly'``
193            * ``'yearly'``
194            * ``'never'``
195
196    .. method:: Sitemap.priority
197
198        **Optional.** Either a method or attribute.
199
200        If it's a method, it should take one argument -- an object as returned by
201        :attr:`~Sitemap.items()` -- and return that object's priority, as either a string or float.
202
203        If it's an attribute, its value should be either a string or float representing
204        the priority of *every* object returned by :attr:`~Sitemap.items()`.
205
206        Example values for :attr:`~Sitemap.priority`: ``0.4``, ``1.0``. The default priority of a
207        page is ``0.5``. See the `sitemaps.org documentation`_ for more.
208
209        .. _sitemaps.org documentation: http://www.sitemaps.org/protocol.html#prioritydef
210
211Shortcuts
212=========
213
214The sitemap framework provides a couple convenience classes for common cases:
215
216.. class:: FlatPageSitemap
217
218    The :class:`django.contrib.sitemaps.FlatPageSitemap` class looks at all
219    publicly visible :mod:`flatpages <django.contrib.flatpages>`
220    defined for the current :setting:`SITE_ID` (see the
221    :mod:`sites documentation <django.contrib.sites>`) and
222    creates an entry in the sitemap. These entries include only the
223    :attr:`~Sitemap.location` attribute -- not :attr:`~Sitemap.lastmod`,
224    :attr:`~Sitemap.changefreq` or :attr:`~Sitemap.priority`.
225
226.. class:: GenericSitemap
227
228    The :class:`django.contrib.sitemaps.GenericSitemap` class works with any
229    :doc:`generic views </ref/generic-views>` you already have.
230    To use it, create an instance, passing in the same :data:`info_dict` you pass to
231    the generic views. The only requirement is that the dictionary have a
232    :data:`queryset` entry. It may also have a :data:`date_field` entry that specifies a
233    date field for objects retrieved from the :data:`queryset`. This will be used for
234    the :attr:`~Sitemap.lastmod` attribute in the generated sitemap. You may
235    also pass :attr:`~Sitemap.priority` and :attr:`~Sitemap.changefreq`
236    keyword arguments to the :class:`~django.contrib.sitemaps.GenericSitemap`
237    constructor to specify these attributes for all URLs.
238
239Example
240-------
241
242Here's an example of a :doc:`URLconf </topics/http/urls>` using both::
243
244    from django.conf.urls.defaults import *
245    from django.contrib.sitemaps import FlatPageSitemap, GenericSitemap
246    from blog.models import Entry
247
248    info_dict = {
249        'queryset': Entry.objects.all(),
250        'date_field': 'pub_date',
251    }
252
253    sitemaps = {
254        'flatpages': FlatPageSitemap,
255        'blog': GenericSitemap(info_dict, priority=0.6),
256    }
257
258    urlpatterns = patterns('',
259        # some generic view using info_dict
260        # ...
261
262        # the sitemap
263        (r'^sitemap\.xml$', 'django.contrib.sitemaps.views.sitemap', {'sitemaps': sitemaps})
264    )
265
266.. _URLconf: ../url_dispatch/
267
268Creating a sitemap index
269========================
270
271The sitemap framework also has the ability to create a sitemap index that
272references individual sitemap files, one per each section defined in your
273:data:`sitemaps` dictionary. The only differences in usage are:
274
275    * You use two views in your URLconf: :func:`django.contrib.sitemaps.views.index`
276      and :func:`django.contrib.sitemaps.views.sitemap`.
277    * The :func:`django.contrib.sitemaps.views.sitemap` view should take a
278      :data:`section` keyword argument.
279
280Here's what the relevant URLconf lines would look like for the example above::
281
282    urlpatterns = patterns('django.contrib.sitemaps.views',
283        (r'^sitemap\.xml$', 'index', {'sitemaps': sitemaps}),
284        (r'^sitemap-(?P<section>.+)\.xml$', 'sitemap', {'sitemaps': sitemaps}),
285    )
286
287This will automatically generate a :file:`sitemap.xml` file that references both
288:file:`sitemap-flatpages.xml` and :file:`sitemap-blog.xml`. The
289:class:`~django.contrib.sitemaps.Sitemap` classes and the :data:`sitemaps` dict
290don't change at all.
291
292You should create an index file if one of your sitemaps has more than 50,000
293URLs. In this case, Django will automatically paginate the sitemap, and the
294index will reflect that.
295
296.. versionadded:: 1.3
297
298Template customization
299======================
300
301If you wish to use a different template for each sitemap or sitemap index available on your site,
302you may specify it by passing a `template_name` parameter to the `sitemap` and `index` views via
303the URLconf::
304
305    urlpatterns = patterns('django.contrib.sitemaps.views',
306        (r'^custom-sitemap\.xml$', 'index', {
307            'sitemaps': sitemaps,
308            'template_name': 'custom_sitemap.html'
309        }),
310        (r'^custom-sitemap-(?P<section>.+)\.xml$', 'sitemap', {
311            'sitemaps': sitemaps,
312            'template_name': 'custom_sitemap.html'
313        }),
314    )
315
316Pinging Google
317==============
318
319You may want to "ping" Google when your sitemap changes, to let it know to
320reindex your site. The sitemaps framework provides a function to do just
321that: :func:`django.contrib.sitemaps.ping_google()`.
322
323.. function:: ping_google
324
325    :func:`ping_google` takes an optional argument, :data:`sitemap_url`,
326    which should be the absolute path to your site's sitemap (e.g.,
327    :file:`'/sitemap.xml'`). If this argument isn't provided,
328    :func:`ping_google` will attempt to figure out your
329    sitemap by performing a reverse looking in your URLconf.
330
331    :func:`ping_google` raises the exception
332    :exc:`django.contrib.sitemaps.SitemapNotFound` if it cannot determine your
333    sitemap URL.
334
335.. admonition:: Register with Google first!
336
337    The :func:`ping_google` command only works if you have registered your
338    site with `Google Webmaster Tools`_.
339
340.. _`Google Webmaster Tools`: http://www.google.com/webmasters/tools/
341
342One useful way to call :func:`ping_google` is from a model's ``save()``
343method::
344
345   from django.contrib.sitemaps import ping_google
346
347    class Entry(models.Model):
348        # ...
349        def save(self, force_insert=False, force_update=False):
350            super(Entry, self).save(force_insert, force_update)
351            try:
352                ping_google()
353            except Exception:
354                # Bare 'except' because we could get a variety
355                # of HTTP-related exceptions.
356                pass
357
358A more efficient solution, however, would be to call :func:`ping_google` from a
359cron script, or some other scheduled task. The function makes an HTTP request
360to Google's servers, so you may not want to introduce that network overhead
361each time you call ``save()``.
362
363Pinging Google via `manage.py`
364------------------------------
365
366.. django-admin:: ping_google
367
368Once the sitemaps application is added to your project, you may also
369ping Google using the ``ping_google`` management command::
370
371    python manage.py ping_google [/sitemap.xml]