The "sites" framework

Use it if your single Django installation powers more than one site and youneed to differentiate between those sites in some way.

The sites framework is mainly based on a simple model:

• class Site

• A model for storing the domain and name attributes of a website.

  • domain

  • The fully qualified domain name associated with the website.For example, www.example.com.

  • name

  • A human-readable "verbose" name for the website.

The setting specifies the database ID of theSite object associated with thatparticular settings file. If the setting is omitted, the function willtry to get the current site by comparing thedomain with the host name fromthe method.

How you use this is up to you, but Django uses it in a couple of waysautomatically via simple conventions.

Why would you use sites? It's best explained through examples.

The Django-powered sites LJWorld.com and are operated by thesame news organization — the Lawrence Journal-World newspaper in Lawrence,Kansas. LJWorld.com focuses on news, while Lawrence.com focuses on localentertainment. But sometimes editors want to publish an article on _both_sites.

The naive way of solving the problem would be to require site producers topublish 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 storemultiple copies of the same story in the database.

The better solution is simple: Both sites use the same article database, and anarticle is associated with one or more sites. In Django model terminology,that's represented by a ManyToManyField in theArticle model:

This accomplishes several things quite nicely:

• It lets the site producers edit all content — on both sites — in asingle interface (the Django admin).

• It means the same story doesn't have to be published twice in thedatabase; it only has a single record in the database.

• 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 therequested story is on the current site. It looks something like this:

from django.contrib.sites.shortcuts import get_current_site
 
def article_detail(request, article_id):
    try:
        a = Article.objects.get(id=article_id, sites__id=get_current_site(request).id)
    except Article.DoesNotExist:
        raise Http404("Article does not exist on this site")
    # ...

Similarly, you can associate a model to themodel in a many-to-one relationship, usingForeignKey.

For example, if an article is only allowed on a single site, you'd use a modellike this:

from django.contrib.sites.models import Site
from django.db import models
 
class Article(models.Model):
    headline = models.CharField(max_length=200)
    # ...
    site = models.ForeignKey(Site, on_delete=models.CASCADE)

You can use the sites framework in your Django views to doparticular things based on the site in which the view is being called.For example:

from django.conf import settings
 
def my_view(request):
    if settings.SITE_ID == 3:
        # Do something.
        pass
    else:
        # Do something else.
        pass

Of course, it's ugly to hard-code the site IDs like that. This sort ofhard-coding is best for hackish fixes that you need done quickly. Thecleaner way of accomplishing the same thing is to check the current site'sdomain:

 
def my_view(request):
    current_site = get_current_site(request)
    if current_site.domain == 'foo.com':
        # Do something
        pass
    else:
        # Do something else.
        pass

This has also the advantage of checking if the sites framework is installed,and return a instance ifit is not.

If you don't have access to the request object, you can use theget_current() method of the Sitemodel's manager. You should then ensure that your settings file does containthe setting. This example is equivalent to the previous one:

LJWorld.com and Lawrence.com both have email alert functionality, which letsreaders sign up to get notifications when news happens. It's pretty basic: Areader signs up on a Web form and immediately gets an email saying,"Thanks for your subscription."

It'd be inefficient and redundant to implement this sign up processing codetwice, so the sites use the same code behind the scenes. But the "thank you forsigning up" notice needs to be different for each site. By usingSiteobjects, we can abstract the "thank you" notice to use the values of thecurrent site's anddomain.

Here's an example of what the form-handling view looks like:

from django.contrib.sites.shortcuts import get_current_site
from django.core.mail import send_mail
 
def register_for_newsletter(request):
    # Check form values, etc., and subscribe the user.
    # ...
 
    current_site = get_current_site(request)
    send_mail(
        'Thanks for subscribing to %s alerts' % current_site.name,
        'Thanks for your subscription. We appreciate it.\n\n-The %s team.' % (
            current_site.name,
        ),
        'editor@%s' % current_site.domain,
        [user.email],
    )
 
    # ...

On Lawrence.com, this email has the subject line "Thanks for subscribing tolawrence.com alerts." On LJWorld.com, the email has the subject "Thanks forsubscribing to LJWorld.com alerts." Same goes for the email's message body.

Note that an even more flexible (but more heavyweight) way of doing this wouldbe to use Django's template system. Assuming Lawrence.com and LJWorld.com havedifferent template directories (), you couldsimply farm out to the template system like so:

from django.core.mail import send_mail
from django.template import Context, loader
 
def register_for_newsletter(request):
    # Check form values, etc., and subscribe the user.
    # ...
 
    subject = loader.get_template('alerts/subject.txt').render(Context({}))
    message = loader.get_template('alerts/message.txt').render(Context({}))
    send_mail(subject, message, 'editor@ljworld.com', [user.email])
 
    # ...

In this case, you'd have to create subject.txt and message.txttemplate files for both the LJWorld.com and Lawrence.com template directories.That gives you more flexibility, but it's also more complex.

It's a good idea to exploit the Siteobjects as much as possible, to remove unneeded complexity and redundancy.

Django's get_absolute_url() convention is nice for getting your objects'URL without the domain name, but in some cases you might want to display thefull URL — with http:// and the domain and everything — for an object.To do this, you can use the sites framework. A simple example:

>>> from django.contrib.sites.models import Site
>>> obj = MyModel.objects.get(id=3)
>>> obj.get_absolute_url()
'/mymodel/objects/3/'
>>> Site.objects.get_current().domain
'example.com'
>>> 'https://%s%s' % (Site.objects.get_current().domain, obj.get_absolute_url())

