\n\n独自のテンプレートタグやフィルタを指定するための最も一般的な場所は、Django のアプリケーションの内部です。それらが既存のアプリに関連するものである場合は、この場所にバンドルするのが最適です。それ以外の場合は、新しいアプリケーションに追加されてしまいます。Django のアプリケーションが INSTALLED_APPS
\nアプリケーションは、"models.py" や "views.py" などと同じレベルに "templatetags" ディレクトリを含むべきです。まだ存在していない場合は、ディレクトリが Python パッケージとして扱われるようにするため、"__init__.py" を忘れないでください。
\n\nカスタムタグやフィルタは templatetags ディレクトリ内のモジュールにあります。モジュールファイルの名前は、あとでタグをロードして使うので、別のアプリでカスタムタグやフィルタと衝突しない名前を選択するように心がけてください。
\n例えば、カスタムタグ/フィルタが poll_extras.py というファイルにある場合、アプリのレイアウトは次のようになります:
\nText Copy
polls/\n __init__.py\n models.py\n templatetags/\n __init__.py\n poll_extras.py\n views.py\nそして、テンプレートでは次のように使います:
\nDjango template Copy
{% load poll_extras %} \nカスタムタグを含むアプリケーションは、{% load %}INSTALLED_APPS
\ntemplatetags パッケージに入れられるモジュールの数に制限はありません。ただ、{% load %}
\n有効なタグライブラリにするため、モジュールは、register という名前のモジュールレベルの変数を含む必要があります。これは、すべてのタグとフィルタが登録されている template.Library のインスタンスです。そのため、あなたのモジュールの上部に、次のコードを記述してください:
\nCode Copy
from django import template\n\nregister = template. Library() \nあるいは、テンプレートタグのモジュールは、DjangoTemplates'libraries' 引数を通じて登録することもできます。テンプレートタグをロードするときに、テンプレートタグのモジュール名とは異なるラベルを使用したい場合に便利です。また、アプリケーションをインストールせずに、タグを登録できるようになります。
\n\n \n\n独自のフィルタは、1つか2つの引数を取るPythonの関数です:
\n\n例えば、フィルタ {{ var|foo:"bar" }} の中で、フィルタ foo は変数 var と引数 "bar" を渡されます。
\nテンプレート言語は例外処理を提供しないので、テンプレートフィルタから生成された例外はすべてサーバーエラーとして公開されます。したがって、フィルタ関数は、返すべき妥当なフォールバック値がある場合には例外を発生させないようにする必要があります。テンプレートの明確なバグを表すインプットの場合、例外を発生させる方が、バグを隠すサイレントな失敗よりも適切でしょう。
\n以下はフィルタ定義の例です:
\nCode Copy
def cut ( value, arg): \n """Removes all values of arg from the given string""" \n return value. replace( arg, "" ) \nそして、以下はフィルタがどのように使われるかの例です:
\nDjango template Copy
{{ somevariable | cut :"0" }} \nほとんどのフィルタは引数を取りません。この場合、次のように関数の第2引数を省略してください:
\nCode Copy
def lower ( value): # Only one argument. \n """Converts a string into all lowercase""" \n return value. lower() \n\n\n\n\ndjango.template.Library. filter ( ) Link to this definition # \n \n\nフィルタ定義を書き終わったら、Django のテンプレート言語で使用できるようにするため、Library のインスタンスに登録する必要があります。
\nCode Copy
register. filter( "cut" , cut) \nregister. filter( "lower" , lower) \nLibrary.filter() メソッドは 2 つの引数を取ります:
\n\nフィルタの名前 -- 文字列です。
編集用の関数 -- Python の関数です (文字列としての関数名ではありません)。
\n代わりに register.filter() をデコレータとして使用できます。
\nCode Copy
@register . filter( name= "cut" ) \ndef cut ( value, arg): \n return value. replace( arg, "" ) \n\n\n@register . filter\ndef lower ( value): \n return value. lower() \nname 引数を省略した場合、上記の 2 番目の例と同じように、Django はフィルタ名として関数の名前を利用します。
\n最後に、register.filter() は 3 つのキーワード引数 (is_safe、needs_autoescape、 expects_localtime) を受け入れます。これらの引数は、後述の フィルタと自動エスケープ フィルタとタイムゾーン
\n \n\n\n\n\ndjango.template.defaultfilters. stringfilter ( ) Link to this definition # \n \n\n第 1 引数として文字数を要求するだけのテンプレートフィルタを記述している場合、デコレータ stringfilter を使う必要があります。これは、関数に渡される前にオブジェクトを文字列に変換します。
\nCode Copy
from django import template\nfrom django.template.defaultfilters import stringfilter\n\nregister = template. Library() \n\n\n@register . filter\n@stringfilter \ndef lower ( value): \n return value. lower() \nこれにより、このフィルタに整数を渡したとしても AttributeError は発生しません。(整数は lower() メソッドを持ちませんが。)
\n \n\n独自のフィルタを作成する場合、フィルタがDjangoの自動エスケープの挙動とどのように関連するか考慮してください。2種類の文字列がテンプレートコードに渡されることに留意してください:
\n\nRaw strings はPythonのネイティブの文字列です。出力時に、自動エスケープが有効な場合はエスケープされ、それ以外の場合は変更されません。
Safe strings は出力時にさらなるエスケープがされないように安全とマークされた文字列です。必要なエスケープはすでに行われています。これらはクライアント側でそのまま解釈されることを目的とした生のHTMLを含む出力によく利用されます。
\n内部では、これらの文字列は SafeString
\nCode Copy
from django.utils.safestring import SafeString\n\nif isinstance ( value, SafeString): \n # Do something with the "safe" string. \n ... \n \nテンプレートフィルタのコードは、次の2つの状況のいずれかに当てはまります:
\n\nフィルタが結果に新たにHTMLで安全でない文字 (<, >, ', " or &) を導入しない場合。この場合、Djangoにすべての自動エスケープ処理を任せることができます。フィルタ関数を登録する際に、 is_safe フラグを True に設定するだけです。次のようにします:
\nCode Copy
@register . filter( is_safe= True ) \ndef myfilter ( value): \n return value\nこのフラグは、"安全"な文字列がフィルタに渡された場合、結果も依然として"安全"であることをDjangoに伝えます。そして、安全でない文字列が渡された場合、必要に応じてDjangoが自動的にエスケープします。
\nこの場合、"このフィルタは安全である ―― それはどんな非安全なHTMLも導入する可能性はない。" と考えて構いません。
\nis_safe が必要な理由は、 SafeData オブジェクトを普通の str オブジェクトに変換するような標準的な文字列操作が多数存在し、これら全てを捉えることが非常に難しいため、Djangoではフィルタの処理が完了した後に問題を修正するためです。
\n例えば、任意の入力の末尾に文字列 xx を追加するフィルタがあるとします。これは結果に危険なHTML文字を導入しません（元々存在していたものを除く）。よって、フィルタを is_safe でマークすべきです:
\nCode Copy
@register . filter( is_safe= True ) \ndef add_xx ( value): \n return " %s xx" % value\nこのフィルタが自動エスケープが有効なテンプレートで使用される場合、入力が既に"安全"としてマークされていない限り、Djangoは出力をエスケープします。
\nデフォルトでは is_safe は False ですが、それが必要でないフィルタでは省略できます。
\nフィルタが本当に安全な文字列を安全なまま残すかどうかを判断するときには注意してください。文字を 除去 している場合、不注意で結果の中に不均衡なHTMLタグやエンティティが残ってしまうかもしれません。例えば、入力から > を取り除くと <a> が <a になってしまうかもしれません。同様に、セミコロン(;)を削除すると、& が & に変わります。ほとんどの場合、ここまでトリッキーになることはありませんが、コードをレビューする際はこのような問題がないか注意してください。
\nMarking a filter is_safe will coerce the filter's return value to\na string. If your filter should return a boolean or other non-string\nvalue, marking it is_safe will probably have unintended\nconsequences (such as converting a boolean False to the string\n'False').
\nまたは、フィルタのコードで必要なエスケープ処理を手動で行うこともできます。これは、結果に新しいHTMLマークアップを導入する場合に必要です。HTMLマークアップがさらにエスケープされないように、出力を安全としてマークしたい場合は、入力を自分で処理する必要があります。
\n出力を安全な文字列としてマークするには django.utils.safestring.mark_safe()
\nただし注意が必要です。出力を安全としてマークするだけでは不十分です。本当にそれが 安全である ことを確認する必要があり、行うべきことは自動エスケープが有効かどうかによって異なります。テンプレート作成者のために、自動エスケープがオンまたはオフのどちらのテンプレートでも操作できるフィルタを書くことが考えられます。
\nフィルタが現在の自動エスケープの状態を知るためには、フィルタ関数を登録する際に needs_autoescape フラグを True に設定します。(このフラグを指定しない場合、デフォルトは False です)。このフラグは、追加のキーワード引数 autoescape をDjangoに渡すようにフィルタ関数に伝えます。この引数は自動エスケープが有効の場合は True 、そうでない場合は False となります。 autoescape パラメータのデフォルトは True に設定しておくことが推奨されます。これにより、Pythonコードから関数を呼び出したときにデフォルトでエスケープが有効になります。
\n例えば、文字列の最初の文字を強調するフィルタを書いてみましょう:
\nCode Copy
from django import template\nfrom django.utils.html import conditional_escape\nfrom django.utils.safestring import mark_safe\n\nregister = template. Library() \n\n\n@register . filter( needs_autoescape= True ) \ndef initial_letter_filter ( text, autoescape= True ): \n first, other = text[ 0 ], text[ 1 :] \n if autoescape: \n esc = conditional_escape\n else : \n esc = lambda x: x\n result = "<strong> %s </strong> %s " % ( esc( first), esc( other)) \n return mark_safe( result) \nneeds_autoescape フラグと autoescape キーワード引数により、フィルタが呼び出された際に自動エスケープが有効かどうかを関数が知ることができます。 autoescape を使用して、入力データを django.utils.html.conditional_escape に通す必要があるかどうかを決定します（必要なければ、恒等関数を "escapse" 関数として使用します）。 conditional_escape() 関数は escape() に似ていますが、 SafeData インスタンス でない 入力のみをエスケープします。 SafeData インスタンスが conditional_escape() に渡された場合、データは変更されずにそのまま返されます。
\n最後に、上の例では、HTMLがさらにエスケープされることなくテンプレートに直接挿入されるように、結果を安全としてマークすることを忘れないでください。
\nこの場合、 is_safe フラグを気にする必要はありません (フラグを指定しても何も問題はありませんが)。自動エスケープの問題を手動で処理して安全な文字列を返す場合、 is_safe フラグを指定しても何も変わりません。
\n \n\n警告
\n組み込みのフィルタを再利用するときに XSS 脆弱性を回避する
\nDjango に組み込みのフィルタは、適切な自動エスケープを行い、クロスサイトスクリプティング（XSS）の脆弱性を回避するために、デフォルトで autoescape=True となっています。
\n古いバージョンの Django では、 autoescape のデフォルトは None ですので、 Django の組み込みのフィルタを再利用する際には注意してください。オートエスケープを有効にするには autoescape=True を渡す必要があります。
\n例えば、 urlizelinebreaksbrurlize_and_linebreaks というカスタムフィルタを書きたい場合、フィルタは次のようになります:
\nCode Copy
from django.template.defaultfilters import linebreaksbr, urlize\n\n\n@register . filter( needs_autoescape= True ) \ndef urlize_and_linebreaks ( text, autoescape= True ): \n return linebreaksbr( urlize( text, autoescape= autoescape), autoescape= autoescape) \n次のように使います:
\nDjango template Copy
{{ comment | urlize_and_linebreaks }} \nこれは以下と同等です:
\nDjango template Copy
{{ comment | urlize | linebreaksbr }} \n \n \n\ndatetimeexpects_localtime フラグを True に設定して登録します:
\nCode Copy
@register . filter( expects_localtime= True ) \ndef businesshours ( value): \n try : \n return 9 <= value. hour < 17 \n except AttributeError : \n return "" \nこのフラグがセットされていると、フィルタの最初の引数がタイムゾーンを意識した datetime である場合、Django は テンプレートにおけるタイムゾーン変換ルール
\n \n \n\nタグはあらゆることができるため、フィルタより複雑です。Django は、ほとんどのタイプのタグを簡単に書けるように、多数のショートカットを提供しています。まず最初にこうしたショートカットを見てから、ショートカットでは機能が不足している場合にゼロからタグを書く方法を説明します。
\n\n\n\n\n\ndjango.template.Library. inclusion_tag ( ) Link to this definition # \n \n\nテンプレートタグのもう一つの一般的なタイプは、 別の テンプレートをレンダリングしてデータを表示するものです。例えば、 Django の admin インタフェースでは、カスタムテンプレートタグを使って、"add/change" フォームページの下にあるボタンを表示しています。これらのボタンはいつも同じように見えますが、編集中のオブジェクトによってリンク先が変わります -- なので、現在のオブジェクトの詳細で埋められた小さなテンプレートを使うのに最適なケースです。(admin の場合、これは submit_row タグです)。
\nこの種のタグは "inclusion tag" と呼ばれます。
\nInclusion tag の書き方は例で示すのが一番わかりやすいでしょう。 チュートリアル Poll オブジェクトの選択肢のリストを出力するタグを書いてみましょう。タグはこのように使います:
\nDjango template Copy
{% show_results poll %} \n...そして出力は次のようになります:
\nHtml Copy
< ul > \n < li > First choice</ li > \n < li > Second choice</ li > \n < li > Third choice</ li > \n</ ul > \nまず、引数を受け取り、結果のデータの辞書を生成する関数を定義します。ここで重要なのは、辞書を返すだけでよく、それ以上複雑なものは必要ないということです。これは、テンプレートの断片のテンプレート・コンテキストとして使用されます。例:
\nCode Copy
def show_results ( poll): \n choices = poll. choice_set. all() \n return { "choices" : choices} \n次に、タグの出力をレンダリングするためのテンプレートを作成します。このテンプレートはタグの固定機能であり、テンプレート設計者ではなく、タグ作成者が指定します。この例では、テンプレートはとても短いです:
\nDjango template Copy
< ul > \n{% for choice in choices %} \n < li > {{ choice }} </ li > \n{% endfor %} \n</ ul > \n次に、 Library オブジェクトの inclusion_tag() メソッドを呼び出して、 inclusion tag を作成し、登録します。例に従って、上記のテンプレートがテンプレートローダーによって検索されるディレクトリの results.html というファイルにある場合、次のようにタグを登録します:
\nCode Copy
# Here, register is a django.template.Library instance, as before \n@register . inclusion_tag( "results.html" ) \ndef show_results ( poll): ... \nあるいは、 django.template.Template
\nCode Copy
from django.template.loader import get_template\n\nt = get_template( "results.html" ) \nregister. inclusion_tag( t)( show_results) \n…これは、関数を最初に作成する際に行います。
\n時に、 inclusion tag は多くの引数を要求することがあり、テンプレート作者が全ての引数を渡したり、引数の順番を覚えたりするのは面倒です。これを解決するために、 Django は inclusion tag に takes_context オプションを用意しています。テンプレートタグを作成する際に takes_context を指定すると、タグには必要な引数がなくなり、 Python 関数の引数は 1 つになります――タグが呼び出された時点のテンプレートコンテキストです。
\n例えば、メインページを指す home_link と home_title 変数を含むコンテキストの中で常に使用される inclusion tag を書くとします。Python の関数は次のようになります:
\nCode Copy
@register . inclusion_tag( "link.html" , takes_context= True ) \ndef jump_link ( context): \n return { \n "link" : context[ "home_link" ], \n "title" : context[ "home_title" ], \n } \n最初の引数は context に しなければならない ことに注意してください。
\nこの register.inclusion_tag() の行では、 takes_context=True と、テンプレートの名前を指定しています。テンプレート link.html は以下のようになるでしょう:
\nDjango template Copy
Jump directly to < a href = " {{ link }} " > {{ title }} </ a > .\nそして、そのカスタムタグを使いたいときはいつでも、そのライブラリをロードして、引数なしで次のように呼び出します:
\nDjango template Copy
{% jump_link %} \ntakes_context=True を使用している場合、テンプレートタグに引数を渡す必要がないことに注意してください。自動的に context にアクセスします。
\ntakes_context パラメータのデフォルトは False です。これを True に設定すると、この例のようにタグに context オブジェクトが渡されます。これが先ほどの inclusion_tag の例との唯一の違いです。
\ninclusion_tag 関数は任意の数の位置引数またはキーワード引数を受け取ることができます。例えば:
\nCode Copy
@register . inclusion_tag( "my_template.html" ) \ndef my_tag ( a, b, * args, ** kwargs): \n warning = kwargs[ "warning" ] \n profile = kwargs[ "profile" ] \n ... \n return ... \nこのようにすることで、テンプレートからはスペースで区切られた変数をいくつでもテンプレートタグに渡すことができます。Pythonの文法と同じように、キーワード引数の値は等号（"="）を用いて位置引数の後に記述します。たとえば：
\nDjango template Copy
{% my_tag 123 "abcd" book.title warning = message | lower profile = user.profile %} \n \n\n\n\nテンプレート・システムは、コンパイルとレンダリングの 2 段階のプロセスで動作します。カスタムテンプレートタグを定義するには、コンパイルの仕組みとレンダリングの仕組みを指定します。
\nWhen Django compiles a template, it splits the raw template text into nodes .\nEach node is an instance of django.template.Node and has a render()\nmethod. A compiled template is a list of Node objects. When you call\nrender() on a compiled template object, the template calls render() on\neach Node in its node list, with the given context. The results are all\nconcatenated together to form the output of the template.
\nこのように、カスタムテンプレートタグを定義するには、生のテンプレートタグを Node に変換する方法（コンパイル関数）と、ノードの render() メソッドの動作を指定します。
\n \n\n\nテンプレートパーサーが見つけたそれぞれのテンプレートタグに対して、タグの内容とパーサーオブジェクト自身を使って Python 関数を呼び出します。この関数はタグの内容に基づいて Node インスタンスを返す役割を担います。
\n例えば、テンプレートタグの完全な実装である {% current_time %} を書いてみましょう。このタグは strftime()
\nDjango template Copy
< p > The time is {% current_time "%Y-%m-%d %I:%M %p" %} .</ p > \nこの関数のパーサは、パラメータを取得して Node オブジェクトを作成する必要があります:
\nCode Copy
from django import template\n\n\ndef do_current_time ( parser, token): \n try : \n # split_contents() knows not to split quoted strings. \n tag_name, format_string = token. split_contents() \n except ValueError : \n raise template. TemplateSyntaxError( \n " %r tag requires a single argument" % token. contents. split()[ 0 ] \n ) \n if not ( format_string[ 0 ] == format_string[ - 1 ] and format_string[ 0 ] in ( '"' , "'" )): \n raise template. TemplateSyntaxError( \n " %r tag's argument should be in quotes" % tag_name\n ) \n return CurrentTimeNode( format_string[ 1 : - 1 ]) \nメモ:
\n\nparser はテンプレートパーサーオブジェクトです。この例では不要です。
token.contents はタグの生の内容を表す文字列です。この例では 'current_time "%Y-%m-%d %I:%M %p"' です。
token.split_contents() メソッドは、引用符で囲まれた文字列はそのままに、引数をスペースで分割します。より単純な token.contents.split() を使用すると、引用符で囲まれた文字列内を含む すべての スペースで単純に分割してしまうため、それほど堅牢ではありません。常に token.split_contents() を使用することをお勧めします。
この関数は構文エラーに対して django.template.TemplateSyntaxError を親切なメッセージとともに発生させます。
The TemplateSyntaxError exceptions use the tag_name variable.\nDon't hardcode the tag's name in your error messages, because that\ncouples the tag's name to your function. token.contents.split()[0]\nwill always be the name of your tag -- even when the tag has no arguments.
この関数は、ノードがこのタグについて知る必要があるすべての情報を含む CurrentTimeNode を返します。この場合、引数 "%Y-%m-%d %I:%M %p" を渡します。 format_string[1:-1] では、テンプレートタグの先頭と末尾の引用符が取り除かれます。
構文解析は非常に低レベルです。Django の開発者は、 EBNF 文法などのテクニックを使って、この構文解析システムの上に小さなフレームワークを書く実験をしましたが、 その実験ではテンプレートエンジンが遅すぎました。 低レベルなのは、それが最速だからです。
\n \n\n\nカスタムタグを書く2つ目のステップは、 render() メソッドを持つ Node サブクラスを定義することです。
\n上記の例の続きで、 CurrentTimeNode を定義する必要があります:
\nCode Copy
import datetime \nfrom django import template\n\n\nclass CurrentTimeNode ( template. Node): \n def __init__ ( self , format_string): \n self . format_string = format_string\n\n def render ( self , context): \n return datetime. datetime. now() . strftime( self . format_string) \nメモ:
\n\n__init__() は do_current_time() から format_string を取得します。オプションやパラメータ、引数は常に Node の __init__() から渡します。
render() メソッドは、実際に処理が行われる場所です。
特に実運用環境では、 render() は通常は静かに失敗するべきです。しかし、場合によっては、特に context.template.engine.debug が True の場合、このメソッドはデバッグを容易にするために例外を発生させることがあります。例えば、いくつかのコアタグは、引数の数や型を間違えると django.template.TemplateSyntaxError を発生させます。
\n最終的に、コンパイルとレンダリングを切り離すことで、効率的なテンプレートシステムが実現します。なぜなら、テンプレートは何度もパースされることなく、複数のコンテキストをレンダリングできるからです。
\n \n\nテンプレートタグからの出力は自動エスケープフィルタに自動的に通されることは ありません (上で説明した simple_tag()
\nテンプレートタグの render() メソッドが(結果を文字列で返すのではなく)コンテキスト変数に結果を格納する場合、適切であれば mark_safe() を呼び出すように注意しなければなりません。変数が最終的にレンダリングされるとき、その時点で有効な自動エスケープ設定の影響を受けます、そのため、さらなるエスケープから安全であるべきコンテンツは、そのようにマークされる必要があります。
\nまた、テンプレートタグがサブレンダリングを行うために新しいコンテキストを作成する場合、auto-escape 属性に現在のコンテキストの値を指定します。 Context クラスの __init__ メソッドはこの目的で使用できる autoescape というパラメータを受け取ります。例えば:
\nCode Copy
from django.template import Context\n\n\ndef render ( self , context): \n # ... \n new_context = Context({ "var" : obj}, autoescape= context. autoescape) \n # ... Do something with new_context ... \nこれはあまり一般的な状況ではありませんが、テンプレートを自分でレンダリングする場合に便利です。例えば:
\nCode Copy
def render ( self , context): \n t = context. template. engine. get_template( "small_fragment.html" ) \n return t. render( Context({ "var" : obj}, autoescape= context. autoescape)) \nもしこの例で、現在の context.autoescape の値を新しい Context に渡すのを怠っていたら、結果は 常に 自動的にエスケープされていたでしょう。これは、テンプレートタグが {% autoescape off %}
\n \n\nノードがパースされると、その render メソッドは何度でも呼び出されます。Django はマルチスレッド環境で実行されることがあるので、1つのノードが2つのリクエストに応答して、異なるコンテキストで同時にレンダリングされることがあります。したがって、テンプレートタグをスレッドセーフにすることが重要です。
\nテンプレートタグを常にスレッドセーフに保つため、ノード自体に状態情報を保存してはいけません。例えば、 Django にはレンダリングされる度に与えられた文字列のリストを循環させる cycle
\nDjango template Copy
{% for o in some_list %} \n < tr class = " {% cycle 'row1' 'row2' %} " > \n ...\n </ tr > \n{% endfor %} \nナイーブな CycleNode の実装は次のようになります:
\nCode Copy
import itertools \nfrom django import template\n\n\nclass CycleNode ( template. Node): \n def __init__ ( self , cyclevars): \n self . cycle_iter = itertools. cycle( cyclevars) \n\n def render ( self , context): \n return next ( self . cycle_iter) \nしかし、上のテンプレートコードを同時にレンダリングする2つのテンプレートがあるとします:
\n\nスレッド1が最初のループを実行し、 CycleNode.render() は 'row1' を返します。
スレッド2が最初のループを実行し、 CycleNode.render() は 'row2' を返します。
スレッド1が2回目のループを実行し、 CycleNode.render() は 'row1' を返します。
スレッド2が2回目のループを実行し、 CycleNode.render() は 'row2' を返します。
\nCycleNodeは反復していますが、グローバルに反復しています。スレッド1とスレッド2に関しては、常に同じ値を返しています。これは私たちが望んでいることではありません！
\nこの問題に対処するために、 Django は render_context を提供します。この render_context は、現在レンダリング中のテンプレートの context に関連付けられます。この render_context は Python の辞書のように動作し、 render メソッドを呼び出す間の Node の状態を保存するために使う必要があります。
\nCycleNode の実装を render_context を使うようにリファクタリングしましょう:
\nCode Copy
class CycleNode ( template. Node): \n def __init__ ( self , cyclevars): \n self . cyclevars = cyclevars\n\n def render ( self , context): \n if self not in context. render_context: \n context. render_context[ self ] = itertools. cycle( self . cyclevars) \n cycle_iter = context. render_context[ self ] \n return next ( cycle_iter) \nNode のライフサイクルを通して変化しないグローバルな情報を属性として保存することは完全に安全であることに注意してください。 CycleNode の場合、 Node がインスタンス化された後も cyclevars 引数は変化しないので、 render_context に格納する必要はありません。しかし、 CycleNode の現在の繰り返し処理のように、現在レンダリングされているテンプレートに固有の状態情報は render_context に格納する必要があります。
\n\n注釈
\nself を使用して render_context 内の CycleNode 固有の情報をスコープしていることに注意してください。 テンプレート内には複数の CycleNode が存在する可能性があるので、別のノードの状態情報を上書きしないよう注意する必要があります。最も簡単な方法は、常に render_context のキーとして self を使用することです。複数の状態変数を管理している場合は、 render_context[self] を辞書にします。
\n \n \n\n\n最後に、上記の カスタムテンプレートタグを書く Library インスタンスに登録します。次に例を示します。
\nCode Copy
register. tag( "current_time" , do_current_time) \ntag() メソッドは次の2つの引数を取ります。
\n\nテンプレート タグの名前の文字列。これを省略した場合は、コンパイル関数の名前が使用されます。
編集用の関数 -- Python の関数です (文字列としての関数名ではありません)。
\nフィルタ登録と同様に、これをデコレータとして使うこともできます。
\nCode Copy
@register . tag( name= "current_time" ) \ndef do_current_time ( parser, token): ... \n\n\n@register . tag\ndef shout ( parser, token): ... \nname 引数を省略した場合、上記の2番目の例と同じように、Django はタグ名として関数の名前を利用します。
\n \n\n\ntoken.split_contents() を使用するテンプレート タグには任意の個数の引数を渡せますが、引数はすべて文字列リテラルとしてアンパックされます。動的なコンテンツ (テンプレート変数) をテンプレートタグに引数として渡すためには、少し追加の作業が必要になります。
\n前の例では現在時刻を文字列にフォーマットして文字列として返しましたが、オブジェクトから DateTimeField
\nDjango template Copy
< p > This post was last updated at {% format_time blog_entry.date_updated "%Y-%m-%d %I:%M %p" %} .</ p > \n最初に、token.split_contents() が3つの値を返します。
\n\nタグ名 format_time。
文字列 'blog_entry.date_updated' (両側のクオートは含まない)
フォーマット文字列 '"%Y-%m-%d %I:%M %p"'。split_contents() からの返り値は、このように文字列リテラルの前後にクオートを含みます。
\nこれで、タグは次のようになります。
\nCode Copy
from django import template\n\n\ndef do_format_time ( parser, token): \n try : \n # split_contents() knows not to split quoted strings. \n tag_name, date_to_be_formatted, format_string = token. split_contents() \n except ValueError : \n raise template. TemplateSyntaxError( \n " %r tag requires exactly two arguments" % token. contents. split()[ 0 ] \n ) \n if not ( format_string[ 0 ] == format_string[ - 1 ] and format_string[ 0 ] in ( '"' , "'" )): \n raise template. TemplateSyntaxError( \n " %r tag's argument should be in quotes" % tag_name\n ) \n return FormatTimeNode( date_to_be_formatted, format_string[ 1 : - 1 ]) \nYou also have to change the renderer to retrieve the actual contents of the\ndate_updated property of the blog_entry object. This can be\naccomplished by using the Variable() class in django.template.
\nVariable クラスを使うには、クラスを解決されるべき変数名でインスタンス化した後に、variable.resolve(context) を呼びます。したがって、たとえば次のようになります。
\nCode Copy
class FormatTimeNode ( template. Node): \n def __init__ ( self , date_to_be_formatted, format_string): \n self . date_to_be_formatted = template. Variable( date_to_be_formatted) \n self . format_string = format_string\n\n def render ( self , context): \n try : \n actual_date = self . date_to_be_formatted. resolve( context) \n return actual_date. strftime( self . format_string) \n except template. VariableDoesNotExist: \n return "" \nページの現在のコンテキスト内で渡された文字列が解決できない場合、変数を解決しようとすると VariableDoesNotExist 例外が発生します。
\n \n\n\n上記の例は値を出力します。一般に、テンプレートタグは値を出力する代わりに、テンプレート変数を設定するほうがより柔軟です。それにより、テンプレートの作者はテンプレートタグが作成した値を再利用できるようになります。
\nコンテキスト内に変数を設定するには、render() メソッド内で、コンテキスト オブジェクト上のディクショナリ代入を使います。以下は、出力する代わりにテンプレート変数 current_time を設定する、更新されたバージョンの CurrentTimeNode です。
\nCode Copy
import datetime \nfrom django import template\n\n\nclass CurrentTimeNode2 ( template. Node): \n def __init__ ( self , format_string): \n self . format_string = format_string\n\n def render ( self , context): \n context[ "current_time" ] = datetime. datetime. now() . strftime( self . format_string) \n return "" \nrender() は空の文字列を返すことに注意してください。render() はつねに文字列の出力を返します。すべてのテンプレートタグが変数の設定だけを行う場合、render() は空の文字列を返す必要があります。
\nこの新しいバージョンのタグの使い方はこちらです。
\nDjango template Copy
{% current_time "%Y-%m-%d %I:%M %p" %} < p > The time is {{ current_time }} .</ p > \n\nコンテキスト内の変数のスコープ
\nコンテキストに設定された変数は、その変数が割り当てられたテンプレートの同じ block でのみ使用できます。 この動作は意図的なもので、他のブロックのコンテキストと衝突しないように、変数にスコープを提供します。
\n \nBut, there's a problem with CurrentTimeNode2: The variable name\ncurrent_time is hardcoded. This means you'll need to make sure your\ntemplate doesn't use {{ current_time }} anywhere else, because the\n{% current_time %} will blindly overwrite that variable's value. A cleaner\nsolution is to make the template tag specify the name of the output variable,\nlike so:
\nDjango template Copy
{% current_time "%Y-%m-%d %I:%M %p" as my_current_time %} \n< p > The current time is {{ my_current_time }} .</ p > \nそのためには、コンパイル関数と Node クラスの両方を次のようにリファクタリングする必要があります:
\nCode Copy
import re \n\n\nclass CurrentTimeNode3 ( template. Node): \n def __init__ ( self , format_string, var_name): \n self . format_string = format_string\n self . var_name = var_name\n\n def render ( self , context): \n context[ self . var_name] = datetime. datetime. now() . strftime( self . format_string) \n return "" \n\n\ndef do_current_time ( parser, token): \n # This version uses a regular expression to parse tag contents. \n try : \n # Splitting by None == splitting by spaces. \n tag_name, arg = token. contents. split( None , 1 ) \n except ValueError : \n raise template. TemplateSyntaxError( \n " %r tag requires arguments" % token. contents. split()[ 0 ] \n ) \n m = re. search( r "(.*?) as (\\w+)" , arg) \n if not m: \n raise template. TemplateSyntaxError( " %r tag had invalid arguments" % tag_name) \n format_string, var_name = m. groups() \n if not ( format_string[ 0 ] == format_string[ - 1 ] and format_string[ 0 ] in ( '"' , "'" )): \n raise template. TemplateSyntaxError( \n " %r tag's argument should be in quotes" % tag_name\n ) \n return CurrentTimeNode3( format_string[ 1 : - 1 ], var_name) \nここでの違いは、 do_current_time() がフォーマット文字列と変数名を取得し、その両方を CurrentTimeNode3 に渡していることです。
\n最後に、コンテキストを更新するカスタムテンプレートタグの簡単な構文が必要なだけなら、 simple_tag()
\n \n\n\nテンプレートタグは連動して動作します。例えば、標準の {% comment %}{% endcomment %} まですべてを隠蔽します。このようなテンプレートタグを作成するには、コンパイル関数の中で parser.parse() を使います。
\n以下は {% comment %} タグをシンプル化したものです:
\nCode Copy
def do_comment ( parser, token): \n nodelist = parser. parse(( "endcomment" ,)) \n parser. delete_first_token() \n return CommentNode() \n\n\nclass CommentNode ( template. Node): \n def render ( self , context): \n return "" \n\n注釈
\n実際の {% comment %}{% comment %} と {% endcomment %} の間に壊れたテンプレートタグを表示することを許可します。これは parser.parse(('endcomment',)) の代わりに parser.skip_past('endcomment') を呼び出し、その後に parser.delete_first_token() を実行することで、ノードリストの生成を回避しています。
\n \nparser.parse() takes a tuple of names of block tags to parse until . It\nreturns an instance of django.template.NodeList, which is a list of\nall Node objects that the parser encountered before it encountered\nany of the tags named in the tuple.
\n上の例 "nodelist = parser.parse(('endcomment',))" において、 nodelist は {% comment %} と {% endcomment %} の間にある全てのノードのリストであり、 {% comment %} と {% endcomment %} 自体は含まれません。
\nparser.parse() が呼ばれた後、パーサはまだ {% endcomment %} タグを "消費" していないので、コードは明示的に parser.delete_first_token() を呼び出す必要があります。
\nCommentNode.render() は空の文字列を返します。 {% comment %} と {% endcomment %} の間はすべて無視されます。
\n \n\n\n先ほどの例では、 do_comment() は {% comment %} と {% endcomment %} の間をすべて破棄していました。その代わりに、ブロックタグの間のコードで好きなことができます。
\n例えば、これはカスタムテンプレートタグ {% upper %} で、それ自身と {% endupper %} の間をすべて大文字にします。
\n使い方:
\nDjango template Copy
{% upper %} This will appear in uppercase, {{ your_name }} .{% endupper %} \n上の例と同様に parser.parse() を使いますが、今回は次のように、結果の nodelist を Node に渡します。
\nCode Copy
def do_upper ( parser, token): \n nodelist = parser. parse(( "endupper" ,)) \n parser. delete_first_token() \n return UpperNode( nodelist) \n\n\nclass UpperNode ( template. Node): \n def __init__ ( self , nodelist): \n self . nodelist = nodelist\n\n def render ( self , context): \n output = self . nodelist. render( context) \n return output. upper() \nここで唯一の新しい概念は、UpperNode.render() 内の self.nodelist.render(context) だけです。
\n複雑なレンダリングの追加の例としては、django/template/defaulttags.py 内の {% for %}django/template/smartif.py 内の {% if %}
\n \n ","rootId":"how-to-create-custom-template-tags-and-filters","toc":[{"title":"コードのレイアウト","anchor":"code-layout","children":[]},{"title":"独自のテンプレートフィルタを記述する","anchor":"writing-custom-template-filters","children":[{"title":"独自のフィルタを登録する","anchor":"registering-custom-filters","children":[]},{"title":"文字列を要するテンプレートフィルタ","anchor":"template-filters-that-expect-strings","children":[]},{"title":"フィルタと自動エスケープ","anchor":"filters-and-auto-escaping","children":[]},{"title":"フィルタとタイムゾーン","anchor":"filters-and-time-zones","children":[]}]},{"title":"独自のテンプレートタグを記述する","anchor":"writing-custom-template-tags","children":[{"title":"シンプルなタグ","anchor":"simple-tags","children":[]},{"title":"シンプル・ブロック・タグ","anchor":"simple-block-tags","children":[{"title":"完全な例","anchor":"a-complete-example","children":[]}]},{"title":"Inclusion tag (インクルージョン・タグ)","anchor":"inclusion-tags","children":[]},{"title":"高度なカスタムテンプレートタグ","anchor":"advanced-custom-template-tags","children":[]},{"title":"簡単な概要","anchor":"a-quick-overview","children":[]},{"title":"コンパイル関数の書き方","anchor":"writing-the-compilation-function","children":[]},{"title":"レンダラーの書き方","anchor":"writing-the-renderer","children":[]},{"title":"自動エスケープに関する注意点","anchor":"auto-escaping-considerations","children":[]},{"title":"スレッド安全性の考慮","anchor":"thread-safety-considerations","children":[]},{"title":"タグを登録する","anchor":"registering-the-tag","children":[]},{"title":"テンプレート変数をタグに渡す","anchor":"passing-template-variables-to-the-tag","children":[]},{"title":"コンテキスト内で変数を設定する","anchor":"setting-a-variable-in-the-context","children":[]},{"title":"他のブロックタグまでパースする","anchor":"parsing-until-another-block-tag","children":[]},{"title":"別のブロックタグまでのパースと内容の保存","anchor":"parsing-until-another-block-tag-and-saving-contents","children":[]}]}],"breadcrumbs":[{"docname":"howto/index","title":"How-to ガイド","url":"/ja/6.1/howto/"}],"prev":{"docname":"howto/custom-template-backend","title":"テンプレートのバックエンドをカスタマイズする","url":"/ja/6.1/howto/custom-template-backend/"},"next":{"docname":"howto/static-files/index","title":"静的ファイル (画像、JavaScript、CSS など) を管理する","url":"/ja/6.1/howto/static-files/"},"formats":{"html":"/ja/6.1/howto/custom-template-tags/","markdown":"/ja/6.1/howto/custom-template-tags.md","json":"/ja/6.1/howto/custom-template-tags.json"},"source":"https://github.com/django/django/blob/stable/6.1.x/docs/howto/custom-template-tags.txt","official":"https://docs.djangoproject.com/ja/6.1/howto/custom-template-tags/","inVersions":["6.1","6.0","5.2","5.1","5.0","4.2","4.1","4.0","3.2","3.1","3.0","2.2","2.1","2.0","1.11","1.10","1.9"],"inLocales":["en","sv","zh-hans","ga","fr","ja","id","it","pt-br","ko","es","el","pl"]}