カスタムテンプレートバックエンド
カスタムバックエンド
別のテンプレートシステムを使用するためにカスタムテンプレートバックエンドを実装する方法は次のとおりです。 テンプレートバックエンドは、django.template.backends.base.BaseEngine
を継承するクラスです。 get_template()
およびオプションでfrom_string()
を実装する必要があります。 架空のfoobar
テンプレートライブラリの例を次に示します。
from django.template import TemplateDoesNotExist, TemplateSyntaxError
from django.template.backends.base import BaseEngine
from django.template.backends.utils import csrf_input_lazy, csrf_token_lazy
import foobar
class FooBar(BaseEngine):
# Name of the subdirectory containing the templates for this engine
# inside an installed application.
app_dirname = 'foobar'
def __init__(self, params):
params = params.copy()
options = params.pop('OPTIONS').copy()
super().__init__(params)
self.engine = foobar.Engine(**options)
def from_string(self, template_code):
try:
return Template(self.engine.from_string(template_code))
except foobar.TemplateCompilationFailed as exc:
raise TemplateSyntaxError(exc.args)
def get_template(self, template_name):
try:
return Template(self.engine.get_template(template_name))
except foobar.TemplateNotFound as exc:
raise TemplateDoesNotExist(exc.args, backend=self)
except foobar.TemplateCompilationFailed as exc:
raise TemplateSyntaxError(exc.args)
class Template:
def __init__(self, template):
self.template = template
def render(self, context=None, request=None):
if context is None:
context = {}
if request is not None:
context['request'] = request
context['csrf_input'] = csrf_input_lazy(request)
context['csrf_token'] = csrf_token_lazy(request)
return self.template.render(context)
詳細については、 DEP 182 を参照してください。
カスタムエンジンのデバッグ統合
Djangoデバッグページには、テンプレートエラーが発生したときに詳細情報を提供するためのフックがあります。 カスタムテンプレートエンジンは、これらのフックを使用して、ユーザーに表示されるトレースバック情報を強化できます。 次のフックを使用できます。
テンプレートの事後分析
TemplateDoesNotExist が発生すると、事後分析が表示されます。 特定のテンプレートを検索するときに使用されたテンプレートエンジンとローダーが一覧表示されます。 たとえば、2つのDjangoエンジンが構成されている場合、事後分析は次のように表示されます。
../_images/postmortem.png
カスタムエンジンは、 TemplateDoesNotExist を発生させるときに、backend
およびtried
引数を渡すことにより、事後分析を行うことができます。 事後分析を使用するバックエンドは、テンプレートオブジェクトの起点を指定する必要があります。
コンテキストライン情報
テンプレートの解析またはレンダリング中にエラーが発生した場合、Djangoはエラーが発生した行を表示できます。 例えば:
../_images/template-lines.png
カスタムエンジンは、解析およびレンダリング中に発生した例外にtemplate_debug
属性を設定することにより、この情報を取り込むことができます。 この属性は、次の値を持つdict
です。
'name'
:例外が発生したテンプレートの名前。'message'
:例外メッセージ。'source_lines'
:例外が発生した行の前、後、およびそれを含む行。 これはコンテキスト用であるため、20行程度を超えないようにする必要があります。'line'
:例外が発生した行番号。'before'
:エラーを発生させたトークンの前のエラー行の内容。'during'
:エラーを発生させたトークン。'after'
:エラーを発生させたトークンの後のエラー行の内容。'total'
:source_lines
の行数。'top'
:source_lines
が始まる行番号。'bottom'
:source_lines
が終了する行番号。
上記のテンプレートエラーを考えると、template_debug
は次のようになります。
{
'name': '/path/to/template.html',
'message': "Invalid block tag: 'syntax'",
'source_lines': [
(1, 'some\n'),
(2, 'lines\n'),
(3, 'before\n'),
(4, 'Hello {% syntax error %} {{ world }}\n'),
(5, 'some\n'),
(6, 'lines\n'),
(7, 'after\n'),
(8, ''),
],
'line': 4,
'before': 'Hello ',
'during': '{% syntax error %}',
'after': ' {{ world }}\n',
'total': 9,
'bottom': 9,
'top': 1,
}
OriginAPIとサードパーティの統合
Djangoテンプレートには、template.origin
属性を介して使用できる Origin オブジェクトがあります。 これにより、デバッグ情報をテンプレートの事後分析や、 Djangoデバッグツールバーなどのサードパーティライブラリに表示できます。
カスタムエンジンは、次の属性を指定するオブジェクトを作成することにより、独自のtemplate.origin
情報を提供できます。
'name'
:テンプレートへのフルパス。'template_name'
:テンプレートの読み込みメソッドに渡されるテンプレートへの相対パス。'loader_name'
:テンプレートのロードに使用される関数またはクラスを識別するオプションの文字列。django.template.loaders.filesystem.Loader
。