The Django template language: for Python programmers

The Django template language: for Python programmers

This document explains the Django template system from a technicalperspective — how it works and how to extend it. If you're just looking forreference on the language syntax, see The Django template language.

It assumes an understanding of templates, contexts, variables, tags, andrendering. Start with the introduction to the Django template language if you aren't familiar with these concepts.

Overview

Using the template system in Python is a three-step process:

You configure an Engine.
You compile template code into a Template.
You render the template with a Context.
Django projects generally rely on the high level, backend agnostic APIs for each of these steps instead of the template system'slower level APIs:
For each DjangoTemplates backendin the TEMPLATES setting, Django instantiates anEngine. DjangoTemplateswraps Engine and adapts it to the common template backend API.
The django.template.loader module provides functions such asget_template() for loading templates. Theyreturn a django.template.backends.django.Template which wraps theactual django.template.Template.
The Template obtained in the previous step has arender() method whichmarshals a context and possibly a request into a Context anddelegates the rendering to the underlying Template.

Configuring an engine

If you are simply using theDjangoTemplates backend, thisprobably isn't the documentation you're looking for. An instance of theEngine class described below is accessible using the engine attributeof that backend and any attribute defaults mentioned below are overridden bywhat's passed by DjangoTemplates.

class Engine(dirs=None, app_dirs=False, context_processors=None, debug=False, loaders=None, string_if_invalid='', file_charset='utf-8', libraries=None, builtins=None, autoescape=True)[源代码]
When instantiating an Engine all arguments must be passed as keywordarguments:
- dirs is a list of directories where the engine should look fortemplate source files. It is used to configurefilesystem.Loader.

It defaults to an empty list.

app_dirs only affects the default value of loaders. See below.

It defaults to False.

autoescape controls whether HTML autoescaping is enabled.

It defaults to True.

警告

Only set it to False if you're rendering non-HTML templates!

context_processors is a list of dotted Python paths to callablesthat are used to populate the context when a template is rendered with arequest. These callables take a request object as their argument andreturn a dict of items to be merged into the context.

It defaults to an empty list.

See RequestContext for more information.

debug is a boolean that turns on/off template debug mode. If it isTrue, the template engine will store additional debug informationwhich can be used to display a detailed report for any exception raisedduring template rendering.

It defaults to False.

loaders is a list of template loader classes, specified as strings.Each Loader class knows how to import templates from a particularsource. Optionally, a tuple can be used instead of a string. The firstitem in the tuple should be the Loader class name, subsequent itemsare passed to the Loader during initialization.

It defaults to a list containing:

- <code>&#39;django.template.loaders.filesystem.Loader&#39;</code>
- <code>&#39;django.template.loaders.app_directories.Loader&#39;</code> if and only if<code>app_dirs</code> is <code>True</code>.

If debug is False, these loaders are wrapped indjango.template.loaders.cached.Loader.

See Loader types for details.

string_if_invalid is the output, as a string, that the templatesystem should use for invalid (e.g. misspelled) variables.

It defaults to the empty string.

See How invalid variables are handled for details.

file_charset is the charset used to read template files on disk.

It defaults to 'utf-8'.

'libraries': A dictionary of labels and dotted Python paths of templatetag modules to register with the template engine. This is used to add newlibraries or provide alternate labels for existing ones. For example:

Engine(
    libraries={
        'myapp_tags': 'path.to.myapp.tags',
        'admin.urls': 'django.contrib.admin.templatetags.admin_urls',
    },
)

Libraries can be loaded by passing the corresponding dictionary key tothe {% load %} tag.

'builtins': A list of dotted Python paths of template tag modules toadd to built-ins. For example:

Engine(
    builtins=['myapp.builtins'],
)

Tags and filters from built-in libraries can be used without first callingthe {% load %} tag.

static Engine.get_default()[源代码]
Returns the underlying Engine from the first configuredDjangoTemplates engine. RaisesImproperlyConfigured if no engines areconfigured.

It's required for preserving APIs that rely on a globally available,implicitly configured engine. Any other use is strongly discouraged.

Engine.fromstring(_template_code)[源代码]
Compiles the given template code and returns a Template object.
Engine.gettemplate(_template_name)[源代码]
Loads a template with the given name, compiles it and returns aTemplate object.
Engine.selecttemplate(_template_name_list)[源代码]
Like get_template(), except it takes a list of namesand returns the first template that was found.

Loading a template

The recommended way to create a Template is by calling the factorymethods of the Engine: get_template(),select_template() and from_string().

