テンプレート¶

テンプレートは単なるテキストファイルでできています。 テンプレートはあらゆる テキストベースのデータ形式 (HTML, XML, CSV など) を生成できます。

テンプレートには、テンプレートを処理する際に実際の値に置き換えられる 変数 (variable) と、テンプレート上でロジックを制御する タグ (tag) が入っています。

以下に示すのは、基本的な項目をいくつか組み込んだ最小限のテンプレートです。 各項目についてはこのドキュメントの後の部分で詳しく説明します:

{% extends "base_generic.html" %}

{% block title %}{{ section.title }}{% endblock %}

{% block content %}
<h1>{{ section.title }}</h1>

{% for story in story_list %}
<h2>
  <a href="{{ story.get_absolute_url }}">
    {{ story.headline|upper }}
  </a>
</h2>
<p>{{ story.tease|truncatewords:"100" }}</p>
{% endfor %}
{% endblock %}

変数¶

変数 (variable) は {{ variable }} のような形式になります。テンプレート エンジンが変数名を見つけると、変数を評価して値を置き換えたものを出力します。

変数の属性値にアクセスするには、ドット (.) 表記を使います。

上の例では、 {{ section.title }} は section オブジェクトの title 属性に置き換えられます。

実在しない変数を使うと、テンプレートシステムは TEMPLATE_STRING_INVALID の設定値を挿入します。デフォルトの値は '' (空文字列) です。

後述の「 組み込みのリファレンスドキュメント 」を読めば、テンプレートで使 える変数名を調べる手がかりになります。

フィルタ¶

変数を表示するために手を加えたい場合には フィルタ (filter) を使います。

フィルタは {{ name|lower }} のように書きます。この例では、変数 {{ name }} の値は lower フィルタ、すなわち文字を小文字に変換するフィルタ を通してから表示します。フィルタの適用は (|) で表します。

フィルタは「連鎖 (chain)」できます。フィルタを連鎖させると、あるフィルタか らの出力を別のフィルタに渡せます。例えば、 {{ text|escape|linebreaks }} は、テキストの内容をエスケープして、改行を <p> タグに置き換える時の慣用 句としてよく使われています。

フィルタによっては引数をとります。フィルタの引数は {{ bio|truncatewords:"30" }} のような形式で表します。この例では、変数 bio の最初の 30 語を表示します。

フィルタの引数にスペースが入っている場合は、二重引用符で囲ってください。例 えば、カンマとスペースでリストを結合するには {{ list|join:", " }} のようにします。

組み込みフィルタリファレンス では、 全ての組み込みフィルタについて説明しています。

組み込みフィルタでできることを知ってもらうために、よく使うテンプレートフィ ルタをいくつか挙げましょう:

default

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

使用例:

{{ value|default:"nothing" }}

value が存在しなかったり空だったりすると、 "nothing" を出力 します。

length

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

使用例:

{{ value|length }}

value が ['a', 'b', 'c', 'd'] なら、 4 を出力します。

striptags

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

使用例:

{{ value|striptags }}

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

これらはほんの一部に過ぎません。全ての組み込みフィルタの一覧は 組み込みフィルタリファレンス を参照 してください。

テンプレートフィルタは自作できます。 テンプレートタグやフィルタを自作する を参照してください。

タグ¶

タグは {% tag %} のように書きます。タグの考え方は、変数よりもやや複雑 です。出力されるテキストを生成するものもありますし、ループやロジックを実行 して、処理の流れを制御するものもあります。また、外部の情報を取り込んで、後 に出て来る変数から使えるようにするものもあります。

タグによっては、開始タグと終了タグ ({% tag %} ... tag contents ... {% endtag %}) を必要とするものがありま す。

Django にはたくさんの組み込みタグが付属しています。組み込みタグの解説は 組み込みタグリファレンス にあります。 組み込みタグでできることを知ってもらうために、よく使うタグをいくつか挙げま しょう:

for

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

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

if and else

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

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

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

ifequal and ifnotequal

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

{% ifequal athlete.name coach.name %}
    ...
{% endifequal %}

あるいは、以下のように書きます:

{% ifnotequal athlete.name "Joe" %}
    ...
{% endifequal %}

block and extends

テンプレートで「定型文 ("boilerplate")」を切り出す強力な方法である、 テンプレートの継承 を組みます。

これらはほんの一部に過ぎません。全ての組み込みフィルタの一覧は 組み込みタグリファレンス を参照してく ださい。

テンプレートタグは自作できます。 テンプレートタグやフィルタを自作する を参照してください。

コメント¶

テンプレート中で行内の一部をコメントアウトするには、コメント構文 {# #} を使います。

例えば、以下のテンプレートをレンダすると 'hello' になります:

{# greeting #}hello

コメント内には任意のテンプレートコードを入れられます。コメント内の テンプレートコードが無効なものであってもエラーにはなりません:

{# {% if foo %}bar{% else %} #}

この構文を使えるのは、一行のコメントの場合だけです ({# と #} の間に は改行を入れられません)。複数行のコメントアウトを行いたければ、後述の comment タグを使ってください。

テンプレートの継承¶

Django のテンプレートエンジンにおいて、テンプレートの継承 (inheritance) は 最もパワフル -- かつ最も難解 -- な部分です。テンプレートの継承は、自分のサ イトで共通に使われる全ての要素の入った、ベースとなる「骨組みの」テンプレー トを作っておき、その中に子のテンプレートでオーバライドできる ブロック(block) を定義できます。

テンプレートの継承を理解するには、まず例を挙げるのが一番でしょう:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
    <link rel="stylesheet" href="style.css" />
    <title>{% block title %}My amazing site{% endblock %}</title>
</head>

<body>
    <div id="sidebar">
        {% block sidebar %}
        <ul>
            <li><a href="/">Home</a></li>
            <li><a href="/blog/">Blog</a></li>
        </ul>
        {% endblock %}
    </div>

    <div id="content">
        {% block content %}{% endblock %}
    </div>
</body>
</html>

このテンプレートは、単純な 2 カラム形式のページで使うような HTML のスケルト ンドキュメントです。これを base.html と呼びましょう。空のブロックをコン テンツで埋めるのは「子 (child)」のテンプレートの仕事です。

この例では、 {% block %} タグを使って 3 つのブロックを定義し、子テンプ レートが値を埋められるようにしています。 block タグの役割は、テンプレー ト中のタグで囲まれた部分を子テンプレートでオーバライドできることをテンプレー トエンジンに知らせることにあります。

子テンプレートは以下のようになります:

{% extends "base.html" %}

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

{% block content %}
{% for entry in blog_entries %}
    <h2>{{ entry.title }}</h2>
    <p>{{ entry.body }}</p>
{% endfor %}
{% endblock %}

{% extends %} タグが継承のカギです。このタグはテンプレートエンジンに対 して、自分自身が他のテンプレートを拡張 (extend) していることを教えます。テ ンプレートシステムがこのテンプレートを処理する際、システムはまず親となるテ ンプレート -- ここでは "base.html" を探します。

さて、この時点で、テンプレートエンジンは base.html 内に三箇所の {% block %} が定義されていることに気づき、これらのブロックを子テンプレー トの該当するブロックで置き換えます。 blog_entries の値に応じて、出力は 以下のようになります:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
    <link rel="stylesheet" href="style.css" />
    <title>My amazing blog</title>
</head>

<body>
    <div id="sidebar">
        <ul>
            <li><a href="/">Home</a></li>
            <li><a href="/blog/">Blog</a></li>
        </ul>
    </div>

    <div id="content">
        <h2>Entry one</h2>
        <p>This is my first entry.</p>

        <h2>Entry two</h2>
        <p>This is my second entry.</p>
    </div>
</body>
</html>

子テンプレートには sidebar ブロックが定義されていないので、親テンプレー トの値がそのまま使われます。親テンプレートの {% block %} タグの内容は、 常にフォールバックの値として使われます。

テンプレートの継承は必要に応じて何段階にもできます。継承を使うよくある場合 の一つに、以下のような三段階のアプローチがあります:

• サイトの主なルック & フィールを決める base.html テンプレートを作 成します。
• サイトの各「セクション」ごとに base_SECTIONNAME.html テンプレート を作成します。たとえば、 base_news.html , base_sports.html と いった具合です。これらのテンプレートでは base.html を拡張して、セ クション固有のスタイルやデザインを取り込んでおきます。
• ニュース記事やブログエントリといった各種ページ用の個々のテンプレート を作成します。これらのテンプレートでは適切なセクションテンプレートを 拡張します。

このようなアプローチを取れば、コードの最利用性を最大限に高め、セクション毎 のナビゲーションのような項目を簡単に共通のコンテンツ領域に追加できます。

継承を扱うときの小技をいくつか挙げておきます:

• テンプレートで {% extends %} を使う場合は、テンプレート中の最初の テンプレートタグにせねばなりません。さもなければテンプレート継承はう まく動作しません。

• ベースのテンプレートで {% block %} を多用すればするほど、よりよい テンプレートになります。子テンプレートは親テンプレートのブロックを必 ずしも全て定義しなくてもよいことを思い出して下さい。ブロックをたくさ ん用意しておき、適切なデフォルト値を入れておいて、子テンプレートで必 要な値だけを再定義すればよいのです。フックは少ないよりも沢山ある方が よいのです。

• 同じような内容を含むテンプレートをいくつも作っていることに気づいたら、 それはすなわちその内容を親テンプレートの {% block %} に入れるべき だということです。

• 親テンプレートのブロックに入っているコンテンツを取り出す必要がある場 合、 {{ block.super }} とするとうまくいきます。親テンプレートのブ ロックをオーバライドするのではなく、内容を追加したい場合に便利です。 {{ block.super }} で挿入されたデータは、通常、親テンプレートで 既にエスケープされているので、自動的にエスケープされません (HTML の自動エスケープ を参照)。

• 可読性を高めるために、例えば以下のように、 {% endblock %} にブロッ クの 名前 を指定できます:

  {% block content %}
  ...
  {% endblock content %}

  大きなテンプレートの編集で、どこで {% block %} タグが閉じているか 探すのに便利です。

最後に、同じテンプレート中に同じ名前の {% block %} を複数定義できないこ とに注意して下さい。この制限は、ブロックタグが「双方向」に作用するため、す なわち、あるブロックタグは何らかの値を埋めるための穴であるだけでなく、穴を 埋める 親テンプレートの コンテンツも定義しているために存在しています。同 じ名前の {% block %} が一つのテンプレート内に複数あると、そのテンプレー トの親テンプレートは、該当するブロックの内容を子テンプレートのどの {% block %} 設定で置き換えればよいのか分からなくなってしまいます。

HTML の自動エスケープ¶

テンプレートから HTML を生成するときには、変数内の文字が HTML のレンダリン グ結果を壊してしまうというリスクが常に付きまといます。例えば、以下のような テンプレートフラグメントを考えてみましょう:

こんにちは {{ name }} さん

一件、このコードはユーザ名を表示するだけの無害なものに見えますが、名前を以 下のような値にすると、何が起こるでしょう:

<script>alert('hello')</script>

テンプレートは以下のようにレンダされます:

Hello, <script>alert('hello')</script>

その結果、 JavaScript の警告ボックスを表示できてしまいます！

同様に、名前に以下のようにして '<' 文字をいれると同でしょう:

<b>username

レンダ結果は以下のようになります:

Hello, <b>username

これで、以降のWebページは全部ボールド表示になってしまいます！

言うまでもなく、ユーザが入力したデータは盲目に信頼してはならず、直接 Web ペー ジに挿入すべきでもありません。悪意のあるユーザはこの手の穴を使って悪さをす るものです。こうしたセキュリティホールは、 クロスサイトスクリプティング (XSS) 攻撃と呼ばれています。

クロスサイトスクリプティングを防ぐには、二つの方法があります:

• まず、信頼できない変数は全て (後述の) escape フィルタを通します。 このフィルタは危険を及ぼす可能性のある HTML 文字を無害な文字に変換し ます。 Django では、初期の数年はこの方法をデフォルトとして採用してい ましたが、ユーザ、すなわち開発者やテンプレートの作者に、全てをエスケー プするよう気配りする負荷をかけるという問題がありました。
• もう一つは、自動 HTML エスケープを使うというものです。この節の後半で は、自動エスケープのからくりについて述べています。

開発版の Django では、デフォルトの設定として、全てのテンプレートは変数タグ を自動的にエスケープします。具体的には、以下の 5 つの文字がエスケープされます:

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

この動作はデフォルトで適用されていることを強調しておきます。Django テンプレー トシステムを使っているかぎり、エスケープに関する問題からは守られているのです。

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

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

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

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 %}

# base.html

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


# child.html

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

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

{{ data|default:"文字列リテラルだよ" }}

{{ data|default:"3 < 2" }}

{{ data|default:"3 < 2" }}  <-- ダメ。こんな書き方をしてはいけません

組み込みのリファレンスドキュメント¶

Django の admin インタフェースには、サイトで使える全てのテンプレート関連要 素のリファレンスがあります。このドキュメントを読みたければ、 admin インタ フェースにアクセスして、ページの右上部分にある「ドキュメント (Documentation)」というリンクをクリックして下さい。

リファレンスは、タグ(Tags)、フィルタ(Filters)、モデル(Models)、そしてビュー (Views)の 4 つのセクションに分かれています。

Tags や Filters セクションでは、全ての組み込みタグについて解説して います。 (実際、後で示すタグやフィルタのリファレンスは全てこれらのセクショ ンから直接取り出したものです) また、利用可能なカスタムのタグやフィルタライ ブラリについてのリファレンスもあります。

最も大事なのは Views ページです。サイトの各 URL には個別のエントリが 表示され、 URL をクリックすると以下のような内容を表示します:

• ビューを生成する view 関数の名前。
• ビューの役割を示す短い説明。
• コンテキスト 、ビューのテンプレートで使える変数のリスト。
• ビューで使われているテンプレートの名前。

各ビューのドキュメントにはブックマークレット(bookmarklet)があり、別のページ からこのビューのドキュメントにジャンプするために使えます。

Django で作成したサイトは通常、データベースオブジェクト中心に動いているので、 Models のセクションはシステム中の各タイプのオブジェクトと、そのオブジェ クトで利用できる全てのフィールドについて説明しています。

ドキュメントのページを読めば、全てのタグ、フィルタ、テンプレートで利用でき る変数やオブジェクトが分かります。

カスタムタグとカスタムフィルタのライブラリ¶

アプリケーションによっては、カスタムのタグやフィルタライブラリを提供してい ます。こうしたタグをテンプレートで使いたい場合、 {% load %} タグを使い ます:

{% load comments %}

{% comment_form for blogs.entries entry.id with is_public yes %}

上の例では、 load タグは comments という名前のタグライブラリを読み 込んでいます。このタグライブラリを読み込むと、 comment_form タグを使え るようになります。カスタムライブラリのリストを探したければ、自分のサイトの admin でドキュメント置場を参照してください。

{% load %} タグは複数のライブラリ名を同時に読み込めます。ライブラリ名は スペースで区切って下さい:

{% load comments i18n %}

カスタムのテンプレートライブラリを作成する方法は テンプレートタグやフィルタを自作する を参照してください。