テンプレートエンジンのサポートLink to this heading#
\n設定Link to this heading#
\nテンプレートエンジンは、TEMPLATES で設定できます。ここには、各エンジンに対する設定のリストを設定します。デフォルト値は空リストです。startproject コマンドで生成された settings.py には、以下のように便利な値がいくつか設定されます。
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 は、Django テンプレートバックエンド API を実装したテンプレートエンジンのクラスへの、ドット区切りの Python path です。ビルトインのバックエンドは、django.template.backends.django.DjangoTemplates と django.template.backends.jinja2.Jinja2 です。
ほとんどのエンジンはファイルからテンプレートを読み込むため、各エンジンのトップレベルの設定には次の2つの設定があります。
\n- \n
DIRSには、エンジンがテンプレートのソースファイルを検索するディレクトリのリストを、検索順に定義します。 \nAPP_DIRSには、エンジンがインストールしたアプリケーション内のテンプレートを検索するべきかどうかを指定します。各バックエンドは、アプリケーション内でテンプレートを保存するべきサブディレクトリ名として、慣習的な名前を定義しています。 \n
めったにないことですが、同じバックエンドの複数のインスタンスを、オプションだけ変えて設定することも可能です。その場合、各エンジンに対して、NAME にユニークな名前を設定しなければなりません。
OPTIONS には、バックエンド特有の設定を書きます。
使い方Link to this heading#
\ndjango.template.loader モジュールは、テンプレートを読み込むための2つの関数を定義しています。
- \n
- \nget_template(template_name, using=None)Link to this definition# \n
この関数は、指定した名前のテンプレートを読み込み、
\nTemplateオブジェクトを返します。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()はget_template()に似ていますが、1つのテンプレート名の代わりにテンプレート名のリストを取ります。各名前のテンプレートを順番に探し、最初に見つかったテンプレートを返します。
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
与えられたコンテキストを用いて、このテンプレートをレンダリングします。
\n
\ncontextを指定する場合は、dictでなければなりません。もし指定しなければ、エンジンは空のコンテキストでレンダリングします。
\nrequestを指定する場合は、HttpRequestでなければなりません。テンプレートエンジンは、テンプレート内では、このインスタンスと CSRF トークンを使用できるようにする必要があります。そのための実装はバックエンドに依存します。
以下に、検索アルゴリズムの例を示します。この例の場合、TEMPLATES 設定は次のようになっています。
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]\nget_template('story_detail.html') を呼び出した場合、Django は次の順番にファイルを探します。
- \n
/home/html/example.com/story_detail.html('django'エンジン) \n/home/html/default/story_detail.html('django'エンジン) \n/home/html/jinja2/story_detail.html('jinja2'エンジン) \n
select_template(['story_253_detail.html', 'story_detail.html']) を呼び出した場合、Djangoは以下の順番にファイルを探します。
- \n
/home/html/example.com/story_253_detail.html('django'エンジン) \n/home/html/default/story_253_detail.html('django'エンジン) \n/home/html/jinja2/story_253_detail.html('jinja2'エンジン) \n/home/html/example.com/story_detail.html('django'エンジン) \n/home/html/default/story_detail.html('django'エンジン) \n/home/html/jinja2/story_detail.html('jinja2'エンジン) \n
Django がテンプレートを発見したら、その時点で探索は停止します。
\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
In addition, to cut down on the repetitive nature of loading and rendering\ntemplates, Django provides a shortcut function which automates the process.
\n- \n
- \nrender_to_string(template_name, context=None, request=None, using=None)Link to this definition# \n
\nrender_to_string()loads a template likeget_template()and\ncalls itsrender()method immediately. It takes the following\narguments.- \n
template_nameThe name of the template to load and render. If it's a list of template\nnames, Django uses
\nselect_template()instead of\nget_template()to find the template. \ncontextA
\ndictto be used as the template's context for rendering. \nrequestAn optional
\nHttpRequestthat will be available\nduring the template's rendering process. \nusingAn optional template engine
\nNAME. The\nsearch for the template will be restricted to that engine. \n
Usage example:
\n\nfrom django.template.loader import render_to_string\nrendered = render_to_string('my_template.html', {'foo': 'bar'})\n
See also the render() shortcut which calls\nrender_to_string() and feeds the result into an\nHttpResponse suitable for returning from a view.
Finally, you can use configured engines directly:
\n- \n
- \nenginesLink to this definition# \n
Template engines are available in
\ndjango.template.engines:\nfrom django.template import engines\n\ndjango_engine = engines['django']\ntemplate = django_engine.from_string("Hello {{ name }}!")\nThe lookup key —
\n'django'in this example — is the engine's\nNAME.
Built-in backendsLink to this heading#
\n- \n
- \nclass DjangoTemplatesLink to this definition# \n
Set BACKEND to\n'django.template.backends.django.DjangoTemplates' to configure a Django\ntemplate engine.
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:
\nLinux / macOS
$ pip install Jinja2\nWindows
...\\> 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.templatetags.static import static\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': static,\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.
\nカスタムのバックエンドLink 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)\n詳しい情報は DEP 182 を参照してください。
\nカスタムエンジンに対するデバッグの統合Link 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:
\nテンプレートの死体解剖 (postmortem)Link to this heading#
\nテンプレートの死体解剖を行うのは、TemplateDoesNotExist 例外が発生した時です。例外には、使用されたテンプレートエンジンとテンプレートローダーのリストが含まれているので、与えられたテンプレートを見つけることができます。たとえば、2つの Django エンジンが設定されている場合、死体解剖の結果は次のように表示されます。
![\"/ja/2.1/_images/postmortem.png\"](\"/ja/2.1/_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.
コンテキストの行情報Link to this heading#
\nIf an error happens during template parsing or rendering, Django can display\nthe line the error happened on. For example:
\n![\"/ja/2.1/_images/template-lines.png\"](\"/ja/2.1/_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 と サードパーティとの統合Link 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': テンプレートへのフルパス。 \n'template_name': テンプレートの読み込みメソッドに渡されるテンプレートへの相対パス。 \n'loader_name': テンプレートの読み込みに使われる関数またはクラスを識別するためのオプションの文字列。例:django.template.loaders.filesystem.Loader。 \n