In a Django project where the TEMPLATES setting defines aDjangoTemplates engine, it'spossible to instantiate a Template directly. If more than oneDjangoTemplates engine is defined,the first one will be used.

class Template[源代码]
This class lives at django.template.Template. The constructor takesone argument — the raw template code:

from django.template import Template
 
template = Template("My name is {{ my_name }}.")

Behind the scenes

The system only parses your raw template code once — when you create theTemplate object. From then on, it's stored internally as a treestructure for performance.

Even the parsing itself is quite fast. Most of the parsing happens via asingle call to a single, short, regular expression.

Rendering a context

Once you have a compiled Template object, you can render a contextwith it. You can reuse the same template to render it several times withdifferent contexts.

class Context(dict=None_)[源代码]
The constructor of django.template.Context takes an optional argument —a dictionary mapping variable names to variable values.

For details, see Playing with Context objects below.

Template.render(context)[源代码]
Call the Template object's render() method with aContext to "fill" the template:

>>> from django.template import Context, Template
>>> template = Template("My name is {{ my_name }}.")
 
>>> context = Context({"my_name": "Adrian"})
>>> template.render(context)
"My name is Adrian."
 
>>> context = Context({"my_name": "Dolores"})
>>> template.render(context)
"My name is Dolores."

Variables and lookups

Variable names must consist of any letter (A-Z), any digit (0-9), an underscore(but they must not start with an underscore) or a dot.

Dots have a special meaning in template rendering. A dot in a variable namesignifies a lookup. Specifically, when the template system encounters adot in a variable name, it tries the following lookups, in this order:

Dictionary lookup. Example: foo["bar"]
Attribute lookup. Example: foo.bar
List-index lookup. Example: foo[bar]
Note that "bar" in a template expression like {{ foo.bar }} will beinterpreted as a literal string and not using the value of the variable "bar",if one exists in the template context.

The template system uses the first lookup type that works. It's short-circuitlogic. Here are a few examples:

>>> from django.template import Context, Template
>>> t = Template("My name is {{ person.first_name }}.")
>>> d = {"person": {"first_name": "Joe", "last_name": "Johnson"}}
>>> t.render(Context(d))
"My name is Joe."
 
>>> class PersonClass: pass
>>> p = PersonClass()
>>> p.first_name = "Ron"
>>> p.last_name = "Nasty"
>>> t.render(Context({"person": p}))
"My name is Ron."
 
>>> t = Template("The first stooge in the list is {{ stooges.0 }}.")
>>> c = Context({"stooges": ["Larry", "Curly", "Moe"]})
>>> t.render(c)
"The first stooge in the list is Larry."

If any part of the variable is callable, the template system will try callingit. Example:

>>> class PersonClass2:
...     def name(self):
...         return "Samantha"
>>> t = Template("My name is {{ person.name }}.")
>>> t.render(Context({"person": PersonClass2}))
"My name is Samantha."

Callable variables are slightly more complex than variables which only requirestraight lookups. Here are some things to keep in mind:

If the variable raises an exception when called, the exception will bepropagated, unless the exception has an attributesilentvariable_failure whose value is True. If the exception_does have a silent_variable_failure attribute whose value isTrue, the variable will render as the value of the engine'sstring_if_invalid configuration option (an empty string, by default).Example:

>>> t = Template("My name is {{ person.first_name }}.")
>>> class PersonClass3:
...     def first_name(self):
...         raise AssertionError("foo")
>>> p = PersonClass3()
>>> t.render(Context({"person": p}))
Traceback (most recent call last):
...
AssertionError: foo
 
>>> class SilentAssertionError(Exception):
...     silent_variable_failure = True
>>> class PersonClass4:
...     def first_name(self):
...         raise SilentAssertionError
>>> p = PersonClass4()
>>> t.render(Context({"person": p}))
"My name is ."

Note that django.core.exceptions.ObjectDoesNotExist, which is thebase class for all Django database API DoesNotExist exceptions, hassilent_variable_failure = True. So if you're using Django templateswith Django model objects, any DoesNotExist exception will failsilently.

A variable can only be called if it has no required arguments. Otherwise,the system will return the value of the engine's string_if_invalidoption.
Obviously, there can be side effects when calling some variables, andit'd be either foolish or a security hole to allow the template systemto access them.

A good example is the delete() method oneach Django model object. The template system shouldn't be allowed to dosomething like this:

I will now delete this valuable data. {{ data.delete }}

