Python プログラマのための Django テンプレート言語ガイド

無効な値の扱い

基本的に、変数が存在しなければ、 テンプレートシステムは TEMPLATE_STRING_IF_INVALID の設定値を挿入します。この値のデフォルトは '' (空文字列) です。

無効な値に対してフィルタが適用されるのは、 TEMPLATE_STRING_IF_INVALID の値が '' に設定されている場合だけです。 TEMPLATE_STRING_IF_INVALID が '' 以外の値になっていると、フィルタは無視されます。

ただし、 if, for, regroup といったテンプレートタグの中では、少 し違った挙動になります。これらのテンプレートタグ中では、無効な値は None であると解釈されます。また、これらのテンプレートタグ中のフィルタは、無効な 値に対しも常に適用されます。

TEMPLATE_STRING_IF_INVALID にフォーマット指示文字の '%s' が入ってい る場合、 '%s' は不正な変数の変数名で置き換えられます。

django.core.context_processors.auth

このプロセッサが TEMPLATE_CONTEXT_PROCESSORS にある場合、以下の 3 つの 変数が RequestContext に入ります:

• user -- 現在ログインしているユーザを表す auth.User インスタン ス (クライアントがログインしていない場合には AnonymousUser インス タンス) です。 ユーザ認証のドキュメント を参照してください。

• messages -- 現在ログインしているユーザ宛の (文字列の) メッセージ のリストです。舞台裏では、この変数を参照するたびに request.user.get_and_delete_messaages() を呼び出しています。 request.user.get_and_delete_messaages() は、ユーザ宛の全メッセー ジを集めて返し、 Message オブジェクトを削除します。

  メッセージは user.message_set.create で設定します。詳しくは メッセージのドキュメント を参照してください。

• perms -- 現在ログインしているユーザが有しているパーミッションを表 す、 django.core.context_processors.PermWrapper のインスタンスで す。 パーミッションのドキュメント を参照してください。

django.core.context_processors.debug

このプロセッサが TEMPLATE_CONTEXT_PROCESSORS にある場合、以下の 2 つの 変数が RequestContext に入ります。ただし、 DEBUG の設定が True で、リクエストの IP アドレス (request.META['REMOTE_ADDR']) が INTERNAL_IPS 設定に入っている場合だけです:

• debug -- True です。 DEBUG モードかどうかをテストするのに 使えます。
• sql_queries -- {'sql': ..., 'time': ...} 辞書のリストです。 このリストはリクエスト処理中に実行された SQL クエリと、それにかかった 時間を表しています。リストはクエリの実行順にならんでいます。

django.core.context_processors.i18n

このプロセッサが TEMPLATE_CONTEXT_PROCESSORS にある場合、以下の 2 つの 変数が RequestContext に入ります:

• LANGUAGES -- LANGUAGES 設定 の値です。
• LANGUAGE_CODE -- request.LANGUAGE_CODE が存在する場合、その値 です。値がなければ LANGUAGE_CODE 設定 の値になります。

詳しくは 国際化のドキュメント を参照してください。

django.core.context_processors.media

開発版の Django で新たに登場した機能です

TEMPLATE_CONTEXT_PROCESSORS にこのコンテキストプロセッサを入れると、 RequestContext に MEDIA_URL というコンテキスト変数が入ります。 MEDIA_URL には MEDIA_URL 設定 の値が入っています。

django.core.context_processors.request

このプロセッサが TEMPLATE_CONTEXT_PROCESSORS にある場合、変数 request が RequestContext に入ります。この変数は現在の HttpRequest オブジェクト を表現します。このプロセッサはデフォルトでは有 効でないので注意してください。利用したければ有効にせねばなりません。

コンテキストプロセッサを自作する

コンテキストプロセッサのインタフェースはとても簡単です。コンテキストプロセッ サは単なる Python の関数で、 HttpRequest オブジェクトを引数にとり、 テンプレートコンテキストに追加できるような辞書を返します。コンテキストプロ セッサは、 必ず 辞書型を返さねばなりません。

自分のコードベースに自作のコンテキストプロセッサを入れてもかまいません。 Django 側からは、自作のコンテキストプロセッサを TEMPLATE_CONTEXT_PROCESSORS 設定で指定するようにしてください。

TEMPLATE_DIRS 設定

設定ファイル中で、 TEMPLATE_DIRS 設定を使ってどのディレクトリにテンプレー トが収められているかを指定してください。この値は文字列のリストかタプルで指 定します。文字列にはテンプレートディレクトリへの完全なパスを指定せねばなり ません。例えば:

TEMPLATE_DIRS = (
    "/home/html/templates/lawrence.com",
    "/home/html/templates/default",
)

