The “sites” framework¶

Example usage¶

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

from django.db import models
from django.contrib.sites.models import Site

class Article(models.Model):
    headline = models.CharField(max_length=200)
    # ...
    sites = models.ManyToManyField(Site)

from django.db import models
from django.contrib.sites.models import Site

class Article(models.Model):
    headline = models.CharField(max_length=200)
    # ...
    site = models.ForeignKey(Site)

from django.conf import settings

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

from django.contrib.sites.models import get_current_site

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

from django.contrib.sites.models import Site

def my_function_without_request():
    current_site = Site.objects.get_current()
    if current_site.domain == 'foo.com':
        # Do something
        pass
    else:
        # Do something else.
        pass

from django.contrib.sites.models 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])

    # ...

from django.core.mail import send_mail
from django.template import loader, Context

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])

    # ...

>>> 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'
>>> 'http://%s%s' % (Site.objects.get_current().domain, obj.get_absolute_url())
'http://example.com/mymodel/objects/3/'

Default site and syncdb¶

django.contrib.sites registers a post_syncdb signal handler which creates a default site named example.com with the domain example.com. For example, this site will be created after Django creates the test database.

Caching the current Site object¶

As the current site is stored in the database, each call to Site.objects.get_current() 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.

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

# First call; current site fetched from database.
current_site = Site.objects.get_current()
# ...

# Second call; current site fetched from cache.
current_site = Site.objects.get_current()
# ...

# Force a database query for the third call.
Site.objects.clear_cache()
current_site = Site.objects.get_current()

The CurrentSiteManager¶

class CurrentSiteManager¶

If Site plays a key role in your application, consider using the helpful CurrentSiteManager in your model(s). It’s a model manager that automatically filters its queries to include only objects associated with the current Site.

Use CurrentSiteManager by adding it to your model explicitly. For example:

from django.db import models
from django.contrib.sites.models import Site
from django.contrib.sites.managers import CurrentSiteManager

class Photo(models.Model):
    photo = models.FileField(upload_to='/home/photos')
    photographer_name = models.CharField(max_length=100)
    pub_date = models.DateField()
    site = models.ForeignKey(Site)
    objects = models.Manager()
    on_site = CurrentSiteManager()

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

Put another way, these two statements are equivalent:

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

How did CurrentSiteManager know which field of Photo was the Site? By default, CurrentSiteManager looks for a either a ForeignKey called site or a ManyToManyField called sites to filter on. If you use a field named something other than site or sites to identify which Site objects your object is related to, then you need to explicitly pass the custom field name as a parameter to 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
from django.contrib.sites.managers import CurrentSiteManager

class Photo(models.Model):
    photo = models.FileField(upload_to='/home/photos')
    photographer_name = models.CharField(max_length=100)
    pub_date = models.DateField()
    publish_on = models.ForeignKey(Site)
    objects = models.Manager()
    on_site = CurrentSiteManager('publish_on')

If you attempt to use CurrentSiteManager 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 use CurrentSiteManager. As explained in the 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 CurrentSiteManager.

How Django uses the sites framework¶

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 domain and name, and point to its ID in your SITE_ID setting.

Here’s how Django uses the sites framework:

• In the redirects framework, each redirect object is associated with a particular site. When Django searches for a redirect, it takes into account the current site.
• In the comments framework, each comment is associated with a particular site. When a comment is posted, its Site is set to the current site, and when comments are listed via the appropriate template tag, only the comments for the current site are displayed.
• In the flatpages framework, each flatpage is associated with a particular site. When a flatpage is created, you specify its Site, and the FlatpageFallbackMiddleware checks the current site in retrieving flatpages to display.
• In the syndication framework, the templates for title and description automatically have access to a variable {{ site }}, which is the Site object representing the current site. Also, the hook for providing item URLs will use the domain from the current Site object if you don’t specify a fully-qualified domain.
• In the authentication framework, the django.contrib.auth.views.login() view passes the current Site name to the template as {{ site_name }}.
• The shortcut view (django.views.defaults.shortcut) uses the domain of the current Site object when calculating an object’s URL.
• In the admin framework, the “view on site” link uses the current Site to work out the domain for the site that it will redirect to.

RequestSite objects¶

Some django.contrib applications take advantage of the sites framework but are architected in a way that doesn’t require the sites 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 sites framework requires.) For those cases, the framework provides a RequestSite class, which can be used as a fallback when the database-backed sites framework is not available.

class RequestSite¶

A class that shares the primary interface of Site (i.e., it has domain and name attributes) but gets its data from a Django HttpRequest object rather than from a database.

The save() and delete() methods raise NotImplementedError.

__init__(request)¶

Sets the name and domain attributes to the value of get_host().

A RequestSite object has a similar interface to a normal Site object, except its __init__() method takes an HttpRequest object. It’s able to deduce the domain and name by looking at the request’s domain. It has save() and delete() methods to match the interface of Site, but the methods raise NotImplementedError.