To prevent this, set an alters_data attribute on the callablevariable. The template system won't call a variable if it hasalters_data=True set, and will instead replace the variable withstring_if_invalid, unconditionally. Thedynamically-generated delete() andsave() methods on Django model objects getalters_data=True automatically. Example:

def sensitive_function(self):
    self.database_record.delete()
sensitive_function.alters_data = True

Occasionally you may want to turn off this feature for other reasons,and tell the template system to leave a variable uncalled no matterwhat. To do so, set a do_not_call_in_templates attribute on thecallable with the value True. The template system then will act asif your variable is not callable (allowing you to access attributes ofthe callable, for example).

How invalid variables are handled

Generally, if a variable doesn't exist, the template system inserts the valueof the engine's string_if_invalid configuration option, which is set to'' (the empty string) by default.

Filters that are applied to an invalid variable will only be applied ifstring_if_invalid is set to '' (the empty string). Ifstring_if_invalid is set to any other value, variable filters will beignored.

This behavior is slightly different for the if, for and regrouptemplate tags. If an invalid variable is provided to one of these templatetags, the variable will be interpreted as None. Filters are alwaysapplied to invalid variables within these template tags.

If string_if_invalid contains a '%s', the format marker will bereplaced with the name of the invalid variable.

For debug purposes only!

While string_if_invalid can be a useful debugging tool, it is a badidea to turn it on as a 'development default'.

Many templates, including some of Django's, rely upon the silence of thetemplate system when a nonexistent variable is encountered. If you assign avalue other than '' to string_if_invalid, you will experiencerendering problems with these templates and sites.

Generally, string_if_invalid should only be enabled in order to debuga specific template problem, then cleared once debugging is complete.

Built-in variables

Every context contains True, False and None. As you would expect,these variables resolve to the corresponding Python objects.

Limitations with string literals

Django's template language has no way to escape the characters used for its ownsyntax. For example, the templatetag tag is required if you need tooutput character sequences like {% and %}.

A similar issue exists if you want to include these sequences in template filteror tag arguments. For example, when parsing a block tag, Django's templateparser looks for the first occurrence of %} after a {%. This preventsthe use of "%}" as a string literal. For example, a TemplateSyntaxErrorwill be raised for the following expressions:

{% include "template.html" tvar="Some string literal with %} in it." %}
 
{% with tvar="Some string literal with %} in it." %}{% endwith %}

The same issue can be triggered by using a reserved sequence in filterarguments:

{{ some.variable|default:"}}" }}

If you need to use strings with these sequences, store them in templatevariables or use a custom template tag or filter to workaround the limitation.

Playing with Context objects

Most of the time, you'll instantiate Context objects by passing in afully-populated dictionary to Context(). But you can add and delete itemsfrom a Context object once it's been instantiated, too, using standarddictionary syntax:

>>> from django.template import Context
>>> c = Context({"foo": "bar"})
>>> c['foo']
'bar'
>>> del c['foo']
>>> c['foo']
Traceback (most recent call last):
...
KeyError: 'foo'
>>> c['newvariable'] = 'hello'
>>> c['newvariable']
'hello'

Context.get(key, otherwise=None)
Returns the value for key if key is in the context, else returnsotherwise.
Context.setdefault(key, default=None)
If key is in the context, returns its value. Otherwise inserts keywith a value of default and returns default.
Context.pop()
Context.push()
exception ContextPopException[源代码]
A Context object is a stack. That is, you can push() and pop() it.If you pop() too much, it'll raisedjango.template.ContextPopException:

>>> c = Context()
>>> c['foo'] = 'first level'
>>> c.push()
{}
>>> c['foo'] = 'second level'
>>> c['foo']
'second level'
>>> c.pop()
{'foo': 'second level'}
>>> c['foo']
'first level'
>>> c['foo'] = 'overwritten'
>>> c['foo']
'overwritten'
>>> c.pop()
Traceback (most recent call last):
...
ContextPopException

You can also use push() as a context manager to ensure a matching pop()is called.

>>> c = Context()
>>> c['foo'] = 'first level'
>>> with c.push():
...     c['foo'] = 'second level'
...     c['foo']
'second level'
>>> c['foo']
'first level'

All arguments passed to push() will be passed to the dict constructorused to build the new context level.

>>> c = Context()
>>> c['foo'] = 'first level'
>>> with c.push(foo='second level'):
...     c['foo']
'second level'
>>> c['foo']
'first level'

