模板引擎的支持Link to this heading#
\n配置Link to this heading#
\nTemplates engines are configured with the TEMPLATES setting. It's a\nlist of configurations, one for each engine. The default value is empty. The\nsettings.py generated by the startproject command defines a\nmore useful value:
TEMPLATES = [\n {\n 'BACKEND': 'django.template.backends.django.DjangoTemplates',\n 'DIRS': [],\n 'APP_DIRS': True,\n 'OPTIONS': {\n # ... some options here ...\n },\n },\n]\nBACKEND is a dotted Python path to a template\nengine class implementing Django's template backend API. The built-in backends\nare django.template.backends.django.DjangoTemplates and\ndjango.template.backends.jinja2.Jinja2.
Since most engines load templates from files, the top-level configuration for\neach engine contains two common settings:
\n- \n
DIRSdefines a list of directories where the\nengine should look for template source files, in search order. \nAPP_DIRStells whether the engine should\nlook for templates inside installed applications. Each backend defines a\nconventional name for the subdirectory inside applications where its\ntemplates should be stored. \n
While uncommon, it's possible to configure several instances of the same\nbackend with different options. In that case you should define a unique\nNAME for each engine.
OPTIONS contains backend-specific settings.
UsageLink to this heading#
\nThe django.template.loader module defines two functions to load templates.
- \n
- \nget_template(template_name, using=None)Link to this definition# \n
This function loads the template with the given name and returns a\n
\nTemplateobject.The exact type of the return value depends on the backend that loaded the\ntemplate. Each backend has its own
\nTemplateclass.
\nget_template()tries each template engine in order until one succeeds.\nIf the template cannot be found, it raises\nTemplateDoesNotExist. If the template is found but\ncontains invalid syntax, it raises\nTemplateSyntaxError.How templates are searched and loaded depends on each engine's backend and\nconfiguration.
\nIf you want to restrict the search to a particular template engine, pass\nthe engine's
\nNAMEin theusingargument.
- \n
- \nselect_template(template_name_list, using=None)Link to this definition# \n
\nselect_template()is just likeget_template(), except it takes a\nlist of template names. It tries each name in order and returns the first\ntemplate that exists.
If loading a template fails, the following two exceptions, defined in\ndjango.template, may be raised:
- \n
- \nexception TemplateDoesNotExist(msg, tried=None, backend=None, chain=None)Link to this definition# \n
This exception is raised when a template cannot be found. It accepts the\nfollowing optional arguments for populating the template postmortem on the debug page:
\n- \n
backendThe template backend instance from which the exception originated.
\n \ntriedA list of sources that were tried when finding the template. This is\nformatted as a list of tuples containing
\n(origin, status), where\noriginis an origin-like object and\nstatusis a string with the reason the template wasn't found. \nchainA list of intermediate
\nTemplateDoesNotExist\nexceptions raised when trying to load a template. This is used by\nfunctions, such asget_template(), that\ntry to load a given template from multiple engines. \n
- \n
- \nexception TemplateSyntaxError(msg)Link to this definition# \n
This exception is raised when a template was found but contains errors.
\n
Template objects returned by get_template() and select_template()\nmust provide a render() method with the following signature:
- \n
- \nTemplate.render(context=None, request=None)Link to this definition# \n
Renders this template with a given context.
\nIf
\ncontextis provided, it must be adict. If it isn't\nprovided, the engine will render the template with an empty context.If
\nrequestis provided, it must be anHttpRequest.\nThen the engine must make it, as well as the CSRF token, available in the\ntemplate. How this is achieved is up to each backend.
Here's an example of the search algorithm. For this example the\nTEMPLATES setting is:
TEMPLATES = [\n {\n 'BACKEND': 'django.template.backends.django.DjangoTemplates',\n 'DIRS': [\n '/home/html/example.com',\n '/home/html/default',\n ],\n },\n {\n 'BACKEND': 'django.template.backends.jinja2.Jinja2',\n 'DIRS': [\n '/home/html/jinja2',\n ],\n },\n]\nIf you call get_template('story_detail.html'), here are the files Django\nwill look for, in order:
- \n
/home/html/example.com/story_detail.html('django'engine) \n/home/html/default/story_detail.html('django'engine) \n/home/html/jinja2/story_detail.html('jinja2'engine) \n
If you call select_template(['story_253_detail.html', 'story_detail.html']),\nhere's what Django will look for:
- \n
/home/html/example.com/story_253_detail.html('django'engine) \n/home/html/default/story_253_detail.html('django'engine) \n/home/html/jinja2/story_253_detail.html('jinja2'engine) \n/home/html/example.com/story_detail.html('django'engine) \n/home/html/default/story_detail.html('django'engine) \n/home/html/jinja2/story_detail.html('jinja2'engine) \n
When Django finds a template that exists, it stops looking.
\n\nIt's possible -- and preferable -- to organize templates in subdirectories\ninside each directory containing templates. The convention is to make a\nsubdirectory for each Django app, with subdirectories within those\nsubdirectories as needed.
\nDo this for your own sanity. Storing all templates in the root level of a\nsingle directory gets messy.
\nTo load a template that's within a subdirectory, just use a slash, like so:
\nget_template('news/story_detail.html')\nUsing the same TEMPLATES option as above, this will attempt to load\nthe following templates:
- \n
/home/html/example.com/news/story_detail.html('django'engine) \n/home/html/default/news/story_detail.html('django'engine) \n/home/html/jinja2/news/story_detail.html('jinja2'engine) \n
此外，为了减少加载和渲染模板的重复性，Django 提供了一个自动处理的快捷函数。
\n- \n
- \nrender_to_string(template_name, context=None, request=None, using=None)Link to this definition# \n
\nrender_to_string()加载一个模板get_template()，并立即调用它的render()方法。它需要下面的参数。- \n
template_name加载和呈现模板的名称。如果是模板名称列表，Django 使用
\nselect_template()，而不是get_template()找到模板。 \ncontext
\ndict用作模板的渲染上下文。 \nrequest可选项
\nHttpRequest在模板的渲染过程中可用。 \nusing可选的模板引擎
\nNAME。对模板的搜索将限于该引擎。 \n
使用实例：
\n\nfrom django.template.loader import render_to_string\nrendered = render_to_string('my_template.html', {'foo': 'bar'})\n
还可以参看 render() 快捷函数，它调用 render_to_string() ，并将结果提供给 HttpResponse ，适合从视图返回。
最后，您可以直接使用配置好的引擎：
\n- \n
- \nenginesLink to this definition# \n
模板引擎可在
\ndjango.template.engines中使用：\nfrom django.template import engines\n\ndjango_engine = engines['django']\ntemplate = django_engine.from_string("Hello {{ name }}!")\n在这个例子中，查找关键字“django”是引擎的
\nNAME。
内置后端Link to this heading#
\n- \n
- \nclass DjangoTemplatesLink to this definition# \n
设置 BACKEND 为 'django.template.backends.django.DjangoTemplates'，以配置 Django 模板引擎。
When APP_DIRS is True, DjangoTemplates\nengines look for templates in the templates subdirectory of installed\napplications. This generic name was kept for backwards-compatibility.
DjangoTemplates engines accept the following OPTIONS:
- \n
\n'autoescape': a boolean that controls whether HTML autoescaping is\nenabled.It defaults to
\n\nTrue. \n
\n'context_processors': a list of dotted Python paths to callables that\nare used to populate the context when a template is rendered with a request.\nThese callables take a request object as their argument and return a\ndictof items to be merged into the context.It defaults to an empty list.
\nSee
\nRequestContextfor more information. \n
\n'debug': a boolean that turns on/off template debug mode. If it is\nTrue, the fancy error page will display a detailed report for any\nexception raised during template rendering. This report contains the\nrelevant snippet of the template with the appropriate line highlighted.It defaults to the value of the
\nDEBUGsetting. \n
\n'loaders': a list of dotted Python paths to template loader classes.\nEachLoaderclass knows how to import templates from a particular\nsource. Optionally, a tuple can be used instead of a string. The first item\nin the tuple should be theLoaderclass name, and subsequent items are\npassed to theLoaderduring initialization.The default depends on the values of
\nDIRSand\nAPP_DIRS.See Loader types for details.
\n \n
\n'string_if_invalid': the output, as a string, that the template system\nshould use for invalid (e.g. misspelled) variables.It defaults to an empty string.
\nSee How invalid variables are handled for details.
\n \n
\n'file_charset': the charset used to read template files on disk.It defaults to the value of
\nFILE_CHARSET. \n
\n'libraries': A dictionary of labels and dotted Python paths of template\ntag modules to register with the template engine. This can be used to add\nnew libraries or provide alternate labels for existing ones. For example:\nOPTIONS={\n 'libraries': {\n 'myapp_tags': 'path.to.myapp.tags',\n 'admin.urls': 'django.contrib.admin.templatetags.admin_urls',\n },\n}\nLibraries can be loaded by passing the corresponding dictionary key to\nthe
\n{% load %}tag. \n
\n'builtins': A list of dotted Python paths of template tag modules to\nadd to built-ins. For example:\nOPTIONS={\n 'builtins': ['myapp.builtins'],\n}\nTags and filters from built-in libraries can be used without first calling\nthe
\n{% load %}tag. \n
- \n
- \nclass Jinja2Link to this definition# \n
Requires Jinja2 to be installed:
\n$ pip install Jinja2\nSet BACKEND to\n'django.template.backends.jinja2.Jinja2' to configure a Jinja2 engine.
When APP_DIRS is True, Jinja2 engines\nlook for templates in the jinja2 subdirectory of installed applications.
The most important entry in OPTIONS is\n'environment'. It's a dotted Python path to a callable returning a Jinja2\nenvironment. It defaults to 'jinja2.Environment'. Django invokes that\ncallable and passes other options as keyword arguments. Furthermore, Django\nadds defaults that differ from Jinja2's for a few options:
- \n
'autoescape':True\n- \n
'auto_reload':settings.DEBUG\n'undefined':DebugUndefined if settings.DEBUG else Undefined\n
Jinja2 engines also accept the following OPTIONS:
- \n
\n'context_processors': a list of dotted Python paths to callables that\nare used to populate the context when a template is rendered with a request.\nThese callables take a request object as their argument and return a\ndictof items to be merged into the context.It defaults to an empty list.
\n\n \n
The default configuration is purposefully kept to a minimum. If a template is\nrendered with a request (e.g. when using render()),\nthe Jinja2 backend adds the globals request, csrf_input, and\ncsrf_token to the context. Apart from that, this backend doesn't create a\nDjango-flavored environment. It doesn't know about Django filters and tags.\nIn order to use Django-specific APIs, you must configure them into the\nenvironment.
For example, you can create myproject/jinja2.py with this content:
from django.contrib.staticfiles.storage import staticfiles_storage\nfrom django.urls import reverse\n\nfrom jinja2 import Environment\n\n\ndef environment(**options):\n env = Environment(**options)\n env.globals.update({\n 'static': staticfiles_storage.url,\n 'url': reverse,\n })\n return env\nand set the 'environment' option to 'myproject.jinja2.environment'.
Then you could use the following constructs in Jinja2 templates:
\n<img src="{{ static('path/to/company-logo.png') }}" alt="Company Logo">\n\n<a href="{{ url('admin:index') }}">Administration</a>\nThe concepts of tags and filters exist both in the Django template language\nand in Jinja2 but they're used differently. Since Jinja2 supports passing\narguments to callables in templates, many features that require a template tag\nor filter in Django templates can be achieved simply by calling a function in\nJinja2 templates, as shown in the example above. Jinja2's global namespace\nremoves the need for template context processors. The Django template language\ndoesn't have an equivalent of Jinja2 tests.
\nCustom backendsLink to this heading#
\nHere's how to implement a custom template backend in order to use another\ntemplate system. A template backend is a class that inherits\ndjango.template.backends.base.BaseEngine. It must implement\nget_template() and optionally from_string(). Here's an example for a\nfictional foobar template library:
from django.template import TemplateDoesNotExist, TemplateSyntaxError\nfrom django.template.backends.base import BaseEngine\nfrom django.template.backends.utils import csrf_input_lazy, csrf_token_lazy\n\nimport foobar\n\n\nclass FooBar(BaseEngine):\n\n # Name of the subdirectory containing the templates for this engine\n # inside an installed application.\n app_dirname = 'foobar'\n\n def __init__(self, params):\n params = params.copy()\n options = params.pop('OPTIONS').copy()\n super().__init__(params)\n\n self.engine = foobar.Engine(**options)\n\n def from_string(self, template_code):\n try:\n return Template(self.engine.from_string(template_code))\n except foobar.TemplateCompilationFailed as exc:\n raise TemplateSyntaxError(exc.args)\n\n def get_template(self, template_name):\n try:\n return Template(self.engine.get_template(template_name))\n except foobar.TemplateNotFound as exc:\n raise TemplateDoesNotExist(exc.args, backend=self)\n except foobar.TemplateCompilationFailed as exc:\n raise TemplateSyntaxError(exc.args)\n\n\nclass Template:\n\n def __init__(self, template):\n self.template = template\n\n def render(self, context=None, request=None):\n if context is None:\n context = {}\n if request is not None:\n context['request'] = request\n context['csrf_input'] = csrf_input_lazy(request)\n context['csrf_token'] = csrf_token_lazy(request)\n return self.template.render(context)\nSee DEP 182 for more information.
\nDebug integration for custom enginesLink to this heading#
\nThe Django debug page has hooks to provide detailed information when a template\nerror arises. Custom template engines can use these hooks to enhance the\ntraceback information that appears to users. The following hooks are available:
\nTemplate postmortemLink to this heading#
\nThe postmortem appears when TemplateDoesNotExist is\nraised. It lists the template engines and loaders that were used when trying\nto find a given template. For example, if two Django engines are configured,\nthe postmortem will appear like:
![\"/zh-hans/2.0/_images/postmortem.png\"](\"/zh-hans/2.0/_images/postmortem.png\")
\nCustom engines can populate the postmortem by passing the backend and\ntried arguments when raising TemplateDoesNotExist.\nBackends that use the postmortem should specify an origin on the template object.
Contextual line informationLink to this heading#
\nIf an error happens during template parsing or rendering, Django can display\nthe line the error happened on. For example:
\n![\"/zh-hans/2.0/_images/template-lines.png\"](\"/zh-hans/2.0/_images/template-lines.png\")
\nCustom engines can populate this information by setting a template_debug\nattribute on exceptions raised during parsing and rendering. This attribute\nis a dict with the following values:
- \n
'name': The name of the template in which the exception occurred. \n'message': The exception message. \n'source_lines': The lines before, after, and including the line the\nexception occurred on. This is for context, so it shouldn't contain more than\n20 lines or so. \n'line': The line number on which the exception occurred. \n'before': The content on the error line before the token that raised the\nerror. \n'during': The token that raised the error. \n'after': The content on the error line after the token that raised the\nerror. \n'total': The number of lines insource_lines. \n'top': The line number wheresource_linesstarts. \n'bottom': The line number wheresource_linesends. \n
Given the above template error, template_debug would look like:
{\n 'name': '/path/to/template.html',\n 'message': "Invalid block tag: 'syntax'",\n 'source_lines': [\n (1, 'some\\n'),\n (2, 'lines\\n'),\n (3, 'before\\n'),\n (4, 'Hello {% syntax error %} {{ world }}\\n'),\n (5, 'some\\n'),\n (6, 'lines\\n'),\n (7, 'after\\n'),\n (8, ''),\n ],\n 'line': 4,\n 'before': 'Hello ',\n 'during': '{% syntax error %}',\n 'after': ' {{ world }}\\n',\n 'total': 9,\n 'bottom': 9,\n 'top': 1,\n}\nOrigin API and 3rd-party integrationLink to this heading#
\nDjango templates have an Origin object available\nthrough the template.origin attribute. This enables debug information to be\ndisplayed in the template postmortem, as well as\nin 3rd-party libraries, like the Django Debug Toolbar.
Custom engines can provide their own template.origin information by\ncreating an object that specifies the following attributes:
- \n
'name': The full path to the template. \n'template_name': The relative path to the template as passed into the\nthe template loading methods. \n'loader_name': An optional string identifying the function or class used\nto load the template, e.g.django.template.loaders.filesystem.Loader. \n