Web サーバがテンプレートディレクトリの中身を読みだせる限り、テンプレートは どこにでも置けます。拡張子はなんでもよく、 .html でも .txt でも かまいませんし、拡張子を付けなくてもかまいません。

Windows を使っている場合でも、パスは Unix 形式のスラッシュを使った表記法で 指定せねばならないので注意して下さい。

Python API

Django でファイルからテンプレートを読み出すには二通りの方法があります:

django.template.loader.get_template(template_name)

get_template は、指定した名前のテンプレートに対応したコンパイル済み のテンプレート (Template オブジェクト) を返します。テンプレートが存 在しなければ django.template.TemplateDoesNotExist を送出します。

django.template.loader.select_template(template_name_list)

select_template は get_template と同じです。ただし、テンプレー ト名のリストを引数にとります。リストの中で最初に見つかったテンプレート を返します。

例えば get_template('story_detail.html') を呼び出した場合、前述のような TEMPLATE_DIRS の設定をしていれば、Django は以下のような順番でテンプレー トファイルを探します:

• /home/html/templates/lawrence.com/story_detail.html
• /home/html/templates/default/story_detail.html

select_template(['story_253_detail.html', 'story_detail.html']) なら、 以下の順で探します:

• /home/html/templates/lawrence.com/story_253_detail.html
• /home/html/templates/default/story_253_detail.html
• /home/html/templates/lawrence.com/story_detail.html
• /home/html/templates/default/story_detail.html

テンプレートが見つかった時点で Django は検索を停止します。

サブディレクトリの使用

テンプレートディレクトリを複数のサブディレクトリで構成するのは可能ですし、 お勧めでもあります。慣習的には各 Django アプリケーション毎にサブディレク トリを作成します。必要に応じてさらにサブディレクトリを作成します。

自分の正気を保つためにもぜひテンプレートを階層化しましょう。一つのディレク トリのルートレベルに全てのテンプレートを保存するのは、だらしないことこの上 ありません。

サブディレクトリ下にあるテンプレートをロードするには、以下のようにスラッシュ を使って指定します:

get_template('news/story_detail.html')

この例の get_template() は、上の TEMPLATE_DIRS と同じ設定を使った場 合、以下の順番でテンプレートをロードしようと試みます:

• /home/html/templates/lawrence.com/news/story_detail.html
• /home/html/templates/default/news/story_detail.html

Loader 型

デフォルトでは、 Django はファイルシステムベースのテンプレートローダを使っ ていますが、 Django には他のテンプレートローダも付属しており、その他のデー タソースからテンプレートをロードできるようになっています。

ファイルシステムベース以外のテンプレートローダはデフォルトでは無効化されて いますが、 TEMPLATE_LOADERS 設定を編集して有効にできます。 TEMPLATE_LOADERS は文字列のタプルで、各文字列がテンプレートローダを表し ます。組み込みのテンプレートローダを以下に示します:

django.template.loaders.filesystem.load_template_source

TEMPLATE_DIRS の設定に従って、ファイルシステムからテンプレートをロー ドします。

django.template.loaders.app_directories.load_template_source

ファイルシステム上の Django アプリケーションからテンプレートをロードし ます。このローダは INSTALLED_APPS の各アプリケーションについて templates サブディレクトリを探します。ディレクトリが存在すれば、 Django はその中からテンプレートを探します。

これはすなわち、個々のアプリケーションにテンプレートを保存しておけると いうことです。このローダを使うと、 Django アプリケーションをデフォルト のテンプレート付きで配りやすくなります。

例えば、以下のように設定します:

INSTALLED_APPS = ('myproject.polls', 'myproject.music')

get_template('foo.html') は以下のディレクトリを順番に探します:

• /path/to/myproject/polls/templates/foo.html
• /path/to/myproject/music/templates/foo.html

このローダは最初に import した時に最適化処理を行います。すなわち、 INSTALLED_APPS パッケージリストの中で、 templates サブディレク トリを持つものをキャッシュします。

django.template.loaders.eggs.load_template_source

app_directories と同じですが、ファイルシステムではなく Python eggs からテンプレートをロードします。

Django はテンプレートローダを TEMPLATE_LOADERS 設定の順番に従って 試してゆき、マッチするテンプレートが見つかるまで探します。

テンプレートフィルタに文字列だけを処理させる

第一引数に文字列しかとらないテンプレートフィルタを書きたければ、 stringfilter デコレータを使ってください。このフィルタは、フィルタ処理の 関数を呼び出す前に、第一引数のオブジェクトを文字列に変換します:

from django.template.defaultfilters import stringfilter

@stringfilter
def lower(value):
    return value.lower()

こうすれば、例えばフィルタに整数型を渡したとしても、(整数型に lower() がないために) AttributeError が送出されるようなことはありません。

カスタムフィルタを登録する

