{% block title %}My amazing site{% endblock %}

`` タグに置き換える時の慣用句としてよく使われています。フィルタによっては引数をとります。フィルタの引数は ``{{ bio|truncatewords:"30" }}`` のような形式で表します。この例では、変数 ``bio`` の最初の 30 語を表示します。フィルタの引数にスペースが入っている場合は、二重引用符で囲ってください。例えば、カンマとスペースでリストを結合するには ``{{ list|join:", " }}`` のようにします。 :ref:`組み込みフィルタリファレンス` では、全ての組み込みフィルタについて説明しています。組み込みフィルタでできることを知ってもらうために、よく使うテンプレートフィルタをいくつか挙げましょう: :tfilter:`default` 入力が空や ``False`` の場合、引数に指定したデフォルト値を使います。そうでなければ、入力をそのまま使います使用例:: {{ value|default:"nothing" }} ``value`` が存在しなかったり空だったりすると、 "``nothing``" を出力します。 :tfilter:`length` 入力値の長さを返します。文字列とリストいずれにも作用します。使用例:: {{ value|length }} ``value`` が ``['a', 'b', 'c', 'd']`` なら、 ``4`` を出力します。 :tfilter:`striptags` [X]HTML タグを全てはぎとります。使用例:: {{ value|striptags }} ``value`` が ``"Joel a slug"`` なら、 ``"Joel is a slug"`` を出力します。これらはほんの一部に過ぎません。全ての組み込みフィルタの一覧は :ref:`組み込みフィルタリファレンス ` を参照してください。テンプレートフィルタは自作できます。 :doc:`/howto/custom-template-tags` を参照してください。 .. seealso:: Django のアドミンインターフェイスはすべてのテンプレートタグと利用可能なフィルタに関してはこちらのサイトで完全な参照を得られます。 :doc:`/ref/contrib/admin/admindocs` タグ ==== タグは ``{% tag %}`` のように書きます。タグの考え方は、変数よりもやや複雑です。出力されるテキストを生成するものもありますし、ループやロジックを実行して、処理の流れを制御するものもあります。また、外部の情報を取り込んで、後に出て来る変数から使えるようにするものもあります。タグによっては、開始タグと終了タグ (``{% tag %} ... tag contents ... {% endtag %}``) を必要とするものがあります。 Django にはたくさんの組み込みタグが付属しています。組み込みタグの解説は :ref:`組み込みタグリファレンス ` にあります。組み込みタグでできることを知ってもらうために、よく使うタグをいくつか挙げましょう: :ttag:`for` アレイの各要素に渡ってループします。例えば、アスリート (athlete) のリストを ``athlete_list`` で渡して表示するには、以下のようにします::

{% for athlete in athlete_list %}

{% endfor %}

