diff options
Diffstat (limited to 'parts/django/docs/ref/contrib/sitemaps.txt')
| -rw-r--r-- | parts/django/docs/ref/contrib/sitemaps.txt | 351 |
1 files changed, 351 insertions, 0 deletions
diff --git a/parts/django/docs/ref/contrib/sitemaps.txt b/parts/django/docs/ref/contrib/sitemaps.txt new file mode 100644 index 0000000..eb29c6c --- /dev/null +++ b/parts/django/docs/ref/contrib/sitemaps.txt @@ -0,0 +1,351 @@ +===================== +The sitemap framework +===================== + +.. module:: django.contrib.sitemaps + :synopsis: A framework for generating Google sitemap XML files. + +Django comes with a high-level sitemap-generating framework that makes +creating sitemap_ XML files easy. + +.. _sitemap: http://www.sitemaps.org/ + +Overview +======== + +A sitemap is an XML file on your Web site that tells search-engine indexers how +frequently your pages change and how "important" certain pages are in relation +to other pages on your site. This information helps search engines index your +site. + +The Django sitemap framework automates the creation of this XML file by letting +you express this information in Python code. + +It works much like Django's :doc:`syndication framework +</ref/contrib/syndication>`. To create a sitemap, just write a +:class:`~django.contrib.sitemaps.Sitemap` class and point to it in your +:doc:`URLconf </topics/http/urls>`. + +Installation +============ + +To install the sitemap app, follow these steps: + + 1. Add ``'django.contrib.sitemaps'`` to your :setting:`INSTALLED_APPS` + setting. + + 2. Make sure ``'django.template.loaders.app_directories.Loader'`` + is in your :setting:`TEMPLATE_LOADERS` setting. It's in there by default, + so you'll only need to change this if you've changed that setting. + + 3. Make sure you've installed the + :mod:`sites framework <django.contrib.sites>`. + +(Note: The sitemap application doesn't install any database tables. The only +reason it needs to go into :setting:`INSTALLED_APPS` is so that the +:func:`~django.template.loaders.app_directories.Loader` template +loader can find the default templates.) + +Initialization +============== + +To activate sitemap generation on your Django site, add this line to your +:doc:`URLconf </topics/http/urls>`:: + + (r'^sitemap\.xml$', 'django.contrib.sitemaps.views.sitemap', {'sitemaps': sitemaps}) + +This tells Django to build a sitemap when a client accesses :file:`/sitemap.xml`. + +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 :file:`sitemap.xml` lives in your root directory, it may +reference any URL in your site. However, if your sitemap lives at +:file:`/content/sitemap.xml`, it may only reference URLs that begin with +:file:`/content/`. + +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 :class:`~django.contrib.sitemaps.Sitemap` class +(e.g., ``BlogSitemap`` or ``NewsSitemap``). It may also map to an *instance* of +a :class:`~django.contrib.sitemaps.Sitemap` class (e.g., +``BlogSitemap(some_var)``). + +Sitemap classes +=============== + +A :class:`~django.contrib.sitemaps.Sitemap` class is a simple Python +class that represents a "section" of entries in your sitemap. For example, +one :class:`~django.contrib.sitemaps.Sitemap` class could represent +all the entries of your Weblog, while another could represent all of the +events in your events calendar. + +In the simplest case, all these sections get lumped together into one +:file:`sitemap.xml`, but it's also possible to use the framework to generate a +sitemap index that references individual sitemap files, one per section. (See +`Creating a sitemap index`_ below.) + +:class:`~django.contrib.sitemaps.Sitemap` classes must subclass +``django.contrib.sitemaps.Sitemap``. They can live anywhere in your codebase. + +A simple example +================ + +Let's 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. Here's how +your sitemap class might look:: + + from django.contrib.sitemaps import Sitemap + from 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 + +Note: + + * :attr:`~Sitemap.changefreq` and :attr:`~Sitemap.priority` are class + attributes corresponding to ``<changefreq>`` and ``<priority>`` elements, + respectively. They can be made callable as functions, as + :attr:`~Sitemap.lastmod` was in the example. + * :attr:`~Sitemap.items()` is simply a method that returns a list of + objects. The objects returned will get passed to any callable methods + corresponding to a sitemap property (:attr:`~Sitemap.location`, + :attr:`~Sitemap.lastmod`, :attr:`~Sitemap.changefreq`, and + :attr:`~Sitemap.priority`). + * :attr:`~Sitemap.lastmod` should return a Python ``datetime`` object. + * There is no :attr:`~Sitemap.location` method in this example, but you + can provide it in order to specify the URL for your object. By default, + :attr:`~Sitemap.location()` calls ``get_absolute_url()`` on each object + and returns the result. + +Sitemap class reference +======================= + +.. class:: Sitemap + + A ``Sitemap`` class can define the following methods/attributes: + + .. attribute:: Sitemap.items + + **Required.** A method that returns a list of objects. The framework + doesn't care what *type* of objects they are; all that matters is that + these objects get passed to the :attr:`~Sitemap.location()`, + :attr:`~Sitemap.lastmod()`, :attr:`~Sitemap.changefreq()` and + :attr:`~Sitemap.priority()` methods. + + .. attribute:: Sitemap.location + + **Optional.** Either a method or attribute. + + If it's a method, it should return the absolute path for a given object + as returned by :attr:`~Sitemap.items()`. + + If it's an attribute, its value should be a string representing an + absolute path to use for *every* object returned by + :attr:`~Sitemap.items()`. + + In both cases, "absolute path" means a URL that doesn't include the + protocol or domain. Examples: + + * Good: :file:`'/foo/bar/'` + * Bad: :file:`'example.com/foo/bar/'` + * Bad: :file:`'http://example.com/foo/bar/'` + + If :attr:`~Sitemap.location` isn't provided, the framework will call + the ``get_absolute_url()`` method on each object as returned by + :attr:`~Sitemap.items()`. + + .. attribute:: Sitemap.lastmod + + **Optional.** Either a method or attribute. + + If it's a method, it should take one argument -- an object as returned by + :attr:`~Sitemap.items()` -- and return that object's last-modified date/time, as a Python + ``datetime.datetime`` object. + + If it's an attribute, its value should be a Python ``datetime.datetime`` object + representing the last-modified date/time for *every* object returned by + :attr:`~Sitemap.items()`. + + .. attribute:: Sitemap.changefreq + + **Optional.** Either a method or attribute. + + If it's a method, it should take one argument -- an object as returned by + :attr:`~Sitemap.items()` -- and return that object's change frequency, as a Python string. + + If it's an attribute, its value should be a string representing the change + frequency of *every* object returned by :attr:`~Sitemap.items()`. + + Possible values for :attr:`~Sitemap.changefreq`, whether you use a method or attribute, are: + + * ``'always'`` + * ``'hourly'`` + * ``'daily'`` + * ``'weekly'`` + * ``'monthly'`` + * ``'yearly'`` + * ``'never'`` + + .. method:: Sitemap.priority + + **Optional.** Either a method or attribute. + + If it's a method, it should take one argument -- an object as returned by + :attr:`~Sitemap.items()` -- and return that object's priority, as either a string or float. + + If it's an attribute, its value should be either a string or float representing + the priority of *every* object returned by :attr:`~Sitemap.items()`. + + Example values for :attr:`~Sitemap.priority`: ``0.4``, ``1.0``. The default priority of a + page is ``0.5``. See the `sitemaps.org documentation`_ for more. + + .. _sitemaps.org documentation: http://www.sitemaps.org/protocol.html#prioritydef + +Shortcuts +========= + +The sitemap framework provides a couple convenience classes for common cases: + +.. class:: FlatPageSitemap + + The :class:`django.contrib.sitemaps.FlatPageSitemap` class looks at all + publicly visible :mod:`flatpages <django.contrib.flatpages>` + defined for the current :setting:`SITE_ID` (see the + :mod:`sites documentation <django.contrib.sites>`) and + creates an entry in the sitemap. These entries include only the + :attr:`~Sitemap.location` attribute -- not :attr:`~Sitemap.lastmod`, + :attr:`~Sitemap.changefreq` or :attr:`~Sitemap.priority`. + +.. class:: GenericSitemap + + The :class:`django.contrib.sitemaps.GenericSitemap` class works with any + :doc:`generic views </ref/generic-views>` you already have. + To use it, create an instance, passing in the same :data:`info_dict` you pass to + the generic views. The only requirement is that the dictionary have a + :data:`queryset` entry. It may also have a :data:`date_field` entry that specifies a + date field for objects retrieved from the :data:`queryset`. This will be used for + the :attr:`~Sitemap.lastmod` attribute in the generated sitemap. You may + also pass :attr:`~Sitemap.priority` and :attr:`~Sitemap.changefreq` + keyword arguments to the :class:`~django.contrib.sitemaps.GenericSitemap` + constructor to specify these attributes for all URLs. + +Example +------- + +Here's an example of a :doc:`URLconf </topics/http/urls>` using both:: + + from django.conf.urls.defaults import * + from django.contrib.sitemaps import FlatPageSitemap, GenericSitemap + from 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}) + ) + +.. _URLconf: ../url_dispatch/ + +Creating a sitemap index +======================== + +The sitemap framework also has the ability to create a sitemap index that +references individual sitemap files, one per each section defined in your +:data:`sitemaps` dictionary. The only differences in usage are: + + * You use two views in your URLconf: :func:`django.contrib.sitemaps.views.index` + and :func:`django.contrib.sitemaps.views.sitemap`. + * The :func:`django.contrib.sitemaps.views.sitemap` view should take a + :data:`section` keyword argument. + +Here's what the relevant URLconf lines would look like for the example above:: + + (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 :file:`sitemap.xml` file that references both +:file:`sitemap-flatpages.xml` and :file:`sitemap-blog.xml`. The +:class:`~django.contrib.sitemaps.Sitemap` classes and the :data:`sitemaps` dict +don't change at all. + +You should create an index file if one of your sitemaps has more than 50,000 +URLs. In this case, Django will automatically paginate the sitemap, and the +index will reflect that. + +Pinging Google +============== + +You may want to "ping" Google when your sitemap changes, to let it know to +reindex your site. The sitemaps framework provides a function to do just +that: :func:`django.contrib.sitemaps.ping_google()`. + +.. function:: ping_google + + :func:`ping_google` takes an optional argument, :data:`sitemap_url`, + which should be the absolute path to your site's sitemap (e.g., + :file:`'/sitemap.xml'`). If this argument isn't provided, + :func:`ping_google` will attempt to figure out your + sitemap by performing a reverse looking in your URLconf. + + :func:`ping_google` raises the exception + :exc:`django.contrib.sitemaps.SitemapNotFound` if it cannot determine your + sitemap URL. + +.. admonition:: Register with Google first! + + The :func:`ping_google` command only works if you have registered your + site with `Google Webmaster Tools`_. + +.. _`Google Webmaster Tools`: http://www.google.com/webmasters/tools/ + +One useful way to call :func:`ping_google` is from a model's ``save()`` +method:: + + from django.contrib.sitemaps import ping_google + + class Entry(models.Model): + # ... + def save(self, force_insert=False, force_update=False): + super(Entry, self).save(force_insert, force_update) + 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 :func:`ping_google` from a +cron script, or some other scheduled task. The function makes an HTTP request +to Google's servers, so you may not want to introduce that network overhead +each time you call ``save()``. + +Pinging Google via `manage.py` +------------------------------ + +.. django-admin:: ping_google + +.. versionadded:: 1.0 + +Once the sitemaps application is added to your project, you may also +ping Google using the ``ping_google`` management command:: + + python manage.py ping_google [/sitemap.xml] |