このドキュメントはDjangoテンプレートシステムの文法を説明しています。もしあなたがもっと技術者的な観点でどう動かすかやどう拡張するかを知りたい場合は、The Django template language: for Python programmers をご覧ください。
\nDjango のテンプレート言語は、パワーと使いやすさのバランスを取るように設計されています。HTMLでの作業に使用されるものが快適に感じられるように設計されているのです。あなたが他のテキストベースのテンプレート言語に対して Smarty や Jinja2 のような露出的な処理を習得しているのなら、Django テンプレートをより身近に感じられるはずです。
\n\nテンプレートは、単純なテキストファイルです。これは、任意のテキストベースのフォーマット (HTML、XML、CSV) などを生成することができます。
\nテンプレートに含まれるのは、テンプレートが読み込まれたとき実際の値で置き換えられる 変数 と、テンプレートのロジックを制御する タグ です。
\n下は幾つかの基本を示している少ない見本です。各要素については、このドキュメントの後半で説明します。
\n{% extends "base_generic.html" %}\n\n{% block title %}{{ section.title }}{% endblock %}\n\n{% block content %}\n<h1>{{ section.title }}</h1>\n\n{% for story in story_list %}\n<h2>\n <a href="{{ story.get_absolute_url }}">\n {{ story.headline|upper }}\n </a>\n</h2>\n<p>{{ story.tease|truncatewords:"100" }}</p>\n{% endfor %}\n{% endblock %}\nVariables look like this: {{ variable }}. When the template engine\nencounters a variable, it evaluates that variable and replaces it with the\nresult. Variable names consist of any combination of alphanumeric characters\nand the underscore ("_") but may not start with an underscore. The dot\n(".") also appears in variable sections, although that has a special\nmeaning, as indicated below. Importantly, you cannot have spaces or\npunctuation characters in variable names.
変数の属性にアクセスするには、ドットを ('.') を使用します。
In the above example, {{ section.title }} will be replaced with the\ntitle attribute of the section object.
もし存在しない変数を使いたい場合、テンプレートシステムは`デフォルトで``''`` (the empty string)が置かれている場所に、string_if_invalid` のオプション値を挿入します。
\nNote that "bar" in a template expression like {{ foo.bar }} will be\ninterpreted as a literal string and not using the value of the variable "bar",\nif one exists in the template context.
Variable attributes that begin with an underscore may not be accessed as\nthey're generally considered private.
\nYou can modify variables for display by using filters.
\nFilters look like this: {{ name|lower }}. This displays the value of the\n{{ name }} variable after being filtered through the lower\nfilter, which converts text to lowercase. Use a pipe (|) to apply a filter.
Filters can be "chained." The output of one filter is applied to the next.\n{{ text|escape|linebreaks }} is a common idiom for escaping text contents,\nthen converting line breaks to <p> tags.
Some filters take arguments. A filter argument looks like this: {{\nbio|truncatewords:30 }}. This will display the first 30 words of the bio\nvariable.
Filter arguments that contain spaces must be quoted; for example, to join a\nlist with commas and spaces you'd use {{ list|join:", " }}.
Django provides about sixty built-in template filters. You can read all about\nthem in the built-in filter reference.\nTo give you a taste of what's available, here are some of the more commonly\nused template filters:
\ndefaultIf a variable is false or empty, use given default. Otherwise, use the\nvalue of the variable. For example:
\n{{ value|default:"nothing" }}\nIf value isn't provided or is empty, the above will display\n"nothing".
lengthReturns the length of the value. This works for both strings and lists.\nFor example:
\n{{ value|length }}\nIf value is ['a', 'b', 'c', 'd'], the output will be 4.
filesizeformatFormats the value like a "human-readable" file size (i.e. '13 KB',\n'4.1 MB', '102 bytes', etc.). For example:
{{ value|filesizeformat }}\nvalue が 123456789 のとき、出力は 117.7 MB になります。
Again, these are just a few examples; see the built-in filter reference for the complete list.
\nYou can also create your own custom template filters; see\n独自のテンプレートタグとフィルタ.
\n\nTo comment-out part of a line in a template, use the comment syntax: {# #}.
For example, this template would render as 'hello':
{# greeting #}hello\nA comment can contain any template code, invalid or not. For example:
\n{# {% if foo %}bar{% else %} #}\nThis syntax can only be used for single-line comments (no newlines are permitted\nbetween the {# and #} delimiters). If you need to comment out a\nmultiline portion of the template, see the comment tag.
Django のテンプレートエンジンの中で最もパワフルな -- ゆえに最も複雑な -- 部分が、テンプレートの継承です。テンプレートを継承すると、ベースとなる "骨組みの" テンプレートにサイトの共通要素を記述し、block を定義することで子テンプレートにオーバーライドさせることができます。
\nテンプレートの継承を理解するには、実例を見るのが一番早いでしょう:
\n<!DOCTYPE html>\n<html lang="en">\n<head>\n <link rel="stylesheet" href="style.css">\n <title>{% block title %}My amazing site{% endblock %}</title>\n</head>\n\n<body>\n <div id="sidebar">\n {% block sidebar %}\n <ul>\n <li><a href="/">Home</a></li>\n <li><a href="/blog/">Blog</a></li>\n </ul>\n {% endblock %}\n </div>\n\n <div id="content">\n {% block content %}{% endblock %}\n </div>\n</body>\n</html>\n我々が base.html と呼ぶことになるこのテンプレートは、シンプルな HTML の骨組みを定義し、シンプルな 2 列のサイトを表示できるようになっています。block をコンテンツで埋めるのは、""子"" テンプレートの仕事です。
この例では、block タグにより、子テンプレートが埋めることができる 3 つのブロックが定義されています。block タグの仕事は、テンプレートのこれらの部分が子テンプレートによりオーバーライドされる可能性があることをテンプレートエンジンに伝えることです。
子テンプレートは以下のようになります:
\n{% extends "base.html" %}\n\n{% block title %}My amazing blog{% endblock %}\n\n{% block content %}\n{% for entry in blog_entries %}\n <h2>{{ entry.title }}</h2>\n <p>{{ entry.body }}</p>\n{% endfor %}\n{% endblock %}\nここで重要なのは extends タグです。このタグが、このテンプレートが他のテンプレートを "拡張" することをテンプレートエンジンに伝えるのです。テンプレートシステムがこの点プレートを評価する際に、最初に親テンプレートを探しに行きます -- この例では "base.html" です。
この時点で、テンプレートエンジンは base.html 内の block を認識し、子テンプレートのコンテンツと差し替えます。blog_entries の値に応じて、アウトプットは以下のようになります:
<!DOCTYPE html>\n<html lang="en">\n<head>\n <link rel="stylesheet" href="style.css">\n <title>My amazing blog</title>\n</head>\n\n<body>\n <div id="sidebar">\n <ul>\n <li><a href="/">Home</a></li>\n <li><a href="/blog/">Blog</a></li>\n </ul>\n </div>\n\n <div id="content">\n <h2>Entry one</h2>\n <p>This is my first entry.</p>\n\n <h2>Entry two</h2>\n <p>This is my second entry.</p>\n </div>\n</body>\n</html>\n子テンプレート内で sidebar を定義していないため、親テンプレートの値がそのまま使われていることに留意してください。親テンプレートの {% block %} タグ内のコンテンツは、常にフォールバックとして使用されます。
継承は、必要なだけ段階を経ることができます。継承を使う一般的な方法は、以下の 3 段階のアプローチです:
\nメインのルック・アンド・フィールを保持する base.html を作成します。
それぞれの "セクション" に対して、base_セクション名.html テンプレートを作成します。例えば、base_news.html、base_sports.html などです。これらはすべて base.html を拡張 (extends) し、セクション固有のスタイルやデザインを定義します。
ページのそれぞれのタイプに対して、個別のテンプレートを作成します。たとえばニュース記事やブログエントリーなどです。これらのテンプレートは、適切なセクションの手プレートを拡張 (extends) します。
このアプローチにより、コードの再利用を最大化でき、共通のコンテンツ部 (全セクション共通のナビゲーションなど) に項目を追加するのが容易になります。
\n継承を使用する際のコツをいくつか紹介します:
\nテンプレート内で {% extends %} を使用する際は、その点プレート内で一番最初のテンプレートタグとして指定する必要があります。それ以外の場合、継承が正しく動作しません。
ベースのテンプレートには {% block %} タグを多く配置するほどよいです。子テンプレートがすべてのブロックを埋める必要がないことを思い出してください。多くのブロック内に適当なデフォルトを記述しておき、必要なものを後で定義し直せばいいのです。フックは多ければ多いほどいいということです。
もし同じコンテンツを複数のテンプレート内で記述していたら、そのコンテンツを親テンプレートの {% block %} に移動させるべきかもしれません。
親テンプレートからブロックのコンテンツを取得する必要がある場合、{{ block.super }} が利用できます。親のブロックを完全にオーバーライドせずに、コンテンツを追加したい場合に有用です。{{ block.super }} を使って挿入されたデータは自動的にエスケープされません (next section を参照してください)。これは、必要な場合は親テンプレートですでにエスケープされているからです。
テンプレートタグの as シンタックスを使用して {% block %} の外で生成された変数は、ブロックの内部で使用することはできません。例えば、以下のテンプレートは何も表示しません:
{% trans "Title" as title %}\n{% block content %}{{ title }}{% endblock %}\n可読性を増すために、{% endblock %} タグにも 名前 を記述できます。例えば:
{% block content %}\n...\n{% endblock content %}\n大きなテンプレートでは、このテクニックでどの {% block %} が閉じられているのかが分かりやすくなります。
最後に、同じテンプレート内で同じ名前の block タグを複数定義することはできないことに留意してください。この制限は、block タグが "両方向に" 働くのが理由です。block タグは埋めるための穴を提供するだけではなく -- 親テンプレート 内で穴を埋めるコンテンツを定義します。もし同名の block がテンプレート内に 2 つ存在すると、どちらのブロックのコンテンツを使うべきかテンプレートの親が判断できなくなってしまうのです。
テンプレートから HTML を生成する時には、変数内の文字が HTML のレンダリング結果に悪影響を与えるというリスクが常に付きまといます。例えば、テンプレートに以下のような箇所がある場合を考えてみましょう:
\nHello, {{ name }}\n一見、このコードはユーザの名前を表示するだけの無害なものと思えます。しかし次のような値が名前として入力されていれば、何が起きるでしょうか:
\n<script>alert('hello')</script>\nこの値によって、テンプレートは次のように出力されます:
\nHello, <script>alert('hello')</script>\n……結果として、ブラウザに JavaScript の警告ボックスをポップアップさせることができてしまいます!
\n同様に、名前に '<' 文字が含まれていたらどうでしょうか:
<b>username\nこの値によって、テンプレートはこのように出力されます:
\nHello, <b>username\nこれで、以降の Web ページの内容はすべて太字の表示になってしまいます!
\nユーザーが入力したデータを無条件に信頼したり、直接 Web ページに挿入したりするべきでないことは明らかです。悪意のあるユーザは、この手の抜け穴を使って悪さをするものだからです。こうしたタイプのセキュリティホールの悪用は、 `クロスサイトスクリプティング `_(XSS) 攻撃と呼ばれています。
\nこの問題を防ぐために、二つの方法があります:
\n一つは、信頼できない変数は必ず escape フィルタ (後で述べます) に通すことです。このフィルタは危害を及ぼす可能性をもつ HTML 文字を無害な文字に変換します。 この方法は初期の数年間において Django のデフォルトとして採用されていました。しかしユーザー、すなわち開発者やテンプレートの作者にとっては、すべてのデータをエスケープすることを忘れぬよう注意しなければならないという負担になるのが問題です。
もう一つは、 Django の自動 HTML エスケープを使うというものです。この節の後半では自動エスケープの仕組みについて述べます。
デフォルトでは、Django はすべてのテンプレートの変数タグの出力を自動的にエスケープするよう設定されています。具体的には、以下の 5 つの文字がエスケープされます:
\n< を < に変換
> を > に変換
' ( シングルクォート ) を ' に変換
" ( ダブルクォート ) を " に変換
& を & に変換
この動作は、デフォルトで適用されていることを重ねて強調しておきます。Django テンプレートシステムを使っているかぎり、あなたはエスケープに関する問題からは守られているのです。
\nサイト単位やテンプレート単位、あるいは変数単位でデータの自動エスケープ機能を無効にしたい場合には、いくつかの方法があります。
\nどんなときに、自動エスケープをオフにする必要があるでしょうか。テンプレート変数の中身は、生の HTML として出力するように意図されたデータかもしれません。そうした場合にはコンテンツがエスケープされてほしくはないでしょう。例えば、データベースに HTML を保存していてテンプレートに直接埋め込みたい場合を考えてみましょう。また、 Django のテンプレートシステムを使って、 HTML 以外 のデータ、例えば電子メールメッセージなどを生成したい場合もあるでしょう。
\n変数単位で個々に自動エスケープを無効にするには、 safe フィルタを使います:
This will be escaped: {{ data }}\nThis will not be escaped: {{ data|safe }}\nsafe という言葉は、これ以上エスケープしないよう保護（safe）するとか、 HTML として解釈しても安全（safe）であるという意味だと考えてください。 例えば、 data に '<b>' が入っていた場合、出力は以下のようになります:
This will be escaped: <b>\nThis will not be escaped: <b>\nテンプレート単位で自動エスケープを制御するには、テンプレート (または テンプレートの一部) を、以下のように autoescape タグで囲みます:
{% autoescape off %}\n Hello {{ name }}\n{% endautoescape %}\nautoescape タグは、 on または off を引数にとります。 テンプレートのある範囲を自動エスケープし、さらにその一部で自動エスケープをオフにしたい場合には、次のようにできます:
Auto-escaping is on by default. Hello {{ name }}\n\n{% autoescape off %}\n This will not be auto-escaped: {{ data }}.\n\n Nor this: {{ other_data }}\n {% autoescape on %}\n Auto-escaping applies again: {{ name }}\n {% endautoescape %}\n{% endautoescape %}\n自動エスケープのタグは、他のブロックタグと同様、タグを設定したテンプレートを継承している他のテンプレートや、 :ttag:include で取り込んだテンプレートでも有効です。例えば:
{% autoescape off %}\n<h1>{% block title %}{% endblock %}</h1>\n{% block content %}\n{% endblock %}\n{% endautoescape %}\n{% extends "base.html" %}\n{% block title %}This & that{% endblock %}\n{% block content %}{{ greeting }}{% endblock %}\nベースのテンプレートで自動エスケープが無効化されているので、子テンプレートでも自動エスケープは無効化されます。結果として、 greeting 変数の値が ``<b>Hello!</b>'' のとき、以下の HTML が出力されます:
<h1>This & that</h1>\n<b>Hello!</b>\n一般に、テンプレートの作者は自動エスケープをあまり意識する必要はありません。 データをエスケープすべきではない場合を考えたり、データを適切にマークし、テンプレート上でうまく表示されるように考慮するのは、Python 側の開発者 (ビューやカスタムフィルタの開発者)であるべきです。
\nもしあなたが作成しているテンプレートがどういった状況で使われるのか分からず、自動エスケープが有効かどうかはっきりしない場合には、エスケープの必要な変数全てに escape フィルタを追加してください。自動エスケープがオンの場合、 escape フィルタがデータ を二重にエスケープするような危険性はありません。 escape フィルタは自動エスケープされた変数には影響しなません。
先に説明したように、フィルタの引数は文字列であってもかまいません:
\n{{ data|default:"This is a string literal." }}\n文字列リテラルは、すべて自動エスケープ**されずに**テンプレート内に挿入され、 safe フィルタを通して渡されたかのように振る舞います。なぜならば、テンプレートの作者はその文字列リテラルに何が書かれているかは把握していますし、テンプレートが書かれる時点でテキストが正しくエスケープされていることは確認できるからです。
したがって、以下のようにテンプレートを書いてください:
\n{{ data|default:"3 < 2" }}\n以下のようにはしないでください:
\n{{ data|default:"3 < 2" }} {# Bad! Don't do this. #}\nこの事が、変数自身に由来するデータに対して何かを引き起こす恐れはありません。 変数の内容はテンプレート作者の管理外にあり、必要に応じて自動的にエスケープされます。
\nオブジェクトに備わったほとんどのメソッドは、テンプレートの中からでも呼び出すことができます。これはテンプレートからアクセスできる対象は、単にクラスの属性 (フィールド名のように) やビューを通した変数だけにはとどまらないということを意味します。例えば Django ORM は Foreign キーに関係するオブジェクトの集合を見つけるために "entry_set” という構文を提供しています。これによって、例えば “comment” と呼ばれるモデルが Foreign キーで ”task” というモデルに関連づけられている場合、テンプレートは task モデルに添えられた全ての comment に対して以下のようにアクセスできます:
\n{% for comment in task.comment_set.all %}\n {{ comment }}\n{% endfor %}\n同じように、 QuerySets は、そこに含まれているオブジェクトの個数を数えるため count() というメソッドを提供しています。これによって、 task と関連づけられた全てのコメントの数を取得することも出来ます:
{{ task.comment_set.all.count }}\nそしてもちろん、モデル自身で明示的に定義したメソッドにも簡単にアクセスすることができます:
\nclass Task(models.Model):\n def foo(self):\n return "bar"\n{{ task.foo }}\nDjango ではテンプレート内でのプログラム的な処理を意図的に制限しているため、テンプレートからメソッドに引数を渡すことはできません。データはビューの中で計算され、テンプレートへは表示のためだけに渡されるべきだからです。
\nアプリケーションによっては、カスタムのタグやフィルタライブラリを提供しています。これらをテンプレートで使いたい場合、そのアプリケーションが INSTALLED_APPS に追加されていることを確認し (以下の例では 'django.contrib.humanize' が追加されているものとします) 、そしてテンプレート側で load タグを使います:
{% load humanize %}\n\n{{ 45000|intcomma }}\nこの例では、 load タグは humanize という名前のタグライブラリを読み込み、 intcomma フィルタを使えるようにしています。 django.contrib.admindocs が有効にされている場合、あなたの admin は現在インストールされているアプリケーションのドキュメント文字列を参照してカスタムライブラリの一覧を得ることができます。
load タグは複数のライブラリ名を同時に読み込めます。ライブラリ名は スペースで区切って下さい:
{% load humanize i18n %}\nカスタムのテンプレートライブラリを作成する方法については、:doc:'/howto/custom-template-tags` を参照してください。
\nカスタムタグやフィルタライブラリをロードした場合、タグやフィルタは現在のテンプレートだけで利用でき、テンプレート継承パスにおける親テンプレートや子テンプレートでは利用できません。
\n例えば foo.html に {% load humanize %} というタグが入っていても、子テンプレート ( {% extends "foo.html" %} を使っているテンプレート) で humanize という名前のテンプレートタグやフィルタを使えるわけではありません。子テンプレート側で対応するには独自に {% load humanize %} を入れる必要があります。
これはメンテナンス性と健全性を高めるための仕様です。
\n\n