` を参照してください。テンプレートタグは自作できます。 :doc:`/howto/custom-template-tags` を参照してください。 .. seealso:: Djangoのアドミンインターフェイスはすべてのテンプレートタグと利用可能なフィルタに関してはこちらのサイトで完全な参照を得られます。 :doc:`/ref/contrib/admin/admindocs` コメント ======== テンプレート中で行内の一部をコメントアウトするには、コメント構文 ``{# #}`` を使います。例えば、以下のテンプレートをレンダすると ``'hello'`` になります:: {# greeting #}hello コメント内には任意のテンプレートコードを入れられます。コメント内のテンプレートコードが無効なものであってもエラーにはなりません:: {# {% if foo %}bar{% else %} #} この構文を使えるのは、一行のコメントの場合だけです (``{#`` と ``#}`` の間には改行を入れられません)。複数行のコメントアウトを行いたければ、後述の :ttag:`comment` タグを使ってください。 .. _template-inheritance: テンプレートの継承 ================== Django のテンプレートエンジンにおいて、テンプレートの継承 (inheritance) は最もパワフル -- かつ最も難解 -- な部分です。テンプレートの継承は、自分のサイトで共通に使われる全ての要素の入った、ベースとなる「骨組みの」テンプレートを作っておき、その中に子のテンプレートでオーバライドできる **ブロック(block)** を定義できます。テンプレートの継承を理解するには、まず例を挙げるのが一番でしょう:: {% block title %}My amazing site{% endblock %}

{% block content %}{% endblock %}

このテンプレートは、単純な 2 カラム形式のページで使うような HTML のスケルトンドキュメントです。これを ``base.html`` と呼びましょう。空のブロックをコンテンツで埋めるのは「子 (child)」のテンプレートの仕事です。この例では、 :ttag:`block` タグを使って 3 つのブロックを定義し、子テンプレートが値を埋められるようにしています。 :ttag:`block` タグの役割は、テンプレート中のタグで囲まれた部分を子テンプレートでオーバライドできることをテンプレートエンジンに知らせることにあります。子テンプレートは以下のようになります:: {% extends "base.html" %} {% block title %}My amazing blog{% endblock %} {% block content %} {% for entry in blog_entries %}

{% endfor %} {% endblock %} :ttag:`extends` タグが継承のカギです。このタグはテンプレートエンジンに対して、自分自身が他のテンプレートを拡張 (extend) していることを教えます。テンプレートシステムがこのテンプレートを処理する際、システムはまず親となるテンプレート -- ここでは "base.html" を探します。さて、この時点で、テンプレートエンジンは ``base.html`` 内に三箇所の :ttag:`block` が定義されていることに気づき、これらのブロックを子テンプレートの該当するブロックで置き換えます。 ``blog_entries`` の値に応じて、出力は以下のようになります:: My amazing blog

Entry one

This is my first entry.

Entry two

This is my second entry.

子テンプレートには ``sidebar`` ブロックが定義されていないので、親テンプレートの値がそのまま使われます。親テンプレートの ``{% block %}`` タグの内容は、常にフォールバックの値として使われます。テンプレートの継承は必要に応じて何段階にもできます。継承を使うよくある場合の一つに、以下のような三段階のアプローチがあります: * サイトの主なルック & フィールを決める ``base.html`` テンプレートを作成します。 * サイトの各「セクション」ごとに ``base_SECTIONNAME.html`` テンプレートを作成します。たとえば、 ``base_news.html`` , ``base_sports.html`` といった具合です。これらのテンプレートでは ``base.html`` を拡張して、セクション固有のスタイルやデザインを取り込んでおきます。 * ニュース記事やブログエントリといった各種ページ用の個々のテンプレートを作成します。これらのテンプレートでは適切なセクションテンプレートを拡張します。このようなアプローチを取れば、コードの最利用性を最大限に高め、セクション毎のナビゲーションのような項目を簡単に共通のコンテンツ領域に追加できます。継承を扱うときの小技をいくつか挙げておきます: * テンプレートで :ttag:`{% extends %}` を使う場合は、テンプレート中の最初のテンプレートタグにせねばなりません。さもなければテンプレート継承はうまく動作しません。 * ベースのテンプレートで :ttag:`{% block %}` を多用すればするほど、よりよいテンプレートになります。子テンプレートは親テンプレートのブロックを必ずしも全て定義しなくてもよいことを思い出して下さい。ブロックをたくさん用意しておき、適切なデフォルト値を入れておいて、子テンプレートで必要な値だけを再定義すればよいのです。フックは少ないよりも沢山ある方がよいのです。 * 同じような内容を含むテンプレートをいくつも作っていることに気づいたら、それはすなわちその内容を親テンプレートの ``{% block %}`` に入れるべきだということです。 * 親テンプレートのブロックに入っているコンテンツを取り出す必要がある場合、 ``{{ block.super }}`` とするとうまくいきます。親テンプレートのブロックをオーバライドするのではなく、内容を追加したい場合に便利です。 ``{{ block.super }}`` で挿入されたデータは、通常、親テンプレートで既にエスケープされているので、自動的にエスケープされません (:ref:`automatic-html-escaping` を参照)。 * 可読性を高めるために、例えば以下のように、 ``{% endblock %}`` にブロックの *名前* を指定できます:: {% block content %} ... {% endblock content %} 大きなテンプレートの編集で、どこで ``{% block %}`` タグが閉じているか探すのに便利です。最後に、同じテンプレート中に同じ名前の :ttag:`block` を複数定義できないことに注意して下さい。この制限は、ブロックタグが「双方向」に作用するため、すなわち、あるブロックタグは何らかの値を埋めるための穴であるだけでなく、穴を埋める *親テンプレートの* コンテンツも定義しているために存在しています。同じ名前の :ttag:`block` が一つのテンプレート内に複数あると、そのテンプレートの親テンプレートは、該当するブロックの内容を子テンプレートのどの :ttag:`block` 設定で置き換えればよいのか分からなくなってしまいます。 .. _next section: #automatic-html-escaping .. _automatic-html-escaping: HTML の自動エスケープ ======================= テンプレートから HTML を生成するときには、変数内の文字が HTML のレンダリング結果を壊してしまうというリスクが常に付きまといます。例えば、以下のようなテンプレートフラグメントを考えてみましょう:: こんにちは {{ name }} さん一件、このコードはユーザ名を表示するだけの無害なものに見えますが、名前を以下のような値にすると、何が起こるでしょう:: テンプレートは以下のようにレンダされます:: Hello, その結果、 JavaScript の警告ボックスを表示できてしまいます！同様に、名前に以下のようにして ``'<'`` 文字をいれると同でしょう:: ..code-block::html username レンダ結果は以下のようになります:: Hello, username これで、以降のWebページは全部ボールド表示になってしまいます！言うまでもなく、ユーザが入力したデータは盲目に信頼してはならず、直接 Web ページに挿入すべきでもありません。悪意のあるユーザはこの手の穴を使って悪さをするものです。こうしたセキュリティホールは、 `クロスサイトスクリプティング`_ (XSS) 攻撃と呼ばれています。クロスサイトスクリプティングを防ぐには、二つの方法があります: * まず、信頼できない変数は全て (後述の) ``escape`` フィルタを通します。このフィルタは危険を及ぼす可能性のある HTML 文字を無害な文字に変換します。 Django では、初期の数年はこの方法をデフォルトとして採用していましたが、ユーザ、すなわち開発者やテンプレートの作者に、全てをエスケープするよう気配りする負荷をかけるという問題がありました。 * もう一つは、自動 HTML エスケープを使うというものです。この節の後半では、自動エスケープのからくりについて述べています。開発版の Django では、デフォルトの設定として、全てのテンプレートは変数タグを自動的にエスケープします。具体的には、以下の 5 つの文字がエスケープされます: * ``<`` は ``"<"`` に変換されます。 * ``>`` は ``">"`` に変換されます。 * ``"'"`` (クオート) は ``'''`` に変換されます。 * ``'"'`` (二重クオート) は ``'"'`` に変換されます。 * ``"&"`` は ``"&"`` に変換されます。この動作はデフォルトで適用されていることを強調しておきます。Django テンプレートシステムを使っているかぎり、エスケープに関する問題からは守られているのです。 .. _Cross Site Scripting: http://en.wikipedia.org/wiki/Cross-site_scripting .. _`クロスサイトスクリプティング`: http://ja.wikipedia.org/wiki/クロスサイトスクリプティング自動エスケープを切るには --------------------------- サイト単位やテンプレート単位、変数単位でデータの自動エスケープを切るには、いくつかの方法があります。どんなときに、自動エスケープを切る必要があるのでしょうか。テンプレート変数の中には、生の HTML としてレンダするように *意図された* データがあります。そうした場合にはコンテンツがエスケープされてほしくはないでしょう。例えば、データベースに HTML を保存していて、テンプレートに直接埋め込みたい場合を考えてみましょう。また、 Django のテンプレートシステムを使って、 HTML *以外* のデータ、例えば電子メールメッセージなどを生成したい場合がそうです。変数単位の制御 ~~~~~~~~~~~~~~~~ 変数個々に自動エスケープを無効にするには、 :tfilter:`safe` フィルタを使います:: エスケープされる: {{ data }} エスケープされない: {{ data|safe }} *safe* という言葉を、 *これ以上エスケープしないよう保護(safe)する* とか、 *HTML として解釈しても安全(safe)である* という意味だと考えてください。例えば、 ``data`` に ``''`` が入っていた場合、出力は以下のようになります:: エスケープされる: <b> エスケープされない: テンプレートブロック単位の制御 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ テンプレートで自動エスケープを制御するには、テンプレート (またはテンプレートの一部) を、以下のように :ttag:`autoescape` タグで囲みます:: {% autoescape off %} こんにちは {{ name }} さん {% endautoescape %} :ttag:`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 %}
{% block title %}{% endblock %}
{% block content %} {% endblock %} {% endautoescape %} # child.html {% extends "base.html" %} {% block title %}This & that{% endblock %} {% block content %}{{ greeting }}{% endblock %} 自動エスケープがベースのテンプレートで無効化されているので、子テンプレートでも自動エスケープは無効化されます。結果として、 ``greeting`` 変数の値が ``Hello!`` の時には以下の HTML がレンダされます::
This & that
Hello! 注意点 ------- 一般に、テンプレートの作者は自動エスケープをあまり意識するべきではありません。 Python サイドの開発者 (ビューやカスタムフィルタ) の作者が、どのデータをエスケープすべきでないかを考え、データを適切にマークして、テンプレートにうまく表示されるようにすべきなのです。テンプレートを作成していて、自動エスケープが有効な環境で使われるかどうか分からないような場合には、エスケープの必要な変数全てに ``escape`` フィルタを追加してください。自動エスケープがオンの場合、 :tfilter:`escape` フィルタがデータを *二重にエスケープする* ような危険性はありません。 :tfilter:`escape` フィルタは変数の自動エスケープには影響しないのです。 .. _string-literals-and-automatic-escaping: 文字列リテラルと自動エスケープ ------------------------------- 先に説明したように、フィルタの引数は文字列であってもかまいません:: {{ data|default:"文字列リテラルだよ" }} 文字列リテラルは、自動エスケープ **されずに** テンプレート内に挿入されます。文字列リテラルは、 :tfilter:`safe` フィルタを通して渡されたかのように振る舞います。このような仕様になっているのは、テンプレートの作者が文字列リテラルがどのように処理されるかを制御でき、テンプレートを書くときにテキストが正しくエスケープされるよう配慮できるからです。従って、以下のようにテンプレートを書いてください:: {{ data|default:"3 < 2" }} 以下のようにはしないでください:: {{ data|default:"3 < 2" }} <-- ダメ。こんな書き方をしてはいけません引数にリテラルを使っても、変数自体に対するエスケープの挙動には影響しません。変数はテンプレート作者の制御の範囲外にあり、自動的にエスケープされます。 .. _template-accessing-methods: メソッドの呼び出しにアクセスする ================================ オブジェクトに備え付けられたほとんどのメソッドの呼び出しはテンプレートの中からでも使うことができます。これは、テンプレートがただのクラスの属性（フィールド名のように）とビューでの変数を通したアクセス以上のものであるということです。例えば、Djangoでの例ではORMは :ref:`"entry_set"` 文法を提供していて、Foreign キーに関係するオブジェクトの集合を見つけることができます。従って、 "comment"と呼ばれるモデルが"task"というモデルとフォーリンキーで繋がっているとき、ループを用いることで"task"を通して全ての"comment"オブジェクトにアクセスすることができます。ちょうど、こんな風に。:: {% for comment in task.comment_set.all %} {{ comment }} {% endfor %} 似たように、 :doc:`QuerySets` は ``count()`` メソッドというオブジェクトの個数を数えるために提供しています。従って、タスクと関連する全てのコメントの個数を取得することも出来ます。:: {{ task.comment_set.all.count }} そして、もちろん簡単にモデル自身で定義されたメソッドにもアクセスすることができます:: # モデル内で class Task(models.Model): def foo(self): return "bar" # テンプレート内で {{ task.foo }} なぜなら、Django ではテンプレートのプログラム的な使用を厳しく制限していて、テンプレートの中からメソッドを呼び出すことは出来ないからです。データはビューの中で作られ、テンプレートでは表示のためだけに使うべきだからです。 .. _loading-custom-template-libraries: カスタムタグとカスタムフィルタのライブラリ ========================================== アプリケーションによっては、カスタムのタグやフィルタライブラリを提供しています。こうしたタグをテンプレートで使いたい場合、 :ttag:`load` タグを使います:: {% load comments %} {% comment_form for blogs.entries entry.id with is_public yes %} 上の例では、 :ttag:`load` タグは ``comments`` という名前のタグライブラリを読み込んでいます。このタグライブラリを読み込むと、 ``comment_form`` タグを使えるようになります。カスタムライブラリのリストを探したければ、自分のサイトの admin でドキュメント置場を参照してください。 :ttag:`load` タグは複数のライブラリ名を同時に読み込めます。ライブラリ名はスペースで区切って下さい:: {% load comments i18n %} カスタムのテンプレートライブラリを作成する方法は :doc:`/howto/custom-template-tags` を参照してください。カスタムのライブラリとテンプレートの継承 ---------------------------------------- カスタムタグやフィルタライブラリをロードした場合、タグやフィルタは現在のテンプレートだけで利用でき、テンプレート継承パス上の親テンプレートや子テンプレートでは利用できません。例えば、 ``foo.html`` に ``{% load comments %}`` というタグを入れておいても、子テンプレート (``{% extends "foo.html" %}`` を使っているテンプレート) で comments という名前のテンプレートタグやフィルタを使えるわけでは *ありません* 。子テンプレート側で独自に ``{% load comments %}`` を入れておく必要があります。これはメンテナンス性を高めるための仕様です。

{{ section.title }}

{{ story.headline|upper }}

{{ entry.title }}

Entry one

Entry two

{% block title %}{% endblock %}

This & that