テンプレート作者のための Django テンプレート言語ガイド

変数単位の制御

変数個々に自動エスケープを無効にするには、 safe フィルタを使います:

エスケープされる: {{ data }}
エスケープされない: {{ data|safe }}

safe という言葉を、 これ以上エスケープしないよう保護(safe)する とか、 HTML として解釈しても安全(safe)である という意味だと考えてください。 例えば、 data に '<b>' が入っていた場合、出力は以下のようになります:

エスケープされる: <b>
エスケープされない: <b>

テンプレートブロック単位の制御

テンプレートで自動エスケープを制御するには、テンプレート (または テンプレートの一部) を、以下のように autoescape タグで囲みます:

{% autoescape off %}
    こんにちは {{ name }} さん
{% endautoescape %}

autoescape タグは、 on または off を引数にとります。 テンプレートのある範囲を自動エスケープして、さらにその一部で自動エスケープ を切りたい場合には、以下のように入れ子にできます:

Auto-escaping is on by default. Hello {{ name }}

{% autoescape off %}
    This will not be auto-escaped: {{ data }}.

    Nor this: {{ other_data }}
    {% autoescape on %}
        Auto-escaping applies again: {{ name }}
    {% endautoescape %}
{% endautoescape %}

自動エスケープのタグは、他のブロックタグと同様、タグを設定したテンプレート を継承している他のテンプレートや、 include で取り込んだテンプレートでも 有効です。例えば:

# base.html

{% autoescape off %}
<h1>{% block title %}{% endblock %}</h1>
{% block content %}
{% endautoescape %}
{% endblock %}

# child.html

{% extends "base.html" %}
{% block title %}This & that{% endblock %}
{% block content %}{{ greeting }}{% endblock %}

自動エスケープがベースのテンプレートで無効化されているので、子テンプレート でも自動エスケープは無効化されます。結果として、 greeting 変数の値が <b>Hello!</b> の時には以下の HTML がレンダされます:

<h1>This & that</h1>
<b>Hello!</b>

autoescape

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

自動エスケープ機能を制御します。このタグは引数に on または off を取 り、ブロック内の自動エスケープの有効・無効を決定します。

自動エスケープがオンの場合、変数の値は全て、最終的な文字列出力になる直前に HTML エスケープされます (他のフィルタは先に適用されます)。この動作は、 変数に escape フィルタを手動で適用した場合と同じです。

例外として、変数をテンプレートに挿入するコードや、 safe, escape と いったフィルタの適用によって、 "safe" マーク済みの変数はエスケープされませ ん。

block

子テンプレートでオーバライドできるブロックを定義します。 テンプレートの継承 を参照してください。

comment

{% comment %} から {% endcomment %} までの内容を全て無視します。

cycle

開発版の Django で機能が変更されました

タグを処理するごとに、指定した文字列や変数を循環して返します。

ループの中では、ループごとに指定した文字列や変数を循環して返します:

{% for o in some_list %}
    <tr class="{% cycle 'row1' 'row2' rowvar %}">
        ...
    </tr>
{% endfor %}

ループの外側では、最初に一意な名前を与えておき、以後はその名前を使います。 例えば:

<tr class="{% cycle 'row1' 'row2' rowvar as rowcolors %}">...</tr>
<tr class="{% cycle rowcolors %}">...</tr>
<tr class="{% cycle rowcolors %}">...</tr>