Context.update(other_dict)[源代码]
In addition to push() and pop(), the Contextobject also defines an update() method. This works like push()but takes a dictionary as an argument and pushes that dictionary ontothe stack instead of an empty one.

>>> c = Context()
>>> c['foo'] = 'first level'
>>> c.update({'foo': 'updated'})
{'foo': 'updated'}
>>> c['foo']
'updated'
>>> c.pop()
{'foo': 'updated'}
>>> c['foo']
'first level'

Like push(), you can use update() as a context manager to ensure amatching pop() is called.

>>> c = Context()
>>> c['foo'] = 'first level'
>>> with c.update({'foo': 'second level'}):
...     c['foo']
'second level'
>>> c['foo']
'first level'

Using a Context as a stack comes in handy in some custom templatetags.

Context.flatten()
Using flatten() method you can get whole Context stack as one dictionaryincluding builtin variables.

>>> c = Context()
>>> c['foo'] = 'first level'
>>> c.update({'bar': 'second level'})
{'bar': 'second level'}
>>> c.flatten()
{'True': True, 'None': None, 'foo': 'first level', 'False': False, 'bar': 'second level'}

A flatten() method is also internally used to make Context objects comparable.

>>> c1 = Context()
>>> c1['foo'] = 'first level'
>>> c1['bar'] = 'second level'
>>> c2 = Context()
>>> c2.update({'bar': 'second level', 'foo': 'first level'})
{'foo': 'first level', 'bar': 'second level'}
>>> c1 == c2
True

Result from flatten() can be useful in unit tests to compare Contextagainst dict:

class ContextTest(unittest.TestCase):
    def test_against_dictionary(self):
        c1 = Context()
        c1['update'] = 'value'
        self.assertEqual(c1.flatten(), {
            'True': True,
            'None': None,
            'False': False,
            'update': 'value',
        })

Using RequestContext

class RequestContext(request, dict=None, _processors=None)[源代码]
Django comes with a special Context class,django.template.RequestContext, that acts slightly differently from thenormal django.template.Context. The first difference is that it takes anHttpRequest as its first argument. For example:

c = RequestContext(request, {
    'foo': 'bar',
})

The second difference is that it automatically populates the context with afew variables, according to the engine's context_processors configurationoption.

The context_processors option is a list of callables — called contextprocessors — that take a request object as their argument and return adictionary of items to be merged into the context. In the default generatedsettings file, the default template engine contains the following contextprocessors:

[
    'django.template.context_processors.debug',
    'django.template.context_processors.request',
    'django.contrib.auth.context_processors.auth',
    'django.contrib.messages.context_processors.messages',
]

In addition to these, RequestContext always enables'django.template.context_processors.csrf'. This is a security relatedcontext processor required by the admin and other contrib apps, and, in caseof accidental misconfiguration, it is deliberately hardcoded in and cannot beturned off in the context_processors option.

Each processor is applied in order. That means, if one processor adds avariable to the context and a second processor adds a variable with the samename, the second will override the first. The default processors are explainedbelow.

When context processors are applied

Context processors are applied on top of context data. This means that acontext processor may overwrite variables you've supplied to yourContext or RequestContext, so take care to avoidvariable names that overlap with those supplied by your contextprocessors.

If you want context data to take priority over context processors, use thefollowing pattern:

from django.template import RequestContext
 
request_context = RequestContext(request)
request_context.push({"my_name": "Adrian"})

Django does this to allow context data to override context processors inAPIs such as render() andTemplateResponse.

Also, you can give RequestContext a list of additional processors,using the optional, third positional argument, processors. In thisexample, the RequestContext instance gets a ip_address variable:

from django.http import HttpResponse
from django.template import RequestContext, Template
 
def ip_address_processor(request):
    return {'ip_address': request.META['REMOTE_ADDR']}
 
def client_ip_view(request):
    template = Template('{{ title }}: {{ ip_address }}')
    context = RequestContext(request, {
        'title': 'Your IP Address',
    }, [ip_address_processor])
    return HttpResponse(template.render(context))

Built-in template context processors

Here's what each of the built-in processors does:

django.contrib.auth.context_processors.auth

