Inside Template Loading

Generally, you’ll store templates in files on your filesystem rather than using the low-level Template API yourself. Save templates in a directory specified as a template directory. Django searches for template directories in a number of places, depending on your template loading settings, but the most basic way of specifying template directories is by using the DIRS option.

The DIRS option

Tell Django what your template directories are by using the DIRS option in the TEMPLATES setting in your settings file – or the dirs argument of Engine. This should be set to a list of strings that contain full paths to your template directories:

TEMPLATES = [
{
‘BACKEND’: ‘django.template.backends.django.DjangoTemplates’,
‘DIRS’: [
‘/home/html/templates/lawrence.com’,
‘/home/html/templates/default’,
],
},
]

Your templates can go anywhere you want, as long as the directories and templates are readable by the Web server. They can have any extension you want, such as .html or .txt, or they can have no extension at all. Note that these paths should use Unix-style forward slashes, even on Windows.

Loader types

By default, Django uses a filesystem-based template loader, but Django comes with a few other template loaders, which know how to load templates from other sources; the most commonly used of them, the apps loader, is described below.

Filesystem loader – filesystem.Loader Loads templates from the filesystem, according to DIRS <TEMPLATES-DIRS>. This loader is enabled by default. However, it won’t find any templates until you set DIRS <TEMPLATES-DIRS> to a non-empty list:

TEMPLATES = [{
‘BACKEND’: ‘django.template.backends.django.DjangoTemplates’,
‘DIRS’: [os.path.join(BASE_DIR, ‘templates’)],
}]

App directories loader – app_directories.Loader Loads templates from Django apps on the filesystem. For each app in INSTALLED_APPS, the loader looks for a templates subdirectory. If the directory exists, Django looks for templates in there. This means you can store templates with your individual apps. This also makes it easy to distribute Django apps with default templates. For example, for this setting:

INSTALLED_APPS = [‘myproject.reviews’, ‘myproject.music’]

get_template(‘foo.html’) will look for foo.html in these directories, in this order:

/path/to/myproject/reviews/templates/
/path/to/myproject/music/templates/

and will use the one it finds first.

The order of INSTALLED_APPS is significant! For example, if you want to customize the Django admin, you might choose to override the standard admin/base_site.html template, from django.contrib.admin, with your own admin/base_site.html in myproject.reviews.

You must then make sure that your myproject.reviews comes before django.contrib.admin in INSTALLED_APPS, otherwise django.contrib.admin’s will be loaded first and yours will be ignored. Note that the loader performs an optimization when it first runs: it caches a list of which INSTALLED_APPS packages have a templates subdirectory.

You can enable this loader simply by setting APP_DIRS to True:

TEMPLATES = [{
‘BACKEND’: ‘django.template.backends.django.DjangoTemplates’,
‘APP_DIRS’: True,
}]

Other loaders – The remaining template loaders are:

• django.template.loaders.eggs.Loader
• django.template.loaders.cached.Loader
• django.template.loaders.locmem.Loader

These loaders are disabled by default, but you can activate them by adding a ‘loaders’ option to your DjangoTemplates backend in the TEMPLATES setting or passing a loaders argument to Engine. Details on these advanced loaders, as well as building your own custom loader, can be found on the Django Project website.

Back to Tutorial