PageRenderTime 23ms CodeModel.GetById 8ms RepoModel.GetById 0ms app.codeStats 0ms

Plain Text | 449 lines | 338 code | 111 blank | 0 comment | 0 complexity | 91346811eb90a1838bc7a5fb2d72a282 MD5 | raw file
Possible License(s): BSD-3-Clause
  1. =====================
  2. The "sites" framework
  3. =====================
  4. .. module:: django.contrib.sites
  5. :synopsis: Lets you operate multiple Web sites from the same database and
  6. Django project
  7. .. currentmodule:: django.contrib.sites.models
  8. Django comes with an optional "sites" framework. It's a hook for associating
  9. objects and functionality to particular Web sites, and it's a holding place for
  10. the domain names and "verbose" names of your Django-powered sites.
  11. Use it if your single Django installation powers more than one site and you
  12. need to differentiate between those sites in some way.
  13. The whole sites framework is based on a simple model:
  14. .. class:: Site
  15. A model for storing the ``domain`` and ``name`` attributes of a Web site.
  16. The :setting:`SITE_ID` setting specifies the database ID of the
  17. :class:`~django.contrib.sites.models.Site` object associated with that
  18. particular settings file.
  19. .. attribute:: domain
  20. The domain name associated with the Web site.
  21. .. attribute:: name
  22. A human-readable "verbose" name for the Web site.
  23. How you use this is up to you, but Django uses it in a couple of ways
  24. automatically via simple conventions.
  25. Example usage
  26. =============
  27. Why would you use sites? It's best explained through examples.
  28. Associating content with multiple sites
  29. ---------------------------------------
  30. The Django-powered sites LJWorld.com_ and Lawrence.com_ are operated by the
  31. same news organization -- the Lawrence Journal-World newspaper in Lawrence,
  32. Kansas. focuses on news, while focuses on local
  33. entertainment. But sometimes editors want to publish an article on *both*
  34. sites.
  35. The brain-dead way of solving the problem would be to require site producers to
  36. publish the same story twice: once for and again for
  37. But that's inefficient for site producers, and it's redundant to store
  38. multiple copies of the same story in the database.
  39. The better solution is simple: Both sites use the same article database, and an
  40. article is associated with one or more sites. In Django model terminology,
  41. that's represented by a :class:`~django.db.models.ManyToManyField` in the
  42. ``Article`` model::
  43. from django.db import models
  44. from django.contrib.sites.models import Site
  45. class Article(models.Model):
  46. headline = models.CharField(max_length=200)
  47. # ...
  48. sites = models.ManyToManyField(Site)
  49. This accomplishes several things quite nicely:
  50. * It lets the site producers edit all content -- on both sites -- in a
  51. single interface (the Django admin).
  52. * It means the same story doesn't have to be published twice in the
  53. database; it only has a single record in the database.
  54. * It lets the site developers use the same Django view code for both sites.
  55. The view code that displays a given story just checks to make sure the
  56. requested story is on the current site. It looks something like this::
  57. from django.conf import settings
  58. def article_detail(request, article_id):
  59. try:
  60. a = Article.objects.get(id=article_id, sites__id__exact=settings.SITE_ID)
  61. except Article.DoesNotExist:
  62. raise Http404
  63. # ...
  64. ..
  65. ..
  66. Associating content with a single site
  67. --------------------------------------
  68. Similarly, you can associate a model to the
  69. :class:`~django.contrib.sites.models.Site`
  70. model in a many-to-one relationship, using
  71. :class:`~django.db.models.ForeignKey`.
  72. For example, if an article is only allowed on a single site, you'd use a model
  73. like this::
  74. from django.db import models
  75. from django.contrib.sites.models import Site
  76. class Article(models.Model):
  77. headline = models.CharField(max_length=200)
  78. # ...
  79. site = models.ForeignKey(Site)
  80. This has the same benefits as described in the last section.
  81. .. _hooking-into-current-site-from-views:
  82. Hooking into the current site from views
  83. ----------------------------------------
  84. You can use the sites framework in your Django views to do
  85. particular things based on the site in which the view is being called.
  86. For example::
  87. from django.conf import settings
  88. def my_view(request):
  89. if settings.SITE_ID == 3:
  90. # Do something.
  91. else:
  92. # Do something else.
  93. Of course, it's ugly to hard-code the site IDs like that. This sort of
  94. hard-coding is best for hackish fixes that you need done quickly. A slightly
  95. cleaner way of accomplishing the same thing is to check the current site's
  96. domain::
  97. from django.conf import settings
  98. from django.contrib.sites.models import Site
  99. def my_view(request):
  100. current_site = Site.objects.get(id=settings.SITE_ID)
  101. if current_site.domain == '':
  102. # Do something
  103. else:
  104. # Do something else.
  105. The idiom of retrieving the :class:`~django.contrib.sites.models.Site` object
  106. for the value of :setting:`settings.SITE_ID <SITE_ID>` is quite common, so
  107. the :class:`~django.contrib.sites.models.Site` model's manager has a
  108. ``get_current()`` method. This example is equivalent to the previous one::
  109. from django.contrib.sites.models import Site
  110. def my_view(request):
  111. current_site = Site.objects.get_current()
  112. if current_site.domain == '':
  113. # Do something
  114. else:
  115. # Do something else.
  116. .. versionchanged:: 1.3
  117. For code which relies on getting the current domain but cannot be certain
  118. that the sites framework will be installed for any given project, there is a
  119. utility function :func:`~django.contrib.sites.models.get_current_site` that
  120. takes a request object as an argument and returns either a Site instance (if
  121. the sites framework is installed) or a RequestSite instance (if it is not).
  122. This allows loose coupling with the sites framework and provides a usable
  123. fallback for cases where it is not installed.
  124. .. versionadded:: 1.3
  125. .. function:: get_current_site(request)
  126. Checks if contrib.sites is installed and returns either the current
  127. :class:`~django.contrib.sites.models.Site` object or a
  128. :class:`~django.contrib.sites.models.RequestSite` object based on
  129. the request.
  130. Getting the current domain for display
  131. --------------------------------------
  132. and both have e-mail alert functionality, which lets
  133. readers sign up to get notifications when news happens. It's pretty basic: A
  134. reader signs up on a Web form, and he immediately gets an e-mail saying,
  135. "Thanks for your subscription."
  136. It'd be inefficient and redundant to implement this signup-processing code
  137. twice, so the sites use the same code behind the scenes. But the "thank you for
  138. signing up" notice needs to be different for each site. By using
  139. :class:`~django.contrib.sites.models.Site`
  140. objects, we can abstract the "thank you" notice to use the values of the
  141. current site's :attr:`` and
  142. :attr:`~django.contrib.sites.models.Site.domain`.
  143. Here's an example of what the form-handling view looks like::
  144. from django.contrib.sites.models import Site
  145. from django.core.mail import send_mail
  146. def register_for_newsletter(request):
  147. # Check form values, etc., and subscribe the user.
  148. # ...
  149. current_site = Site.objects.get_current()
  150. send_mail('Thanks for subscribing to %s alerts' %,
  151. 'Thanks for your subscription. We appreciate it.\n\n-The %s team.' %,
  152. 'editor@%s' % current_site.domain,
  153. [])
  154. # ...
  155. On, this e-mail has the subject line "Thanks for subscribing to
  156. alerts." On, the e-mail has the subject "Thanks for
  157. subscribing to alerts." Same goes for the e-mail's message body.
  158. Note that an even more flexible (but more heavyweight) way of doing this would
  159. be to use Django's template system. Assuming and have
  160. different template directories (:setting:`TEMPLATE_DIRS`), you could simply farm out
  161. to the template system like so::
  162. from django.core.mail import send_mail
  163. from django.template import loader, Context
  164. def register_for_newsletter(request):
  165. # Check form values, etc., and subscribe the user.
  166. # ...
  167. subject = loader.get_template('alerts/subject.txt').render(Context({}))
  168. message = loader.get_template('alerts/message.txt').render(Context({}))
  169. send_mail(subject, message, '', [])
  170. # ...
  171. In this case, you'd have to create :file:`subject.txt` and :file:`message.txt` template
  172. files for both the and template directories. That
  173. gives you more flexibility, but it's also more complex.
  174. It's a good idea to exploit the :class:`~django.contrib.sites.models.Site`
  175. objects as much as possible, to remove unneeded complexity and redundancy.
  176. Getting the current domain for full URLs
  177. ----------------------------------------
  178. Django's ``get_absolute_url()`` convention is nice for getting your objects'
  179. URL without the domain name, but in some cases you might want to display the
  180. full URL -- with ``http://`` and the domain and everything -- for an object.
  181. To do this, you can use the sites framework. A simple example::
  182. >>> from django.contrib.sites.models import Site
  183. >>> obj = MyModel.objects.get(id=3)
  184. >>> obj.get_absolute_url()
  185. '/mymodel/objects/3/'
  186. >>> Site.objects.get_current().domain
  187. ''
  188. >>> 'http://%s%s' % (Site.objects.get_current().domain, obj.get_absolute_url())
  189. ''
  190. Caching the current ``Site`` object
  191. ===================================
  192. As the current site is stored in the database, each call to
  193. ``Site.objects.get_current()`` could result in a database query. But Django is a
  194. little cleverer than that: on the first request, the current site is cached, and
  195. any subsequent call returns the cached data instead of hitting the database.
  196. If for any reason you want to force a database query, you can tell Django to
  197. clear the cache using ``Site.objects.clear_cache()``::
  198. # First call; current site fetched from database.
  199. current_site = Site.objects.get_current()
  200. # ...
  201. # Second call; current site fetched from cache.
  202. current_site = Site.objects.get_current()
  203. # ...
  204. # Force a database query for the third call.
  205. Site.objects.clear_cache()
  206. current_site = Site.objects.get_current()
  207. .. currentmodule:: django.contrib.sites.managers
  208. The ``CurrentSiteManager``
  209. ==========================
  210. .. class:: CurrentSiteManager
  211. If :class:`~django.contrib.sites.models.Site` plays a key role in your
  212. application, consider using the helpful
  213. :class:`~django.contrib.sites.managers.CurrentSiteManager` in your
  214. model(s). It's a model :doc:`manager </topics/db/managers>` that
  215. automatically filters its queries to include only objects associated
  216. with the current :class:`~django.contrib.sites.models.Site`.
  217. Use :class:`~django.contrib.sites.managers.CurrentSiteManager` by adding it to
  218. your model explicitly. For example::
  219. from django.db import models
  220. from django.contrib.sites.models import Site
  221. from django.contrib.sites.managers import CurrentSiteManager
  222. class Photo(models.Model):
  223. photo = models.FileField(upload_to='/home/photos')
  224. photographer_name = models.CharField(max_length=100)
  225. pub_date = models.DateField()
  226. site = models.ForeignKey(Site)
  227. objects = models.Manager()
  228. on_site = CurrentSiteManager()
  229. With this model, ``Photo.objects.all()`` will return all ``Photo`` objects in
  230. the database, but ``Photo.on_site.all()`` will return only the ``Photo`` objects
  231. associated with the current site, according to the :setting:`SITE_ID` setting.
  232. Put another way, these two statements are equivalent::
  233. Photo.objects.filter(site=settings.SITE_ID)
  234. Photo.on_site.all()
  235. How did :class:`~django.contrib.sites.managers.CurrentSiteManager`
  236. know which field of ``Photo`` was the
  237. :class:`~django.contrib.sites.models.Site`? By default,
  238. :class:`~django.contrib.sites.managers.CurrentSiteManager` looks for a
  239. either a :class:`~django.db.models.ForeignKey` called
  240. ``site`` or a
  241. :class:`~django.db.models.ManyToManyField` called
  242. ``sites`` to filter on. If you use a field named something other than
  243. ``site`` or ``sites`` to identify which
  244. :class:`~django.contrib.sites.models.Site` objects your object is
  245. related to, then you need to explicitly pass the custom field name as
  246. a parameter to
  247. :class:`~django.contrib.sites.managers.CurrentSiteManager` on your
  248. model. The following model, which has a field called ``publish_on``,
  249. demonstrates this::
  250. from django.db import models
  251. from django.contrib.sites.models import Site
  252. from django.contrib.sites.managers import CurrentSiteManager
  253. class Photo(models.Model):
  254. photo = models.FileField(upload_to='/home/photos')
  255. photographer_name = models.CharField(max_length=100)
  256. pub_date = models.DateField()
  257. publish_on = models.ForeignKey(Site)
  258. objects = models.Manager()
  259. on_site = CurrentSiteManager('publish_on')
  260. If you attempt to use :class:`~django.contrib.sites.managers.CurrentSiteManager`
  261. and pass a field name that doesn't exist, Django will raise a ``ValueError``.
  262. Finally, note that you'll probably want to keep a normal
  263. (non-site-specific) ``Manager`` on your model, even if you use
  264. :class:`~django.contrib.sites.managers.CurrentSiteManager`. As
  265. explained in the :doc:`manager documentation </topics/db/managers>`, if
  266. you define a manager manually, then Django won't create the automatic
  267. ``objects = models.Manager()`` manager for you. Also note that certain
  268. parts of Django -- namely, the Django admin site and generic views --
  269. use whichever manager is defined *first* in the model, so if you want
  270. your admin site to have access to all objects (not just site-specific
  271. ones), put ``objects = models.Manager()`` in your model, before you
  272. define :class:`~django.contrib.sites.managers.CurrentSiteManager`.
  273. How Django uses the sites framework
  274. ===================================
  275. Although it's not required that you use the sites framework, it's strongly
  276. encouraged, because Django takes advantage of it in a few places. Even if your
  277. Django installation is powering only a single site, you should take the two
  278. seconds to create the site object with your ``domain`` and ``name``, and point
  279. to its ID in your :setting:`SITE_ID` setting.
  280. Here's how Django uses the sites framework:
  281. * In the :mod:`redirects framework <django.contrib.redirects>`, each
  282. redirect object is associated with a particular site. When Django searches
  283. for a redirect, it takes into account the current :setting:`SITE_ID`.
  284. * In the comments framework, each comment is associated with a particular
  285. site. When a comment is posted, its
  286. :class:`~django.contrib.sites.models.Site` is set to the current
  287. :setting:`SITE_ID`, and when comments are listed via the appropriate
  288. template tag, only the comments for the current site are displayed.
  289. * In the :mod:`flatpages framework <django.contrib.flatpages>`, each
  290. flatpage is associated with a particular site. When a flatpage is created,
  291. you specify its :class:`~django.contrib.sites.models.Site`, and the
  292. :class:`~django.contrib.flatpages.middleware.FlatpageFallbackMiddleware`
  293. checks the current :setting:`SITE_ID` in retrieving flatpages to display.
  294. * In the :mod:`syndication framework <django.contrib.syndication>`, the
  295. templates for ``title`` and ``description`` automatically have access to a
  296. variable ``{{ site }}``, which is the
  297. :class:`~django.contrib.sites.models.Site` object representing the current
  298. site. Also, the hook for providing item URLs will use the ``domain`` from
  299. the current :class:`~django.contrib.sites.models.Site` object if you don't
  300. specify a fully-qualified domain.
  301. * In the :mod:`authentication framework <django.contrib.auth>`, the
  302. :func:`django.contrib.auth.views.login` view passes the current
  303. :class:`~django.contrib.sites.models.Site` name to the template as
  304. ``{{ site_name }}``.
  305. * The shortcut view (``django.views.defaults.shortcut``) uses the domain
  306. of the current :class:`~django.contrib.sites.models.Site` object when
  307. calculating an object's URL.
  308. * In the admin framework, the "view on site" link uses the current
  309. :class:`~django.contrib.sites.models.Site` to work out the domain for the
  310. site that it will redirect to.
  311. .. currentmodule:: django.contrib.sites.models
  312. ``RequestSite`` objects
  313. =======================
  314. .. _requestsite-objects:
  315. Some :doc:`django.contrib </ref/contrib/index>` applications take advantage of
  316. the sites framework but are architected in a way that doesn't *require* the
  317. sites framework to be installed in your database. (Some people don't want to, or
  318. just aren't *able* to install the extra database table that the sites framework
  319. requires.) For those cases, the framework provides a
  320. :class:`~django.contrib.sites.models.RequestSite` class, which can be used as a
  321. fallback when the database-backed sites framework is not available.
  322. .. class:: RequestSite
  323. A class that shares the primary interface of
  324. :class:`~django.contrib.sites.models.Site` (i.e., it has
  325. ``domain`` and ``name`` attributes) but gets its data from a Django
  326. :class:`~django.http.HttpRequest` object rather than from a database.
  327. The ``save()`` and ``delete()`` methods raise ``NotImplementedError``.
  328. .. method:: __init__(request)
  329. Sets the ``name`` and ``domain`` attributes to the value of
  330. :meth:`~django.http.HttpRequest.get_host`.
  331. A :class:`~django.contrib.sites.models.RequestSite` object has a similar
  332. interface to a normal :class:`~django.contrib.sites.models.Site` object, except
  333. its :meth:`~django.contrib.sites.models.RequestSite.__init__()` method takes an
  334. :class:`~django.http.HttpRequest` object. It's able to deduce the
  335. ``domain`` and ``name`` by looking at the request's domain. It has ``save()``
  336. and ``delete()`` methods to match the interface of
  337. :class:`~django.contrib.sites.models.Site`, but the methods raise
  338. ``NotImplementedError``.