Ticket #12040: 12040_sites_docs.diff

File 12040_sites_docs.diff, 3.9 KB (added by gabrielhurley, 5 years ago)

Cleans up the docs in that area and adds information about "sites" vs. "site"

  • docs/ref/contrib/sites.txt

     
    257257
    258258.. class:: django.contrib.sites.managers.CurrentSiteManager
    259259
    260 If :class:`~django.contrib.sites.models.Site`\s play a key role in your application,
    261 consider using the helpful
     260If :class:`~django.contrib.sites.models.Site` plays a key role in your
     261application, consider using the helpful
    262262:class:`~django.contrib.sites.managers.CurrentSiteManager` in your model(s).
    263263It's a model :ref:`manager <topics-db-managers>` that automatically filters
    264264its queries to include only objects associated with the current
     
    288288    Photo.objects.filter(site=settings.SITE_ID)
    289289    Photo.on_site.all()
    290290
    291 How did :class:`~django.contrib.sites.managers.CurrentSiteManager` know which
    292 field of ``Photo`` was the :class:`~django.contrib.sites.models.Site`? It
    293 defaults to looking for a field called
    294 :class:`~django.contrib.sites.models.Site`. If your model has a
    295 :class:`~django.db.models.fields.related.ForeignKey` or
    296 :class:`~django.db.models.fields.related.ManyToManyField` called something
    297 *other* than :class:`~django.contrib.sites.models.Site`, you need to explicitly
    298 pass that as the parameter to
    299 :class:`~django.contrib.sites.managers.CurrentSiteManager`. The following model,
    300 which has a field called ``publish_on``, demonstrates this::
     291By default, :class:`~django.contrib.sites.managers.CurrentSiteManager`
     292looks for a either a :class:`~django.db.models.fields.related.ForeignKey`
     293called ``site`` or a :class:`~django.db.models.fields.related.ManyToManyField`
     294called ``sites`` to filter on. If you use a field named something other than
     295``site`` or ``sites`` to identify which
     296:class:`~django.contrib.sites.models.Site` objects your object is related to,
     297then you need to explicitly pass the custom field name as a parameter to
     298:class:`~django.contrib.sites.managers.CurrentSiteManager` on your model. The
     299following model, which has a field called ``publish_on``, demonstrates this::
    301300
    302301    from django.db import models
    303302    from django.contrib.sites.models import Site
     
    311310        objects = models.Manager()
    312311        on_site = CurrentSiteManager('publish_on')
    313312
    314 If you attempt to use :class:`~django.contrib.sites.managers.CurrentSiteManager`
    315 and pass a field name that doesn't exist, Django will raise a :exc:`ValueError`.
     313Django will raise a :exc:`ValueError` if you pass a field name that doesn't
     314exist to :class:`~django.contrib.sites.managers.CurrentSiteManager`.
    316315
    317316Finally, note that you'll probably want to keep a normal (non-site-specific)
    318317``Manager`` on your model, even if you use
    319318:class:`~django.contrib.sites.managers.CurrentSiteManager`. As explained
    320 in the :ref:`manager documentation <topics-db-managers>`, if you define a manager
    321 manually, then Django won't create the automatic ``objects = models.Manager()``
    322 manager for you.Also, note that certain parts of Django -- namely, the Django admin site and
    323 generic views -- use whichever manager is defined *first* in the model, so if
    324 you want your admin site to have access to all objects (not just site-specific
    325 ones), put ``objects = models.Manager()`` in your model, before you define
     319in the :ref:`manager documentation <topics-db-managers>`, if you define a
     320manager manually, then Django won't create the automatic
     321``objects = models.Manager()`` manager for you. Also note that certain parts
     322of Django -- namely, the Django admin site and generic views -- use whichever
     323manager is defined *first* in the model, so if you want your admin site to
     324have access to all objects (not just site-specific ones), put
     325``objects = models.Manager()`` in your model, before you define
    326326:class:`~django.contrib.sites.managers.CurrentSiteManager`.
    327327
    328328How Django uses the sites framework
Back to Top