組み込みテンプレートタグとフィルタ¶
このドキュメントでは、 Django の組み込みテンプレートタグとフィルタについて述べます。 また 自動ドキュメンテーション を使えばインストールされている組み込みタグとカスタムタグのドキュメントを読めるのでお勧めです。
組み込みタグリファレンス¶
autoescape¶
自動エスケープ機能を制御します。このタグは引数に on または off を取り、ブロック内の自動エスケープの有効・無効を決定します。ブロックの最後は endautoescape タグで閉じるようにします。
使用例：
{% autoescape on %}
{{ body }}
{% endautoescape %}
自動エスケープがオンの場合、すべての変数由来の値を出力前に HTML エスケープします (他のフィルタはエスケープの前に適用されます)。この動作は、変数に escape フィルタを手動で適用した場合と同じです。
ただ一つの例外は、すでにエスケープに関して "safe" としてマークされている変数です。変数は、その変数に値を代入するコードによって safe フィルタや escape フィルタを適用されることで、 "safe" とマークされる可能性があります。
自動エスケープが無効であるスコープ内では、 escape を含むフィルタを連結すると、以下のような予期しない（しかしドキュメント化されている）結果を引き起こす可能性があります：
{% autoescape off %}
{{ my_list|join:", "|escape }}
{% endautoescape %}
上記のコードは my_list の結合された要素をエスケープせずに出力します。これは、フィルタ連結シーケンスが最初に my_list に対して join を実行し (autoescape が off のため、各項目をエスケープせずに)、その結果を safe としてマークするからです。その後、この safe な結果が escape フィルタに送られても2回目のエスケープはされません。
シーケンスのすべての要素を適切にエスケープするには escapeseq フィルタを使います：
{% autoescape off %}
{{ my_list|escapeseq|join:", " }}
{% endautoescape %}
block¶
子テンプレートによってオーバーライドされる部分を定義します。詳しくは テンプレートの継承 を参照してください。
comment¶
{% comment %} ～ {% endcomment %} で囲まれた部分はすべて無視されます。最初のタグには追加の説明文を含めることができます。たとえばコードの一部をコメント化した際、その部分を無効にした理由を記述したいときなどに便利です。
使用例：
<p>Rendered text with {{ pub_date|date:"c" }}</p>
{% comment "Optional note" %}
<p>Commented out text with {{ create_date|date:"c" }}</p>
{% endcomment %}
comment タグを入れ子にすることはできません。
csrf_token¶
このタグは CSRF の防止のために使用します。詳細は クロスサイトリクエストフォージェリ (CSRF) を参照してください。.
cycle¶
タグを実行するごとに、引数の文字列や変数から、順に一つずつ値を出力します。最初の処理では 1 番目の値が、その次に 2 番目の値、以下、4 個まで同様に処理されます。サイクルのすべての値を出力すると、再び 1 番目に戻って出力します。
このタグは特にループの中で役立ちます：
{% for o in some_list %}
<tr class="{% cycle 'row1' 'row2' %}">
...
</tr>
{% endfor %}
この例では、繰り返しの最初の実行では row1 クラスを参照する HTML が生成されます。 2 回目には row2、 3 回目は再び row1 というように、ループを繰り返すたびに交互に処理されます。
変数を使うこともできます。例えば、 rowvalue1 と rowvalue2 という2つのテンプレート変数がある場合、以下のように交互に値を変更できます：
{% for o in some_list %}
<tr class="{% cycle rowvalue1 rowvalue2 %}">
...
</tr>
{% endfor %}
サイクルに含まれる変数はエスケープされます。自動エスケープを無効にするには下記のようにします：
{% for o in some_list %}
<tr class="{% autoescape off %}{% cycle rowvalue1 rowvalue2 %}{% endautoescape %}">
...
</tr>
{% endfor %}
下記のように、変数と文字列を混在させることもできます：
{% for o in some_list %}
<tr class="{% cycle 'row1' rowvalue2 'row3' %}">
...
</tr>
{% endfor %}
場合によっては、次の値に進まずにサイクルの現在の値を参照したいこともあるでしょう。これを行うには、 {% cycle %} タグに名前を付けます：
{% cycle 'row1' 'row2' as rowcolors %}
これ以降、コンテキスト変数としてサイクル名を参照することで、テンプレート内のどの場所にも現在のサイクルの値を挿入できます。元の cycle タグから独立してサイクルの値を次へ進めたいときには、変数の名前を指定して別の cycle タグを使用します。以下にテンプレートの例を挙げます:
<tr>
<td class="{% cycle 'row1' 'row2' as rowcolors %}">...</td>
<td class="{{ rowcolors }}">...</td>
</tr>
<tr>
<td class="{% cycle rowcolors %}">...</td>
<td class="{{ rowcolors }}">...</td>
</tr>
これは以下のように出力されます：
<tr>
<td class="row1">...</td>
<td class="row1">...</td>
</tr>
<tr>
<td class="row2">...</td>
<td class="row2">...</td>
</tr>
cycle タグ内では、空白で区切ることでいくつでも値を使うことができます。一重引用符 ( ' ) または二重引用符 ( " ) で囲まれた値は文字列リテラルとして扱われ、引用符のない値はテンプレート変数として扱われます。
標準の設定において、 cycle タグに as を使う場合、 {% cycle %} はサイクルの初期設定を行うときサイクル内で使う値を初期化します。これは、入れ子となったループや include されたテンプレートで値を使う場合に問題になるかもしれません。もしあなたがサイクルを宣言したいだけで初期値を生成させたくない場合には、タグのキーワードの最後に silent を加えてください。以下に例を示します:
{% for obj in some_list %}
{% cycle 'row1' 'row2' as rowcolors silent %}
<tr class="{{ rowcolors }}">{% include "subtemplate.html" %}</tr>
{% endfor %}
これは <tr> エレメントのリストを出力し、 class には row1 と row2 が交互に設定されます。サブテンプレートではそのコンテキスト内で rowcolors にアクセスし、値はそれを取り囲む <tr> のクラスに一致します。ここでもし silent キーワードが無かったら、 row1 と row2 は <tr> エレメントの外側で通常のテキストとして発行されます。
あるサイクルの定義において silent キーワードが使われているとき、後に続いて使われる cycle タグには自動的に silent が適用されます。次に示すテンプレートは、 2 番めの {% cycle %} 呼び出しでは silent を設定していませんが、何も出力しません。：
{% cycle 'row1' 'row2' as rowcolors silent %}
{% cycle rowcolors %}
resetcycle タグを使うと、{% cycle %} タグが次に現れたときに最初の値から再スタートできます。
debug¶
現在のコンテキストやインポートモジュールを含むデバッグ情報を出力します。DEBUG 設定が False の場合、{% debug %} は何も出力しません。
extends¶
このテンプレートが親テンプレートからの拡張であることを指示します。
このタグには 2 種類の使い方があります:
{% extends "base.html" %}(引用符つき) の場合、リテラル値 "base.html" を親テンプレートの名前として使います。{% extends variable %}とした場合、変数variableの値を親テンプレートの名前として使います。変数の値が文字列の場合、 Django はその文字列を親テンプレートの名前として使います。値がTemplateオブジェクトの場合、Django はそのオブジェクトを親テンプレートにします。
詳しくは テンプレートの継承 を参照してください。
通常、テンプレート名はテンプレートローダーのルートディレクトリからの相対パスです。文字列引数には ./ または ../ で始まる相対パスを指定することもできます。例えば、以下のようなディレクトリ構造を仮定します：
dir1/
template.html
base2.html
my/
base3.html
base1.html
template.html では、以下のパスが有効です：
{% extends "./base2.html" %}
{% extends "../base1.html" %}
{% extends "./my/base3.html" %}
filter¶
タグブロック内のコンテンツを、1 つまたは複数のフィルタに通します。複数のフィルタを使うときはパイプ（ " | " ）を使って連結します。フィルタには変数のように引数を与えることができます。
filter タグと endfilter タグに囲まれたテキストは、すべて ブロックに含まれることに注意しましょう。
使用例：
{% filter force_escape|lower %}
This text will be HTML-escaped, and will appear in all lowercase.
{% endfilter %}
注釈
escape と safe フィルタは引数として与えることができません。ブロックの自動エスケープを管理するには、代わりに autoescape タグを使ってください。
firstof¶
最初の引数変数が "false" でない（つまり、存在し、空でなく、False の真偽値でなく、0 の数値でない）場合、その変数を出力します。渡された変数がすべて "false" の場合は何も出力しません。
使用例：
{% firstof var1 var2 var3 %}
上のコードは以下と等価です：
{% if var1 %}
{{ var1 }}
{% elif var2 %}
{{ var2 }}
{% elif var3 %}
{{ var3 }}
{% endif %}
また、渡された変数がすべて False の場合のフォールバック値として、リテラル文字列を使うこともできます：
{% firstof var1 var2 var3 "fallback value" %}
このタグは変数の値を自動エスケープします。自動エスケープを無効にするには下記のようにします：
{% autoescape off %}
{% firstof var1 var2 var3 "<strong>fallback value</strong>" %}
{% endautoescape %}
一部の変数だけをエスケープするには、下記のようにします：
{% firstof var1 var2|safe var3 "<strong>fallback value</strong>"|safe %}
{% firstof var1 var2 var3 as value %} のように書くことで、出力を 1 つの変数内に格納することもできます。
for¶
配列の各項目をループし、コンテキスト変数でその項目を利用できるようにします。例えば、athlete_list で渡されたアスリートのリストを表示するには以下のようにします：
<ul>
{% for athlete in athlete_list %}
<li>{{ athlete.name }}</li>
{% endfor %}
</ul>
{% for obj in list reversed %} で、リストに対して逆順のループを実行できます。
リストのリストをループする必要がある場合は、各サブリストの値を個々の変数にアンパックします。たとえば、コンテキストに points という (x,y) 座標のリストが含まれている場合、以下のように点のリストを出力できます：
{% for x, y in points %}
There is a point at {{ x }},{{ y }}
{% endfor %}
この方法は、辞書の各要素にアクセスしたい場合にも便利です。例えば data という辞書がある場合、以下のように辞書内のキーと値を表示できます:
{% for key, value in data.items %}
{{ key }}: {{ value }}
{% endfor %}
ドット演算子を使う場合、メソッドよりも辞書キーへの参照が優先することに注意してください。したがって、もしも data 辞書が 'items' という名前のキーを持っていたなら、 data.items は data.items() ではなく data['items'] の値を出力します。テンプレート内で辞書のメソッドを使いたい場合、そのような名前のキー (items、values、keys など) を辞書に追加しないでください。ドット演算子による参照の優先順位についての詳細は テンプレート変数のドキュメント を参照してください。
for ループには、ループ内で使える多くの変数が設定されています:
変数 |
説明 |
|---|---|
|
現在のループカウンタ番号 ( 1 から順にカウント ) |
|
現在のループカウンタ番号 ( 0 から順にカウント ) |
|
現在のループカウンタ値 ( 1 から順に、末尾からカウント) |
|
現在のループカウンタ値 ( 0 から順に、末尾からカウント) |
|
最初のループであれば True |
|
最後のループであれば True |
|
入れ子のループであるとき、現在のループを囲んでいる 1 つ上のループを表します。 |
for ... empty¶
for タグのオプションとして {% empty %} 節を使うこともできます。これはループさせようとした配列が空、または存在しなかった場合に表示する文字列を指定します:
<ul>
{% for athlete in athlete_list %}
<li>{{ athlete.name }}</li>
{% empty %}
<li>Sorry, no athletes in this list.</li>
{% endfor %}
</ul>
上記の例は以下のテンプレートと同等です。しかし {% empty %} を使ったほうが簡潔で、かつ高速になる場合もあります。：
<ul>
{% if athlete_list %}
{% for athlete in athlete_list %}
<li>{{ athlete.name }}</li>
{% endfor %}
{% else %}
<li>Sorry, no athletes in this list.</li>
{% endif %}
</ul>
if¶
{% if %} タグは変数を評価し、その変数が "true" であるとき (すなわち変数が存在し、空ではなく、その値が False でないとき ) にブロックの内容を出力します:
{% if athlete_list %}
Number of athletes: {{ athlete_list|length }}
{% elif athlete_in_locker_room_list %}
Athletes should be out of the locker room soon!
{% else %}
No athletes.
{% endif %}
上の例では、 athlete_list が空でなければ、アスリートの人数を {{ athlete_list|length }} 変数で表示します。
例にもあるように if タグはオプションで 1 個以上の {% elif %} 節、および 1 個の {% else %} 節をつけることができます。 {% else %} はそれまでの評価結果がすべて True でなかった場合に表示されるコンテンツを定義します。
論理演算子¶
if タグは 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.
{% endif %}
{% if athlete_list and not coach_list %}
There are some athletes and absolutely no coaches.
{% endif %}
and と or は同じタグの中で同時に使用できます。このとき優先順位は and が優先します:
{% if athlete_list and coach_list or cheerleader_list %}
これは以下のように解釈されます:
if (athlete_list and coach_list) or cheerleader_list:
...
実際には if タグの中で丸括弧を使うことはできません。優先順位を示す必要がある場合には、if タグを入れ子にして表してください。
if タグは演算子 ==, !=, <, >, <=, >=, in, not in, is, and is not が使え、以下のように機能します:
== 演算子¶
等しい場合。例:
{% if somevar == "x" %}
This appears if variable somevar equals the string "x"
{% endif %}
!= 演算子¶
等しくない場合。例:
{% if somevar != "x" %}
This appears if variable somevar does not equal the string "x",
or if somevar is not found in the context
{% endif %}
< 演算子¶
左辺が右辺より小さい場合。例:
{% if somevar < 100 %}
This appears if variable somevar is less than 100.
{% endif %}
> 演算子¶
左辺が右辺より大きい場合。例:
{% if somevar > 0 %}
This appears if variable somevar is greater than 0.
{% endif %}
<= 演算子¶
左辺が右辺の値以下の場合。例:
{% if somevar <= 100 %}
This appears if variable somevar is less than 100 or equal to 100.
{% endif %}
>= 演算子¶
左辺が右辺の値以上の場合。例:
{% if somevar >= 1 %}
This appears if variable somevar is greater than 1 or equal to 1.
{% endif %}
in 演算子¶
左辺の値が右辺の値に含まれる場合。この演算子は多くのPythonコンテナデータ型によってサポートされており、指定された値がコンテナ内に存在するかどうかをチェックできます。以下に x in y がどのように解釈されるかの例をいくつか示します：
{% if "bc" in "abcdef" %}
This appears since "bc" is a substring of "abcdef"
{% endif %}
{% if "hello" in greetings %}
If greetings is a list or set, one element of which is the string
"hello", this will appear.
{% endif %}
{% if user in users %}
If users is a QuerySet, this will appear if user is an
instance that belongs to the QuerySet.
{% endif %}
not in 演算子¶
左辺の値が右辺の値に含まれない場合。これは in 演算子の逆です。
is 演算子¶
オブジェクトの同一性。2つの値が同じオブジェクトかどうかをテストします。例：
{% if somevar is True %}
This appears if and only if somevar is True.
{% endif %}
{% if somevar is None %}
This appears if somevar is None, or if somevar is not found in the context.
{% endif %}
is not 演算子¶
オブジェクトの非同一性。2つの値が同じオブジェクトでないかどうかをテストします。これは is 演算子の否定です。例：
{% if somevar is not True %}
This appears if somevar is not True, or if somevar is not found in the
context.
{% endif %}
{% if somevar is not None %}
This appears if and only if somevar is not None.
{% endif %}
フィルタ¶
if 内でフィルタを使うこともできます。例を示します:
{% if messages|length >= 100 %}
You have lots of messages today!
{% endif %}
複雑な表現¶
ここまでのすべてを組み合わせて複雑な式を作ることができます。このような式では、式を評価するときに演算子がどのようにグループ化されるか、すなわち優先順位の規則を理解することが重要です。演算子の優先順位は次のようになっています:
orandnotin==,!=,<,>,<=,>=
(この順序は Python とまったく同じです)。 そこで、例えば次に挙げる複雑な if タグの場合:
{% if a == b or c == d and e %}
...次のように解釈されます:
(a == b) or ((c == d) and e)
もしこれと違った優先順位が必要ならば、if タグを入れ子にして使う必要があります。優先順位の規則がはっきりしない場合には、こうした方がより明確な表現になることもあるでしょう。
比較演算子は Python や数学における記法のように、つないで書くことはできません。例えば次のような使い方はできません:
{% if a > b > c %} (WRONG)
このように使うべきです:
{% if a > b and b > c %}
ifchanged¶
値が前回のループ実行時から変わっているかどうかを調べます。
{% ifchanged %} ブロックタグはループの内部で使います。このタグには 2 通りの使い方があります。
今回の出力内容が、前回の状態に対して変化しているときだけ表示します。例えば、日付の一覧を表示する場合に、月が変わったときだけ月名を表示したければ以下のようにします:
<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 %}
タグに 1 個以上の変数が与えられている場合、それぞれの変数について内容が変化したかどうかを調べます。例えば、以下の例では日付が変化したときには日付を表示し、日付と時刻が同時に変化したときだけ時刻も表示します:
{% for date in days %} {% ifchanged date.date %} {{ date.date }} {% endifchanged %} {% ifchanged date.hour date.date %} {{ date.hour }} {% endifchanged %} {% endfor %}
ifchanged タグは、オプションで {% else %} 節を使うこともできます。これは値に変化がないときに表示されます:
{% for match in matches %}
<div style="background-color:
{% ifchanged match.ballot_id %}
{% cycle "red" "blue" %}
{% else %}
gray
{% endifchanged %}
">{{ match }}</div>
{% endfor %}
include¶
テンプレートをロードし、現在のコンテキストを使って出力します。これはテンプレート内に他のテンプレートを取り込む（ “include” ）方法の一つです。
テンプレート名はハードコードされた (引用符で囲った) 文字列でもよく、引用符は一重引用符 （'...'）でも二重引用符（"..."）でもかまいません。
次の例では、 "foo/bar.html" という名前のテンプレートの内容を include します:
{% include "foo/bar.html" %}
通常、テンプレート名はテンプレートローダーのルートディレクトリからの相対パスです。 extends タグで説明されているように、文字列引数には ./ または ../ で始まる相対パスを指定することもできます。
次の例では、変数 template_name の値をテンプレート名として、そのテンプレートの内容を include します:
{% include template_name %}
変数は、コンテキストを受け取る render() メソッドを持っていればオブジェクトでも構いません。これによって、コンテキスト内のコンパイル済みの Template を参照できます。
さらに、この変数はテンプレート名のイテラブルにすることもできます。その場合、 select_template() に従って、ロードできる最初のものが使用されます。
include されたテンプレートは、include した側のコンテキストにおいて解釈されます。以下の例は "Hello, John!" を出力します:
コンテキスト: 変数
personに"John"を、変数greetingに"Hello"をセット。テンプレート:
{% include "name_snippet.html" %}
name_snippet.htmlテンプレート:{{ greeting }}, {{ person|default:"friend" }}!
キーワード引数を使って、テンプレートに追加のコンテキストを渡すことができます:
{% include "name_snippet.html" with person="Jane" greeting="Hello" %}
あらかじめ準備された変数だけを使って (あるいは変数をまったく使わずに) 出力させたい場合は only オプションを使います。テンプレートを取り込むために、他の変数は利用できません:
{% include "name_snippet.html" with greeting="Hi" only %}
注釈
include タグの実行は『サブテンプレートを出力し、その結果である HTML を取り込む』と考えるべきで、『サブテンプレートを解析し、親テンプレートの一部分として、そこに組み込まれている』かのように考えるべきではありません。これは、取り込んだテンプレートの間では状態を共有できず、まったく独立した過程で出力されることを意味します。
ブロックは取り込まれる 前に 評価されます。ブロックを含んでいる他のテンプレートを取り込む場合、そのブロックは すでに評価され、出力された結果 としてのブロックであり、たとえばテンプレートを継承したときのような、オーバーライド可能なブロックではありません。
load¶
カスタムのテンプレートタグセットを読み込みます。
例えば次のテンプレートは somelibrary 、そして package パッケージの otherlibrary に登録されたすべてのタグとフィルタを読み込みます。:
{% load somelibrary package.otherlibrary %}
引数に from を使えば、ライブラリからフィルタやタグを個別に選んで読み込むことができます。以下の例では、 foo、bar という名前のテンプレートタグまたはフィルタを somelibrary から読み込みます:
{% load foo bar from somelibrary %}
詳しくは カスタムタグとフィルタのライブラリ を参照してください。
lorem¶
ランダムな"lorem ipsum" のラテン語テキストを表示させます。テンプレート内でサンプルデータを用意するのに便利です。
使い方:
{% lorem [count] [method] [random] %}
{% lorem %} タグは 0 から 3 個の引数をとります:
引数 |
説明 |
|---|---|
|
生成する単語または段落の数を指定する、数値または変数 (デフォルトは 1 ) 。 |
|
|
|
|
例:
{% lorem %}は、一般的な "lorem ipsum" を出力します。{% lorem 3 p %}は一般的な "lorem ipsum" と 2 個のランダムな文章を、それぞれ HTML の<p>タグで括って出力します。{% lorem 2 w random %}は 2 個のランダムなラテン単語を出力します。
now¶
指定したフォーマット文字列にしたがって現在の日付や時刻を表示します。フォーマット文字列で使われる文字については、 date フィルタの項で説明しています。
例:
It is {% now "jS F Y H:i" %}
文字列の中でフォーマット文字を普通の文字として扱いたい場合は、バックスラッシュ文字（ \ ）でエスケープします。次の例では、 "o" と "f" をエスケープしています。そうしなければ、これらはそれぞれ年と時刻を表示するためのフォーマット文字とみなされるからです:
It is the {% now "jS \o\f F" %}
この表示結果は "It is the 4th of September" となります。
注釈
フォーマットはプリセット（ DATE_FORMAT、 DATETIME_FORMAT、 SHORT_DATE_FORMAT、 SHORT_DATETIME_FORMAT ）の中から 1 つを選ぶこともできます。 表示形式のローカライズ が有効なときは、プリセットフォーマットの内容は現在設定されているロケールによって変わります。たとえば、下記のようにします:
It is {% now "SHORT_DATETIME_FORMAT" %}
出力を (文字列として) 変数に入れる場合には {% now "Y" as current_year %} の書式が使えます。これは blocktranslate のようなテンプレートタグで {% now %} を使いたいときに役立ちます:
{% now "Y" as current_year %}
{% blocktranslate %}Copyright {{ current_year }}{% endblocktranslate %}
querystring¶
提供されたパラメータに基づいて、URLエンコードされた形式のクエリ文字列を出力します。
このタグには QueryDict インスタンスが必要で、提供されない場合はデフォルトで request.GET が使用されます。
もし QueryDict が空で、追加のパラメータが提供されていない場合、空の文字列が返されます。空でない結果には先頭に "?" が付加されます。
request.GET をデフォルトとして使う
request.GET をデフォルトの QueryDict インスタンスとして使用するには、django.template.context_processors.request コンテキストプロセッサを有効にする必要があります。これが有効でない場合、テンプレートコンテキストに request オブジェクトを明示的に渡すか、またはこのタグに QueryDict インスタンスを渡す必要があります。
基本的な使用法¶
{% querystring %}
現在のクエリ文字列をそのまま出力します。たとえば、クエリ文字列が ?color=green の場合、出力は ?color=green になります。
{% querystring size="M" %}
現在のクエリ文字列に size パラメータを追加して出力します。前の例を続けると、出力は ?color=green&size=M になります。
独自の QueryDict¶
{% querystring my_query_dict %}
カスタムの QueryDict を渡して、request.GET の代わりに使用できます。例えば、my_query_dict が <QueryDict: {'color': ['blue']}> の場合、出力は ?color=blue になります。
アイテムをセットする¶
{% querystring color="red" size="S" %}
クエリ文字列にパラメータを追加または変更します。各キーワード引数はクエリ文字列に追加され、そのキーの既存の値を置き換えます。例えば、現在のクエリ文字列が ?color=green の場合、出力は ?color=red&size=S になります。
アイテムを削除する¶
{% querystring color=None %}
値として None を渡すと、クエリ文字列からそのパラメータが削除されます。例えば、現在のクエリ文字列が ?color=green&size=M の場合、出力は ?size=M になります。
リストを扱う¶
{% querystring color=my_list %}
もし my_list が ["red", "blue"] の場合、出力は ?color=red&color=blue となり、リストの構造がクエリ文字列に保持されます。
動的な使用方法¶
このタグを使う一般的な例は、結果のページを表示する際に現在のクエリ文字列を保持しつつ、次のページや前のページへのリンクを追加することです。例えば、ページネーターが現在ページ3にあり、現在のクエリ文字列が ?color=blue&size=M&page=3 の場合、次のコードは ?color=blue&size=M&page=4 を出力します。
{% querystring page=page.next_page_number %}
値を変数に格納することもできます。例えば、同じページへのリンクを複数必要とする場合は、次のように定義します。
{% querystring page=page.next_page_number as next_page %}
regroup¶
オブジェクトのリストから、同じ属性値を持つオブジェクトのグループを作ります。
この複雑なタグは例を通して説明するのがいいでしょう: cities は "name", "population", and "country" をキーとして含むディクショナリによって表された都市のリストとします:
cities = [
{"name": "Mumbai", "population": "19,000,000", "country": "India"},
{"name": "Calcutta", "population": "15,000,000", "country": "India"},
{"name": "New York", "population": "20,000,000", "country": "USA"},
{"name": "Chicago", "population": "7,000,000", "country": "USA"},
{"name": "Tokyo", "population": "33,000,000", "country": "Japan"},
]
...そして、あなたは次のように、国別に並べた一覧を表示させたいものとしましょう:
India
Mumbai: 19,000,000
Calcutta: 15,000,000
USA
New York: 20,000,000
Chicago: 7,000,000
Japan
Tokyo: 33,000,000
ここで {% regroup %} タグを使って都市のリストを国別にグループ化できます。以下は、そのためのテンプレートコード例です:
{% regroup cities by country as country_list %}
<ul>
{% for country in country_list %}
<li>{{ country.grouper }}
<ul>
{% for city in country.list %}
<li>{{ city.name }}: {{ city.population }}</li>
{% endfor %}
</ul>
</li>
{% endfor %}
</ul>
この例を見てみましょう。{% regroup %} タグは 3 つの引数を取ります。グループ分けを行うリスト、グループ分けに使う属性の名前、そして結果とするリストの名前の 3 つです。ここでは cities リストを country 属性でグループ化し、その結果を country_list と呼んでいます。
{% regroup %} は グループオブジェクト のリスト(この場合は country_list) を生成します。グループオブジェクトは2つのフィールドを持つ namedtuple() のインスタンスです：
grouper-- グループ分けに使われた要素 ( ここでは "India" "Japan" といった文字列 )list-- このグループ内のすべての要素からなるリスト ( たとえば country='India' であるすべての都市のリスト)
{% regroup %} は namedtuple() オブジェクトを生成するので、上の例を次のように書くこともできます：
{% regroup cities by country as country_list %}
<ul>
{% for country, local_cities in country_list %}
<li>{{ country }}
<ul>
{% for city in local_cities %}
<li>{{ city.name }}: {{ city.population }}</li>
{% endfor %}
</ul>
</li>
{% endfor %}
</ul>
{% regroup %} は入力をソートしないことに注意してください！ 上の例では、リスト cities は、あらかじめ country の順でソート済みだという前提です。cities が country の順に並べられて いなかった 場合、regroup はそのまま何も考えずに 1 つの国に対してグループを 1 つ以上作ってしまうかもしれません。たとえばリスト cities が、次のように (リスト内で国ごとにまとまっていない状態に) なっていたとしましょう。
cities = [
{"name": "Mumbai", "population": "19,000,000", "country": "India"},
{"name": "New York", "population": "20,000,000", "country": "USA"},
{"name": "Calcutta", "population": "15,000,000", "country": "India"},
{"name": "Chicago", "population": "7,000,000", "country": "USA"},
{"name": "Tokyo", "population": "33,000,000", "country": "Japan"},
]
この cities を入力に使うと、先ほどの {% regroup %} テンプレートコードは次のような結果を出力するでしょう:
India
Mumbai: 19,000,000
USA
New York: 20,000,000
India
Calcutta: 15,000,000
USA
Chicago: 7,000,000
Japan
Tokyo: 33,000,000
このような落し穴を解決するには、ビューコード内であらかじめデータを表示したい順番に並べておくのが最も簡単でしょう。
データが辞書のリストである場合には、もう一つの解決策として、テンプレートの中で dictsort フィルタを使ってデータを並べ変えることができます:
{% regroup cities|dictsort:"country" by country as country_list %}
その他の属性によるグループ化¶
テンプレートの有効な参照は、いずれも regroup タグでグループ化するための属性として扱うことができます。これにはメソッド、属性、辞書のキー、リスト項目が含まれます。例えば "country" というフィールドが外部キーで、その参照するクラスが "description" 属性を持つ場合、次のように使うことができます:
{% regroup cities by country.description as country_list %}
また、 country が choices をともなうフィールドである場合、それは属性として使える get_FOO_display() メソッドを持っているので choices のキーではなく表示文字列でグループ化することもできます：
{% regroup cities by get_country_display as country_list %}
これで、 {{ country.grouper }} はキーではなく choices セットの値フィールドを表示するようになります。
resetcycle¶
前の cycle をリセットし、次の遭遇時に最初の項目から再開するようにします。引数がない場合、 {% resetcycle %} はテンプレートで定義された最後の {% cycle %} をリセットします。
使用例:
{% for coach in coach_list %}
<h1>{{ coach.name }}</h1>
{% for athlete in coach.athlete_set.all %}
<p class="{% cycle 'odd' 'even' %}">{{ athlete.name }}</p>
{% endfor %}
{% resetcycle %}
{% endfor %}
上記の例は以下のようなHTMLを返します：
<h1>Gareth</h1>
<p class="odd">Harry</p>
<p class="even">John</p>
<p class="odd">Nick</p>
<h1>John</h1>
<p class="odd">Andrea</p>
<p class="even">Melissa</p>
最初のブロックが class="odd" で終わり、新しいブロックは class="odd" で始まることに注意してください。 {% resetcycle %} タグがなければ、2番目のブロックは class="even" から始まります。
名前付きのサイクルタグをリセットすることもできます：
{% for item in list %}
<p class="{% cycle 'odd' 'even' as stripe %} {% cycle 'major' 'minor' 'minor' 'minor' 'minor' as tick %}">
{{ item.data }}
</p>
{% ifchanged item.category %}
<h1>{{ item.category }}</h1>
{% if not forloop.first %}{% resetcycle tick %}{% endif %}
{% endifchanged %}
{% endfor %}
この例では、"odd" と "even" の交互の行と、5行目ごとの "major" な行の両方があります。カテゴリーが変わると、5列のサイクルだけがリセットされます。
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 %}
templatetag¶
テンプレートタグの構文で使われる文字を、通常の文字として出力します。
テンプレートシステムには個々の文字を「エスケープ」する概念はありません。しかし、{% templatetag %} タグを使えば、テンプレートタグの文字の組み合わせを表示できます。
どの要素を出力するかは、引数で指定します:
引数 |
出力 |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
使用例：
The {% templatetag openblock %} characters open a block.
これらの文字を含める別の方法については verbatim タグも参照してください。
url¶
ビューとオプションの引数を指定して、これとマッチする絶対パスへの参照 ( ドメイン部分を除いた URL ) を返します。結果のパスに特殊文字が含まれる場合、 iri_to_uri() を使ってエンコードされます。
これによって、テンプレート内での URL のハードコードによって DRY 原則に反することなくリンクを出力できます:
{% url 'some-url-name' v1 v2 %}
第 1 引数は URL パターン名 です。これは引用符で括ったリテラル、またはその他のコンテキスト変数です。続く引数はオプションで、空白で区切って指定します。引数はそれぞれ URL の引数として使われます。上の例では固定引数によって引数を指定していますが、代わりにキーワード引数で指定することもできます:
{% url 'some-url-name' arg1=v1 arg2=v2 %}
1 つの呼び出しのなかで、固定引数とキーワード引数を混ぜることはできません。また URLconf で必要とされる引数はすべて指定しなければなりません。
たとえば app_views.client という名前のビューがあって、クライアントの ID を引数に取るとしましょう ( client() は、 views ファイル app_views.py の中で定義されているメソッドです ) 。 URLconf は以下のようなものになるでしょう:
path("client/<int:id>/", app_views.client, name="app-views-client")
このアプリケーションの URLconf が、プロジェクトの URLconf の中に次のような形で include されていたとします:
path("clients/", include("project_name.app_name.urls"))
...このとき、テンプレート内でこのビューへのリンクを作るには、次のようにします:
{% url 'app-views-client' client.id %}
テンプレートタグの出力は、文字列 /clients/client/123/ となります。
逆引きしようとしている URL が存在しなかった場合、 NoReverseMatch 例外が発生して、あなたのサイトにはエラーページが表示されることに注意しましょう。
ページを表示させずに URL を取り出したい場合、少し違った呼び出し方が使えます:
{% url 'some-url-name' arg arg2 as the_url %}
<a href="{{ the_url }}">I'm linking to {{ the_url }}</a>
`` ～ as 変数`` の構文で作られた変数は、 {% url %} タグのある {% block %} 内がスコープとなります。
次の例で、 {% url ... as var %} 構文はビューが見つからなくてもエラーを起こしません。実用としては、オプションのビューへリンクする場合に使えます:
{% url 'some-url-name' as the_url %}
{% if the_url %}
<a href="{{ the_url }}">Link to optional stuff</a>
{% endif %}
名前空間化された URL を取り出したい場合は、完全修飾名で指定してください：
{% url 'myapp:view-name' %}
これは通常の 名前付き URL の解決順序 に従います。ここには現在のアプリケーションに関してコンテキストから得られる様々なヒントについて書かれています。
警告
URL パターン name は忘れずに引用符で囲んで下さい。そうしないと、値はコンテキスト変数であると解釈されます！
verbatim¶
このブロックタグ内では、テンプレートエンジンによる解釈を行いません。
これは JavaScript テンプレート の文法が Django と衝突してしまう時によく使われます。例えば:
{% verbatim %}
{{if dying}}Still alive.{{/if}}
{% endverbatim %}
verbatim ブロックの中で "{% endverbatim %}" を使うには、開始・終了タグが特定できるように名前をつけます:
{% verbatim myblock %}
Avoid template rendering via the {% verbatim %}{% endverbatim %} block.
{% endverbatim myblock %}
widthratio¶
バーチャートなどを生成する場合のために、指定した値と最大値との比を計算し、 定数に掛けた値を返します。
例:
<img src="bar.png" alt="Bar"
height="10" width="{% widthratio this_value max_value max_width %}">
ここで this_value = 175 、 max_value = 200 であるとき、画像の幅は 88 ピクセルになります (175 / 200 = .875、 .875 * 100 = 87.5 から四捨五入して 88 )。
widthratio の結果を変数に入れてキャプチャーしたいことがあります。例えば blocktranslate で使う場合、次のようにできます:
{% widthratio this_value max_value max_width as width %}
{% blocktranslate %}The width is: {{ width }}{% endblocktranslate %}
with¶
複雑な表現の変数の値をキャッシュし、簡単な名前で参照できるようにします。呼出しコストの高いメソッド (たとえばデータベースを操作するようなメソッド) に何度もアクセスする際に便利です。
例:
{% with total=business.employees.count %}
{{ total }} employee{{ total|pluralize }}
{% endwith %}
値を組み込んだ変数 (上の例でいえば total ) は {% with %} と {% endwith %} タグの間でだけ有効です。
コンテキスト変数は、複数割り当てることができます:
{% with alpha=1 beta=2 %}
...
{% endwith %}
注釈
従来の冗長な書式もサポートされています: {% with business.employees.count as total %}
組み込みフィルタリファレンス¶
add¶
入力値に対して引数の値を加算します。
例:
{{ value|add:"2" }}
value が 4 なら、出力は 6 になるでしょう。
このフィルタは、まず両方の値を強制的に整数とみなして加算しようとします。失敗した場合は、とにかく値を足し合わせることを試みます。これはいくつかのデータ型 (文字列、リストなど) では動作しますが、それ以外では失敗します。失敗した場合、結果は空の文字列になります。
例として、次のようなフィルタがあるとしましょう:
{{ first|add:second }}
first が [1, 2, 3] 、 second が [4, 5, 6] であった場合、出力は [1, 2, 3, 4, 5, 6] になります。
警告
整数に変換可能な文字列は、整数として「加算」されます。上の例のように「結合」されません。
addslashes¶
引用符の前にスラッシュを追加します。CSV などの文字列をエスケープする際に便利です。
例:
{{ value|addslashes }}
value の値が "I'm using Django" のとき、出力は "I\'m using Django" となります。
capfirst¶
入力値の先頭の文字を大文字に変換します。最初の文字がアルファベットでなければ効果はありません。
例:
{{ value|capfirst }}
value が django のとき、出力は "Django" となります。
center¶
入力値を引数で指定された幅のフィールド内に中央寄せします。
例:
"{{ value|center:"15" }}"
value の値が "django" のとき、出力は " Django " となります。
cut¶
入力値の中から、引数に指定した値を全て取り除きます。
例:
{{ value|cut:" " }}
value の値が "String with spaces" のとき、出力は "Stringwithspaces" となります。
date¶
引数に指定した書式で日付をフォーマットします。
PHP の date() 関数と似た書式を使いますが、若干の違いがあります。
注釈
これらのフォーマット文字は、テンプレート以外では使えません。デザイナーが PHP のテンプレートから容易に変換できるように互換性を持たせています。
利用可能なフォーマット文字:
フォーマット文字 |
説明 |
出力の例 |
|---|---|---|
日 |
||
|
日。 2 桁のゼロ詰め表示です。 |
|
|
日。ゼロ埋め表示なし。 |
|
|
曜日。 アルファベット 3 文字のテキスト形式です。 |
|
|
曜日。長いテキスト形式です。 |
|
|
日を表わす数字につける、英語特有の接尾辞。アルファベット 2 文字です。 |
|
|
曜日（数字 1 桁）。 |
|
|
日（１年間における） |
|
週 |
||
|
ISO-8601 による年間の週番号。 週は月曜日から始まります。 |
|
月 |
||
|
月。数字 2 桁で、ゼロ埋め表示します。 |
|
|
月。ゼロ埋め表示しません。 |
|
|
月。アルファベット 3 文字のテキスト形式です。 |
|
|
月。アルファベット（小文字） 3 文字のテキスト形式です。 |
|
|
月。ロケールが定義する代替表現が使われ、通常は長いテキスト形式になります。 |
|
|
月。長いテキスト形式で表したものです。 |
|
|
AP スタイルブックによる月の省略表記。独自の拡張です。 |
|
|
その月の日数。 |
|
年 |
||
|
年。数字 2 桁で、先頭をゼロ埋めします。 |
|
|
年。数字 4 桁で、先頭をゼロ埋めします。 |
|
|
うるう年かどうかを表すブール値です。 |
|
|
ISO-8601 の週番号付き記法による年。うるう週を用いた ISO-8601 週番号 (W) に対応します。一般的な年のフォーマットは Y を参照してください。 |
|
時刻 |
||
|
時（ 12 時間表記）。ゼロ埋め表示なし。 |
|
|
時（ 24 時間表記）。ゼロ埋め表示なし。 |
|
|
時（ 12 時間表記）。 |
|
|
時（ 24 時間表記）。 |
|
|
分。 |
|
|
秒。数字 2 桁で、ゼロ埋め表示です。 |
|
|
マイクロ秒。 |
|
|
|
|
|
|
|
|
時と分（12 時間表記）。ただしゼロ分であるときは時間だけを表示します。これは独自の拡張です。 |
|
|
時刻。12 時間表記による 時間:分 に続けて ‘a.m.’ または ’p.m.’ を表示します。ゼロ分である場合には分の表示が省略され、必要に応じて ‘midnight’ または ‘noon’ の表示になります。 独自の拡張です。 |
|
タイムゾーン |
||
|
タイムゾーン名。どのフォーマットでも使えますが、 datetime によっては空の文字列を返す場合もあります。 |
|
|
夏時間（DST）が有効か、そうでないかを表します。 |
|
|
グリニッジ標準時からの時差。 |
|
|
計算機のタイムゾーン設定。 |
|
|
タイムゾーンオフセットを秒であらわしたもの。UTC よりも西側のタイムゾーン値は全て負の値になり、東側の値は常に正になります。 |
|
日付/時刻 |
||
|
ISO 8601 フォーマット。 ( 注： これは他の "Z"、"O"、"r" といったフォーマット文字とは異なり、 入力値がタイムゾーン情報を含まない（"naive"な） datetime であっても、タイムゾーンによる時差を加算しません ( |
|
|
RFC 5322 フォーマットの日付。 |
|
|
Unix エポック時 ( UTC 協定世界時 1970年1月1日 00:00:00 ) からの秒数。 |
例:
{{ value|date:"D d M Y" }}
上の例で、値が datetime オブジェクトである場合 (たとえば datetime.datetime.now() の結果など)、出力は 'Wed 09 Jan 2008' となります。
フォーマットには、プリセット（ DATE_FORMAT, DATETIME_FORMAT, SHORT_DATE_FORMAT or SHORT_DATETIME_FORMAT ）のうちの１つ、または上記の表で示したフォーマット指定文字を使ったカスタムフォーマットが使えます。プリセットのフォーマットは、現在のロケールに応じて表示が変化することに注意してください。
たとえば LANGUAGE_CODE が "es" だったとして、：
{{ value|date:"SHORT_DATE_FORMAT" }}
上記の出力は、文字列 "09/01/2008" となります ( es ロケールの "SHORT_DATE_FORMAT" フォーマットは、 Django の初期設定では "d/m/Y" です)。
フォーマット文字列を指定せずに使用する場合、 DATE_FORMAT フォーマット指定子が使用されます。先ほどの例と同じ設定だとすると：
{{ value|date }}
は 9 de Enero de 2008 を出力します (es ロケールの DATE_FORMAT フォーマット指定子は r'j \d\e F \d\e Y')。 "d "と "e "はどちらもバックスラッシュでエスケープされていますが、それ以外はそれぞれ曜日とタイムゾーン名を表示するフォーマット文字列だからです。
date と time フィルタを組み合わせることで、 datetime 値を完全に表示することもできます。 たとえば以下のようにします：
{{ value|date:"D d M Y" }} {{ value|time:"H:i" }}
default¶
入力の評価値が False の場合、引数に指定したデフォルト値を使います。そうでなければ、入力値を使います。
例:
{{ value|default:"nothing" }}
value が "" ( 空の文字列 ) のとき、出力は nothing になります。
default_if_none¶
入力値が 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},
]
より複雑なリストに対しても、以下のように処理できます:
{% for book in books|dictsort:"author.age" %}
* {{ book.title }} ({{ book.author.name }})
{% endfor %}
ここで books が以下の内容だとします:
[
{"title": "1984", "author": {"name": "George", "age": 45}},
{"title": "Timequake", "author": {"name": "Kurt", "age": 75}},
{"title": "Alice", "author": {"name": "Lewis", "age": 33}},
]
このとき出力は以下のようになるでしょう:
* Alice (Lewis)
* 1984 (George)
* Timequake (Kurt)
dictsort はリスト（または __getitem__() を実装した他のオブジェクト）のリストを指定したインデックスの要素でソートすることもできます。たとえば、：
{{ value|dictsort:0 }}
value が以下の内容であるとします:
[
("a", "42"),
("c", "string"),
("b", "foo"),
]
このとき出力は以下のようになるでしょう:
[
("a", "42"),
("b", "foo"),
("c", "string"),
]
インデックスは文字列ではなく整数で渡す必要があります。以下のコードの出力は空です：
{{ values|dictsort:"0" }}
指定したインデックスの要素によるソートは辞書ではサポートされていません。
dictsortreversed¶
辞書のリストを入力に取り、引数に指定したキーでリストを逆順にソートして返します。これは上のフィルタと全く同じ処理をしますが、返す値は逆順です。
divisibleby¶
値が引数の値で割り切れる場合に True を返します。
例:
{{ value|divisibleby:"3" }}
value が 21 であるとき、出力は True です。
escape¶
入力文字中にある HTML の特殊文字をエスケープします。具体的には、以下のような置換を行います:
<を<に変換>を>に変換'( シングルクォート ) を'に変換"( ダブルクォート ) を"に変換&を&に変換
escape を変数に適用するとき、変数にはすでに自動エスケープが適用されているかもしれませんが、エスケープが二重に実行されることはありません。したがって自動エスケープ環境であっても、この機能は安全に使用できます。複数回のエスケープが適用されるようにしたい場合は force_escape フィルタを使用してください。
以下は autoescape がオフであるときに、フィールドに escape を適用する例です:
{% autoescape off %}
{{ title|escape }}
{% endautoescape %}
escape を他のフィルタと連結する場合
autoescape のセクションで述べたように、escape を含むフィルタが連結されている場合、 autoescape が off であることが原因でエスケープが行われず、先行するフィルタが安全でない可能性のある文字列を安全であるとマークしてしまうと、予期しない結果になることがあります。
このような場合、escape を連結させても、すでに安全であるとマークされている文字列を再エスケープすることはできません。
これは、例えば join のようなシーケンスを操作するフィルタを使う場合に特に重要です。シーケンスの各要素をエスケープする必要がある場合は、専用の escapeseq フィルタを使用してください。
escapejs¶
JavaScript の文字列リテラル全体として、以下のように一重引用符または二重引用符で囲んで使用する文字をエスケープします。このフィルタは文字列を "JavaScript テンプレートリテラル " (JavaScript のバックティック構文) では安全に使えません。これ以外の使い方はサポートされていません。通常は、データは埋め込み JavaScript ではなく、HTMLの data- 属性や json_script フィルタを使って渡すことを推奨します。
例:
<script>
let myValue = '{{ value|escapejs }}'
escapeseq¶
シーケンスのそれぞれの要素に対して escape フィルタを適用します。これはたとえば join のような、シーケンスを処理する他のフィルタと組み合わせて使うのが便利です。例をあげます:
{% autoescape off %}
{{ my_list|escapeseq|join:", " }}
{% endautoescape %}
filesizeformat¶
入力値を、人間が読みやすいファイルサイズ表現 ('13 KB', '4.1 MB', '102 bytes' など) に変換します。
例:
{{ value|filesizeformat }}
value が 123456789 のとき、出力は 117.7 MB になります。
ファイルサイズと国際単位系（SI）
filesizeformat は、厳密には国際単位系（SI）に準拠していません。国際単位系ではバイトサイズを 1024 の累乗で計算する場合 (上の例がそうですが) 、 KiB、MiB、GiB などの単位を使うよう推奨しています。しかし Django ではより一般的な表記に対応して、従来の単位名（ KB、 MB、GB など）を使用しています。
first¶
リスト中の最初の要素を返します。
例:
{{ value|first }}
value がリスト ['a', 'b', 'c'] であるとき、出力は 'a' になります。
floatformat¶
引数なしで使った場合、浮動小数点数を小数点以下１桁に丸めます。ただし小数部分がない時には整数部分だけを表示します。例を示します:
|
テンプレート |
出力 |
|---|---|---|
|
|
|
|
|
|
|
|
|
引数に１以上の整数を指定した場合、 floatformat は小数部分を指定された桁数で丸めます。以下に例を示します:
|
テンプレート |
出力 |
|---|---|---|
|
|
|
|
|
|
|
|
|
特に便利な使い方として、引数に 0 (ゼロ) を指定した場合、入力値を一番近い整数に丸めます。
|
テンプレート |
出力 |
|---|---|---|
|
|
|
|
|
|
|
|
|
引数に負の数を指定した場合、小数部分を指定された桁数（指定された数の絶対値）で丸めます。ただし小数部分がない時には整数部分だけを表示します。例を示します:
|
テンプレート |
出力 |
|---|---|---|
|
|
|
|
|
|
|
|
|
もし floatformat に渡された引数の接尾辞が g の場合、アクティブなロケールの THOUSAND_SEPARATOR によるグループ化を強制します。例えば、アクティブなロケールが en (英語) の場合、以下のようになります：
|
テンプレート |
出力 |
|---|---|---|
|
|
|
|
|
|
|
|
|
{% localize off %} タグに関係なく）出力は常にローカライズされます。ただし、 floatformat に渡された引数の接尾辞が u であった場合は、ローカライズが無効になります。例えば、アクティブなロケールが pl (ポーランド語) の場合、以下のようになります：
|
テンプレート |
出力 |
|---|---|---|
|
|
|
|
|
|
floatformat を引数なしで使用した場合の動作は、引数に -1 を指定した場合と同じです。
force_escape¶
文字列に HTML エスケープを適用します。 ( 詳しくは escape フィルタを参照してください )。フィルタは 即座に 適用され、新たなエスケープ済みの文字列を返します。このタグが有用となるケースは稀で、複数回のエスケープが必要な場合や、エスケープされた結果に対して他のフィルタを適用したい場合に使います。通常は escape フィルタを使うことになるでしょう。
例えば、 linebreaks フィルタによって作成された <p> HTML 要素をキャッチしたい場合、以下のようにします：
{% autoescape off %}
{{ body|linebreaks|force_escape }}
{% endautoescape %}
get_digit¶
入力値が整数であるとき、引数で指定された桁にある数字を返します。たとえば引数が 1 のとき右端の桁、 2 のとき右から 2 桁目が指定されます。入力が整数でない場合には、入力値をそのまま返します。
例:
{{ value|get_digit:"2" }}
value が 123456789 のとき、出力は 8 です。
iriencode¶
IRI (国際化リソース識別子 Internationalized Resource Identifier) を URL に適した文字列に変換します。これは非 ASCII 文字列を URL に埋め込む場合に必要なフィルタです。
urlencode フィルタを通した後の文字列を、このフィルタに通しても問題はありません。
例:
{{ value|iriencode }}
value が "?test=I ♥ Django" であるとき、出力は "?test=I%20%E2%99%A5%20Django" となります。
join¶
Python の str.join(list) と同じく、リストを文字列でつなぎます。
例:
{{ value|join:" // " }}
value の値がリスト ['a', 'b', 'c'] であるとき、出力は文字列 "a // b // c" となります。
json_script¶
Python オブジェクトを JSON として安全に出力し、 <script> タグでラップします。
引数: オプションで、HTMLの <script> タグの "id" を指定します。
例:
{{ value|json_script:"hello-data" }}
value が辞書 {'hello': 'world'} の場合、次のように出力されます：
<script id="hello-data" type="application/json">{"hello": "world"}</script>
結果のデータは JavaScript で次のようにアクセスできます：
const value = JSON.parse(document.getElementById('hello-data').textContent);
XSS攻撃は "<", ">", "&" をエスケープすることで緩和できます。例えば value が {'hello': 'world</script>&'} の場合、出力は次のようになります：
<script id="hello-data" type="application/json">{"hello": "world\\u003C/script\\u003E\\u0026amp;"}</script>
これは、ページ内でのスクリプト実行を禁止する厳格なコンテンツセキュリティポリシーと互換性があります。また、受動的なデータと実行可能なコードをきれいに分離します。
last¶
リストの末尾の要素を返します。
例:
{{ value|last }}
value の値がリスト ['a', 'b', 'c', 'd'] のとき、出力は文字列 "d" です。
length¶
入力値の長さを返します。これは、文字列とリストの両方で動作します。
例:
{{ value|length }}
value が ['a', 'b', 'c', 'd'] 、 "abcd" であるとき、それぞれ出力は 4 になります。
フィルタは未定義の変数に対して 0 を返します。
linebreaks¶
プレーンテキストの改行を適切な HTML タグに変換します。 改行 1 つは改行タグ (<br>) に、改行およびそれに続く空行は段落タグ (</p>) に変換されます。
例:
{{ value|linebreaks }}
value が Joel\nis a slug であるとき、出力は <p>Joel<br>is a slug</p> になります。
linebreaksbr¶
プレーンテキストの改行を HTML の改行タグ (<br>) に変換します。
例:
{{ value|linebreaksbr }}
value が Joel\nis a slug であるとき、出力は Joel<br>is a slug になります。
linenumbers¶
テキストを行番号付きで表示します。
例:
{{ value|linenumbers }}
value が以下の内容であるとします:
one
two
three
このとき出力は次のようになります:
1. one
2. two
3. three
ljust¶
入力値を指定した幅のフィールド内で左詰めします。
引数: フィールドの幅
例:
"{{ value|ljust:"10" }}"
value が Django であるとき、出力は "Django " となります。
lower¶
文字列を全て小文字に変換します。
例:
{{ value|lower }}
value が Totally LOVING this Album! であるとき、出力は totally loving this album! となります。
make_list¶
リストに変換された値を返します。文字列の場合は、文字のリストになります。整数の場合は、リストを作成する前に引数を文字列にキャストします。
例:
{{ value|make_list }}
value の値が文字列 "Joel" であるとき、出力はリスト ['J', 'o', 'e', 'l'] です。 value が 123 のとき、出力はリスト ['1', '2', '3'] となります。
phone2numeric¶
電話番号 (文字を含む場合もあります) を数値だけの番号に変換します。
入力値は正しい電話番号でなくてもかまいません。このフィルタはどんな文字列でも変換します。
例:
{{ value|phone2numeric }}
value が 800-COLLECT のとき、出力は 800-2655328 となります。
pluralize¶
値が 1, '1', または長さ 1 のオブジェクトでない場合、複数形を表す接尾辞を返します。デフォルトでは、この接尾辞は 's' です。
例:
You have {{ num_messages }} message{{ num_messages|pluralize }}.
num_messages が 1 のとき、出力は You have 1 message. です。 num_messages が 2 のとき、出力は You have 2 messages. となります。
's' 以外の接尾辞が必要な場合は、代わりの接尾辞をフィルタの引数で指定できます。
例:
You have {{ num_walruses }} walrus{{ num_walruses|pluralize:"es" }}.
単純な接尾辞では複数形にできない単語の場合、単数形と複数形の接尾辞の両方をコンマで区切って指定できます。
例:
You have {{ num_cherries }} cherr{{ num_cherries|pluralize:"y,ies" }}.
注釈
飜訳された文字列を複数形に変換するときは blocktranslate を使ってください。
pprint¶
pprint.pprint() のラッパーです -– 実のところ、これはデバッグ用です。
random¶
与えられたリストからランダムな要素を返します。
例:
{{ value|random }}
value の値がリスト ['a', 'b', 'c', 'd'] であるとき、出力は "b" かもしれません。
rjust¶
入力値を指定した幅のフィールド内で右詰めします。
引数: フィールドの幅
例:
"{{ value|rjust:"10" }}"
value が Django であるとき、出力は " Django" となります。
safe¶
文字列に対して、さらなる HTML エスケープが必要でないことをマークするのに使います。 autoescaping がオフの場合、このフィルタは何もしません。
注釈
フィルタを連鎖させる場合、 safe の後に適用されるフィルタはその内容を再び安全でない状態にしてしまうことが可能です。例えば以下のコードは、変数をそのまま、エスケープされない状態で出力します:
{{ var|safe|escape }}
safeseq¶
シーケンスのそれぞれの要素に対して safe フィルタを適用します。これは例えば join のような、シーケンスを処理する他のフィルタと組み合わせて使うのが便利です。例を挙げます:
{{ some_list|safeseq|join:", " }}
この場合、直接 safe フィルタを使用すると正しく動作しないかもしれません。シーケンスの個々の要素に対して作用するのではなく、まず変数を文字列に変換して処理するからです。
slice¶
リストに対するスライスを返します。
Python のリストスライスと同じ構文を使います。 Python ドキュメント を参照してください。
例:
{{ some_list|slice:":2" }}
some_list が ['a', 'b', 'c'] ならば、出力は ['a', 'b'] となります。
slugify¶
ASCIIに変換します。スペースをハイフンに変換します。英数字以外の文字、アンダースコア、ハイフンは削除します。小文字に変換します。また、先頭と末尾の空白を取り除きます。
例:
{{ value|slugify }}
value が "Joel is a slug" であるとき、出力は "joel-is-a-slug" となります。
stringformat¶
引数 (表示形式を指定する文字列) に応じて、変数の表示形式を変更します。指定方法には、printf-style String Formatting シンタックスを使います。例外として、最初の ''%'' は無視されます。
例:
{{ value|stringformat:"E" }}
たとえば value が 10 の場合、出力は 1.000000E+01 となります。
striptags¶
[X]HTML タグを全てはぎとるようにします。
例:
{{ value|striptags }}
value が "<b>Joel</b> <button>is</button> a <span>slug</span>" であるとき、出力は "Joel is a slug" となります。
安全性の保証はありません
注意してください。 striptags の出力は、特に不正な HTML の入力に対しては HTML の安全性を一切保証しません。 striptags の出力に safe フィルタを適用しては いけません 。より堅牢なものを探しているなら、サードパーティ製の HTML サニタイズツールの使用を検討してください。
time¶
時刻を指定の書式にしたがってフォーマットします。
フォーマットは date と同様に、あらかじめ定義された TIME_FORMAT のプリセット、またはカスタムフォーマットを使うこともできます。この定義はロケールに依存することに注意してください。
例:
{{ value|time:"H:i" }}
value が datetime.datetime.now() の値であるとき、出力は "01:23" といった文字列になります。
文字列の中でフォーマット文字を普通の文字として扱いたい場合は、バックスラッシュ文字（ \ ）でエスケープします。次の例では、 "h" と "m" をエスケープしています。そうしないと、これらはそれぞれ年と時刻を表示するためのフォーマット文字とみなされるからです:
{{ value|time:"H\h i\m" }}
上記は "01h 23m" と表示されます。
その他の例:
たとえば LANGUAGE_CODE が "de" だったとして、：
{{ value|time:"TIME_FORMAT" }}
このときの出力は、"01:23" といった文字列になります (初期状態の Django では、ロケール de の "TIME_FORMAT" には "H:i" が定義されています) 。
time フィルタは日付ではなく、1 日における時刻に関連するパラメータのみをフォーマット文字列として受け付けます。日付 のフォーマットを行いたいときは、 date フィルタを使ってください ( datetime の値をすべて表示させたい場合は time と一緒に使います)。
上記のルールにはひとつ例外があります。タイムゾーン情報が付加された datetime 値 (タイムゾーンを意識した aware な datetime インスタンス) が渡された場合、time フィルターはタイムゾーン関連の フォーマット指定子 'e', 'O', 'T', 'Z' を受け付けます。
フォーマット文字列なしで使用する場合は、 TIME_FORMAT フォーマット指定子が使用されます：
{{ value|time }}
上記は以下と同じです：
{{ value|time:"TIME_FORMAT" }}
timesince¶
日付を経過時間の形式にフォーマットします (たとえば "4 days, 6 hours")。
オプションの引数として、比較対象とする時刻をとります (引数を省略すると 現在時刻 を使います)。例えば、 blog_date が 2006年 6月 1日 を表す日付オブジェクトで、comment_date が 2006年 6月 1日 08:00 を表す日時オブジェクトであるとき、以下のコードは "8 hours" を返します：
{{ blog_date|timesince:comment_date }}
タイムゾーン情報を持たない値（offset-naive）と、タイムゾーン情報つき（offset-aware）の値とを比較した場合は、空の文字列を返します。
最小単位は "分" です。比較対象からみて未来にある日時に対しては "0 minutes" を返します。
timeuntil¶
timesince に似ていますが、現在時刻を起点として指定の日付または日時までの時刻を計算します。たとえば今日が2006年6月1日で conference_date が 2006年6月29日の値を保持する日付インスタンスだったとすれば、{{ conference_date|timeuntil }} は "4 weeks" を返します。
オプションの引数として、 (現在時刻 の代わりに) 比較対象として使う時刻をとります。 例えば、 from_date が 2006年 6月 22日 の場合、以下のコードは "1 week" を返します:
{{ conference_date|timeuntil:from_date }}
タイムゾーン情報を持たない値（offset-naive）と、タイムゾーン情報つき（offset-aware）の値とを比較した場合は、空の文字列を返します。
最小単位は "分" です。比較対象からみて過去にある日時に対しては “0 minutes” を返します。
title¶
文字列中の単語に対して、それぞれ先頭の文字を大文字に、残りを小文字にすることで文字列をタイトルケースに変換します。"主要でない単語" については小文字を維持できないこともあります。
例:
{{ value|title }}
value が "my FIRST post" であるとき、出力は "My First Post" となります。
truncatechars¶
文字列が指定した文字数より長い場合は切り捨てます。切り捨てられた文字列の末尾は、翻訳可能な省略記号 ("...") になります。
引数: 切り詰める文字数
例:
{{ value|truncatechars:7 }}
value が "Joel is a slug" であるとき、出力は "Joel i…" となります。
truncatechars_html¶
truncatechars に似ていますが、 HTML タグを認識します。切り詰めを行う時点で閉じていないタグがあれば、切り詰めた文字の直後に全て閉じます。
例:
{{ value|truncatechars_html:7 }}
value が "<p>Joel is a slug</p>" の場合、出力は "<p>Joel i…</p>" となります。
HTML コンテンツ内の改行は保持されます。
入力文字列のサイズ
大きく、潜在的に不正なHTML文字列を処理することは、リソースを消費し、サービスのパフォーマンスに影響を与える可能性があります。 truncatechars_html は入力を最初の500万文字に制限します。
古いバージョンでは、500万文字以上の文字列も処理されていました。
truncatewords¶
文字列を指定された単語数以内に切り詰めます。
引数: 切り詰めた後の単語数
例:
{{ value|truncatewords:2 }}
value が "Joel is a slug" の場合、出力は "Joel is …" になります。
文字列中の改行は取り除かれます。
truncatewords_html¶
truncatewords に似ていますが、 HTML タグを認識します。切り詰めを行う時点で閉じていないタグがあれば、切り詰めた文字の直後に全て閉じます。
このタグの処理は truncatewords よりも効率が悪いため、 HTML テキストを 渡す場合にだけ使うようにしてください。
例:
{{ value|truncatewords_html:2 }}
value が "<p>Joel is a slug</p>" の場合、出力は "<p>Joel is …</p>" となります。
HTML コンテンツ内の改行は保持されます。
入力文字列のサイズ
大きく、潜在的に不正なHTML文字列を処理することは、リソースを消費し、サービスのパフォーマンスに影響を与える可能性があります。 truncatewords_html は入力を最初の500万文字に制限します。
古いバージョンでは、500万文字以上の文字列も処理されていました。
unordered_list¶
再帰的に入れ子になったリストを入力として、 HTML の順序なしリスト (UL, unordered list) に変換します。ただし先頭と末尾の <ul> タグは表示しません。
リストは適切な形式になっているものとみなします。例えば、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>
upper¶
入力値をすべて大文字に変換します。
例:
{{ value|upper }}
value が "Joel is a slug" であるとき、出力は "JOEL IS A SLUG" となります。
urlencode¶
入力値を URL で使えるようにエスケープします。
例:
{{ value|urlencode }}
value が "https://www.example.org/foo?a=b&c=d" のとき、出力は "https%3A//www.example.org/foo%3Fa%3Db%26c%3Dd" となります。
オプションの引数で、エスケープさせない文字を指定できます。
特に指定しなくても '/' の文字はエスケープされません。オプションで空の文字列が指定された場合は、すべての 文字がエスケープされます。例を挙げます:
{{ value|urlencode:"" }}
ここで value が "https://www.example.org/" であるとき、出力は "https%3A%2F%2Fwww.example.org%2F" となります。
urlize¶
テキスト内の URL と Email アドレスをクリック可能なリンクに変換します。
このテンプレートタグは、http://、https://、または www. で始まるリンクに対して動作します。例えば、https://djangocon.eu は変換されますが、 djangocon.eu は変換されません。
末尾が .com、.edu、.gov、.int、.mil、.net、.org である場合は、ドメイン名のみのリンクもサポートします。たとえば djangoproject.com は変換されます。
リンクの末尾に句読点（ピリオド、カンマ、閉じ括弧）や先頭に句読点（開き括弧）があっても、 urlize は正しく処理します。
urlize が生成したリンクにはアトリビュート rel="nofollow" が加えられています。
例:
{{ value|urlize }}
value が "Check out www.djangoproject.com" であるとき、出力は "Check out <a href="http://www.djangoproject.com" rel="nofollow">www.djangoproject.com</a>" となります。
ウェブリンクに加えて、 urlize は email アドレスも mailto: リンクに変換できます。value が "Send questions to foo@example.com" であるとき、出力は "Send questions to <a href="mailto:foo@example.com">foo@example.com</a>" となります。
urlize フィルタはオプションの引数 autoescape をとることができます。autoescape が True のとき、リンクテキストと URL は Django の組み込みフィルタ escape でエスケープされます。指定しない場合の autoescape の値は True です。
注釈
もし urlize をすでに HTML マークアップを含むテキストに適用したり、シングルクォート(')を含むメールアドレスに適用したりすると、期待通りに動作しません。このフィルタはプレーンテキストにだけ適用してください。
警告
urlize や urlizetrunc を使用すると、パフォーマンスに悪影響が出ることがあります。特に、TextField のようにユーザーが制御できる値に適用すると、悪影響が大きくなることがあります。そのような入力に制限を加えるには、truncatechars を使用します。
{{ value|truncatechars:500|urlize }}
urlizetrunc¶
urlize と同じように、URL と email アドレスをクリック可能なリンクに変換します。ただし、指定の文字数以上の表示を切り詰めます。
引数: URL を切り詰める長さ。省略記号の長さを含みます。省略記号は省略が必要な場合につけられます。
例:
{{ value|urlizetrunc:15 }}
value が "Check out www.djangoproject.com" であるとき、出力は 'Check out <a href="http://www.djangoproject.com" rel="nofollow">www.djangoproj…</a>' となります。
urlize と同じく、このフィルタはプレーンテキストに対してだけ使ってください。
wordcount¶
ワード数を返します。
例:
{{ value|wordcount }}
value が "Joel is a slug" のとき、出力は 4 です。
wordwrap¶
指定した行幅でワードラップします。
引数: テキストをラップするまでのワード数
例:
{{ value|wordwrap:5 }}
value が Joel is a slug の場合、出力は以下のようになります:
Joel
is a
slug
yesno¶
入力値 ( "True" 、 "False" 、オプションで "None" ) に対応する文字列を返します。対応する文字列はデフォルトでは "yes"、"no"、"maybe" です。またコンマ区切りの文字列を引数として与えることでカスタムマッピングを指定できます。
例:
{{ value|yesno:"yeah,no,maybe" }}
値 |
引数 |
出力 |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
国際化タグとフィルタ¶
Django はテンプレートの 国際化 をそれぞれの角度から制御するタグやフィルタを提供し、翻訳、書式設定、およびタイムゾーン変換のきめ細かい制御を可能にしています。
i18n¶
このライブラリは、テンプレート内の飜訳可能なテキストを指定できます。これを有効化するには USE_I18N を True に設定し、 {% load i18n %} でロードします。
国際化: テンプレート内 も参照してください。
l10n¶
このライブラリはテンプレート内の値のローカライズを制御します。このライブラリは {% load l10n %} を使って読み込むだけです。
テンプレート内でローカライズをコントロールする も参照してください。
tz¶
このライブラリは、テンプレートのタイムゾーン変換を制御します。 l10n と同じく、必要なのは {% load tz %} を使ってライブラリをロードするだけですが、通常はデフォルトでローカル時間に変換されるよう、 USE_TZ を True に設定するでしょう。
テンプレートでのタイムゾーン aware な出力 も参照してください。
その他のタグとフィルタライブラリ¶
この他にも、Django にはいくつかのテンプレートタグ・ライブラリがあります。これらのライブラリは INSTALLED_APPS 設定で明示的に有効化したうえ、 {% load %} タグを使ってテンプレート上にロードする必要があります。
django.contrib.humanize¶
データを「ヒトにやさしい」表現にする上で便利な Django テンプレートフィルタのセットです。くわしくは django.contrib.humanize を参照してください。
static¶
static¶
STATIC_ROOT に保存されている静的ファイルにリンクするために、 Django には static テンプレートタグが同梱されています。 django.contrib.staticfiles アプリケーションがインストールされていれば、このタグは STORAGES で staticfiles で指定されたストレージの url() メソッドを使ってファイルを配信します。たとえば以下のようにします：
{% load static %}
<img src="{% static 'images/hi.jpg' %}" alt="Hi!">
普通のコンテキスト変数を使うこともできます。例えば user_stylesheet 変数をテンプレートに渡す場合は、以下のようにします:
{% load static %}
<link rel="stylesheet" href="{% static user_stylesheet %}" media="screen">
静的 URL を表示することなく取得したい場合は、少し異なる呼び出し方法になります：
{% load static %}
{% static "images/hi.jpg" as myphoto %}
<img src="{{ myphoto }}" alt="Hi!">
Jinja2 テンプレートを使いますか？
Jinja2 で static タグを使う方法については Jinja2 を参照してください。
get_static_prefix¶
通常は static テンプレートタグの使用を推奨しますが、 STATIC_URL がテンプレートに挿入される場所と方法をより厳密に制御する必要がある場合は、 get_static_prefix テンプレートタグが使用できます：
{% load static %}
<img src="{% get_static_prefix %}images/hi.jpg" alt="Hi!">
値を何度も使う必要がある場合、不要な処理を避けるために使用できる別の方式もあります:
{% load static %}
{% get_static_prefix as STATIC_PREFIX %}
<img src="{{ STATIC_PREFIX }}images/hi.jpg" alt="Hi!">
<img src="{{ STATIC_PREFIX }}images/hi2.jpg" alt="Hello!">
get_media_prefix¶
get_static_prefix と同じように、get_media_prefix はテンプレート変数に MEDIA_URL のメディア・プレフィックスを加えます。たとえば:
{% load static %}
<body data-media-url="{% get_media_prefix %}">
値をデータ属性に格納することで、JavaScriptのコンテキストで使用する場合に適切にエスケープされるようになります。
