The "sites" framework

Django comes with an optional "sites" framework. It's a hook for associating objects and functionality to particular websites, and it's a holding place for the domain names and "verbose" names of your Django-powered sites.

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

The sites framework is mainly based on a simple model:

class models.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 SITE_ID setting specifies the database ID of the Site object associated with that particular settings file. If the setting is omitted, the get_current_site() function will try to get the current site by comparing the domain with the host name from the request.get_host() method.

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

Example usage

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

Associating content with multiple sites

The Django-powered sites LJWorld.com and Lawrence.com 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 both sites.

The naive 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.

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 ManyToManyField in the Article model:

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

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

Ini menyelesaikan beberapa hal cukup baik:

• Itu membiarkan pembuat situs menyunting semua isi -- pada kedua situs -- dalam antarmuka tunggal (admin Django).

• Itu berarti cerita sams tidak harus menerbitkan kedua kali di basisdata; itu hanya mempunyai rekaman tunggal di basisdata.

• Itu membiarkan pengembang situs menggunakan kode tampilan Django sama untuk kedua situs. Kode tampilan yang memperlihatkan cerita yang diberikan cukup memeriksa untuk memastikan cerita diminta pada situs saat ini. Itu terlihat sesuatu seperti ini:

  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")
      # ...
  

Associating content with a single site

Similarly, you can associate a model to the Site model in a many-to-one relationship, using ForeignKey.

For example, if an article is only allowed on a single site, you'd use a model like 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)

Ini mempunyai keuntungan sama seperti digambarkan di bagian terakhir.

Mengaitkan kedalam situs saat ini dari tampilan

Anda dapat menggunakan kerangka kerja situs di tampilan Django anda untuk melakukan hal-hal tertentu berdasarkan pada situs dimana tampilan sedang dipanggil. Sebagai contoh:

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 of hard-coding is best for hackish fixes that you need done quickly. The cleaner way of accomplishing the same thing is to check the current site's domain:

from django.contrib.sites.shortcuts 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

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

Jika anda tidak mempunyai akses ke obyek diminta, anda dapat menggunakan metode get_current() dari pengelola model Site. Anda harus kemudian memastikan bahwa berkas pengaturan anda mengandung pengaturan SITE_ID. Contoh ini adalah setara pada satu sebelumnya:

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

Mendapatkan ranah saat ini untuk ditampilkan

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 immediately gets an email saying, "Thanks for your subscription."

It'd be inefficient and redundant to implement this sign up 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 Site objects, we can abstract the "thank you" notice to use the values of the current site's name and domain.

Disini adalah contoh dari apa tampilan penanganan formulir kelihatannya:

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 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.

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 (DIRS), you could simply 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, '[e-mail]', [user.email])

    # ...

In this case, you'd have to create subject.txt and message.txt template 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 Site objects as much as possible, to remove unneeded complexity and redundancy.

Mendapatkan ranah saat ini untuk URL penuh

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 the full 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())
'https://example.com/mymodel/objects/3/'

Mengadakan kerangka situs

Untuk mengadakan kerangka situs ini, ikuti langkah-langkah ini:

1. Menambahkan 'django.contrib.sites' ke pengaturan INSTALLED_APPS anda.

2. Menentukan pengaturan SITE_ID:

   SITE_ID = 1
   

3. Menjalankan migrate.

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

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

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

CurrentSiteManager

class managers.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.

SITE_ID wajib

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

Use CurrentSiteManager by adding it to your 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 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.

Taruh di jalan lain, dua pernyataan ini adalah sama:

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.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 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.

Situs middleware

Jika anda sering menggunakan pola ini:

from django.contrib.sites.models import Site

def my_view(request):
    site = Site.objects.get_current()
    ...

there is simple way to avoid repetitions. Add django.contrib.sites.middleware.CurrentSiteMiddleware to MIDDLEWARE. The middleware sets the site attribute on every request object, so you can use request.site to get the current site.

Bagaimana Django menggunakan kerangka situs

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.

Ini adalah bagaimana Django menggunakan kerangka situs:

• 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.
• Dalam flatpages framework, setiap flatpage dihubungkan dengan situs tertentu. Ketika sebuah flatpage dibuat, anda menentukan Site nya, dan FlatpageFallbackMiddleware memeriksa situs saat ini dalam mengambil flatpage untuk dimunculkan.
• 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, django.contrib.auth.views.LoginView passes the current Site name to the template as {{ site_name }}.
• The shortcut view (django.contrib.contenttypes.views.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.

Obyek RequestSite

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 django.contrib.sites.requests.RequestSite class, which can be used as a fallback when the database-backed sites framework is not available.

class requests.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.

__init__(request)

Setel atribut name dan domain ke nilai dari get_host().

Sebuah obyek RequestSite mempunyai antarmuka mirip pada obyek Site biasa, kecuali metode __init__() nya mengambil sebuah obyek HttpRequest. Itu dapat menyimpulkan domain dan name dengan mencari domain permintaan. Itu mempunyai metode save() dan delete() untuk mencocokkan antarmuka dari Site, tetapi metode-metode memunculkan NotImplementedError.

Jalan pintas get_current_site

Akhirnya, untuk menghindari kode fallback berulang, kerangka kerja menyediakan sebuah fungsi django.contrib.sites.shortcuts.get_current_site()

shortcuts.get_current_site(request)

Sebuah fungsi yang memeriksa jika django.contrib.sites dipasang dan mengembalikan salah satu obyek Site object saat ini atau obyek RequestSite berdasarkan pada permintaan. Itu mencari situs saat ini berdasarkan pada request.get_host() jika pengaturan SITE_ID tidak ditentukan.

Both a domain and a port may be returned by request.get_host() when the Host header has a port explicitly specified, e.g. example.com:80. In such cases, if the lookup fails because the host does not match a record in the database, the port is stripped and the lookup is retried with the domain part only. This does not apply to RequestSite which will always use the unmodified host.