auth()[源代码]
If this processor is enabled, every RequestContext will contain thesevariables:
user — An auth.User instance representing the currentlylogged-in user (or an AnonymousUser instance, if the client isn'tlogged in).
perms — An instance ofdjango.contrib.auth.context_processors.PermWrapper, representing thepermissions that the currently logged-in user has.

django.template.context_processors.debug

debug()[源代码]
If this processor is enabled, every RequestContext will contain these twovariables — but only if your DEBUG setting is set to True andthe request's IP address (request.META['REMOTE_ADDR']) is in theINTERNAL_IPS setting:
debug — True. You can use this in templates to test whetheryou're in DEBUG mode.
sql_queries — A list of {'sql': …, 'time': …} dictionaries,representing every SQL query that has happened so far during the requestand how long it took. The list is in order by database alias and then byquery. It's lazily generated on access.

django.template.context_processors.i18n

i18n()[源代码]
If this processor is enabled, every RequestContext will contain thesevariables:
LANGUAGES — The value of the LANGUAGES setting.
LANGUAGE_BIDI — True if the current language is a right-to-leftlanguage, e.g. Hebrew, Arabic. False if it's a left-to-right language,e.g. English, French, German.
LANGUAGE_CODE — request.LANGUAGE_CODE, if it exists. Otherwise,the value of the LANGUAGE_CODE setting.
See i18n template tags for template tags thatgenerate the same values.

django.template.context_processors.media

If this processor is enabled, every RequestContext will contain a variableMEDIA_URL, providing the value of the MEDIA_URL setting.

django.template.context_processors.static

static()[源代码]
If this processor is enabled, every RequestContext will contain a variableSTATIC_URL, providing the value of the STATIC_URL setting.

django.template.context_processors.csrf

This processor adds a token that is needed by the csrf_token templatetag for protection against Cross Site Request Forgeries.

django.template.context_processors.request

If this processor is enabled, every RequestContext will contain a variablerequest, which is the current HttpRequest.

django.template.context_processors.tz

tz()[源代码]
If this processor is enabled, every RequestContext will contain a variableTIME_ZONE, providing the name of the currently active time zone.

django.contrib.messages.context_processors.messages

If this processor is enabled, every RequestContext will contain these twovariables:

messages — A list of messages (as strings) that have been setvia the messages framework.
DEFAULT_MESSAGE_LEVELS — A mapping of the message level names totheir numeric value.

Writing your own context processors

A context processor has a very simple interface: It's a Python functionthat takes one argument, an HttpRequest object, andreturns a dictionary that gets added to the template context. Each contextprocessor must return a dictionary.

Custom context processors can live anywhere in your code base. All Djangocares about is that your custom context processors are pointed to by the'context_processors' option in your TEMPLATES setting — or thecontext_processors argument of Engine if you'reusing it directly.

Loading templates

Generally, you'll store templates in files on your filesystem rather thanusing the low-level Template API yourself. Savetemplates in a directory specified as a template directory.

Django searches for template directories in a number of places, depending onyour template loading settings (see "Loader types" below), but the most basicway 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 settingsfile — or the dirs argument of Engine. Thisshould be set to a list of strings that contain full paths to your templatedirectories:

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 andtemplates 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 comeswith a few other template loaders, which know how to load templates from othersources.

Some of these other loaders are disabled by default, but you can activate themby adding a 'loaders' option to your DjangoTemplates backend in theTEMPLATES setting or passing a loaders argument toEngine. loaders should be a list of strings ortuples, where each represents a template loader class. Here are the templateloaders that come with Django:

django.template.loaders.filesystem.Loader

class filesystem.Loader
Loads templates from the filesystem, according toDIRS.

This loader is enabled by default. However it won't find any templatesuntil you set DIRS to a non-empty list:

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

You can also override 'DIRS' and specify specific directories for aparticular filesystem loader:

TEMPLATES = [{
    'BACKEND': 'django.template.backends.django.DjangoTemplates',
    'OPTIONS': {
        'loaders': [
            (
                'django.template.loaders.filesystem.Loader',
                [os.path.join(BASE_DIR, 'templates')],
            ),
        ],
    },
}]

django.template.loaders.app_directories.Loader

class app_directories.Loader
Loads templates from Django apps on the filesystem. For each app inINSTALLED_APPS, the loader looks for a templatessubdirectory. If the directory exists, Django looks for templates in there.

This means you can store templates with your individual apps. This alsomakes it easy to distribute Django apps with default templates.

For example, for this setting:

INSTALLED_APPS = ['myproject.polls', 'myproject.music']

…then get_template('foo.html') will look for foo.html in thesedirectories, in this order:

/path/to/myproject/polls/templates/
/path/to/myproject/music/templates/
… and will use the one it finds first.

The order of INSTALLED_APPS is significant! For example, if youwant to customize the Django admin, you might choose to override thestandard admin/basesite.html template, from django.contrib.admin,with your own admin/base_site.html in myproject.polls. You mustthen make sure that your myproject.polls comes _beforedjango.contrib.admin in INSTALLED_APPS, otherwisedjango.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 atemplates subdirectory.

You can enable this loader simply by settingAPP_DIRS to True:

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

django.template.loaders.cached.Loader

class cached.Loader
By default (when DEBUG is True), the template system readsand compiles your templates every time they're rendered. While the Djangotemplate system is quite fast, the overhead from reading and compilingtemplates can add up.

You configure the cached template loader with a list of other loaders thatit should wrap. The wrapped loaders are used to locate unknown templateswhen they're first encountered. The cached loader then stores the compiledTemplate in memory. The cached Template instance is returned forsubsequent requests to load the same template.

This loader is automatically enabled if OPTIONS['loaders'] isn't specified and OPTIONS['debug'] is False (the latter option defaults to the valueof DEBUG).

You can also enable template caching with some custom template loadersusing settings like this:

TEMPLATES = [{
    'BACKEND': 'django.template.backends.django.DjangoTemplates',
    'DIRS': [os.path.join(BASE_DIR, 'templates')],
    'OPTIONS': {
        'loaders': [
            ('django.template.loaders.cached.Loader', [
                'django.template.loaders.filesystem.Loader',
                'django.template.loaders.app_directories.Loader',
                'path.to.custom.Loader',
            ]),
        ],
    },
}]

注解

All of the built-in Django template tags are safe to use with thecached loader, but if you're using custom template tags that come fromthird party packages, or that you wrote yourself, you should ensurethat the Node implementation for each tag is thread-safe. For moreinformation, see template tag thread safety considerations.

django.template.loaders.locmem.Loader

class locmem.Loader
Loads templates from a Python dictionary. This is useful for testing.

This loader takes a dictionary of templates as its first argument:

TEMPLATES = [{
    'BACKEND': 'django.template.backends.django.DjangoTemplates',
    'OPTIONS': {
        'loaders': [
            ('django.template.loaders.locmem.Loader', {
                'index.html': 'content here',
            }),
        ],
    },
}]

This loader is disabled by default.

Django uses the template loaders in order according to the 'loaders'option. It uses each loader until a loader finds a match.

Custom loaders

It's possible to load templates from additional sources using custom templateloaders. Custom Loader classes should inherit fromdjango.template.loaders.base.Loader and define the get_contents() andget_template_sources() methods.

Loader methods

class Loader[源代码]
Loads templates from a given source, such as the filesystem or a database.
- gettemplate_sources(_template_name)[源代码]
- A method that takes a template_name and yieldsOrigin instances for each possiblesource.

For example, the filesystem loader may receive 'index.html' as atemplate_name argument. This method would yield origins for thefull path of index.html as it appears in each template directorythe loader looks at.

The method doesn't need to verify that the template exists at a givenpath, but it should ensure the path is valid. For instance, thefilesystem loader makes sure the path lies under a valid templatedirectory.

getcontents(_origin)
Returns the contents for a template given aOrigin instance.

This is where a filesystem loader would read contents from thefilesystem, or a database loader would read from the database. If amatching template doesn't exist, this should raise aTemplateDoesNotExist error.

gettemplate(_template_name, skip=None)[源代码]
Returns a Template object for a given template_name by loopingthrough results from get_template_sources() and callingget_contents(). This returns the first matching template. If notemplate is found, TemplateDoesNotExist israised.

The optional skip argument is a list of origins to ignore whenextending templates. This allow templates to extend other templates ofthe same name. It also used to avoid recursion errors.

In general, it is enough to define get_template_sources() andget_contents() for custom template loaders. get_template()will usually not need to be overridden.

Building your own

For examples, read the source code for Django's built-in loaders.

Template origin

Templates have an origin containing attributes depending on the sourcethey are loaded from.

class Origin(name, template_name=None, loader=None)[源代码]
- name
- The path to the template as returned by the template loader.For loaders that read from the file system, this is the fullpath to the template.

If the template is instantiated directly rather than through atemplate loader, this is a string value of <unknown_source>.

template_name
The relative path to the template as passed into thetemplate loader.

If the template is instantiated directly rather than through atemplate loader, this is None.

loader
The template loader instance that constructed this Origin.

If the template is instantiated directly rather than through atemplate loader, this is None.

django.template.loaders.cached.Loader requires all of itswrapped loaders to set this attribute, typically by instantiatingthe Origin with loader=self.