フィルタ定義を書き終えたら、 Django テンプレート言語で使えるようにするため に Library インスタンスに登録する必要があります:

register.filter('cut', cut)
register.filter('lower', lower)

Library.filter() は二つの引数を取ります:

1. フィルタの名前。文字列です。
2. コンパイル関数。(関数名の文字列ではなく) Python 関数です。

バージョン 2.4 以上の Python を使っているのなら、 register.filter() デコレータを使えます:

@register.filter(name='cut')
@stringfilter
def cut(value, arg):
    return value.replace(arg, '')

@register.filter
@stringfilter
def lower(value):
    return value.lower()

上の例の下の定義のようにして name 引数を省略すると、 Django は関数名を そのままフィルタ名として使います。

フィルタと自動エスケープ

カスタムフィルタを書く場合、フィルタが Django の自動エスケープとどう関わっ ているかに少し配慮しておく必要があります。

まず、テンプレートのコード内では、 3 種類の文字列が受け渡しされています:

• 生の文字列 とは、 Python ネイティブの str や unicode 型の オブジェクトです。出力時、自動エスケープが有効であればエスケープされ、 そうでなければ変更されません。

• safe 文字列 とは、出力時にさらなるエスケープ処理を行わなくてもよ い文字列です。safe 文字列は、必要なエスケープが済んでいる文字列です。 クライアント側でそのまま解釈されるべき生の HTML を含んだ文字列を表現 するのに使われます。

  内部的には、これらの文字列は SafeString や SafeUnicode 型で表 現されています。 SafeString と SafeUnicode は SafeData を 共通の基底クラスに持つので、以下のようにすれば判別できます:

  if isinstance(value, SafeData):
      # "safe" 文字列を扱う処理をここに
  

• "エスケープが必要" であるとマークされている文字列 は、 autoescape ブロックの指定に関係なく、必ずエスケープされます。 マークされている文字列は、自動エスケープの設定に関係なく、一度だけエ スケープ処理を受けます。

  内部的には、エスケープ必要文字列は、 EscapeString や EscapeUnicode 型で表現されています。通常、これらの型のことを気に する必要はありません。 EscapeString や EscapeUnicode は、 escape フィルタの実装のために用意されています。

テンプレートフィルタのコードは、以下の二つのうちどちらかに落ち着きます:

