<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"> <head> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <title>The “sites” framework — Django 1.4.13 documentation</title> <link rel="stylesheet" href="../../_static/default.css" type="text/css" /> <link rel="stylesheet" href="../../_static/pygments.css" type="text/css" /> <script type="text/javascript"> var DOCUMENTATION_OPTIONS = { URL_ROOT: '../../', VERSION: '1.4.13', COLLAPSE_INDEX: false, FILE_SUFFIX: '.html', HAS_SOURCE: true }; </script> <script type="text/javascript" src="../../_static/jquery.js"></script> <script type="text/javascript" src="../../_static/underscore.js"></script> <script type="text/javascript" src="../../_static/doctools.js"></script> <link rel="top" title="Django 1.4.13 documentation" href="../../index.html" /> <link rel="up" title="contrib packages" href="index.html" /> <link rel="next" title="The staticfiles app" href="staticfiles.html" /> <link rel="prev" title="The sitemap framework" href="sitemaps.html" /> <script type="text/javascript" src="../../templatebuiltins.js"></script> <script type="text/javascript"> (function($) { if (!django_template_builtins) { // templatebuiltins.js missing, do nothing. return; } $(document).ready(function() { // Hyperlink Django template tags and filters var base = "../templates/builtins.html"; if (base == "#") { // Special case for builtins.html itself base = ""; } // Tags are keywords, class '.k' $("div.highlight\\-html\\+django span.k").each(function(i, elem) { var tagname = $(elem).text(); if ($.inArray(tagname, django_template_builtins.ttags) != -1) { var fragment = tagname.replace(/_/, '-'); $(elem).html("<a href='" + base + "#" + fragment + "'>" + tagname + "</a>"); } }); // Filters are functions, class '.nf' $("div.highlight\\-html\\+django span.nf").each(function(i, elem) { var filtername = $(elem).text(); if ($.inArray(filtername, django_template_builtins.tfilters) != -1) { var fragment = filtername.replace(/_/, '-'); $(elem).html("<a href='" + base + "#" + fragment + "'>" + filtername + "</a>"); } }); }); })(jQuery); </script> </head> <body> <div class="document"> <div id="custom-doc" class="yui-t6"> <div id="hd"> <h1><a href="../../index.html">Django 1.4.13 documentation</a></h1> <div id="global-nav"> <a title="Home page" href="../../index.html">Home</a> | <a title="Table of contents" href="../../contents.html">Table of contents</a> | <a title="Global index" href="../../genindex.html">Index</a> | <a title="Module index" href="../../py-modindex.html">Modules</a> </div> <div class="nav"> « <a href="sitemaps.html" title="The sitemap framework">previous</a> | <a href="../index.html" title="API Reference" accesskey="U">up</a> | <a href="staticfiles.html" title="The staticfiles app">next</a> »</div> </div> <div id="bd"> <div id="yui-main"> <div class="yui-b"> <div class="yui-g" id="ref-contrib-sites"> <div class="section" id="s-module-django.contrib.sites"> <span id="s-the-sites-framework"></span><span id="module-django.contrib.sites"></span><span id="the-sites-framework"></span><h1>The “sites” framework<a class="headerlink" href="#module-django.contrib.sites" title="Permalink to this headline">¶</a></h1> <p>Django comes with an optional “sites” framework. It’s a hook for associating objects and functionality to particular Web sites, and it’s a holding place for the domain names and “verbose” names of your Django-powered sites.</p> <p>Use it if your single Django installation powers more than one site and you need to differentiate between those sites in some way.</p> <p>The whole sites framework is based on a simple model:</p> <dl class="class"> <dt id="django.contrib.sites.models.Site"> <em class="property">class </em><tt class="descname">Site</tt><a class="headerlink" href="#django.contrib.sites.models.Site" title="Permalink to this definition">¶</a></dt> <dd><p>A model for storing the <tt class="docutils literal"><span class="pre">domain</span></tt> and <tt class="docutils literal"><span class="pre">name</span></tt> attributes of a Web site. The <a class="reference internal" href="../settings.html#std:setting-SITE_ID"><tt class="xref std std-setting docutils literal"><span class="pre">SITE_ID</span></tt></a> setting specifies the database ID of the <a class="reference internal" href="#django.contrib.sites.models.Site" title="django.contrib.sites.models.Site"><tt class="xref py py-class docutils literal"><span class="pre">Site</span></tt></a> object associated with that particular settings file.</p> <dl class="attribute"> <dt id="django.contrib.sites.models.Site.domain"> <tt class="descname">domain</tt><a class="headerlink" href="#django.contrib.sites.models.Site.domain" title="Permalink to this definition">¶</a></dt> <dd><p>The domain name associated with the Web site.</p> </dd></dl> <dl class="attribute"> <dt id="django.contrib.sites.models.Site.name"> <tt class="descname">name</tt><a class="headerlink" href="#django.contrib.sites.models.Site.name" title="Permalink to this definition">¶</a></dt> <dd><p>A human-readable “verbose” name for the Web site.</p> </dd></dl> </dd></dl> <p>How you use this is up to you, but Django uses it in a couple of ways automatically via simple conventions.</p> <div class="section" id="s-example-usage"> <span id="example-usage"></span><h2>Example usage<a class="headerlink" href="#example-usage" title="Permalink to this headline">¶</a></h2> <p>Why would you use sites? It’s best explained through examples.</p> <div class="section" id="s-associating-content-with-multiple-sites"> <span id="associating-content-with-multiple-sites"></span><h3>Associating content with multiple sites<a class="headerlink" href="#associating-content-with-multiple-sites" title="Permalink to this headline">¶</a></h3> <p>The Django-powered sites <a class="reference external" href="http://www.ljworld.com/">LJWorld.com</a> and <a class="reference external" href="http://www.lawrence.com/">Lawrence.com</a> are operated by the same news organization – the Lawrence Journal-World newspaper in Lawrence, Kansas. LJWorld.com focuses on news, while Lawrence.com focuses on local entertainment. But sometimes editors want to publish an article on <em>both</em> sites.</p> <p>The brain-dead way of solving the problem would be to require site producers to publish the same story twice: once for LJWorld.com and again for Lawrence.com. But that’s inefficient for site producers, and it’s redundant to store multiple copies of the same story in the database.</p> <p>The better solution is simple: Both sites use the same article database, and an article is associated with one or more sites. In Django model terminology, that’s represented by a <a class="reference internal" href="../models/fields.html#django.db.models.ManyToManyField" title="django.db.models.ManyToManyField"><tt class="xref py py-class docutils literal"><span class="pre">ManyToManyField</span></tt></a> in the <tt class="docutils literal"><span class="pre">Article</span></tt> model:</p> <div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">django.db</span> <span class="kn">import</span> <span class="n">models</span> <span class="kn">from</span> <span class="nn">django.contrib.sites.models</span> <span class="kn">import</span> <span class="n">Site</span> <span class="k">class</span> <span class="nc">Article</span><span class="p">(</span><span class="n">models</span><span class="o">.</span><span class="n">Model</span><span class="p">):</span> <span class="n">headline</span> <span class="o">=</span> <span class="n">models</span><span class="o">.</span><span class="n">CharField</span><span class="p">(</span><span class="n">max_length</span><span class="o">=</span><span class="mi">200</span><span class="p">)</span> <span class="c"># ...</span> <span class="n">sites</span> <span class="o">=</span> <span class="n">models</span><span class="o">.</span><span class="n">ManyToManyField</span><span class="p">(</span><span class="n">Site</span><span class="p">)</span> </pre></div> </div> <p>This accomplishes several things quite nicely:</p> <ul> <li><p class="first">It lets the site producers edit all content – on both sites – in a single interface (the Django admin).</p> </li> <li><p class="first">It means the same story doesn’t have to be published twice in the database; it only has a single record in the database.</p> </li> <li><p class="first">It lets the site developers use the same Django view code for both sites. The view code that displays a given story just checks to make sure the requested story is on the current site. It looks something like this:</p> <div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">django.conf</span> <span class="kn">import</span> <span class="n">settings</span> <span class="k">def</span> <span class="nf">article_detail</span><span class="p">(</span><span class="n">request</span><span class="p">,</span> <span class="n">article_id</span><span class="p">):</span> <span class="k">try</span><span class="p">:</span> <span class="n">a</span> <span class="o">=</span> <span class="n">Article</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="nb">id</span><span class="o">=</span><span class="n">article_id</span><span class="p">,</span> <span class="n">sites__id__exact</span><span class="o">=</span><span class="n">settings</span><span class="o">.</span><span class="n">SITE_ID</span><span class="p">)</span> <span class="k">except</span> <span class="n">Article</span><span class="o">.</span><span class="n">DoesNotExist</span><span class="p">:</span> <span class="k">raise</span> <span class="n">Http404</span> <span class="c"># ...</span> </pre></div> </div> </li> </ul> </div> <div class="section" id="s-associating-content-with-a-single-site"> <span id="associating-content-with-a-single-site"></span><h3>Associating content with a single site<a class="headerlink" href="#associating-content-with-a-single-site" title="Permalink to this headline">¶</a></h3> <p>Similarly, you can associate a model to the <a class="reference internal" href="#django.contrib.sites.models.Site" title="django.contrib.sites.models.Site"><tt class="xref py py-class docutils literal"><span class="pre">Site</span></tt></a> model in a many-to-one relationship, using <a class="reference internal" href="../models/fields.html#django.db.models.ForeignKey" title="django.db.models.ForeignKey"><tt class="xref py py-class docutils literal"><span class="pre">ForeignKey</span></tt></a>.</p> <p>For example, if an article is only allowed on a single site, you’d use a model like this:</p> <div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">django.db</span> <span class="kn">import</span> <span class="n">models</span> <span class="kn">from</span> <span class="nn">django.contrib.sites.models</span> <span class="kn">import</span> <span class="n">Site</span> <span class="k">class</span> <span class="nc">Article</span><span class="p">(</span><span class="n">models</span><span class="o">.</span><span class="n">Model</span><span class="p">):</span> <span class="n">headline</span> <span class="o">=</span> <span class="n">models</span><span class="o">.</span><span class="n">CharField</span><span class="p">(</span><span class="n">max_length</span><span class="o">=</span><span class="mi">200</span><span class="p">)</span> <span class="c"># ...</span> <span class="n">site</span> <span class="o">=</span> <span class="n">models</span><span class="o">.</span><span class="n">ForeignKey</span><span class="p">(</span><span class="n">Site</span><span class="p">)</span> </pre></div> </div> <p>This has the same benefits as described in the last section.</p> </div> <div class="section" id="s-hooking-into-the-current-site-from-views"> <span id="s-hooking-into-current-site-from-views"></span><span id="hooking-into-the-current-site-from-views"></span><span id="hooking-into-current-site-from-views"></span><h3>Hooking into the current site from views<a class="headerlink" href="#hooking-into-the-current-site-from-views" title="Permalink to this headline">¶</a></h3> <p>You can use the sites framework in your Django views to do particular things based on the site in which the view is being called. For example:</p> <div class="highlight-python"><pre>from django.conf import settings def my_view(request): if settings.SITE_ID == 3: # Do something. else: # Do something else.</pre> </div> <p>Of course, it’s ugly to hard-code the site IDs like that. This sort of hard-coding is best for hackish fixes that you need done quickly. A slightly cleaner way of accomplishing the same thing is to check the current site’s domain:</p> <div class="highlight-python"><pre>from django.conf import settings from django.contrib.sites.models import Site def my_view(request): current_site = Site.objects.get(id=settings.SITE_ID) if current_site.domain == 'foo.com': # Do something else: # Do something else.</pre> </div> <p>The idiom of retrieving the <a class="reference internal" href="#django.contrib.sites.models.Site" title="django.contrib.sites.models.Site"><tt class="xref py py-class docutils literal"><span class="pre">Site</span></tt></a> object for the value of <a class="reference internal" href="../settings.html#std:setting-SITE_ID"><tt class="xref std std-setting docutils literal"><span class="pre">settings.SITE_ID</span></tt></a> is quite common, so the <a class="reference internal" href="#django.contrib.sites.models.Site" title="django.contrib.sites.models.Site"><tt class="xref py py-class docutils literal"><span class="pre">Site</span></tt></a> model’s manager has a <tt class="docutils literal"><span class="pre">get_current()</span></tt> method. This example is equivalent to the previous one:</p> <div class="highlight-python"><pre>from django.contrib.sites.models import Site def my_view(request): current_site = Site.objects.get_current() if current_site.domain == 'foo.com': # Do something else: # Do something else.</pre> </div> <div class="versionchanged"> <span class="title">Changed in Django 1.3:</span> <a class="reference internal" href="../../releases/1.3.html"><em>Please see the release notes</em></a></div> <p>For code which relies on getting the current domain but cannot be certain that the sites framework will be installed for any given project, there is a utility function <a class="reference internal" href="#django.contrib.sites.models.get_current_site" title="django.contrib.sites.models.get_current_site"><tt class="xref py py-func docutils literal"><span class="pre">get_current_site()</span></tt></a> that takes a request object as an argument and returns either a Site instance (if the sites framework is installed) or a RequestSite instance (if it is not). This allows loose coupling with the sites framework and provides a usable fallback for cases where it is not installed.</p> <div class="versionadded"> <span class="title">New in Django 1.3:</span> <a class="reference internal" href="../../releases/1.3.html"><em>Please see the release notes</em></a></div> <dl class="function"> <dt id="django.contrib.sites.models.get_current_site"> <tt class="descname">get_current_site</tt>(<em>request</em>)<a class="headerlink" href="#django.contrib.sites.models.get_current_site" title="Permalink to this definition">¶</a></dt> <dd><p>Checks if contrib.sites is installed and returns either the current <a class="reference internal" href="#django.contrib.sites.models.Site" title="django.contrib.sites.models.Site"><tt class="xref py py-class docutils literal"><span class="pre">Site</span></tt></a> object or a <a class="reference internal" href="#django.contrib.sites.models.RequestSite" title="django.contrib.sites.models.RequestSite"><tt class="xref py py-class docutils literal"><span class="pre">RequestSite</span></tt></a> object based on the request.</p> </dd></dl> </div> <div class="section" id="s-getting-the-current-domain-for-display"> <span id="getting-the-current-domain-for-display"></span><h3>Getting the current domain for display<a class="headerlink" href="#getting-the-current-domain-for-display" title="Permalink to this headline">¶</a></h3> <p>LJWorld.com and Lawrence.com both have email alert functionality, which lets readers sign up to get notifications when news happens. It’s pretty basic: A reader signs up on a Web form, and he immediately gets an email saying, “Thanks for your subscription.”</p> <p>It’d be inefficient and redundant to implement this signup-processing code twice, so the sites use the same code behind the scenes. But the “thank you for signing up” notice needs to be different for each site. By using <a class="reference internal" href="#django.contrib.sites.models.Site" title="django.contrib.sites.models.Site"><tt class="xref py py-class docutils literal"><span class="pre">Site</span></tt></a> objects, we can abstract the “thank you” notice to use the values of the current site’s <a class="reference internal" href="#django.contrib.sites.models.Site.name" title="django.contrib.sites.models.Site.name"><tt class="xref py py-attr docutils literal"><span class="pre">name</span></tt></a> and <a class="reference internal" href="#django.contrib.sites.models.Site.domain" title="django.contrib.sites.models.Site.domain"><tt class="xref py py-attr docutils literal"><span class="pre">domain</span></tt></a>.</p> <p>Here’s an example of what the form-handling view looks like:</p> <div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">django.contrib.sites.models</span> <span class="kn">import</span> <span class="n">Site</span> <span class="kn">from</span> <span class="nn">django.core.mail</span> <span class="kn">import</span> <span class="n">send_mail</span> <span class="k">def</span> <span class="nf">register_for_newsletter</span><span class="p">(</span><span class="n">request</span><span class="p">):</span> <span class="c"># Check form values, etc., and subscribe the user.</span> <span class="c"># ...</span> <span class="n">current_site</span> <span class="o">=</span> <span class="n">Site</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">get_current</span><span class="p">()</span> <span class="n">send_mail</span><span class="p">(</span><span class="s">'Thanks for subscribing to </span><span class="si">%s</span><span class="s"> alerts'</span> <span class="o">%</span> <span class="n">current_site</span><span class="o">.</span><span class="n">name</span><span class="p">,</span> <span class="s">'Thanks for your subscription. We appreciate it.</span><span class="se">\n\n</span><span class="s">-The </span><span class="si">%s</span><span class="s"> team.'</span> <span class="o">%</span> <span class="n">current_site</span><span class="o">.</span><span class="n">name</span><span class="p">,</span> <span class="s">'editor@</span><span class="si">%s</span><span class="s">'</span> <span class="o">%</span> <span class="n">current_site</span><span class="o">.</span><span class="n">domain</span><span class="p">,</span> <span class="p">[</span><span class="n">user</span><span class="o">.</span><span class="n">email</span><span class="p">])</span> <span class="c"># ...</span> </pre></div> </div> <p>On Lawrence.com, this email has the subject line “Thanks for subscribing to lawrence.com alerts.” On LJWorld.com, the email has the subject “Thanks for subscribing to LJWorld.com alerts.” Same goes for the email’s message body.</p> <p>Note that an even more flexible (but more heavyweight) way of doing this would be to use Django’s template system. Assuming Lawrence.com and LJWorld.com have different template directories (<a class="reference internal" href="../settings.html#std:setting-TEMPLATE_DIRS"><tt class="xref std std-setting docutils literal"><span class="pre">TEMPLATE_DIRS</span></tt></a>), you could simply farm out to the template system like so:</p> <div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">django.core.mail</span> <span class="kn">import</span> <span class="n">send_mail</span> <span class="kn">from</span> <span class="nn">django.template</span> <span class="kn">import</span> <span class="n">loader</span><span class="p">,</span> <span class="n">Context</span> <span class="k">def</span> <span class="nf">register_for_newsletter</span><span class="p">(</span><span class="n">request</span><span class="p">):</span> <span class="c"># Check form values, etc., and subscribe the user.</span> <span class="c"># ...</span> <span class="n">subject</span> <span class="o">=</span> <span class="n">loader</span><span class="o">.</span><span class="n">get_template</span><span class="p">(</span><span class="s">'alerts/subject.txt'</span><span class="p">)</span><span class="o">.</span><span class="n">render</span><span class="p">(</span><span class="n">Context</span><span class="p">({}))</span> <span class="n">message</span> <span class="o">=</span> <span class="n">loader</span><span class="o">.</span><span class="n">get_template</span><span class="p">(</span><span class="s">'alerts/message.txt'</span><span class="p">)</span><span class="o">.</span><span class="n">render</span><span class="p">(</span><span class="n">Context</span><span class="p">({}))</span> <span class="n">send_mail</span><span class="p">(</span><span class="n">subject</span><span class="p">,</span> <span class="n">message</span><span class="p">,</span> <span class="s">'editor@ljworld.com'</span><span class="p">,</span> <span class="p">[</span><span class="n">user</span><span class="o">.</span><span class="n">email</span><span class="p">])</span> <span class="c"># ...</span> </pre></div> </div> <p>In this case, you’d have to create <tt class="file docutils literal"><span class="pre">subject.txt</span></tt> and <tt class="file docutils literal"><span class="pre">message.txt</span></tt> template files for both the LJWorld.com and Lawrence.com template directories. That gives you more flexibility, but it’s also more complex.</p> <p>It’s a good idea to exploit the <a class="reference internal" href="#django.contrib.sites.models.Site" title="django.contrib.sites.models.Site"><tt class="xref py py-class docutils literal"><span class="pre">Site</span></tt></a> objects as much as possible, to remove unneeded complexity and redundancy.</p> </div> <div class="section" id="s-getting-the-current-domain-for-full-urls"> <span id="getting-the-current-domain-for-full-urls"></span><h3>Getting the current domain for full URLs<a class="headerlink" href="#getting-the-current-domain-for-full-urls" title="Permalink to this headline">¶</a></h3> <p>Django’s <tt class="docutils literal"><span class="pre">get_absolute_url()</span></tt> convention is nice for getting your objects’ URL without the domain name, but in some cases you might want to display the full URL – with <tt class="docutils literal"><span class="pre">http://</span></tt> and the domain and everything – for an object. To do this, you can use the sites framework. A simple example:</p> <div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">django.contrib.sites.models</span> <span class="kn">import</span> <span class="n">Site</span> <span class="gp">>>> </span><span class="n">obj</span> <span class="o">=</span> <span class="n">MyModel</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="nb">id</span><span class="o">=</span><span class="mi">3</span><span class="p">)</span> <span class="gp">>>> </span><span class="n">obj</span><span class="o">.</span><span class="n">get_absolute_url</span><span class="p">()</span> <span class="go">'/mymodel/objects/3/'</span> <span class="gp">>>> </span><span class="n">Site</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">get_current</span><span class="p">()</span><span class="o">.</span><span class="n">domain</span> <span class="go">'example.com'</span> <span class="gp">>>> </span><span class="s">'http://</span><span class="si">%s%s</span><span class="s">'</span> <span class="o">%</span> <span class="p">(</span><span class="n">Site</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">get_current</span><span class="p">()</span><span class="o">.</span><span class="n">domain</span><span class="p">,</span> <span class="n">obj</span><span class="o">.</span><span class="n">get_absolute_url</span><span class="p">())</span> <span class="go">'http://example.com/mymodel/objects/3/'</span> </pre></div> </div> </div> </div> <div class="section" id="s-caching-the-current-site-object"> <span id="caching-the-current-site-object"></span><h2>Caching the current <tt class="docutils literal"><span class="pre">Site</span></tt> object<a class="headerlink" href="#caching-the-current-site-object" title="Permalink to this headline">¶</a></h2> <p>As the current site is stored in the database, each call to <tt class="docutils literal"><span class="pre">Site.objects.get_current()</span></tt> could result in a database query. But Django is a little cleverer than that: on the first request, the current site is cached, and any subsequent call returns the cached data instead of hitting the database.</p> <p>If for any reason you want to force a database query, you can tell Django to clear the cache using <tt class="docutils literal"><span class="pre">Site.objects.clear_cache()</span></tt>:</p> <div class="highlight-python"><div class="highlight"><pre><span class="c"># First call; current site fetched from database.</span> <span class="n">current_site</span> <span class="o">=</span> <span class="n">Site</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">get_current</span><span class="p">()</span> <span class="c"># ...</span> <span class="c"># Second call; current site fetched from cache.</span> <span class="n">current_site</span> <span class="o">=</span> <span class="n">Site</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">get_current</span><span class="p">()</span> <span class="c"># ...</span> <span class="c"># Force a database query for the third call.</span> <span class="n">Site</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">clear_cache</span><span class="p">()</span> <span class="n">current_site</span> <span class="o">=</span> <span class="n">Site</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">get_current</span><span class="p">()</span> </pre></div> </div> </div> <div class="section" id="s-the-currentsitemanager"> <span id="the-currentsitemanager"></span><h2>The <tt class="docutils literal"><span class="pre">CurrentSiteManager</span></tt><a class="headerlink" href="#the-currentsitemanager" title="Permalink to this headline">¶</a></h2> <dl class="class"> <dt id="django.contrib.sites.managers.CurrentSiteManager"> <em class="property">class </em><tt class="descname">CurrentSiteManager</tt><a class="headerlink" href="#django.contrib.sites.managers.CurrentSiteManager" title="Permalink to this definition">¶</a></dt> <dd></dd></dl> <p>If <a class="reference internal" href="#django.contrib.sites.models.Site" title="django.contrib.sites.models.Site"><tt class="xref py py-class docutils literal"><span class="pre">Site</span></tt></a> plays a key role in your application, consider using the helpful <a class="reference internal" href="#django.contrib.sites.managers.CurrentSiteManager" title="django.contrib.sites.managers.CurrentSiteManager"><tt class="xref py py-class docutils literal"><span class="pre">CurrentSiteManager</span></tt></a> in your model(s). It’s a model <a class="reference internal" href="../../topics/db/managers.html"><em>manager</em></a> that automatically filters its queries to include only objects associated with the current <a class="reference internal" href="#django.contrib.sites.models.Site" title="django.contrib.sites.models.Site"><tt class="xref py py-class docutils literal"><span class="pre">Site</span></tt></a>.</p> <p>Use <a class="reference internal" href="#django.contrib.sites.managers.CurrentSiteManager" title="django.contrib.sites.managers.CurrentSiteManager"><tt class="xref py py-class docutils literal"><span class="pre">CurrentSiteManager</span></tt></a> by adding it to your model explicitly. For example:</p> <div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">django.db</span> <span class="kn">import</span> <span class="n">models</span> <span class="kn">from</span> <span class="nn">django.contrib.sites.models</span> <span class="kn">import</span> <span class="n">Site</span> <span class="kn">from</span> <span class="nn">django.contrib.sites.managers</span> <span class="kn">import</span> <span class="n">CurrentSiteManager</span> <span class="k">class</span> <span class="nc">Photo</span><span class="p">(</span><span class="n">models</span><span class="o">.</span><span class="n">Model</span><span class="p">):</span> <span class="n">photo</span> <span class="o">=</span> <span class="n">models</span><span class="o">.</span><span class="n">FileField</span><span class="p">(</span><span class="n">upload_to</span><span class="o">=</span><span class="s">'/home/photos'</span><span class="p">)</span> <span class="n">photographer_name</span> <span class="o">=</span> <span class="n">models</span><span class="o">.</span><span class="n">CharField</span><span class="p">(</span><span class="n">max_length</span><span class="o">=</span><span class="mi">100</span><span class="p">)</span> <span class="n">pub_date</span> <span class="o">=</span> <span class="n">models</span><span class="o">.</span><span class="n">DateField</span><span class="p">()</span> <span class="n">site</span> <span class="o">=</span> <span class="n">models</span><span class="o">.</span><span class="n">ForeignKey</span><span class="p">(</span><span class="n">Site</span><span class="p">)</span> <span class="n">objects</span> <span class="o">=</span> <span class="n">models</span><span class="o">.</span><span class="n">Manager</span><span class="p">()</span> <span class="n">on_site</span> <span class="o">=</span> <span class="n">CurrentSiteManager</span><span class="p">()</span> </pre></div> </div> <p>With this model, <tt class="docutils literal"><span class="pre">Photo.objects.all()</span></tt> will return all <tt class="docutils literal"><span class="pre">Photo</span></tt> objects in the database, but <tt class="docutils literal"><span class="pre">Photo.on_site.all()</span></tt> will return only the <tt class="docutils literal"><span class="pre">Photo</span></tt> objects associated with the current site, according to the <a class="reference internal" href="../settings.html#std:setting-SITE_ID"><tt class="xref std std-setting docutils literal"><span class="pre">SITE_ID</span></tt></a> setting.</p> <p>Put another way, these two statements are equivalent:</p> <div class="highlight-python"><div class="highlight"><pre><span class="n">Photo</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span><span class="n">site</span><span class="o">=</span><span class="n">settings</span><span class="o">.</span><span class="n">SITE_ID</span><span class="p">)</span> <span class="n">Photo</span><span class="o">.</span><span class="n">on_site</span><span class="o">.</span><span class="n">all</span><span class="p">()</span> </pre></div> </div> <p>How did <a class="reference internal" href="#django.contrib.sites.managers.CurrentSiteManager" title="django.contrib.sites.managers.CurrentSiteManager"><tt class="xref py py-class docutils literal"><span class="pre">CurrentSiteManager</span></tt></a> know which field of <tt class="docutils literal"><span class="pre">Photo</span></tt> was the <a class="reference internal" href="#django.contrib.sites.models.Site" title="django.contrib.sites.models.Site"><tt class="xref py py-class docutils literal"><span class="pre">Site</span></tt></a>? By default, <a class="reference internal" href="#django.contrib.sites.managers.CurrentSiteManager" title="django.contrib.sites.managers.CurrentSiteManager"><tt class="xref py py-class docutils literal"><span class="pre">CurrentSiteManager</span></tt></a> looks for a either a <a class="reference internal" href="../models/fields.html#django.db.models.ForeignKey" title="django.db.models.ForeignKey"><tt class="xref py py-class docutils literal"><span class="pre">ForeignKey</span></tt></a> called <tt class="docutils literal"><span class="pre">site</span></tt> or a <a class="reference internal" href="../models/fields.html#django.db.models.ManyToManyField" title="django.db.models.ManyToManyField"><tt class="xref py py-class docutils literal"><span class="pre">ManyToManyField</span></tt></a> called <tt class="docutils literal"><span class="pre">sites</span></tt> to filter on. If you use a field named something other than <tt class="docutils literal"><span class="pre">site</span></tt> or <tt class="docutils literal"><span class="pre">sites</span></tt> to identify which <a class="reference internal" href="#django.contrib.sites.models.Site" title="django.contrib.sites.models.Site"><tt class="xref py py-class docutils literal"><span class="pre">Site</span></tt></a> objects your object is related to, then you need to explicitly pass the custom field name as a parameter to <a class="reference internal" href="#django.contrib.sites.managers.CurrentSiteManager" title="django.contrib.sites.managers.CurrentSiteManager"><tt class="xref py py-class docutils literal"><span class="pre">CurrentSiteManager</span></tt></a> on your model. The following model, which has a field called <tt class="docutils literal"><span class="pre">publish_on</span></tt>, demonstrates this:</p> <div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">django.db</span> <span class="kn">import</span> <span class="n">models</span> <span class="kn">from</span> <span class="nn">django.contrib.sites.models</span> <span class="kn">import</span> <span class="n">Site</span> <span class="kn">from</span> <span class="nn">django.contrib.sites.managers</span> <span class="kn">import</span> <span class="n">CurrentSiteManager</span> <span class="k">class</span> <span class="nc">Photo</span><span class="p">(</span><span class="n">models</span><span class="o">.</span><span class="n">Model</span><span class="p">):</span> <span class="n">photo</span> <span class="o">=</span> <span class="n">models</span><span class="o">.</span><span class="n">FileField</span><span class="p">(</span><span class="n">upload_to</span><span class="o">=</span><span class="s">'/home/photos'</span><span class="p">)</span> <span class="n">photographer_name</span> <span class="o">=</span> <span class="n">models</span><span class="o">.</span><span class="n">CharField</span><span class="p">(</span><span class="n">max_length</span><span class="o">=</span><span class="mi">100</span><span class="p">)</span> <span class="n">pub_date</span> <span class="o">=</span> <span class="n">models</span><span class="o">.</span><span class="n">DateField</span><span class="p">()</span> <span class="n">publish_on</span> <span class="o">=</span> <span class="n">models</span><span class="o">.</span><span class="n">ForeignKey</span><span class="p">(</span><span class="n">Site</span><span class="p">)</span> <span class="n">objects</span> <span class="o">=</span> <span class="n">models</span><span class="o">.</span><span class="n">Manager</span><span class="p">()</span> <span class="n">on_site</span> <span class="o">=</span> <span class="n">CurrentSiteManager</span><span class="p">(</span><span class="s">'publish_on'</span><span class="p">)</span> </pre></div> </div> <p>If you attempt to use <a class="reference internal" href="#django.contrib.sites.managers.CurrentSiteManager" title="django.contrib.sites.managers.CurrentSiteManager"><tt class="xref py py-class docutils literal"><span class="pre">CurrentSiteManager</span></tt></a> and pass a field name that doesn’t exist, Django will raise a <tt class="docutils literal"><span class="pre">ValueError</span></tt>.</p> <p>Finally, note that you’ll probably want to keep a normal (non-site-specific) <tt class="docutils literal"><span class="pre">Manager</span></tt> on your model, even if you use <a class="reference internal" href="#django.contrib.sites.managers.CurrentSiteManager" title="django.contrib.sites.managers.CurrentSiteManager"><tt class="xref py py-class docutils literal"><span class="pre">CurrentSiteManager</span></tt></a>. As explained in the <a class="reference internal" href="../../topics/db/managers.html"><em>manager documentation</em></a>, if you define a manager manually, then Django won’t create the automatic <tt class="docutils literal"><span class="pre">objects</span> <span class="pre">=</span> <span class="pre">models.Manager()</span></tt> manager for you. Also note that certain parts of Django – namely, the Django admin site and generic views – use whichever manager is defined <em>first</em> in the model, so if you want your admin site to have access to all objects (not just site-specific ones), put <tt class="docutils literal"><span class="pre">objects</span> <span class="pre">=</span> <span class="pre">models.Manager()</span></tt> in your model, before you define <a class="reference internal" href="#django.contrib.sites.managers.CurrentSiteManager" title="django.contrib.sites.managers.CurrentSiteManager"><tt class="xref py py-class docutils literal"><span class="pre">CurrentSiteManager</span></tt></a>.</p> </div> <div class="section" id="s-how-django-uses-the-sites-framework"> <span id="how-django-uses-the-sites-framework"></span><h2>How Django uses the sites framework<a class="headerlink" href="#how-django-uses-the-sites-framework" title="Permalink to this headline">¶</a></h2> <p>Although it’s not required that you use the sites framework, it’s strongly encouraged, because Django takes advantage of it in a few places. Even if your Django installation is powering only a single site, you should take the two seconds to create the site object with your <tt class="docutils literal"><span class="pre">domain</span></tt> and <tt class="docutils literal"><span class="pre">name</span></tt>, and point to its ID in your <a class="reference internal" href="../settings.html#std:setting-SITE_ID"><tt class="xref std std-setting docutils literal"><span class="pre">SITE_ID</span></tt></a> setting.</p> <p>Here’s how Django uses the sites framework:</p> <ul class="simple"> <li>In the <a class="reference internal" href="redirects.html#module-django.contrib.redirects" title="django.contrib.redirects: A framework for managing redirects."><tt class="xref py py-mod docutils literal"><span class="pre">redirects</span> <span class="pre">framework</span></tt></a>, each redirect object is associated with a particular site. When Django searches for a redirect, it takes into account the current <a class="reference internal" href="../settings.html#std:setting-SITE_ID"><tt class="xref std std-setting docutils literal"><span class="pre">SITE_ID</span></tt></a>.</li> <li>In the comments framework, each comment is associated with a particular site. When a comment is posted, its <a class="reference internal" href="#django.contrib.sites.models.Site" title="django.contrib.sites.models.Site"><tt class="xref py py-class docutils literal"><span class="pre">Site</span></tt></a> is set to the current <a class="reference internal" href="../settings.html#std:setting-SITE_ID"><tt class="xref std std-setting docutils literal"><span class="pre">SITE_ID</span></tt></a>, and when comments are listed via the appropriate template tag, only the comments for the current site are displayed.</li> <li>In the <a class="reference internal" href="flatpages.html#module-django.contrib.flatpages" title="django.contrib.flatpages: A framework for managing simple ?flat? HTML content in a database."><tt class="xref py py-mod docutils literal"><span class="pre">flatpages</span> <span class="pre">framework</span></tt></a>, each flatpage is associated with a particular site. When a flatpage is created, you specify its <a class="reference internal" href="#django.contrib.sites.models.Site" title="django.contrib.sites.models.Site"><tt class="xref py py-class docutils literal"><span class="pre">Site</span></tt></a>, and the <a class="reference internal" href="flatpages.html#django.contrib.flatpages.middleware.FlatpageFallbackMiddleware" title="django.contrib.flatpages.middleware.FlatpageFallbackMiddleware"><tt class="xref py py-class docutils literal"><span class="pre">FlatpageFallbackMiddleware</span></tt></a> checks the current <a class="reference internal" href="../settings.html#std:setting-SITE_ID"><tt class="xref std std-setting docutils literal"><span class="pre">SITE_ID</span></tt></a> in retrieving flatpages to display.</li> <li>In the <a class="reference internal" href="syndication.html#module-django.contrib.syndication" title="django.contrib.syndication: A framework for generating syndication feeds, in RSS and Atom, quite easily."><tt class="xref py py-mod docutils literal"><span class="pre">syndication</span> <span class="pre">framework</span></tt></a>, the templates for <tt class="docutils literal"><span class="pre">title</span></tt> and <tt class="docutils literal"><span class="pre">description</span></tt> automatically have access to a variable <tt class="docutils literal"><span class="pre">{{</span> <span class="pre">site</span> <span class="pre">}}</span></tt>, which is the <a class="reference internal" href="#django.contrib.sites.models.Site" title="django.contrib.sites.models.Site"><tt class="xref py py-class docutils literal"><span class="pre">Site</span></tt></a> object representing the current site. Also, the hook for providing item URLs will use the <tt class="docutils literal"><span class="pre">domain</span></tt> from the current <a class="reference internal" href="#django.contrib.sites.models.Site" title="django.contrib.sites.models.Site"><tt class="xref py py-class docutils literal"><span class="pre">Site</span></tt></a> object if you don’t specify a fully-qualified domain.</li> <li>In the <a class="reference internal" href="../../topics/auth.html#module-django.contrib.auth" title="django.contrib.auth: Django's authentication framework."><tt class="xref py py-mod docutils literal"><span class="pre">authentication</span> <span class="pre">framework</span></tt></a>, the <a class="reference internal" href="../../topics/auth.html#django.contrib.auth.views.login" title="django.contrib.auth.views.login"><tt class="xref py py-func docutils literal"><span class="pre">django.contrib.auth.views.login()</span></tt></a> view passes the current <a class="reference internal" href="#django.contrib.sites.models.Site" title="django.contrib.sites.models.Site"><tt class="xref py py-class docutils literal"><span class="pre">Site</span></tt></a> name to the template as <tt class="docutils literal"><span class="pre">{{</span> <span class="pre">site_name</span> <span class="pre">}}</span></tt>.</li> <li>The shortcut view (<tt class="docutils literal"><span class="pre">django.views.defaults.shortcut</span></tt>) uses the domain of the current <a class="reference internal" href="#django.contrib.sites.models.Site" title="django.contrib.sites.models.Site"><tt class="xref py py-class docutils literal"><span class="pre">Site</span></tt></a> object when calculating an object’s URL.</li> <li>In the admin framework, the “view on site” link uses the current <a class="reference internal" href="#django.contrib.sites.models.Site" title="django.contrib.sites.models.Site"><tt class="xref py py-class docutils literal"><span class="pre">Site</span></tt></a> to work out the domain for the site that it will redirect to.</li> </ul> </div> <div class="section" id="s-requestsite-objects"> <span id="requestsite-objects"></span><h2><tt class="docutils literal"><span class="pre">RequestSite</span></tt> objects<a class="headerlink" href="#requestsite-objects" title="Permalink to this headline">¶</a></h2> <p id="id1">Some <a class="reference internal" href="index.html"><em>django.contrib</em></a> applications take advantage of the sites framework but are architected in a way that doesn’t <em>require</em> the sites framework to be installed in your database. (Some people don’t want to, or just aren’t <em>able</em> to install the extra database table that the sites framework requires.) For those cases, the framework provides a <a class="reference internal" href="#django.contrib.sites.models.RequestSite" title="django.contrib.sites.models.RequestSite"><tt class="xref py py-class docutils literal"><span class="pre">RequestSite</span></tt></a> class, which can be used as a fallback when the database-backed sites framework is not available.</p> <dl class="class"> <dt id="django.contrib.sites.models.RequestSite"> <em class="property">class </em><tt class="descname">RequestSite</tt><a class="headerlink" href="#django.contrib.sites.models.RequestSite" title="Permalink to this definition">¶</a></dt> <dd><p>A class that shares the primary interface of <a class="reference internal" href="#django.contrib.sites.models.Site" title="django.contrib.sites.models.Site"><tt class="xref py py-class docutils literal"><span class="pre">Site</span></tt></a> (i.e., it has <tt class="docutils literal"><span class="pre">domain</span></tt> and <tt class="docutils literal"><span class="pre">name</span></tt> attributes) but gets its data from a Django <a class="reference internal" href="../request-response.html#django.http.HttpRequest" title="django.http.HttpRequest"><tt class="xref py py-class docutils literal"><span class="pre">HttpRequest</span></tt></a> object rather than from a database.</p> <p>The <tt class="docutils literal"><span class="pre">save()</span></tt> and <tt class="docutils literal"><span class="pre">delete()</span></tt> methods raise <tt class="docutils literal"><span class="pre">NotImplementedError</span></tt>.</p> <dl class="method"> <dt id="django.contrib.sites.models.RequestSite.__init__"> <tt class="descname">__init__</tt>(<em>request</em>)<a class="headerlink" href="#django.contrib.sites.models.RequestSite.__init__" title="Permalink to this definition">¶</a></dt> <dd><p>Sets the <tt class="docutils literal"><span class="pre">name</span></tt> and <tt class="docutils literal"><span class="pre">domain</span></tt> attributes to the value of <a class="reference internal" href="../request-response.html#django.http.HttpRequest.get_host" title="django.http.HttpRequest.get_host"><tt class="xref py py-meth docutils literal"><span class="pre">get_host()</span></tt></a>.</p> </dd></dl> </dd></dl> <p>A <a class="reference internal" href="#django.contrib.sites.models.RequestSite" title="django.contrib.sites.models.RequestSite"><tt class="xref py py-class docutils literal"><span class="pre">RequestSite</span></tt></a> object has a similar interface to a normal <a class="reference internal" href="#django.contrib.sites.models.Site" title="django.contrib.sites.models.Site"><tt class="xref py py-class docutils literal"><span class="pre">Site</span></tt></a> object, except its <a class="reference internal" href="#django.contrib.sites.models.RequestSite.__init__" title="django.contrib.sites.models.RequestSite.__init__"><tt class="xref py py-meth docutils literal"><span class="pre">__init__()</span></tt></a> method takes an <a class="reference internal" href="../request-response.html#django.http.HttpRequest" title="django.http.HttpRequest"><tt class="xref py py-class docutils literal"><span class="pre">HttpRequest</span></tt></a> object. It’s able to deduce the <tt class="docutils literal"><span class="pre">domain</span></tt> and <tt class="docutils literal"><span class="pre">name</span></tt> by looking at the request’s domain. It has <tt class="docutils literal"><span class="pre">save()</span></tt> and <tt class="docutils literal"><span class="pre">delete()</span></tt> methods to match the interface of <a class="reference internal" href="#django.contrib.sites.models.Site" title="django.contrib.sites.models.Site"><tt class="xref py py-class docutils literal"><span class="pre">Site</span></tt></a>, but the methods raise <tt class="docutils literal"><span class="pre">NotImplementedError</span></tt>.</p> </div> </div> </div> </div> </div> <div class="yui-b" id="sidebar"> <div class="sphinxsidebar"> <div class="sphinxsidebarwrapper"> <h3><a href="../../contents.html">Table Of Contents</a></h3> <ul> <li><a class="reference internal" href="#">The “sites” framework</a><ul> <li><a class="reference internal" href="#example-usage">Example usage</a><ul> <li><a class="reference internal" href="#associating-content-with-multiple-sites">Associating content with multiple sites</a></li> <li><a class="reference internal" href="#associating-content-with-a-single-site">Associating content with a single site</a></li> <li><a class="reference internal" href="#hooking-into-the-current-site-from-views">Hooking into the current site from views</a></li> <li><a class="reference internal" href="#getting-the-current-domain-for-display">Getting the current domain for display</a></li> <li><a class="reference internal" href="#getting-the-current-domain-for-full-urls">Getting the current domain for full URLs</a></li> </ul> </li> <li><a class="reference internal" href="#caching-the-current-site-object">Caching the current <tt class="docutils literal"><span class="pre">Site</span></tt> object</a></li> <li><a class="reference internal" href="#the-currentsitemanager">The <tt class="docutils literal"><span class="pre">CurrentSiteManager</span></tt></a></li> <li><a class="reference internal" href="#how-django-uses-the-sites-framework">How Django uses the sites framework</a></li> <li><a class="reference internal" href="#requestsite-objects"><tt class="docutils literal"><span class="pre">RequestSite</span></tt> objects</a></li> </ul> </li> </ul> <h3>Browse</h3> <ul> <li>Prev: <a href="sitemaps.html">The sitemap framework</a></li> <li>Next: <a href="staticfiles.html">The staticfiles app</a></li> </ul> <h3>You are here:</h3> <ul> <li> <a href="../../index.html">Django 1.4.13 documentation</a> <ul><li><a href="../index.html">API Reference</a> <ul><li><a href="index.html"><tt class="docutils literal"><span class="pre">contrib</span></tt> packages</a> <ul><li>The “sites” framework</li></ul> </li></ul></li></ul> </li> </ul> <h3>This Page</h3> <ul class="this-page-menu"> <li><a href="../../_sources/ref/contrib/sites.txt" rel="nofollow">Show Source</a></li> </ul> <div id="searchbox" style="display: none"> <h3>Quick search</h3> <form class="search" action="../../search.html" method="get"> <input type="text" name="q" /> <input type="submit" value="Go" /> <input type="hidden" name="check_keywords" value="yes" /> <input type="hidden" name="area" value="default" /> </form> <p class="searchtip" style="font-size: 90%"> Enter search terms or a module, class or function name. </p> </div> <script type="text/javascript">$('#searchbox').show(0);</script> </div> </div> <h3>Last update:</h3> <p class="topless">May 15, 2014</p> </div> </div> <div id="ft"> <div class="nav"> « <a href="sitemaps.html" title="The sitemap framework">previous</a> | <a href="../index.html" title="API Reference" accesskey="U">up</a> | <a href="staticfiles.html" title="The staticfiles app">next</a> »</div> </div> </div> <div class="clearer"></div> </div> </body> </html>