Enabling the sites framework

To enable the sites framework, follow these steps:

• Add 'django.contrib.sites' to your INSTALLED_APPS setting.

• Define a setting:

SITE_ID = 1

• Run migrate.

django.contrib.sites registers a signal handler which creates adefault site named example.com with the domain example.com. This sitewill also be created after Django creates the test database. To set thecorrect name and domain for your project, you can use a data migration.

In order to serve different sites in production, you'd create a separatesettings file with each SITE_ID (perhaps importing from a common settingsfile to avoid duplicating shared settings) and then specify the appropriate for each site.

If for any reason you want to force a database query, you can tell Django toclear the cache using Site.objects.clear_cache():

The CurrentSiteManager

• class managers.CurrentSiteManager
• If Site plays a key role in yourapplication, consider using the helpful in yourmodel(s). It's a model manager thatautomatically filters its queries to include only objects associatedwith the current .

Mandatory SITE_ID

The CurrentSiteManager is only usable when the setting is defined in your settings.

Use CurrentSiteManager by adding it toyour model explicitly. For example:

from django.contrib.sites.models import Site
from django.contrib.sites.managers import CurrentSiteManager
from django.db import models
 
class Photo(models.Model):
    photo = models.FileField(upload_to='photos')
    photographer_name = models.CharField(max_length=100)
    pub_date = models.DateField()
    site = models.ForeignKey(Site, on_delete=models.CASCADE)
    objects = models.Manager()
    on_site = CurrentSiteManager()

With this model, Photo.objects.all() will return all Photo objects inthe database, but Photo.on_site.all() will return only the Photo objectsassociated with the current site, according to the setting.

Put another way, these two statements are equivalent:

Photo.objects.filter(site=settings.SITE_ID)
Photo.on_site.all()

How did CurrentSiteManagerknow which field of Photo was the? By default,CurrentSiteManager looks for aeither a calledsite or aManyToManyField calledsites to filter on. If you use a field named something other thansite or sites to identify which objects your object isrelated to, then you need to explicitly pass the custom field name asa parameter toCurrentSiteManager on yourmodel. The following model, which has a field called publish_on,demonstrates this:

from django.contrib.sites.models import Site
from django.contrib.sites.managers import CurrentSiteManager
from django.db import models
 
class Photo(models.Model):
    photo = models.FileField(upload_to='photos')
    photographer_name = models.CharField(max_length=100)
    pub_date = models.DateField()
    publish_on = models.ForeignKey(Site, on_delete=models.CASCADE)
    objects = models.Manager()
    on_site = CurrentSiteManager('publish_on')

If you attempt to use and pass a field name that doesn't exist, Django will raise a ValueError.

Finally, note that you'll probably want to keep a normal(non-site-specific) Manager on your model, even if you useCurrentSiteManager. Asexplained in the , ifyou define a manager manually, then Django won't create the automaticobjects = models.Manager() manager for you. Also note that certainparts of Django — namely, the Django admin site and generic views —use whichever manager is defined first in the model, so if you wantyour admin site to have access to all objects (not just site-specificones), put objects = models.Manager() in your model, before youdefine CurrentSiteManager.

If you often use this pattern:

from django.contrib.sites.models import Site
 
def my_view(request):
    site = Site.objects.get_current()
    ...

there is simple way to avoid repetitions. Add toMIDDLEWARE. The middleware sets the site attribute on everyrequest object, so you can use request.site to get the current site.

How Django uses the sites framework

Although it's not required that you use the sites framework, it's stronglyencouraged, because Django takes advantage of it in a few places. Even if yourDjango installation is powering only a single site, you should take the twoseconds to create the site object with your domain and name, and pointto its ID in your SITE_ID setting.

Here's how Django uses the sites framework:

• In the , eachredirect object is associated with a particular site. When Django searchesfor a redirect, it takes into account the current site.
• In the flatpages framework, eachflatpage is associated with a particular site. When a flatpage is created,you specify its , and theFlatpageFallbackMiddlewarechecks the current site in retrieving flatpages to display.
• In the , thetemplates for title and automatically have access to avariable {{ site }}, which is theSite object representing the currentsite. Also, the hook for providing item URLs will use the domain fromthe current object if you don'tspecify a fully-qualified domain.
• In the authentication framework, passes the currentSite name to the template as{{ site_name }}.
• The shortcut view (django.contrib.contenttypes.views.shortcut)uses the domain of the current object when calculatingan object's URL.
• In the admin framework, the "view on site" link uses the currentSite to work out the domain for thesite that it will redirect to.

Some applications take advantage ofthe sites framework but are architected in a way that doesn't require thesites framework to be installed in your database. (Some people don't want to,or just aren't able to install the extra database table that the sitesframework requires.) For those cases, the framework provides adjango.contrib.sites.requests.RequestSite class, which can be used asa fallback when the database-backed sites framework is not available.

• class requests.RequestSite

• A class that shares the primary interface ofSite (i.e., it hasdomain and name attributes) but gets its data from a Django object rather than from a database.

  • init(request)
  • Sets the name and domain attributes to the value of.

A RequestSite object has a similarinterface to a normal object,except its init()method takes an object. It's able to deducethe domain and name by looking at the request's domain. It hassave() and delete() methods to match the interface ofSite, but the methods raise.

get_current_site shortcut

Finally, to avoid repetitive fallback code, the framework provides a function.

• shortcuts.getcurrent_site(_request)