1. フィルタコードの出力が、 HTML 出力として安全でない文字 (<, >, ', " or &) を含まない場合。この場合、自動エスケー プの処理は全て Django に任せられます。必要なのは、フィルタ関数の is_safe 属性に True を設定しておくことだけです:

   @register.filter
   def myfilter(value):
       return value
   myfilter.is_safe = True
   

   この属性を設定しておくと、このフィルタは「安全な」文字列を渡したとき には出力は「安全な」ままであり、「安全でない」文字列を渡した時には、 必要に応じて自動的にエスケープします。

   is_safe は、「このフィルタは安全 (safe) であり、安全でない HTML を生成する危険性がない」という意味だと考えてください。

   is_safe が必要なのは、通常の文字列操作で、 SafeData オブジェ クトを str や unicode オブジェクトに変換するものが数多くあ るためです。全てを try と catch で拾うのは難しいので、 Django はフィ ルタ処理が完了した時点でダメージを回復する戦略を取っています。

   例えば、入力の末尾に xx を追加するようなフィルタを書くとします。 このフィルタは危険な HTML 文字を出力しないので、フィルタ関数を is_safe でマークしておきます:

   @register.filter
   def add_xx(value):
       return '%sxx' % value
   add_xx.is_safe = True
   

   このフィルタをテンプレート上の自動エスケープが有効な部分で使うと、 Django は "safe" にマークされていない入力の時にフィルタの出力をエス ケープします。

   デフォルトでは、 is_safe は False なので、 is_safe が 必要でなければ無視してかまいません。

   フィルタを作成するときには、フィルタが本当に安全な文字を安全なままに 出力するのかをよく考えてください。例えば、フィルタが文字を 削除 す る場合、出力結果に、対応の取れていないタグや不完全なエンティティ表現 が意図せず混じる可能性があります。例えば、 > を入力から削ってし まうと、 <a> の出力は <a になってしまい、問題を起こさないよ うにするためには、出力をエスケープせねばならなくなってしまいます。同 様に、セミコロン (;) を除去すると、 &amp; は &amp になっ てしまい、有効なエンティティ表現でないために、エスケープが必要になっ てしまいます。たいていのケースでは、このようなトリッキーなことは起こ りませんが、コードをレビューする際にはこの手のことが起こらないように よく確認してください。

2. もう一つは、フィルタのコードで必要なエスケープを行うというものです。 出力に新たな HTML マークアップを含めたい場合に必要です。この場合、 出力する HTML マークアップがそれ以上エスケープされないよう、出力を safe にする必要があるので、入力は自分で扱わねばなりません。

   出力を safe 文字列としてマークするには、 django.utils.safestring.mark_safe() を使います。 ただし、注意してください。出力を safe であるとマークするだけでは十分 ではありません。出力が本当に safe である ことを保証せねばならず、 それは自動エスケープが有効か無効かで変わります。自動エスケープがオン でもオフでも使え、テンプレートの作者が簡単に扱えるフィルタを書くのが 理想です。

   現在の自動エスケープ状態をフィルタに教えるには、関数の needs_autoescape 属性を True に設定します (この属性を設定 しない場合のデフォルト値は False です)。 needs_autoescape を True にすると、フィルタ関数には autoescape という追加の引 数が渡されます。自動エスケープが有効な状況でフィルタが呼び出されると、 autoescape には True が渡され、そうでない場合には False が渡されます。

   例えば、文字列の先頭の文字を強調表示にするようなフィルタを書いてみま しょう:

   from django.utils.html import conditional_escape
   from django.utils.safestring import mark_safe
   
   def initial_letter_filter(text, autoescape=None):
       first, other = text[0], text[1:]
       if autoescape:
           esc = conditional_escape
       else:
           esc = lambda x: x
       result = '<strong>%s</strong>%s' % (esc(first), esc(other))
       return mark_safe(result)
   initial_letter_filter.needs_autoescape = True
   

   フィルタ関数の needs_autoescape 属性と autoescape キーワード 引数の存在によって、フィルタ関数は自身が呼び出されたときの自動エスケー プ状態を検知できます。上の例では、 autoescape を使って、入力デー タを django.utils.html.conditional_escape で処理するべきかどうか 判定しています。 (conditional_escape が不要の場合、 esc を アイデンティティ関数にしています) conditional_escape() は escape() に似ていますが、入力が SafeData インスタンスで ない 場合にのみエスケープを適用します。 conditional_escape() に SafeData を渡すと、データは変更されません。

   最後に、上の例では、フィルタ結果を mark_safe で safe にマークし て、出力結果の HTML をこれ以上エスケープせず、最終的なテンプレート出 力に挿入させています。

   このケースでは、 is_safe 属性について触れていません (実際には、 設定しても何の影響もありません)。自動エスケープの問題を手動で解決し て、 safe 文字列を返している場合、 is_safe 属性は何ら影響をもた ないのです。

テンプレートタグの概要

前に、このドキュメントで、テンプレートシステムはコンパイルとレンダリングと いう二段階のプロセスで動作すると説明しました。カスタムテンプレートタグを定 義するには、コンパイルがどのように行われ、レンダリングがどのように行われる かを指定する必要があります。

テンプレートをコンパイルする時、Django は元のテンプレートテキストを「ノード (node)」に分割します。各ノードは django.template.Node のインスタンスで あり、 render() メソッドを持ちます。コンパイル済みのテンプレートは単な る Node オブジェクトの集まりに過ぎません。コンパイル済みのテンプレート オブジェクトに対して render() を呼び出すと、テンプレートは指定されたコ ンテキストを使ってノードリストの各 Node に対して render() を呼び出 します。戻り値は全て連結され、テンプレートからの出力になります。

従って、カスタムテンプレートタグを定義するには、元のテンプレートタグをどう やって Node (コンパイル関数: compilation function) に変換し、個々のノー ドの render() メソッドが何をするかを指定する必要があります。

コンパイル関数を書く

テンプレートタグに到達するたびに、テンプレートパーザはタグの内容とパーザオ ブジェクト自体を引数にしてある Python 関数を呼び出します。この関数はタグの 内容に応じて Node インスタンスを返すようになっています。

例えば、 {% current_time %} というタグを書いてみましょう。このタグは現 在の日付／時刻を表示し、そのフォーマットはタグの引数に指定した strftime の文法 に従うとします。何をおいてもタグの構文をまず決めておくの がよいでしょう。我々の例では、タグは以下のように使われるものとしましょう:

<p>The time is {% current_time "%Y-%m-%d %I:%M %p" %}.</p>

以下の関数は、パラメタを取り出して、 Node オブジェクトを生成します:

from django import template
def do_current_time(parser, token):
    try:
        # split_contents() knows not to split quoted strings.
        tag_name, format_string = token.split_contents()
    except ValueError:
        raise template.TemplateSyntaxError, \
            "%r tag requires a single argument" % token.contents.split()[0]
    if not (format_string[0] == format_string[-1] and \
        format_string[0] in ('"', "'")):
        raise template.TemplateSyntaxError, \
              "%r tag's argument should be in quotes" % tag_name
    return CurrentTimeNode(format_string[1:-1])

Notes:

• parser はテンプレートパーザオブジェクトです。上の例では特に必要で はありません。
• token.contents はタグの中身を表す文字列です。上の例では 'current_time "%Y-%m-%d %I:%M %p"' になります。
• token.split_contents() メソッドは、クオートされた文字列はそのまま にして、引数をスペースで分割します。 token.contents.split() の方 が直接的なように思えますが、クオート中の空白も含め、 全ての スペー スを区切りとみなすので、これは頑健な方法とはいえません。常に token.split_contents() を使った方がよいでしょう。
• この関数は、何らかの構文エラーが生じた場合、分かりやすいメッセージ付 きで django.template.TemplateSyntaxError を送出せねばなりません。
• TemplateSyntaxError 例外は tag_name 変数を使っています。 エラーメッセージにタグの名前をハードコードしてはなりません。なぜなら 関数とタグの名前がカップリングしてしまうからです。タグに引数があって もなくても、 token.contents.split()[0] は常にタグの名前と同じにな ります。
• この関数は、タグの処理に必要な全ての情報を持った CurrentTimeNode を返します。この例の場合、タグには引数 "%Y-%m-%d %I:%M %p" が渡さ れただけです。テンプレートタグの先頭や末尾のクオートは format_string[1:-1] ではぎ取られています。
• パージング処理は極めて低水準で実現されています。 Django の開発者達は、 EBNF 文法のようなテクニックを使って、このパージングシステムの上に小さ なフレームワークを書く実験を重ねて来ましたが、その結果はテンプレート エンジンをひどく低速にしてしまいました。というわけで、低水準にしてい るのは、それが最も高速だからです。

レンダラを書く

カスタムタグを書く二つめのステップは、 render() メソッドを持つ Node クラスの定義です。

上の例の続きとして話を勧めると、 CurrentTimeNode を定義する必要がありま す:

from django import template
import datetime
class CurrentTimeNode(template.Node):
    def __init__(self, format_string):
        self.format_string = format_string
    def render(self, context):
        return datetime.datetime.now().strftime(self.format_string)

注意:

• __init__() は do_current_time() から format_string を受け 取ります。 Node へのオプション／パラメタ／引数は、常に __init__() を介して渡すようにしてください。
• 実際の処理を実現するのは render() メソッドです。
• render() は TemplateSyntaxError やその他の例外を送出してはな りません。フィルタと同様、失敗は暗黙のうちに処理されるようにせねばな りません、

一つのテンプレートは、繰り返しパージングされることなく複数のコンテキストを レンダリングすることがあるので、このようなコンパイルとレンダリングの脱カッ プリングは究極的には効率的なテンプレートシステムを実現します。

自動エスケープについての注意点

開発版の Django で新たに登場した機能

テンプレートタグの出力は、自動エスケープフィルタで自動的に処理され ません 。とはいえ、テンプレートタグを書くときには、二つのことを心に留めて 置く必要があります。

まず、テンプレートタグの render() が結果をコンテキスト変数に保存する場 合 (文字列でそのまま返さない場合) には、必要なら mark_safe() を呼び出し ておく必要があります。その変数を最終的にレンダした時点で、変数は自動エスケー プの設定の影響を受けるので、自動エスケープから保護したい変数はそのようにマー クしておく必要があるのです。

また、テンプレートタグがサブレンダリングのために新たなコンテキストを生成す る場合、そのコンテキスト変数に autoescape 属性を設定してください。 Context クラスの __init__ メソッドは、この目的のために、 autoescape というパラメタをとれるようになっています。例えば:

def render(self, context):
    # ...
    new_context = Context({'var': obj}, autoescape=context.autoescape)
    # ... 新しいコンテキストで何かする ...

このような状況はあまりありませんが、テンプレートタグ内で別のテンプレートを レンダする場合には便利です。例えば:

def render(self, context):
    t = template.loader.get__template('small_fragment.html')
    return t.render(Context({'var': obj}, autoescape=context.autoescape))

上の例で、 context.autoescape の値を渡し忘れると、出力の変数は 全て 自動エスケープされてしまい、その結果、テンプレートタグを {% autoescape off %} ブロック内で使った場合の出力が期待とは違うものになっ てしまいます。

タグの登録

最後に、上の「カスタムテンプレートフィルタを書く」の節で説明したように、タ グをモジュールの Library インスタンスに登録します:

register.tag('current_time', do_current_time)

tag() メソッドは二つの引数をとります:

1. テンプレートタグの名前、文字列です。省略すると、コンパイル関数の名前 を使います。
2. コンパイル関数。 Python の関数です (関数名を表す文字列ではありません)。

フィルタの登録と同様、バージョン 2.4 以降の Python ではこの関数をデコレータ として使えます:

@register.tag(name="current_time")
def do_current_time(parser, token):
    # ...

@register.tag
def shout(parser, token):
    # ...

上の例の下の定義のようにして name 引数を省略すると、 Django は関数名を そのままフィルタ名として使います。

テンプレート変数をタグに渡す

token.split_contents() を使えば、テンプレートタグにいくつでも引数を渡せ ますが、引数はすべて文字列リテラルになってしまいます。そのため、テンプレー トタグの引数に動的なコンテンツ (テンプレート変数) を渡すには、もうひと工夫 必要です。先に挙げた例では、現在時刻を文字列にフォーマットして文字列で値を 返していましたが、今度は以下のように DateTimeField の値を渡してテンプレー トタグに日付と時刻をフォーマットさせたいとしましょう:

<p>この投稿が最後に更新された時刻:{% format_time blog_entry.date_updated "%Y-%m-%d %I:%M %p" %}</p>

まず、 token.split_contents() は以下の 3 つの値を返します:

1. タグ名である format_time 。
2. blog_entry.date_updated という 文字列 。
3. フォーマット文字列 "%Y-%m-%d %I:%M %p" 。 split_contents() は、 文字列リテラルの先頭と末尾にあるクオート文字を除去しません。

今度は、タグの定義は以下のようになります:

from django import template
def do_format_time(parser, token):
    try:
        # split_contents() はクオート付き文字列を分解しない
        tag_name, date_to_be_formatted, format_string = token.split_contents()
    except ValueError:
        raise template.TemplateSyntaxError, "%r tag requires exactly two arguments" % token.contents.split()[0]
    if not (format_string[0] == format_string[-1] and format_string[0] in ('"', "'")):
        raise template.TemplateSyntaxError, "%r tag's argument should be in quotes" % tag_name
    return FormatTimeNode(date_to_be_formatted, format_string[1:-1])

レンダラの方も変更して、 blog_entry オブジェクトの date_updated プ ロパティの実際の中身を取り出せるようにせねばなりません。これは django.template の resolve_varialbe() で実現します。 resolve_variable() には、変数名と render メソッドを介して渡される現 在のコンテキストを指定します:

from django import template
from django.template import resolve_variable
import datetime
class FormatTimeNode(template.Node):
    def __init__(self, date_to_be_formatted, format_string):
        self.date_to_be_formatted = date_to_be_formatted
        self.format_string = format_string

    def render(self, context):
        try:
            actual_date = resolve_variable(self.date_to_be_formatted, context)
            return actual_date.strftime(self.format_string)
        except template.VariableDoesNotExist:
            return ''

これで、 resolve_variable は blog_entry.date_updated の値を解決して、 その値にしたがってフォーマット処理を行います。

.. parsed-literal::

現在のページのコンテキストに、 Variable に渡した名前がなかった場合、 名前解決の際に VariableDoesNotExist 例外が送出されます。

簡単なタグへのショートカット

多くのテンプレートタグは、文字列やテンプレート変数への参照を単一の引数とし て取り、入力引数や外部の何らかの情報に基づいて処理を行った後、文字列を返し ます。例えば、上で書いた current_time タグがその例で、フォーマット文字 列を指定して、時刻を文字列の形で返すようになっています。

この種のタグを簡単に作成できるようにするため、 Django では simple_tag というヘルパー関数を提供しています。この関数は django.template.Library のメソッドで、何らかの関数を引数にとり、その関数を render メソッドにラッ プし、これまでに述べてきたいくつかのお作法を適用した後、テンプレートシステ ムにタグを登録します。

simple_tag を使うと、上の current_time 関数は以下のように書けます:

def current_time(format_string):
    return datetime.datetime.now().strftime(format_string)

register.simple_tag(current_time)

Python 2.4 からは、デコレータ構文もうまく動作します:

@register.simple_tag
def current_time(token):
    ...

simple_tag ヘルパ関数については、以下の点に注意してください:

• ラップ対象の関数には単一の引数 (だけ) しか渡せません。
• 引数の個数チェックなどは関数の呼び出しの際に行われるので、わざわざ自 分でチェックしなくてもかまいません。
• 関数に渡される引数がクオートされている場合、クオートは自動的に取り去 られます。従って、関数は通常の文字列を受け取ることになります。
• 引数がテンプレート変数なら、関数に渡されるのは変数自体ではなく、 変数の現在値になります。

テンプレートタグが現在のコンテキストにアクセスしなくてもよいのなら、 入力値を引数に取るような関数を定義し、 simple_tag ヘルパ関数を使うのが 一番簡単です。

埋め込みタグ

テンプレートタグによくあるもう一つのタイプは、 別の テンプレートをレンダ して表示するものです。例えば、 Django の admin インタフェースではカスタムの テンプレートタグを使って「追加／変更」フォームページのボタンを表示していま す。これらのボタンはいつも同じように表示されていますが、リンクのターゲット は編集対象のオブジェクトによって変わります。従って、こうした処理は、小さな テンプレートを使って現在のオブジェクトに応じた値を埋めるのが最良の方法と言 えます。 (admin の submit_raw がそのタグです)。

こうしたタグのことを 「埋め込みタグ (inclusion tag)」 と呼びます。

埋め込みタグの書き方を説明するには、例を挙げるのがベストでしょう。 チュートリアル で作成した Poll オブジェクトを例に、ある Poll オ ブジェクトに対する選択肢のリストを出力するようなタグを書いてみましょう。 タグは以下のようになります:

{% show_results poll %}

例えば、出力は以下のようになります:

<ul>
  <li>First choice</li>
  <li>Second choice</li>
  <li>Third choice</li>
</ul>

まず、引数を受け取って、対応するデータの辞書を生成するような関数を定義しま す。ここで重要なのは、辞書を返さねばならず、それ以外の複雑なデータを返して はならないということです。戻り値はテンプレートフラグメントをレンダするとき のテンプレートコンテキストに使われます。例を示します:

def show_results(poll):
    choices = poll.choice_set.all()
    return {'choices': choices}

次に、タグの出力をレンダする際に使うテンプレートを作成します。このテンプレー トはタグ固有のもので、テンプレートデザイナではなくタグの開発者が書くべきも のです。上の例に従えば、テンプレートはとても単純な形になります:

<ul>
{% for choice in choices %}
    <li> {{ choice }} </li>
{% endfor %}
</ul>

さて、 Library オブジェクトの inclusion_tag() メソッドを呼び出して、 埋め込みタグを作成し、登録しましょう。上のテンプレートがテンプレートローダ の検索対象ディレクトリ下にある result.html だとすると、タグの登録は以下 のようにして行います:

# Here, register is a django.template.Library instance, as before
register.inclusion_tag('results.html')(show_results)

ここでも、 Python 2.4 のデコレータ構文を使えます。従って、関数を定義する時 点で下記のようにも書けます:

@register.inclusion_tag('results.html')
def show_results(poll):
    ...

時として、埋め込みタグが大量の引数を取るようになっていて、テンプレートの作 者が全ての引数やその順番を管理しきれなくなるような場合があります。この問題 を解決するために、 Django では埋め込みタグに対して takes_context オプショ ンを提供しています。テンプレートタグの作成時に takes_context を指定する と、タグは必須の引数を取らなくなり、タグのラップしている Python 関数は単一 の引数を取るようになります。この引数には、タグが呼び出されたときのテンプレー トコンテキストが入ります。

例えば、メインページに戻るためのリンクに使う home_link および home_title という変数の入ったコンテキストの下で使う埋め込みタグを書いて いるとしましょう。タグの Python 関数は以下のようになります:

# 最初の引数は *必ず* "context" と *呼ばねばなりません*
def jump_link(context):
    return {
        'link': context['home_link'],
        'title': context['home_title'],
    }
# Register the custom tag as an inclusion tag with takes_context=True.
register.inclusion_tag('link.html', takes_context=True)(jump_link)

(関数の最初のパラメタは 必ず context という名前に せねばならない の で注意してください。)

register.inclusion_tag() の行で、 takes_context=True を指定し、テン プレートの名前を指定しています。 link.html テンプレートの中は以下のよう になります:

Jump directly to <a href="{{ link }}">{{ title }}</a>.

このカスタムタグを使う場合は常に、まずライブラリを呼び出しておき、下記のよ うに引数なしでタグを呼び出します:

{% jump_link %}

takes_context=True を使っている場合、テンプレートタグに引数を渡す必要は ありません。タグが自動的にコンテキストにアクセスします。

takes_context パラメタはデフォルトでは False です。この値を True に設定すると、タグの引数にはコンテキストオブジェクトが渡されます。この点だ けは前述の inclusion_tag の例と異なります。

コンテキスト中の変数を設定する

上の例は、単に値を出力するという単純なものでした。一般的な話として、テンプ レートタグが値を出力するだけでなく、テンプレート変数の値を設定できたりする ともっと柔軟性が増すでしょう。そうすれば、テンプレートの作者はテンプレート タグのつくり出す変数を再利用できるようになります。

コンテキスト中に変数を設定するには、 render() メソッドで渡されるコンテ キストオブジェクトを辞書として代入するだけです。先程の CurrentTimeNode を変更して、値を出力するのではなく current_time というテンプレート変数 を設定した例を示します:

class CurrentTimeNode2(template.Node):
    def __init__(self, format_string):
        self.format_string = format_string
    def render(self, context):
        context['current_time'] = \
            datetime.datetime.now().strftime(self.format_string)
        return ''

render() は空文字列を返していることに注意して下さい。 render() は常に文字列を出力せねばなりません。全てのテンプレートタグが変数の設定 しかしなければ、 render() は空の文字列を返すだけです。

新しいバージョンのタグの使い方を示します:

{% current_time "%Y-%m-%d %I:%M %p" %}<p>The time is {{ current_time }}.</p>

ところで、 CurrentTimeNode2 には問題があります: 変数名 current_time がハードコードされているのです。これはすなわち、テンプレートの他の部分で {{ current_time }} を使わないようにせねばならないことを意味します。とい うのも、 {% current_time %} は変数の値を盲目的に上書きしてしまうからで す。より綺麗な解法は、出力用の変数名を定義させるというものです。例えば:

{% get_current_time "%Y-%m-%d %I:%M %p" as my_current_time %}
<p>The current time is {{ my_current_time }}.</p>

この機能を実現するには、コンパイル関数と Node の両方をリファクタして、 以下のようにせねばなりません:

class CurrentTimeNode3(template.Node):
    def __init__(self, format_string, var_name):
        self.format_string = format_string
        self.var_name = var_name
    def render(self, context):
        context[self.var_name] = \
            datetime.datetime.now().strftime(self.format_string)
        return ''

import re
def do_current_time(parser, token):
    # This version uses a regular expression to parse tag contents.
    try:
        # Splitting by None == splitting by spaces.
        tag_name, arg = token.contents.split(None, 1)
    except ValueError:
        raise template.TemplateSyntaxError, \
              "%r tag requires arguments" % token.contents.split()[0]
    m = re.search(r'(.*?) as (\w+)', arg)
    if not m:
        raise template.TemplateSyntaxError, \
              "%r tag had invalid arguments" % tag_name
    format_string, var_name = m.groups()
    if not (format_string[0] == format_string[-1] and \
        format_string[0] in ('"', "'")):
        raise template.TemplateSyntaxError, \
              "%r tag's argument should be in quotes" % tag_name
    return CurrentTimeNode3(format_string[1:-1], var_name)

ここでの違いは、 do_current_tume() がフォーマット文字列と変数名を取り、 CurrentTimeNode3 に渡すという点です。

他のブロックタグに到達するまでパージングする

テンプレートタグは違いに連携させられます。例えば、標準の {% comment %} というタグは、 {% endcomment %} までの全ての内容を出力しないようにしま す。このようなテンプレートタグを作るには、コンパイル関数中で parser.parse() を使います。

標準の {% comment %} タグの実装方法を示します:

def do_comment(parser, token):
    nodelist = parser.parse(('endcomment',))
    parser.delete_first_token()
    return CommentNode()

class CommentNode(template.Node):
    def render(self, context):
        return ''

parser.parse() は「そこまで読み進める」ブロックタグからなるタプルを引数 にとります。 parser.parse() は django.template.NodeList のインスタ ンスを返します。このインスタンスは、タプルに指定したブロックタグのいずれか に到達する「より以前」に、パーザが出会った全ての Node オブジェクトから なるリストです。

上の例の "nodelist = parser.parse(('endcomment',))" では、 nodelist は {% comment %} から {% endcomment %} までの全てのノードからなる リストになります。ただし、 {% comment %} や {% endcomment %} 自体は除きます。

parser.parse() の呼び出し直後では、パーザはまだ {% endcomment %} タグを「消費」していないので、コードから明示的に parser.delete_first_token() を呼び出してやる必要があります。

CommentNode.render() は単に空文字列を返します。その結果、 {% comment %} と {% endcomment %} の間の内容は全て無視されます。

次のブロックタグまでパージングして、内容を保存する

前節の例では、 do_comment() は {% comment %} から {% endcomment %} までの全ての内容を無視しています。このような処理に代え て、ブロックタグ間のコードを使った処理も行えます。

例えば、 {% upper %} というカスタムのテンプレートタグを定義して、 {% endupper %} までの内容を大文字に変換できるようにします。

使い方はこのようになります:

{% upper %}This will appear in uppercase, {{ your_name }}.{% endupper %}

これmでの例と同様、 parser.parse() を使います。ただし、今回は得られた nodelist を Node に渡します:

def do_upper(parser, token):
    nodelist = parser.parse(('endupper',))
    parser.delete_first_token()
    return UpperNode(nodelist)

class UpperNode(template.Node):
    def __init__(self, nodelist):
        self.nodelist = nodelist
    def render(self, context):
        output = self.nodelist.render(context)
        return output.upper()

UpperNode.render() の self.nodelist.render(context) が、新たに導入 されたコンセプトを表しています。

複雑なレンダリングについて他にも例を見たければ、 {% if %} や {% for %}, {% ifequal %} , {% ifchanged %} のソースを参照してく ださい。ソースは django/template/defaulttags.py にあります。