任意の個数の値を使えます。値はスペースで区切ります。値をクオート (') または二重クオート (") で囲むと、文字列リテラルとして扱います。 クオートされていない値はコンテキスト変数への参照とみなされます。

値をカンマで区切った形式もつかえます:

{% cycle row1,row2,row3 %}

ただし、この構文では、値は全てリテラルテキストとして扱われます。 カンマを使った構文は以前のバージョンとの互換性のために残されています。 新たなプロジェクトでは使わないようにしてください。

debug

現在のコンテキストや import されたモジュールなどを含んだデバッグ情報ひと揃 いを出力します。

extends

このテンプレートが親テンプレートに対する拡張であることを指示します。

このタグには 2 種類の使い方があります:

• {% extends "base.html" %} (引用符つき) のような場合、リテラル値 "base.html" を親テンプレートの名前として使います。
• {% extends variable %} のようにすると、 variable の値を親テンプ レートの名前として使います。 variable の値が文字列の場合、 Django はその文字列を親テンプレートの名前として使います。値が Template オ ブジェクトの場合、Django はそのオブジェクトを親テンプレートにします。

詳しくは テンプレートの継承 を参照してください。

filter

タグのコンテンツを変数フィルタ (variable filter) を使ってフィルタします。

フィルタはパイプでつないで連鎖でき、引数をもたせることができます。

使用例:

{% filter force_escape|lower %}
    This text will be HTML-escaped, and will appear in all lowercase.
{% endfilter %}

firstof

タグに渡された変数のうち、False でない最初の変数の値を出力します。全ての変 数が False であった場合、何も出力しません。

使用例:

{% firstof var1 var2 var3 %}

上は、以下のテンプレートと等価です:

{% if var1 %}
    {{ var1 }}
{% else %}{% if var2 %}
    {{ var2 }}
{% else %}{% if var3 %}
    {{ var3 }}
{% endif %}{% endif %}{% endif %}

また、全ての変数が False の場合のフォールバック値としてリテラル文字列を指定 できます:

{% firstof var1 var2 var3 "fallback value" %}

for

アレイの各要素に渡ってループします。例えば、アスリート (athlete) のリストを athlete_list で渡して表示するには:

<ul>
{% for athlete in athlete_list %}
    <li>{{ athlete.name }}</li>
{% endfor %}
</ul>

のようにします。

{% for obj in list reversed %} のようにすると、リストに対して逆順のルー プを実行できます。

開発バージョンの Django で新たに登場した機能です。

リストのリストにわたってループ処理を行う場合、各サブリストをアンパックして、 個別に名前を割り当てられます。例えば、座標 (x, y) のリストが入った points というコンテキスト変数があり、各座標を出力したい場合には以下のよ うにします:

{% for x, y in points %}
    座標 {{ x }},{{ y }} が登録されています。
{% endfor %}

この方法は、辞書の各要素にアクセスしたい場合にも便利です。例えば、コンテキ スト変数 data に辞書が入っている場合。以下のようにすれば辞書内のキーと 値を表示できます:

{% for key, value in data.items %}
    {{ key }}: {{ value }}
{% endfor %}

for ループは、ループの各回ごとに使える変数を設定します:

変数名	説明
forloop.counter	現在のループ回数番号 (1 から数えたもの)
forloop.counter0	現在のループ回数番号 (0 から数えたもの)
forloop.revcounter	末尾から数えたループ回数番号 (1 から数えたもの)
forloop.revcounter0	末尾から数えたループ回数番号 (0 から数えたもの)
forloop.first	最初のループであれば True になります
forloop.last	最後のループであれば True になります
forloop.parentloop	入れ子のループの場合、一つ上のループを表します

if

変数を評価して、値が「真」 (値が存在して、空の配列でなく、ブール値が偽でな い) の場合、ブロック内のコンテンツを出力します:

{% if athlete_list %}
    Number of athletes: {{ athlete_list|length }}
{% else %}
    No athletes.
{% endif %}

上の例では、 athlete_list が空でなければ、アスリートの人数を {{ athlete_list|length }} で表示します。

例にもあるように、 if タグにはオプションの {% else %} 節があり、テ ストに失敗した場合に表示されるコンテンツを定義できます。

and や or で複数の変数をチェックしたり、 not で否をとったりでき ます:

{% if athlete_list and coach_list %}
    Both athletes and coaches are available.
{% endif %}

{% if not athlete_list %}
    There are no athletes.
{% endif %}

{% if athlete_list or coach_list %}
    There are some athletes or some coaches.
{% endif %}

{% if not athlete_list or coach_list %}
    There are no athletes or there are some coaches (OK, so
    writing English translations of boolean logic sounds
    stupid; it's not our fault).
{% endif %}

{% if athlete_list and not coach_list %}
    There are some athletes and absolutely no coaches.
{% endif %}

{% if athlete_list and not coach_list %}
    There are some athletes and absolutely no coaches.
{% endif %}

and と or 節を同じタグの中に入れると、ロジックの優先順位があいまい になるため、 同じ if タグには入れられません。例えば、以下のテンプレート は無効です:

{% if athlete_list and coach_list or cheerleader_list %}

and タグと or タグを使ったロジックを行いたければ、以下の例のように if タグを入れ子にしてください:

{% if athlete_list %}
    {% if coach_list or cheerleader_list %}
        We have athletes, and either coaches or cheerleaders!
    {% endif %}
{% endif %}

同じ論理記号はいくつでも並べられます。ただし、同じ演算子を使う場合に限りま す。例えば、以下は有効なテンプレートです:

{% if athlete_list or coach_list or parent_list or teacher_list %}

ifchanged

ブロック内のコンテンツが直前のループと違う値になるかどうか調べます。

ifchanged ブロックタグはループの中で使います。このタグには二通りの使い 方があります。

1. ブロック内のレンダリング対象コンテンツを直前のループでの状態と比較して、 内容が変化している場合にのみコンテンツを表示する場合です。たとえば、日付 のリストを表示するときに、月が変わったときだけ月名を表示したければ以下の ようにします:

   <h1>Archive for {{ year }}</h1>
   
   {% for date in days %}
       {% ifchanged %}<h3>{{ date|date:"F" }}</h3>{% endifchanged %}
       <a href="{{ date|date:"M/d"|lower }}/">{{ date|date:"j" }}</a>
   {% endfor %}
   

2. タグに引数を指定すると、変数が変化したかどうかを調べます。例えば、以下の 例では日付が変化したときに日付を表示し、日付と時刻が同時に変化したときの み時刻も表示します:

   {% for date in days %}
       {% ifchanged date.date %} {{ date.date }} {% endifchanged %}
       {% ifchanged date.hour date.date %}
           {{ date.hour }}
       {% endifchanged %}
   {% endfor %}
   

ifequal

2 つの引数が互いに等しい場合にブロックの内容を出力します。

例:

{% ifequal user.id comment.user_id %}
    ...
{% endifequal %}

{% if %} タグと同様、オプションで {% else %} 節を使えます。

引数はハードコードされた文字列でもよいので、以下のような表現は有効です:

{% ifequal user.username "adrian" %}
    ...
{% endifequal %}

引数と比較できるのは、テンプレート変数または文字列だけです。 True や False のような、 Python オブジェクトに対する等価比較は行えません。 True や False との比較を行いたければ if を使ってください。

ifnotequal

2 つの引数が互いに等しくない場合にブロックの内容を出力します。

include

テンプレートをロードして、現在のコンテキストを使ってレンダリングします。あ るテンプレートに別のテンプレートを取り込む ("include") 方法の一つです。

テンプレート名はハードコードされた (引用符で囲った) 文字列でもよく、引用符 は一重でも二重でもかまいません。

以下の例では、 "foo/bar.html" という名前のテンプレートを取り込みます:

{% include "foo/bar.html" %}

次の例では、 変数 template_name に入っている名前のテンプレートを取り込 みます:

{% include template_name %}

取り込まれたテンプレートは、取り込んだ側で使われているコンテキストの下でレ ンダリングされます。下の例では "Hello, John" を出力します:

• コンテキスト: 変数 person を "john" に設定

• テンプレート:

  {% include "name_snippet.html" %}
  

• name_snippet.html テンプレート:

  Hello, {{ person }}
  

{% ssi %} も参照してください。

load

カスタムのテンプレートタグリストを読み込みます。

詳しくは カスタムタグとカスタムフィルタのライブラリ を参照してください。

now

指定したフォーマット文字列にしたがって現在の日時を表示します。

フォーマットは PHP の date() 関数 (http://php.net/date) と同じで、いく つかの点で拡張されています。

利用できるフォーマットを示します:

フォーマット文字	説明	出力例
a	'a.m.' または 'p.m.' (Associated Press に合わせるため、'.' が入っている点 が PHP と違います)。	'a.m.'
A	'AM' または 'PM' です。	'AM'
b	3 文字の小文字で表した月名です。	'jan'
B	実装されていません。
d	月の中の日。 2 桁のゼロ詰めです。	'01' から '31'
D	週の中の日。 3 文字のテキスト形式です。	'Fri'
f	12 時間表記の時と分。ただし、ゼロ分の 場合には表示しません。独自の拡張です。	'1', '1:30'
F	月名を長いテキスト形式で表したものです。	'January'
g	12 時間表記の時。ゼロ詰めはしません。	'1' から '12'
G	24 時間表記の時。ゼロ詰めはしません。	'0' から '23'
h	12 時間表記の時です。	'01' から '12'
H	24 時間表記の時です。	'00' から '23'
i	分です。	'00' から '59'
I	実装されていません。
j	月の中の日。ゼロ詰めしません。	'1' から '31'
l	週の中の曜日。長いテキスト形式です。	'Friday'
L	閏年かどうかを表すブール値です。	True または False
m	月です。2 桁でゼロ詰めしたものです。	'01' から '12'
M	月です。3 文字のテキスト形式です。	'Jan'
n	月です。ゼロ詰めしません。	'1' から '12'
N	Associated Press スタイルの月の省略表記 です。独自の拡張です。	'Jan.', 'Feb.', 'March', 'May'
O	グリニッジ標準時からの時差です。	'+0200'
P	時刻です。12 時間表記の時、分、 そして 'a.m.'/'p.m.' です。分がゼロの 場合には省略され、必要に応じて 'midnight' または 'noon' になります。 独自の拡張です。	'1 a.m.', '1:30 p.m.', 'midnight', 'noon', '12:30 p.m.'
r	RFC 2822に従ったフォーマットの日時です。	'Thu, 21 Dec 2000 16:01:07 +0200'
s	秒です。 2 桁のゼロ詰めです。	'00' から '59'
S	月の中の日につける 2 文字の序数接尾辞 です。	'st', 'nd', 'rd' or 'th'
t	月の日数です。	28 から 31
T	計算機のタイムゾーン設定です。	'EST', 'MDT'
U	実装されていません。
w	週の中の曜日です。ゼロ詰めしません。	'0' (Sunday) to '6' (Saturday)
W	ISO-8601 に従った年の中の週番号です。 週は月曜日から始まります。	1, 53
y	2 桁の年です。	'99'
Y	4 桁の年です。	'1999'
z	年の中の日	0 から 365
Z	タイムゾーンオフセットを秒であらわした ものです。UTC よりも西側のタイムゾーン値 は全て負の値になり、東側の値は常に正に なります。	-43200 から 43200

例:

It is {% now "jS F Y H:i" %}

フォーマット文字列中で普通の文字列を使いたければ、バックスラッシュでエスケー プできます。下の例では、"f" が時刻を表すフォーマット指定子として解釈されな いようにエスケープしています。 "o" はフォーマット指定子ではないのでエスケー プしていません:

It is the {% now "jS o\f F" %}

このテンプレートをレンダすると "It is the 4th of September" になります。

regroup

オブジェクトのリストから、属性値によって同種のオブジェクトをまとめます。

この難解なタグを説明するには、例を使うのが一番でしょう: 仮に、複数人の情報 の入った people というリストがあり、各人の情報は first_name, last_name, および gender といったキーを持つ辞書で表されているとしま しょう:

people = [
    {'first_name': 'George', 'last_name': 'Bush', 'gender': 'Male'},
    {'first_name': 'Bill', 'last_name': 'Clinton', 'gender': 'Male'},
    {'first_name': 'Margaret', 'last_name': 'Thatcher', 'gender': 'Female'},
    {'first_name': 'Condoleezza', 'last_name': 'Rice', 'gender': 'Female'},
    {'first_name': 'Pat', 'last_name': 'Smith', 'gender': 'Unknown'},
]

このデータを、以下のように性別ごとに階層化して表示したいとします:

* Male:
    * George Bush
    * Bill Clinton
* Female:
    * Margaret Thatcher
    * Condoleezza Rice
* Unknown:
    * Pat Smith

{% regroup %} タグを使うと、 people を性別ごとにグループ化できます。 以下のようなテンプレートを使って実現します:

{% regroup people by gender as gender_list %}
<ul>
{% for gender in gender_list  %}
    <li>{{ gender.grouper }}
    <ul>
        {% for item in gender.list %}
        <li>{{ item.first_name }} {{ item.last_name }}</li>
        {% endfor %}
    </ul>
    </li>
{% endfor %}
</ul>

例を順番に見てゆきましょう。 {% regroup %} は 3 つの引数をとります。最 初は再グループ化 (regroup) したいリスト、二つめはグループ化に使う属性やキー の名前、そして最後は再グループ化後のリストにつける名前です。ここでは、 gender キーを使って people を再グループ化し、 gender_list とい う名前で参照できるようにしています。

{% regroup %} は グループオブジェクト のリストを生成して返します (この場合は gender_list です)。グループオブジェクトには二つの属性があり ます:

• grouper -- グループ化している項目 (例えば "Male" や "Female" といっ た文字列) です。
• list -- グループ内の全ての要素からなるリスト (例えば、 gender='Male' の人全員からなるリスト) です。

{% regroup %} は入力をソートしないので注意してください! 上の例では、 リスト people はあらかじめ gender でソート済みという前提に立ってい ます。 people が gender の順に並んで いない 場合、再グループは何 も考えずに一つの性別のグループを複数つくってしまいます。例えば、 people が以下のように ('Male' がリスト内でまとまっていない状態に) なっていたと しましょう:

people = [
    {'first_name': 'Bill', 'last_name': 'Clinton', 'gender': 'Male'},
    {'first_name': 'Pat', 'last_name': 'Smith', 'gender': 'Unknown'},
    {'first_name': 'Margaret', 'last_name': 'Thatcher', 'gender': 'Female'},
    {'first_name': 'George', 'last_name': 'Bush', 'gender': 'Male'},
    {'first_name': 'Condoleezza', 'last_name': 'Rice', 'gender': 'Female'},
]

この people を入力に使うと、上の {% regroup %} のテンプレートコード 例は以下のような出力を生成します:

* Male:
    * Bill Clinton
* Unknown:
    * Pat Smith
* Female:
    * Margaret Thatcher
* Male:
    * George Bush
* Female:
    * Condoleezza Rice

こうした落し穴を解決したければ、ビューコード内であらかじめデータを表示した い順番に並べておくのが最も簡単でしょう。

データが辞書の列の場合には、もう一つの解決策として、テンプレートの中で dictsort フィルタを使ってデータを並べ変えられます:

{% regroup people|dictsort:"gender" by gender as gender_list %}

spaceless

ブロック内の HTML タグ間にある空白文字を除去します。タブ文字や改行も含みま す。

使用例:

{% spaceless %}
    <p>
        <a href="foo/">Foo</a>
    </p>
{% endspaceless %}

上の例は下のような HTML になります:

<p><a href="foo/">Foo</a></p>

タグ間の 空白だけが正規化されます -- タグとテキストの間のスペースは正規化

しません。下の例では、 Hello の周りの空白をはぎとりません:

{% spaceless %}
    <strong>
        Hello
    </strong>
{% endspaceless %}

ssi

指定したファイルの内容をページ内に取り込みます。

"inlcude" タグと同様、 {% ssi %} は別のファイルの内容を取り込みます。引 数は絶対パスで指定せねばなりません:

{% ssi /home/html/ljworld.com/includes/right_generic.html %}

オプションの "parsed" パラメタを指定すると、取り込まれたファイルを現在のコ ンテキストのテンプレートコードとして評価します:

{% ssi /home/html/ljworld.com/includes/right_generic.html parsed %}

{% ssi %} を使う場合には、セキュリティの観点から、 Django の設定に ALLOWED_INCLUDE_ROOTS を定義しておく必要があるでしょう。

See also: {% include %}.

templatetag

テンプレートタグの構成に使われる文字自体を出力します。

Django のテンプレートには「エスケープ」の概念がないので、テンプレートタグの 構成に使われている要素を出力したければ {% templatetag %} タグを使わねば なりません。

引数にはどの要素出力するかを指定します:

Argument	Outputs
openblock	{%
closeblock	%}
openvariable	{{
closevariable	}}
openbrace	{
closebrace	}
opencomment	{#
closecomment	#}

url

このタグの構文は、より堅牢さを増すために将来変更される可能性があります。

ビュー関数とオプションのパラメタを指定すると、絶対 URL (ドメイン名のない URL) を返します。これによって、テンプレートに URL をハードコードするような DRY 則の侵犯を避けられます:

{% url path.to.some_view arg1,arg2,name1=value1 %}

第一引数はビュー関数へのパスで、 package.module.function のよう な形式で指定します。それ以降の引数はオプションで、カンマで区切って指定しま す。引数はそれぞれビューの固定引数やキーワード引数になります。 URLconf に指 定されている引数全てを指定せねばなりません。

例えば、 app_views.client という名前のビューがあり、クライアントの ID を引数に取るとしましょう (client() は app_views.py で定義されている メソッドです)。 URLconf は以下のようになるはずです:

('^client/(\d+)/$', 'app_views.client')

あるアプリケーションの URLconf が、プロジェクトの URLconf に以下のような形 で include されていたとします:

('^clients/', include('project_name.app_name.urls'))

テンプレート内では、以下のようにしてビューへのリンクを生成できます:

{% url app_views.client client.id %}

結果的に、テンプレートは /clients/client/123/ のような文字列を生成しま す。

開発バージョンで新たに登場した機能です: 名前つき URL パターン を使っている場合、 url タグにはビューのパス名 の代わりにパターン名を指定できます。

widthratio

バーチャートなどを生成する場合のために、指定した値と最大値との比を計算し、 定数に掛けた値を返します。

例えば:

<img src="bar.gif" height="10"
 width="{% widthratio this_value max_value 100 %}" />

のようにすると、 this_value が 175 で max_value が 200 の場合には、 (175/200 = .875; .875 * 100 = 87.5 で、88 に丸めた結果) 画像の幅は 88 ピク セルになります。

with

開発バージョンの Django で新たに登場した機能です。

複雑な表記の変数の値をキャッシュします。また、簡単な名前で参照できるように します。呼出しコストの高いメソッド (例えばデータベースを操作するようなメソッ ド) に何度もアクセスする際に便利です。

以下に例を示します:

{% with business.employees.count as total %}
    {{ total }} employee{{ total|pluralize }}
{% endwith %}

値を組み込んだ変数 (上の例でいえば total) は {% with %} と {% endwith %} タグの間でだけ使えます。

add

入力値に対して引数の値を加算します。

使用例:

{{ value|add:"2" }}

value が 4 なら、出力は 6 になるでしょう。

addslashes

入力値のクオートの前にスラッシュを追加します。CSV などの文字列をエスケープ する際に便利です。

開発版の Django で新たに登場した機能: JavaScript のエスケープには、 escapejs フィルタを使ってください。

capfirst

入力値の先頭の文字を大文字に変換します。

center

入力値を引数に指定された幅のフィールド内に中央寄せします。

cut

入力値の中から引数に指定した値を全て除去します。

使用例:

{{ value|cut:" "}}

value が "String with spaces" なら、出力は "Stringwithspaces" に なるでしょう。

date

引数に指定した書式で日付をフォーマットします。 (now タグと同じです)

使用例:

{{ value|date:"D d M Y" }}

value が datetime オブジェクト (例えば、 datetime.datetime.now() の戻り値) ならば、 出力は文字列 'Wed 09 Jan 2008' になります。

default

入力の評価値が False の場合、引数に指定したデフォルト値を使います。そうで なければ、入力値を使います。

使用例:

{{ value|default:"nothing" }}

value が "" (空文字列)ならば、出力は nothing になります。

default_if_none

値が None の場合、かつその場合のみ、引数に指定したデフォルト値を使いま す。そうでなければ、入力値を使います。

空文字列を入力した場合には、デフォルト値を使わ ない ので注意してくださ い。空文字列をフォールバックしたければ default フィルタを使ってください。

使用例:

{{ value|default_if_none:"nothing" }}

value が None ならば、出力は文字列 "nothing" になります。

dictsort

辞書のリストを入力に取り、引数に指定したキーでリストをソートして返します。

使用例:

{{ value|dictsort:"name" }}

value が以下のようだったとします:

[
    {'name': 'zed', 'age': 19},
    {'name': 'amy', 'age': 22},
    {'name': 'joe', 'age': 31},
]

出力は以下のようになるでしょう。:

[
    {'name': 'amy', 'age': 22},
    {'name': 'joe', 'age': 31},
    {'name': 'zed', 'age': 19},
]

dictsortreversed

辞書のリストを入力に取り、引数に指定したキーでリストを逆順にソートして返し ます。上のフィルタと全く同じ処理をしますが、返す値は逆順です。

divisibleby

値を引数で除算できる場合に True を返します。

使用例:

{{ value|divisibleby:"3" }}

value が 21 なら、出力は True になります。

escape

開発版の Django で新たに登場した機能: 開発版では、このフィルタの挙動は 少し変更されています (このフィルタは、他の全てのフィルタの後に適用されます)

入力文字中の HTML 特有の文字をエスケープします。具体的には、以下のような置 換を行います:

• < は "&lt;" に変換されます。
• > は "&gt;" に変換されます。
• "'" (クオート) は '&#39;' に変換されます。
• '"' (二重クオート) は '&quot;' に変換されます。
• "&" は "&amp;" に変換されます。

エスケープは最終的な文字列出力を生成する時に適用されます。従って、フィルタ を連鎖している場合、連鎖のどこにフィルタが置かれていても、フィルタの最後の 段階でエスケープ処理が行われます。エスケープを即座に適用したければ、 force_escape フィルタを使ってください。

すでに自動エスケープが施された変数に escape を適用しても、結果的には一 度しかエスケープを行いません。従って、自動エスケープ環境で escape を呼び出しても問題はありません。意図的に複数回エスケープを施したければ、 force_escape フィルタを使ってください。

開発版の Django で新たに登場した機能: 自動エスケープの導入によって、 このフィルタの挙動は少し変更されました。フィルタによる置き換えは、他の (前 後のフィルタを含め)全てのフィルタを適用した後に一度だけ行われます。

escapejs

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

JavaScript の文字列リテラルとして扱うために文字エスケープを行います。エスケー プ結果は、 HTML としては安全 ではありません が、JavaScrpt/JSON を生成する テンプレートの出力が構文エラーを引き起こすのを防げます。

filesizeformat

ファイルサイズを「目に優しい (human-readable)」表現 ('13 KB', '4.1 MB', '102 bytes' など) に変換します。

使用例:

{{ value|filesizeformat }}

value が 123456789 なら、出力は 117.7 MB になります。

first

リスト中の最初の要素を返します。

使用例:

{{ value|first }}

value がリスト ['a', 'b', 'c'] なら、出力は 'a' になります。

fix_ampersands

アンパーサンド ("&") を &amp; エンティティで置き換えます。

使用例:

{{ value|fix_ampersands }}

value が Tom & Jerry なら、出力は Tom &amp; Jerry になります。

開発版の Django で新たに追加された機能です: アンパーサンドはテンプレー ト内で自動的にエスケープされるようになったので、このフィルタはもはやあまり 役にたたなくなりました。自動エスケープの仕組みは escape を参照してください。

floatformat

引数を指定せずに使うと、小数部がある場合に限り、浮動小数点数を小数点以下ひ と桁でまるめます。例えば:

整数の引数を指定すると、 floatformat は小数部を指定の桁数で丸めます。例 えば:

floatformat の引数に負の数を指定した場合、小数部がある場合に限り、小数 部を指定の桁数で丸めます。例えば:

従って、引数なしの floatformat は -1 を引数に指定した場合と同じにな ります。

force_escape

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

文字列に HTML エスケープを適用します。 (詳しくは escape フィルタを参照 してください)。フィルタは 即座に 適用され、新たなエスケープ済みの文字列を 返します。このタグが有用なケースは稀で、エスケープ済みの結果に対して他のフィ ルタを適用したいような、複数回エスケープが必要な場合に使われるにすぎません。 通常は escape フィルタをつかうことになるでしょう。

get_digit

入力が整数の場合、引数に指定した桁の数字を返します。 1 は右はじの桁、2 は右 から 2 つ目の桁、といった具合に指定します。入力が整数でない場合には、入力値 をそのまま返します。

使用例:

{{ value|get_digit:"2" }}

value が 123456789 なら、出力は 8 になります。

iriencode

IRI (国際化リソース識別子 Internationalized Resource Identifier) を URL 埋め込みに適した文字列に変換します。非 ASCII 文字列を URL に埋め込む 場合に必要なフィルタです。

urlencode フィルタを通した文字列をこのフィルタに通しても問題はありませ ん。

join

Python の str.join(list) と同じく、リストを文字列でつなぎます。

使用例:

{{ value|join:" // " }}

value がリスト ['a', 'b', 'c'] なら、出力は文字列 "a // b // c" に なります。

last

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

リストの末尾の要素を返します。

使用例:

{{ value|last }}

value がリスト ['a', 'b', 'c', 'd'] なら、出力は文字列 "d" になり ます。

length

入力値の長さを返します。文字列とリストいずれにも作用します。

使用例:

{{ value|length }}

value が ['a', 'b', 'c', 'd'] なら、出力は 4 になります。

length_is

入力値の長さと引数が等しければ True を返し、そうでなければ False を 返します。

使用例:

{{ value|length_is:"4" }}

value が ['a', 'b', 'c', 'd'] なら、出力は True になります。

linebreaks

プレーンテキストの改行を適切な HTML タグに変換します。 改行 1 つは HTML 改行 (<br />) タグ、改行と空行はパラグラフ 改行 (<p>) に変換します。

使用例:

{{ value|linebreaks }}

value が Joel\nis a slug なら、出力は <p>Joe<br>is a slug</p> になります。

linebreaksbr

プレーンテキストの改行を HTML の改行 (<br />) タグに変換します。

linenumbers

テキストを行番号付きで表示します。

ljust

入力値を指定幅のフィールド内に左詰めします。

引数: フィールドの幅

lower

文字列を全て小文字に変換します。

使用例:

{{ value|lower }}

value が Still MAD At Yoko なら、出力は still mad at yoko にな ります。

make_list

入力値をリストに変換します。整数の場合には各桁の数字からなるリストに、文字 列の場合は各文字からなるリストに変換します。

使用例:

{{ value|make_list }}

value が文字列 "Joe" なら、出力はリスト [u'J', u'o', u'e'] にな ります。 value が 123 なら、出力はリスト [1, 2, 3] になります。

phone2numeric

電話番号 (文字を含む場合もあります) を数値だけの番号に変換します。例えば、 '800-COLLECT' は '800-2655328' になります。

入力値は正しい電話番号でなくてもかまいません。このフィルタはどんな文字列で も変換します。

pluralize

値が 1 でない場合に、複数形を表す接尾辞を付けます。デフォルトでは、接尾辞は 's' です。

例:

You have {{ num_messages }} message{{ num_messages|pluralize }}.

's' 以外の接尾辞が必要な場合、フィルタのパラメタに指定できます。

例:

You have {{ num_walruses }} walrus{{ num_walrus|pluralize:"es" }}.

単なる接尾辞だけで複数形化できない場合、単数形と複数形の接尾辞の両方をコン マで区切って指定できます。

例:

You have {{ num_cherries }} cherr{{ num_cherries|pluralize:"y,ies" }}.

pprint

pprint.pprint のラッパです -- 単なるデバッグ用にすぎません。

random

与えられたリストからランダムな要素を返します。

使用例:

{{ value|random }}

value がリスト ['a', 'b', 'c', 'd'] なら、出力は "b" かもしれません。

removetags

入力から引数に指定された [X]HTML タグを除去します。タグはスペースで区切って 指定します。

使用例:

{{ value|removetags:"b span"|safe }}

value が "<b>Joel</b> <button>is</button> a <span>slug</span>" なら、 出力は "Joel <button>is</button> a slug" になります。

rjust

指定幅のフィールドに右詰めします。

引数: フィールドの幅

safe

文字列に対して、さらなるエスケープが必要でないことをマークするのに使います。 autoescaping がオフの場合、このフィルタは何もしません。

slice

リストに対するスライスを返します。

Python におけるリストのスライスと同じ構文を使います。スライスについて学びた ければ、 http://diveintopython.org/native_data_types/lists.html#odbchelper.list.slice を読んで下さい。

例: {{ some_list|slice:":2" }}

slugify

入力を小文字に変換し、語でない (英数字またはアンダースコアでない) 文字を除 去し、スペースをハイフンに変換します。また、先頭と末尾の空白をはぎとります。

使用例:

{{ value|slugify }}

value が "Joel is a slug" なら、出力は "joel-is-a-slug" になり ます。

stringformat

引数に指定されたフォーマット指示子に従って変数をフォーマットします。フォー マット指示子は Python のフォーマット指示構文と同じですが、先頭の "%" は必要 ありません。

Python の文字列フォーマットについては http://www.python.jp/doc/release/lib/typesseq-strings.html を参照してくださ い。

使用例:

{{ value|stringformat:"s" }}

value が "Joel is a slug" なら、出力は "Joel is a slug" になり ます。

striptags

[X]HTML タグを全てはぎとります。

使用例:

{{ value|striptags }}

value が "<b>Joel</b> <button>is</button> a <span>slug</span>" なら、 出力は "Joel is a slug" になります。

time

時刻を指定の書式でフォーマットします (now タグと同じです)。 time フィルタの引数は、時刻に関するフォーマット文字しか受け付けません (理由は言うまでもありませんよね)。日付のフォーマットを行いたければ date フィルタを使ってください。

使用例:

{{ value|time:"H:i" }}

value が datetime.datetime.now() と同等な値なら、出力は文字列 "01:23" なります。

timesince

日付を経過時間の形式にフォーマットします (例えば、 "4 days, 6 hours") 。

オプションの引数として、 比較対象として使う時刻をとります (引数を省略すると 現在時刻 を使います)。例えば、 blog_date が 1 June 2006 を表す日 付オブジェクトで、 comment_date が 08:00 on 1 June 2006 を表す日時 オブジェクトの場合、 {{ comment_date|timesince:blog_date }} は "8 hours" を返します。

最小の単位は分で、比較対象の時刻より以前の時刻に対しては "0 minutes" を返します。

timeuntil

timesince に似ていますが、現在時刻から指定の日付または日時までの時刻を 計算します。

例えば、現在の日付が 1 June 2006 で、 conference_date が 29 June 2006 の場合、 {{ conference_date|timeuntil }} は "4 weeks" を返します。

オプションの引数として、 (現在時刻 の代わりに) 比較対象として使う時刻をと ります。 例えば、 from_date が 22 June 2006 の場合、 {{ conference_date|timeuntil:from_date }} は "1 week" を返します。

最小の単位は分で、比較対象の時刻より以前の時刻に対しては "0 minutes" を返します。

title

文字列をタイトルケースに変換します。

truncatewords

文字列を指定語数以下になるように切り詰めます。

引数: 文字列を切り詰めるまでの語数

使用例:

{{ value|truncatewords:2 }}

value が "Joel is a slug" なら、出力は "Joel is ..." になります。

truncatewords_html

truncatewords に似ていますが、 HTML タグを正しく扱えます。切り詰めを行 う時点で閉じていないタグがあれば、切り詰めた文字の直後に全て閉じます。

このタグの処理は truncatewords よりもやや非効率なので、 HTML テキストを 渡す場合にだけ使うようにしてください。

unordered_list

再帰的に入れ子になったリストを入力にとり、 HTML の無番号リスト (UL, unordered list) に変換します。**ただし**、最も外側の <ul> タグは表示しませ ん。

開発版の Django の新機能です: unordered_list の引数の形式は、より分 かりやすく変更されました。

リストは適切な形式になっているものとみなします。例えば、 var が ['States', ['Kansas', ['Lawrence', 'Topeka'], 'Illinois']] であれば、 {{ var|unordered_list }} は以下のようになります:

<li>States
<ul>
        <li>Kansas
        <ul>
                <li>Lawrence</li>
                <li>Topeka</li>
        </ul>
        </li>
        <li>Illinois</li>
</ul>
</li>

ノート: 以前の、より杓子定規で冗長な形式、 ['States', [['Kansas', [['Lawrence', []], ['Topeka', []]]], ['Illinois',[]]]] も継続してサポートしています。

upper

入力値をすべて大文字に変換します。

使用例:

{{ value|upper }}

value が "Joel is a slug" なら、出力は "JOEL IS A SLUG" になり ます。

urlencode

入力値を URL で使えるようにエスケープします。

urlize

平文で書かれた URL をクリック可能なリンクに変換します。

HTML マークアップの入ったテキストに urlize を適用すると、予想通りの出力 を得られない場合があるので注意してください。このフィルタは 素の テキスト に対してだけ使ってください。

使用例:

{{ value|urlize }}

value が "Check out www.djangoproject.com" なら、出力は "Check out <a href="http://www.djangoproject.com">www.djangoproject.com</a>" になります。

urlizetrunc

URL をクリック可能なリンクに変換します。このとき、指定の文字数以上の URL を 切り詰めます。

urlize と同様、このフィルタは 素の テキストに対してだけ使ってください。

引数: URL を切り詰める長さ

使用例:

{{ value|urlizetrunc:15 }}

value が "Check out www.djangoproject.com" なら、出力は 'Check out <a href="http://www.djangoproject.com">www.djangopr...</a>' になります。

wordcount

語数を返します。

wordwrap

指定した行幅で語列をラップします。

引数: テキストをラップするまでの語数

使用例:

{{ value|wordwrap:5 }}

value が Joel is a slug なら、出力はこうなります:

Joel
is a
slug

yesno

入力値 (真、偽、オプションで None) に応じて、引数に指定した文字のいずれかを 返します。