From 1b16a03dba7704f4e5aaaa9344f8eda8c6ff6ae7 Mon Sep 17 00:00:00 2001 From: Russell Keith-Magee Date: Sun, 9 May 2010 06:43:18 +0000 Subject: [PATCH] Fixed #12040 -- Cleaned up the documentation describing how CurrentSiteManager works. Thanks to elpaso66 for the report, and Gabriel Hurley for the draft patch. git-svn-id: http://code.djangoproject.com/svn/django/trunk@13168 bcc190cf-cafb-0310-a4f2-bffc1f526a37 --- docs/ref/contrib/sites.txt | 60 +++++++++++++++++++++----------------- 1 file changed, 33 insertions(+), 27 deletions(-) diff --git a/docs/ref/contrib/sites.txt b/docs/ref/contrib/sites.txt index 91a98c4ae4..b7cb8d6a58 100644 --- a/docs/ref/contrib/sites.txt +++ b/docs/ref/contrib/sites.txt @@ -257,12 +257,12 @@ The ``CurrentSiteManager`` .. class:: django.contrib.sites.managers.CurrentSiteManager -If :class:`~django.contrib.sites.models.Site`\s play a key role in your application, -consider using the helpful -:class:`~django.contrib.sites.managers.CurrentSiteManager` in your model(s). -It's a model :ref:`manager ` that automatically filters -its queries to include only objects associated with the current -:class:`~django.contrib.sites.models.Site`. +If :class:`~django.contrib.sites.models.Site` plays a key role in your +application, consider using the helpful +:class:`~django.contrib.sites.managers.CurrentSiteManager` in your +model(s). It's a model :ref:`manager ` that +automatically filters its queries to include only objects associated +with the current :class:`~django.contrib.sites.models.Site`. Use :class:`~django.contrib.sites.managers.CurrentSiteManager` by adding it to your model explicitly. For example:: @@ -288,16 +288,21 @@ Put another way, these two statements are equivalent:: Photo.objects.filter(site=settings.SITE_ID) Photo.on_site.all() -How did :class:`~django.contrib.sites.managers.CurrentSiteManager` know which -field of ``Photo`` was the :class:`~django.contrib.sites.models.Site`? It -defaults to looking for a field called -:class:`~django.contrib.sites.models.Site`. If your model has a -:class:`~django.db.models.fields.related.ForeignKey` or -:class:`~django.db.models.fields.related.ManyToManyField` called something -*other* than :class:`~django.contrib.sites.models.Site`, you need to explicitly -pass that as the parameter to -:class:`~django.contrib.sites.managers.CurrentSiteManager`. The following model, -which has a field called ``publish_on``, demonstrates this:: +How did :class:`~django.contrib.sites.managers.CurrentSiteManager` +know which field of ``Photo`` was the +:class:`~django.contrib.sites.models.Site`? By default, +:class:`~django.contrib.sites.managers.CurrentSiteManager` looks for a +either a :class:`~django.db.models.fields.related.ForeignKey` called +``site`` or a +:class:`~django.db.models.fields.related.ManyToManyField` called +``sites`` to filter on. If you use a field named something other than +``site`` or ``sites`` to identify which +:class:`~django.contrib.sites.models.Site` objects your object is +related to, then you need to explicitly pass the custom field name as +a parameter to +:class:`~django.contrib.sites.managers.CurrentSiteManager` on your +model. The following model, which has a field called ``publish_on``, +demonstrates this:: from django.db import models from django.contrib.sites.models import Site @@ -314,16 +319,17 @@ which has a field called ``publish_on``, demonstrates this:: If you attempt to use :class:`~django.contrib.sites.managers.CurrentSiteManager` and pass a field name that doesn't exist, Django will raise a :exc:`ValueError`. -Finally, note that you'll probably want to keep a normal (non-site-specific) -``Manager`` on your model, even if you use -:class:`~django.contrib.sites.managers.CurrentSiteManager`. As explained -in the :ref:`manager documentation `, if you define a manager -manually, then Django won't create the automatic ``objects = models.Manager()`` -manager for you.Also, note that certain parts of Django -- namely, the Django admin site and -generic views -- use whichever manager is defined *first* in the model, so if -you want your admin site to have access to all objects (not just site-specific -ones), put ``objects = models.Manager()`` in your model, before you define -:class:`~django.contrib.sites.managers.CurrentSiteManager`. +Finally, note that you'll probably want to keep a normal +(non-site-specific) ``Manager`` on your model, even if you use +:class:`~django.contrib.sites.managers.CurrentSiteManager`. As +explained in the :ref:`manager documentation `, if +you define a manager manually, then Django won't create the automatic +``objects = models.Manager()`` manager for you. Also note that certain +parts of Django -- namely, the Django admin site and generic views -- +use whichever manager is defined *first* in the model, so if you want +your admin site to have access to all objects (not just site-specific +ones), put ``objects = models.Manager()`` in your model, before you +define :class:`~django.contrib.sites.managers.CurrentSiteManager`. How Django uses the sites framework =================================== @@ -345,7 +351,7 @@ Here's how Django uses the sites framework: :class:`~django.contrib.sites.models.Site` is set to the current :setting:`SITE_ID`, and when comments are listed via the appropriate template tag, only the comments for the current site are displayed. - + * In the :mod:`flatpages framework `, each flatpage is associated with a particular site. When a flatpage is created, you specify its :class:`~django.contrib.sites.models.Site`, and the