
<!DOCTYPE html>

<html lang="ja">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Django テンプレート言語 &#8212; Django 5.0.9.dev20240806133106 ドキュメント</title>
    <link rel="stylesheet" type="text/css" href="../../_static/pygments.css" />
    <link rel="stylesheet" type="text/css" href="../../_static/default.css" />
    <script data-url_root="../../" id="documentation_options" src="../../_static/documentation_options.js"></script>
    <script src="../../_static/jquery.js"></script>
    <script src="../../_static/underscore.js"></script>
    <script src="../../_static/doctools.js"></script>
    <script src="../../_static/translations.js"></script>
    <link rel="index" title="索引" href="../../genindex.html" />
    <link rel="search" title="検索" href="../../search.html" />
    <link rel="next" title="組み込みテンプレートタグとフィルタ" href="builtins.html" />
    <link rel="prev" title="テンプレート" href="index.html" />



 
<script src="../../templatebuiltins.js"></script>
<script>
(function($) {
    if (!django_template_builtins) {
       // templatebuiltins.js missing, do nothing.
       return;
    }
    $(document).ready(function() {
        // Hyperlink Django template tags and filters
        var base = "builtins.html";
        if (base == "#") {
            // Special case for builtins.html itself
            base = "";
        }
        // Tags are keywords, class '.k'
        $("div.highlight\\-html\\+django span.k").each(function(i, elem) {
             var tagname = $(elem).text();
             if ($.inArray(tagname, django_template_builtins.ttags) != -1) {
                 var fragment = tagname.replace(/_/, '-');
                 $(elem).html("<a href='" + base + "#" + fragment + "'>" + tagname + "</a>");
             }
        });
        // Filters are functions, class '.nf'
        $("div.highlight\\-html\\+django span.nf").each(function(i, elem) {
             var filtername = $(elem).text();
             if ($.inArray(filtername, django_template_builtins.tfilters) != -1) {
                 var fragment = filtername.replace(/_/, '-');
                 $(elem).html("<a href='" + base + "#" + fragment + "'>" + filtername + "</a>");
             }
        });
    });
})(jQuery);</script>

  </head><body>

    <div class="document">
  <div id="custom-doc" class="yui-t6">
    <div id="hd">
      <h1><a href="../../index.html">Django 5.0.9.dev20240806133106 ドキュメント</a></h1>
      <div id="global-nav">
        <a title="Home page" href="../../index.html">Home</a>  |
        <a title="Table of contents" href="../../contents.html">Table of contents</a>  |
        <a title="Global index" href="../../genindex.html">Index</a>  |
        <a title="Module index" href="../../py-modindex.html">Modules</a>
      </div>
      <div class="nav">
    &laquo; <a href="index.html" title="テンプレート">previous</a>
     |
    <a href="../index.html" title="API リファレンス" accesskey="U">up</a>
   |
    <a href="builtins.html" title="組み込みテンプレートタグとフィルタ">next</a> &raquo;</div>
    </div>

    <div id="bd">
      <div id="yui-main">
        <div class="yui-b">
          <div class="yui-g" id="ref-templates-language">
            
  <div class="section" id="s-the-django-template-language">
<span id="the-django-template-language"></span><h1>Django テンプレート言語<a class="headerlink" href="#the-django-template-language" title="このヘッドラインへのパーマリンク">¶</a></h1>
<p>このドキュメントはDjangoテンプレートシステムの文法を説明しています。もしあなたがもっと技術者的な観点でどう動かすかやどう拡張するかを知りたい場合は、<a class="reference internal" href="api.html"><span class="doc">Python プログラマーのための Django テンプレート言語</span></a> を参照してください。</p>
<p>Django のテンプレート言語は、強力さと使いやすさのバランスを取るように設計されています。HTML の扱いに慣れている人なら、違和感なく使えるように設計されています。 <a class="reference external" href="https://www.smarty.net/">Smarty</a> や  <a class="reference external" href="https://palletsprojects.com/p/jinja/">Jinja2</a> のようなテキストベースのテンプレート言語に触れたことがあれば、 Django のテンプレートに馴染めるはずです。</p>
<div class="admonition-philosophy admonition">
<p class="first admonition-title">設計思想</p>
<p>もしあなたがプログラミングのバックグラウンドを持っていたり、 HTML に直接プログラミングコードを埋め込む言語に慣れているなら、 Django のテンプレートシステムは単に Python を HTML に埋め込んだものではないことを心に留めておいてください。これは、テンプレートシステムはプレゼンテーション（体裁）を表現するためのものであり、プログラムロジックを表現するためのものではないという設計思想から来ています。</p>
<p class="last">Django テンプレートシステムは、いくつかのプログラミング構文に似た機能を持つタグを提供します。真偽値テスト用の <a class="reference internal" href="builtins.html#std-templatetag-if"><code class="xref std std-ttag docutils literal notranslate"><span class="pre">if</span></code></a> タグ、ループ処理用の <a class="reference internal" href="builtins.html#std-templatetag-for"><code class="xref std std-ttag docutils literal notranslate"><span class="pre">for</span></code></a> タグなどです。しかし、これらは単純に対応する Python コードとして実行されるわけではなく、テンプレートシステムは任意の Python 式を実行することはありません。デフォルトでは以下のタグ、フィルタ、構文だけがサポートされています（ただし、必要に応じて <a class="reference internal" href="../../howto/custom-template-tags.html"><span class="doc">独自の拡張機能</span></a> をテンプレート言語に追加することもできます）。</p>
</div>
<div class="section" id="s-templates">
<span id="templates"></span><h2>テンプレート<a class="headerlink" href="#templates" title="このヘッドラインへのパーマリンク">¶</a></h2>
<p>テンプレートは、テキストファイルです。これは、任意のテキストベースのフォーマット (HTML、XML、CSV) などを生成できます。</p>
<p>テンプレートに含まれるのは、テンプレートが読み込まれたとき実際の値で置き換えられる <strong>変数</strong> と、テンプレートのロジックを制御する <strong>タグ</strong> です。</p>
<p>以下は、いくつかの基本を示した最小限のテンプレートです。各要素については、この文書の後半で説明します。</p>
<div class="highlight-html+django notranslate"><div class="highlight"><pre><span></span><span class="cp">{%</span> <span class="k">extends</span> <span class="s2">&quot;base_generic.html&quot;</span> <span class="cp">%}</span>

<span class="cp">{%</span> <span class="k">block</span> <span class="nv">title</span> <span class="cp">%}{{</span> <span class="nv">section.title</span> <span class="cp">}}{%</span> <span class="k">endblock</span> <span class="cp">%}</span>

<span class="cp">{%</span> <span class="k">block</span> <span class="nv">content</span> <span class="cp">%}</span>
<span class="p">&lt;</span><span class="nt">h1</span><span class="p">&gt;</span><span class="cp">{{</span> <span class="nv">section.title</span> <span class="cp">}}</span><span class="p">&lt;/</span><span class="nt">h1</span><span class="p">&gt;</span>

<span class="cp">{%</span> <span class="k">for</span> <span class="nv">story</span> <span class="k">in</span> <span class="nv">story_list</span> <span class="cp">%}</span>
<span class="p">&lt;</span><span class="nt">h2</span><span class="p">&gt;</span>
  <span class="p">&lt;</span><span class="nt">a</span> <span class="na">href</span><span class="o">=</span><span class="s">&quot;</span><span class="cp">{{</span> <span class="nv">story.get_absolute_url</span> <span class="cp">}}</span><span class="s">&quot;</span><span class="p">&gt;</span>
    <span class="cp">{{</span> <span class="nv">story.headline</span><span class="o">|</span><span class="nf">upper</span> <span class="cp">}}</span>
  <span class="p">&lt;/</span><span class="nt">a</span><span class="p">&gt;</span>
<span class="p">&lt;/</span><span class="nt">h2</span><span class="p">&gt;</span>
<span class="p">&lt;</span><span class="nt">p</span><span class="p">&gt;</span><span class="cp">{{</span> <span class="nv">story.tease</span><span class="o">|</span><span class="nf">truncatewords</span><span class="s2">:&quot;100&quot;</span> <span class="cp">}}</span><span class="p">&lt;/</span><span class="nt">p</span><span class="p">&gt;</span>
<span class="cp">{%</span> <span class="k">endfor</span> <span class="cp">%}</span>
<span class="cp">{%</span> <span class="k">endblock</span> <span class="cp">%}</span>
</pre></div>
</div>
<div class="admonition-philosophy admonition">
<p class="first admonition-title">設計思想</p>
<p class="last">なぜ、(ZopeのTALのような) XMLベースのテンプレートではなく、テキストベースのテンプレートを使うのか？それは、Django のテンプレート言語を XML/ HTML テンプレートより使いやすくしたかったからです。テンプレート言語は、どんなEメール、JavaScript、CSVのようなテキストベースのフォーマットにも使用できます。</p>
</div>
</div>
<div class="section" id="s-variables">
<span id="s-template-variables"></span><span id="variables"></span><span id="template-variables"></span><h2>変数<a class="headerlink" href="#variables" title="このヘッドラインへのパーマリンク">¶</a></h2>
<p>変数は次のような見た目です: <code class="docutils literal notranslate"><span class="pre">{{</span> <span class="pre">variable</span> <span class="pre">}}</span></code>。テンプレートエンジンが変数を検出すると、その変数を認識し、その結果に置き換えます。変数名は、英数字の任意の組み合わせとアンダースコア (<code class="docutils literal notranslate"><span class="pre">&quot;_&quot;</span></code>) で構成されています（ただし、先頭を2重のアンダースコアもしくは数字にすることはできません）。ドット (<code class="docutils literal notranslate"><span class="pre">&quot;.&quot;</span></code>) も変数セクションに表示されますが、以下に示すように特別な意味を持っています。重要なのは、<em>変数名にスペースまたは句読点を持つことはできない</em> ということです。</p>
<p>変数の属性にアクセスするには、ドットを ('<code class="docutils literal notranslate"><span class="pre">.</span></code>') を使用します。</p>
<div class="admonition-behind-the-scenes admonition">
<p class="first admonition-title">背景</p>
<p>技術的には、テンプレートシステムがドットを検出した際、以下の参照項目をこの順番で実行しようとします:</p>
<ul class="simple">
<li>辞書検索</li>
<li>属性やメソッドの検索</li>
<li>数値のインデックス検索</li>
</ul>
<p>結果の値が呼び出し可能である場合は、引数なしで呼び出されます。呼び出しの結果は、テンプレートの値となります。</p>
<p>この検索の手順は、辞書検索を上書きするオブジェクトにおいて、予期しない動作を引き起こす可能性があります。たとえば、<code class="docutils literal notranslate"><span class="pre">collections.defaultdict</span></code> すべてをループ処理をしようとする、次のコードスニペットを考えてみましょう。</p>
<div class="highlight-html+django notranslate"><div class="highlight"><pre><span></span><span class="cp">{%</span> <span class="k">for</span> <span class="nv">k</span><span class="o">,</span> <span class="nv">v</span> <span class="k">in</span> <span class="nv">defaultdict.items</span> <span class="cp">%}</span>
    Do something with k and v here...
<span class="cp">{%</span> <span class="k">endfor</span> <span class="cp">%}</span>
</pre></div>
</div>
<p class="last">最初に辞書検索が行われるため、その挙動が動作してしまい、意図していた <code class="docutils literal notranslate"><span class="pre">.items()</span></code> メソッドを使用せずに、デフォルト値を提供してしまいます。この場合、最初に辞書を変換することを検討してください。</p>
</div>
<p>上記の例では、 <code class="docutils literal notranslate"><span class="pre">{{</span> <span class="pre">section.title</span> <span class="pre">}}</span></code> は <code class="docutils literal notranslate"><span class="pre">section</span></code> オブジェクトの <code class="docutils literal notranslate"><span class="pre">title</span></code> 属性と置き換えられます。</p>
<p>もし存在しない変数を使いたい場合、テンプレートシステムはデフォルトで <code class="docutils literal notranslate"><span class="pre">''</span></code> (the empty string)が置かれている場所に、 <code class="docutils literal notranslate"><span class="pre">string_if_invalid</span></code> のオプション値を挿入します。</p>
<p>テンプレートコンテキストに変数 &quot;bar &quot;が存在する場合、<code class="docutils literal notranslate"><span class="pre">{{</span> <span class="pre">foo.bar</span> <span class="pre">}}</span></code> のようなテンプレート式中の &quot;bar &quot;はリテラル文字列として解釈され、変数 &quot;bar&quot; の値は使用されないことに注意してください。</p>
<p>アンダースコアで始まる変数属性は、通常はプライベートとみなされるため、アクセスできません。</p>
</div>
<div class="section" id="s-filters">
<span id="filters"></span><h2>フィルタ<a class="headerlink" href="#filters" title="このヘッドラインへのパーマリンク">¶</a></h2>
<p><strong>フィルタ</strong> を使って、表示される変数に手を加えることができます。</p>
<p>フィルタは <code class="docutils literal notranslate"><span class="pre">{{</span> <span class="pre">name|lower</span> <span class="pre">}}</span></code> のような形式です。これは <code class="docutils literal notranslate"><span class="pre">{{</span> <span class="pre">name</span> <span class="pre">}}</span></code> 変数の値を、テキストを小文字に変換する <a class="reference internal" href="builtins.html#std-templatefilter-lower"><code class="xref std std-tfilter docutils literal notranslate"><span class="pre">lower</span></code></a> フィルタを通してから表示します。フィルタを適用するにはパイプ (<code class="docutils literal notranslate"><span class="pre">|</span></code>) を使用します。</p>
<p>フィルタは &quot;連結&quot; できます。あるフィルタの出力が次のフィルタに適用されます。<code class="docutils literal notranslate"><span class="pre">{{</span> <span class="pre">text|escape|linebreaks</span> <span class="pre">}}</span></code> はテキストの内容をエスケープし、改行を <code class="docutils literal notranslate"><span class="pre">&lt;p&gt;</span></code> タグに変換するためのよくあるイディオムです。</p>
<p>いくつかのフィルタは引数を取ります。フィルタの引数は <code class="docutils literal notranslate"><span class="pre">{{</span> <span class="pre">bio|truncatewords:30</span> <span class="pre">}}</span></code> のように指定します。これは <code class="docutils literal notranslate"><span class="pre">bio</span></code> 変数の最初の30単語を表示します。</p>
<p>スペースを含むフィルタの引数は引用符で囲む必要があります。たとえば、カンマとスペースを含むリストを結合するには <code class="docutils literal notranslate"><span class="pre">{{</span> <span class="pre">list|join:&quot;,</span> <span class="pre">&quot;</span> <span class="pre">}}</span></code> とします。</p>
<p>Django には約 60 個の組み込みテンプレートフィルタがあります。これらについては <a class="reference internal" href="builtins.html#ref-templates-builtins-filters"><span class="std std-ref">組み込みフィルタリファレンス</span></a> を参照してください。どのようなものがあるのかを知ってもらうために、よく使われるテンプレートフィルタをいくつか紹介します:</p>
<dl class="docutils">
<dt><a class="reference internal" href="builtins.html#std-templatefilter-default"><code class="xref std std-tfilter docutils literal notranslate"><span class="pre">default</span></code></a></dt><dd><p>変数が False または空の場合、指定されたデフォルト値を使用します。そうでなければ、その変数の値を使います。たとえば:</p>
<div class="highlight-html+django notranslate"><div class="highlight"><pre><span></span><span class="cp">{{</span> <span class="nv">value</span><span class="o">|</span><span class="nf">default</span><span class="s2">:&quot;nothing&quot;</span> <span class="cp">}}</span>
</pre></div>
</div>
<p>もし <code class="docutils literal notranslate"><span class="pre">value</span></code> が与えられなかったり、空だった場合、上記は &quot;<code class="docutils literal notranslate"><span class="pre">nothing</span></code>&quot; と表示されます。</p>
</dd>
<dt><a class="reference internal" href="builtins.html#std-templatefilter-length"><code class="xref std std-tfilter docutils literal notranslate"><span class="pre">length</span></code></a></dt><dd><p>値の長さを返します。これは文字列でもリストでも使えます。たとえば:</p>
<div class="highlight-html+django notranslate"><div class="highlight"><pre><span></span><span class="cp">{{</span> <span class="nv">value</span><span class="o">|</span><span class="nf">length</span> <span class="cp">}}</span>
</pre></div>
</div>
<p><code class="docutils literal notranslate"><span class="pre">value</span></code> が <code class="docutils literal notranslate"><span class="pre">['a',</span> <span class="pre">'b',</span> <span class="pre">'c',</span> <span class="pre">'d']</span></code> のとき、出力は <code class="docutils literal notranslate"><span class="pre">4</span></code> となります。</p>
</dd>
<dt><a class="reference internal" href="builtins.html#std-templatefilter-filesizeformat"><code class="xref std std-tfilter docutils literal notranslate"><span class="pre">filesizeformat</span></code></a></dt><dd><p>入力値を、&quot;人間が読みやすい&quot; ファイルサイズ表現 ('13 KB', '4.1 MB', '102 bytes' など) に変換します。たとえば:</p>
<div class="highlight-html+django notranslate"><div class="highlight"><pre><span></span><span class="cp">{{</span> <span class="nv">value</span><span class="o">|</span><span class="nf">filesizeformat</span> <span class="cp">}}</span>
</pre></div>
</div>
<p><code class="docutils literal notranslate"><span class="pre">value</span></code> が 123456789 のとき、出力は <code class="docutils literal notranslate"><span class="pre">117.7</span> <span class="pre">MB</span></code> になります。</p>
</dd>
</dl>
<p>繰り返しますが、これらはほんの一例に過ぎません。完全なリストは <a class="reference internal" href="builtins.html#ref-templates-builtins-filters"><span class="std std-ref">組み込みフィルタのリファレンス</span></a> を参照してください。</p>
<p>独自のカスタムテンプレートフィルタを作成することもできます。 <a class="reference internal" href="../../howto/custom-template-tags.html"><span class="doc">独自のテンプレートタグとフィルタを作る</span></a> を参照してください。</p>
<div class="admonition seealso">
<p class="first admonition-title">参考</p>
<p class="last">Django の管理インタフェースには、指定したサイトで利用可能な全てのテンプレートタグとフィルタの完全なリファレンスを含めることができます。 <a class="reference internal" href="../contrib/admin/admindocs.html"><span class="doc">Django admin ドキュメントジェネレータ</span></a> を参照してください。</p>
</div>
</div>
<div class="section" id="s-tags">
<span id="tags"></span><h2>タグ<a class="headerlink" href="#tags" title="このヘッドラインへのパーマリンク">¶</a></h2>
<p>タグは  <code class="docutils literal notranslate"><span class="pre">{%</span> <span class="pre">tag</span> <span class="pre">%}</span></code> のような形式です。タグは変数よりも複雑です。出力にテキストを生成したり、ループやロジックを実行することでフローを制御したり、後の変数で使用される追加情報をテンプレートにロードしたりします。</p>
<p>タグの中には開始タグと終了タグを必要とするものがあります(例 <code class="docutils literal notranslate"><span class="pre">{%</span> <span class="pre">tag</span> <span class="pre">%}</span> <span class="pre">...</span> <span class="pre">tag</span> <span class="pre">contents</span> <span class="pre">...</span> <span class="pre">{%</span> <span class="pre">endtag</span> <span class="pre">%}</span></code>)。</p>
<p>Django には約 20 個の組み込みテンプレートタグが同梱されています。これらについては <a class="reference internal" href="builtins.html#ref-templates-builtins-tags"><span class="std std-ref">組み込みタグのリファレンス</span></a> を参照してください。どのようなタグが利用できるかを知ってもらうために、よく使われるタグをいくつか紹介 します:</p>
<dl class="docutils">
<dt><a class="reference internal" href="builtins.html#std-templatetag-for"><code class="xref std std-ttag docutils literal notranslate"><span class="pre">for</span></code></a></dt><dd><p>配列の各要素に渡ってループします。たとえば、アスリート (athlete) のリストを  <code class="docutils literal notranslate"><span class="pre">athlete_list</span></code> で渡して表示するには、次のようにします。</p>
<div class="highlight-html+django notranslate"><div class="highlight"><pre><span></span><span class="p">&lt;</span><span class="nt">ul</span><span class="p">&gt;</span>
<span class="cp">{%</span> <span class="k">for</span> <span class="nv">athlete</span> <span class="k">in</span> <span class="nv">athlete_list</span> <span class="cp">%}</span>
    <span class="p">&lt;</span><span class="nt">li</span><span class="p">&gt;</span><span class="cp">{{</span> <span class="nv">athlete.name</span> <span class="cp">}}</span><span class="p">&lt;/</span><span class="nt">li</span><span class="p">&gt;</span>
<span class="cp">{%</span> <span class="k">endfor</span> <span class="cp">%}</span>
<span class="p">&lt;/</span><span class="nt">ul</span><span class="p">&gt;</span>
</pre></div>
</div>
</dd>
<dt><a class="reference internal" href="builtins.html#std-templatetag-if"><code class="xref std std-ttag docutils literal notranslate"><span class="pre">if</span></code></a>, <code class="docutils literal notranslate"><span class="pre">elif</span></code>, <code class="docutils literal notranslate"><span class="pre">else</span></code></dt><dd><p>変数を評価し、その変数が &quot;true &quot;の場合、ブロックの内容が表示されます:</p>
<div class="highlight-html+django notranslate"><div class="highlight"><pre><span></span><span class="cp">{%</span> <span class="k">if</span> <span class="nv">athlete_list</span> <span class="cp">%}</span>
    Number of athletes: <span class="cp">{{</span> <span class="nv">athlete_list</span><span class="o">|</span><span class="nf">length</span> <span class="cp">}}</span>
<span class="cp">{%</span> <span class="k">elif</span> <span class="nv">athlete_in_locker_room_list</span> <span class="cp">%}</span>
    Athletes should be out of the locker room soon!
<span class="cp">{%</span> <span class="k">else</span> <span class="cp">%}</span>
    No athletes.
<span class="cp">{%</span> <span class="k">endif</span> <span class="cp">%}</span>
</pre></div>
</div>
<p>上記の場合、 <code class="docutils literal notranslate"><span class="pre">athlete_list</span></code> が空でなければ、 <code class="docutils literal notranslate"><span class="pre">{{</span> <span class="pre">athlete_list|length</span> <span class="pre">}}</span></code> 変数によって選手の数が表示されます。もし <code class="docutils literal notranslate"><span class="pre">athlete_in_locker_room_list</span></code> が空でなければ、&quot;Athletes should be out... &quot; というメッセージが表示されます。両方のリストが空の場合、&quot;No athletes.&quot; と表示されます。</p>
<p><a class="reference internal" href="builtins.html#std-templatetag-if"><code class="xref std std-ttag docutils literal notranslate"><span class="pre">if</span></code></a> タグの中では、フィルタや様々な演算子を使うこともできます:</p>
<div class="highlight-html+django notranslate"><div class="highlight"><pre><span></span><span class="cp">{%</span> <span class="k">if</span> <span class="nv">athlete_list</span><span class="o">|</span><span class="nf">length</span> <span class="o">&gt;</span> <span class="m">1</span> <span class="cp">%}</span>
   Team: <span class="cp">{%</span> <span class="k">for</span> <span class="nv">athlete</span> <span class="k">in</span> <span class="nv">athlete_list</span> <span class="cp">%}</span> ... <span class="cp">{%</span> <span class="k">endfor</span> <span class="cp">%}</span>
<span class="cp">{%</span> <span class="k">else</span> <span class="cp">%}</span>
   Athlete: <span class="cp">{{</span> <span class="nv">athlete_list.0.name</span> <span class="cp">}}</span>
<span class="cp">{%</span> <span class="k">endif</span> <span class="cp">%}</span>
</pre></div>
</div>
<p>上の例はうまくいきますが、ほとんどのテンプレートフィルタは文字列を返すので、フィルタを使った数学的な比較は通常は期待通りにならないことに注意してください。 <a class="reference internal" href="builtins.html#std-templatefilter-length"><code class="xref std std-tfilter docutils literal notranslate"><span class="pre">length</span></code></a> は例外です。</p>
</dd>
<dt><a class="reference internal" href="builtins.html#std-templatetag-block"><code class="xref std std-ttag docutils literal notranslate"><span class="pre">block</span></code></a> と <a class="reference internal" href="builtins.html#std-templatetag-extends"><code class="xref std std-ttag docutils literal notranslate"><span class="pre">extends</span></code></a></dt><dd>テンプレートの &quot;定型文&quot; を削減する強力な方法である <a class="reference internal" href="#id1">template inheritance</a> （下記参照）を設定します。</dd>
</dl>
<p>繰り返しますが、上記は全リストの一部です。全リストは <a class="reference internal" href="builtins.html#ref-templates-builtins-tags"><span class="std std-ref">組み込みタグのリファレンス</span></a> を参照してください。</p>
<p>独自のカスタムテンプレートタグを作成することもできます。 <a class="reference internal" href="../../howto/custom-template-tags.html"><span class="doc">独自のテンプレートタグとフィルタを作る</span></a> を参照してください。</p>
<div class="admonition seealso">
<p class="first admonition-title">参考</p>
<p class="last">Django の管理インタフェースには、指定したサイトで利用可能な全てのテンプレートタグとフィルタの完全なリファレンスを含めることができます。 <a class="reference internal" href="../contrib/admin/admindocs.html"><span class="doc">Django admin ドキュメントジェネレータ</span></a> を参照してください。</p>
</div>
</div>
<div class="section" id="s-comments">
<span id="s-template-comments"></span><span id="comments"></span><span id="template-comments"></span><h2>コメント<a class="headerlink" href="#comments" title="このヘッドラインへのパーマリンク">¶</a></h2>
<p>テンプレートの行の一部をコメントアウトするには、コメント構文 <code class="docutils literal notranslate"><span class="pre">{#</span> <span class="pre">#}</span></code> を使います。</p>
<p>たとえば、このテンプレートは <code class="docutils literal notranslate"><span class="pre">'hello'</span></code> としてレンダリングされます:</p>
<div class="highlight-html+django notranslate"><div class="highlight"><pre><span></span><span class="c">{# greeting #}</span>hello
</pre></div>
</div>
<p>コメントには、たとえ無効でも、どんなテンプレート・コードも含めることができます。たとえば:</p>
<div class="highlight-html+django notranslate"><div class="highlight"><pre><span></span><span class="c">{# {% if foo %}bar{% else %} #}</span>
</pre></div>
</div>
<p>この構文は1行のコメントにしか使えません（改行は <code class="docutils literal notranslate"><span class="pre">{#</span></code> と <code class="docutils literal notranslate"><span class="pre">#}</span></code> の間に入れてはいけません）。テンプレートの複数行の部分をコメントアウトする必要がある場合は <a class="reference internal" href="builtins.html#std-templatetag-comment"><code class="xref std std-ttag docutils literal notranslate"><span class="pre">comment</span></code></a> タグを参照してください。</p>
</div>
<div class="section" id="s-template-inheritance">
<span id="s-id1"></span><span id="template-inheritance"></span><span id="id1"></span><h2>テンプレートの継承<a class="headerlink" href="#template-inheritance" title="このヘッドラインへのパーマリンク">¶</a></h2>
<p>Django のテンプレートエンジンの中で最もパワフルな -- ゆえに最も複雑な -- 部分が、テンプレートの継承です。テンプレートを継承すると、ベースとなる &quot;骨組みの&quot; テンプレートにサイトの共通要素を記述し、<strong>block</strong> を定義することで子テンプレートにオーバーライドさせることができます。</p>
<p>テンプレートの継承について、まず例を見てみましょう:</p>
<div class="highlight-html+django notranslate"><div class="highlight"><pre><span></span><span class="cp">&lt;!DOCTYPE html&gt;</span>
<span class="p">&lt;</span><span class="nt">html</span> <span class="na">lang</span><span class="o">=</span><span class="s">&quot;en&quot;</span><span class="p">&gt;</span>
<span class="p">&lt;</span><span class="nt">head</span><span class="p">&gt;</span>
    <span class="p">&lt;</span><span class="nt">link</span> <span class="na">rel</span><span class="o">=</span><span class="s">&quot;stylesheet&quot;</span> <span class="na">href</span><span class="o">=</span><span class="s">&quot;style.css&quot;</span><span class="p">&gt;</span>
    <span class="p">&lt;</span><span class="nt">title</span><span class="p">&gt;</span><span class="cp">{%</span> <span class="k">block</span> <span class="nv">title</span> <span class="cp">%}</span>My amazing site<span class="cp">{%</span> <span class="k">endblock</span> <span class="cp">%}</span><span class="p">&lt;/</span><span class="nt">title</span><span class="p">&gt;</span>
<span class="p">&lt;/</span><span class="nt">head</span><span class="p">&gt;</span>

<span class="p">&lt;</span><span class="nt">body</span><span class="p">&gt;</span>
    <span class="p">&lt;</span><span class="nt">div</span> <span class="na">id</span><span class="o">=</span><span class="s">&quot;sidebar&quot;</span><span class="p">&gt;</span>
        <span class="cp">{%</span> <span class="k">block</span> <span class="nv">sidebar</span> <span class="cp">%}</span>
        <span class="p">&lt;</span><span class="nt">ul</span><span class="p">&gt;</span>
            <span class="p">&lt;</span><span class="nt">li</span><span class="p">&gt;&lt;</span><span class="nt">a</span> <span class="na">href</span><span class="o">=</span><span class="s">&quot;/&quot;</span><span class="p">&gt;</span>Home<span class="p">&lt;/</span><span class="nt">a</span><span class="p">&gt;&lt;/</span><span class="nt">li</span><span class="p">&gt;</span>
            <span class="p">&lt;</span><span class="nt">li</span><span class="p">&gt;&lt;</span><span class="nt">a</span> <span class="na">href</span><span class="o">=</span><span class="s">&quot;/blog/&quot;</span><span class="p">&gt;</span>Blog<span class="p">&lt;/</span><span class="nt">a</span><span class="p">&gt;&lt;/</span><span class="nt">li</span><span class="p">&gt;</span>
        <span class="p">&lt;/</span><span class="nt">ul</span><span class="p">&gt;</span>
        <span class="cp">{%</span> <span class="k">endblock</span> <span class="cp">%}</span>
    <span class="p">&lt;/</span><span class="nt">div</span><span class="p">&gt;</span>

    <span class="p">&lt;</span><span class="nt">div</span> <span class="na">id</span><span class="o">=</span><span class="s">&quot;content&quot;</span><span class="p">&gt;</span>
        <span class="cp">{%</span> <span class="k">block</span> <span class="nv">content</span> <span class="cp">%}{%</span> <span class="k">endblock</span> <span class="cp">%}</span>
    <span class="p">&lt;/</span><span class="nt">div</span><span class="p">&gt;</span>
<span class="p">&lt;/</span><span class="nt">body</span><span class="p">&gt;</span>
<span class="p">&lt;/</span><span class="nt">html</span><span class="p">&gt;</span>
</pre></div>
</div>
<p>我々が <code class="docutils literal notranslate"><span class="pre">base.html</span></code> と呼ぶことになるこのテンプレートは、HTML の骨組みを定義し、2 列のサイトを表示できるようになっています。block をコンテンツで埋めるのは、&quot;子&quot; テンプレートの仕事です。</p>
<p>この例では、<a class="reference internal" href="builtins.html#std-templatetag-block"><code class="xref std std-ttag docutils literal notranslate"><span class="pre">block</span></code></a> タグにより、子テンプレートが埋めることができる 3 つのブロックが定義されています。<a class="reference internal" href="builtins.html#std-templatetag-block"><code class="xref std std-ttag docutils literal notranslate"><span class="pre">block</span></code></a> タグの仕事は、テンプレートのこれらの部分が子テンプレートによりオーバーライドされる可能性があることをテンプレートエンジンに伝えることです。</p>
<p>子テンプレートは以下のようになります:</p>
<div class="highlight-html+django notranslate"><div class="highlight"><pre><span></span><span class="cp">{%</span> <span class="k">extends</span> <span class="s2">&quot;base.html&quot;</span> <span class="cp">%}</span>

<span class="cp">{%</span> <span class="k">block</span> <span class="nv">title</span> <span class="cp">%}</span>My amazing blog<span class="cp">{%</span> <span class="k">endblock</span> <span class="cp">%}</span>

<span class="cp">{%</span> <span class="k">block</span> <span class="nv">content</span> <span class="cp">%}</span>
<span class="cp">{%</span> <span class="k">for</span> <span class="nv">entry</span> <span class="k">in</span> <span class="nv">blog_entries</span> <span class="cp">%}</span>
    <span class="p">&lt;</span><span class="nt">h2</span><span class="p">&gt;</span><span class="cp">{{</span> <span class="nv">entry.title</span> <span class="cp">}}</span><span class="p">&lt;/</span><span class="nt">h2</span><span class="p">&gt;</span>
    <span class="p">&lt;</span><span class="nt">p</span><span class="p">&gt;</span><span class="cp">{{</span> <span class="nv">entry.body</span> <span class="cp">}}</span><span class="p">&lt;/</span><span class="nt">p</span><span class="p">&gt;</span>
<span class="cp">{%</span> <span class="k">endfor</span> <span class="cp">%}</span>
<span class="cp">{%</span> <span class="k">endblock</span> <span class="cp">%}</span>
</pre></div>
</div>
<p>ここで重要なのは <a class="reference internal" href="builtins.html#std-templatetag-extends"><code class="xref std std-ttag docutils literal notranslate"><span class="pre">extends</span></code></a> タグです。このタグが、このテンプレートが他のテンプレートを &quot;拡張&quot; することをテンプレートエンジンに伝えるのです。テンプレートシステムがこのテンプレートを評価する際に、最初に親テンプレートを探しに行きます -- この例では &quot;base.html&quot; です。</p>
<p>この時点で、テンプレートエンジンは <code class="docutils literal notranslate"><span class="pre">base.html</span></code> 内の <a class="reference internal" href="builtins.html#std-templatetag-block"><code class="xref std std-ttag docutils literal notranslate"><span class="pre">block</span></code></a> を認識し、子テンプレートのコンテンツと差し替えます。<code class="docutils literal notranslate"><span class="pre">blog_entries</span></code> の値に応じて、アウトプットは以下のようになります:</p>
<div class="highlight-html+django notranslate"><div class="highlight"><pre><span></span><span class="cp">&lt;!DOCTYPE html&gt;</span>
<span class="p">&lt;</span><span class="nt">html</span> <span class="na">lang</span><span class="o">=</span><span class="s">&quot;en&quot;</span><span class="p">&gt;</span>
<span class="p">&lt;</span><span class="nt">head</span><span class="p">&gt;</span>
    <span class="p">&lt;</span><span class="nt">link</span> <span class="na">rel</span><span class="o">=</span><span class="s">&quot;stylesheet&quot;</span> <span class="na">href</span><span class="o">=</span><span class="s">&quot;style.css&quot;</span><span class="p">&gt;</span>
    <span class="p">&lt;</span><span class="nt">title</span><span class="p">&gt;</span>My amazing blog<span class="p">&lt;/</span><span class="nt">title</span><span class="p">&gt;</span>
<span class="p">&lt;/</span><span class="nt">head</span><span class="p">&gt;</span>

<span class="p">&lt;</span><span class="nt">body</span><span class="p">&gt;</span>
    <span class="p">&lt;</span><span class="nt">div</span> <span class="na">id</span><span class="o">=</span><span class="s">&quot;sidebar&quot;</span><span class="p">&gt;</span>
        <span class="p">&lt;</span><span class="nt">ul</span><span class="p">&gt;</span>
            <span class="p">&lt;</span><span class="nt">li</span><span class="p">&gt;&lt;</span><span class="nt">a</span> <span class="na">href</span><span class="o">=</span><span class="s">&quot;/&quot;</span><span class="p">&gt;</span>Home<span class="p">&lt;/</span><span class="nt">a</span><span class="p">&gt;&lt;/</span><span class="nt">li</span><span class="p">&gt;</span>
            <span class="p">&lt;</span><span class="nt">li</span><span class="p">&gt;&lt;</span><span class="nt">a</span> <span class="na">href</span><span class="o">=</span><span class="s">&quot;/blog/&quot;</span><span class="p">&gt;</span>Blog<span class="p">&lt;/</span><span class="nt">a</span><span class="p">&gt;&lt;/</span><span class="nt">li</span><span class="p">&gt;</span>
        <span class="p">&lt;/</span><span class="nt">ul</span><span class="p">&gt;</span>
    <span class="p">&lt;/</span><span class="nt">div</span><span class="p">&gt;</span>

    <span class="p">&lt;</span><span class="nt">div</span> <span class="na">id</span><span class="o">=</span><span class="s">&quot;content&quot;</span><span class="p">&gt;</span>
        <span class="p">&lt;</span><span class="nt">h2</span><span class="p">&gt;</span>Entry one<span class="p">&lt;/</span><span class="nt">h2</span><span class="p">&gt;</span>
        <span class="p">&lt;</span><span class="nt">p</span><span class="p">&gt;</span>This is my first entry.<span class="p">&lt;/</span><span class="nt">p</span><span class="p">&gt;</span>

        <span class="p">&lt;</span><span class="nt">h2</span><span class="p">&gt;</span>Entry two<span class="p">&lt;/</span><span class="nt">h2</span><span class="p">&gt;</span>
        <span class="p">&lt;</span><span class="nt">p</span><span class="p">&gt;</span>This is my second entry.<span class="p">&lt;/</span><span class="nt">p</span><span class="p">&gt;</span>
    <span class="p">&lt;/</span><span class="nt">div</span><span class="p">&gt;</span>
<span class="p">&lt;/</span><span class="nt">body</span><span class="p">&gt;</span>
<span class="p">&lt;/</span><span class="nt">html</span><span class="p">&gt;</span>
</pre></div>
</div>
<p>子テンプレート内で <code class="docutils literal notranslate"><span class="pre">sidebar</span></code> を定義していないため、親テンプレートの値がそのまま使われていることに留意してください。親テンプレートの <code class="docutils literal notranslate"><span class="pre">{%</span> <span class="pre">block</span> <span class="pre">%}</span></code> タグ内のコンテンツは、常にフォールバックとして使用されます。</p>
<p>継承は、必要なだけ段階を経ることができます。継承を使う一般的な方法は、以下の 3 段階のアプローチです:</p>
<ul class="simple">
<li>メインのルック・アンド・フィールを保持する <code class="docutils literal notranslate"><span class="pre">base.html</span></code> を作成します。</li>
<li>サイトのそれぞれの「セクション」に対して、<code class="docutils literal notranslate"><span class="pre">base_セクション名.html</span></code> テンプレートを作成します。たとえば、<code class="docutils literal notranslate"><span class="pre">base_news.html</span></code>、<code class="docutils literal notranslate"><span class="pre">base_sports.html</span></code> などです。これらのテンプレートはすべて <code class="docutils literal notranslate"><span class="pre">base.html</span></code> を拡張 (extend) し、セクション固有のスタイルやデザインが含まれています。</li>
<li>ページのそれぞれのタイプに対して、個別のテンプレートを作成します。たとえばニュース記事やブログエントリーなどです。これらのテンプレートは、適切なセクションの手プレートを拡張 (extends) します。</li>
</ul>
<p>このアプローチにより、コードを最大限に再利用でき、共通のコンテンツ部 (全セクション共通のナビゲーションなど) に項目を追加するのに役立ちます。</p>
<p>継承を使用する際のコツをいくつか紹介します:</p>
<ul>
<li><p class="first">テンプレート内で <a class="reference internal" href="builtins.html#std-templatetag-extends"><code class="xref std std-ttag docutils literal notranslate"><span class="pre">{%</span> <span class="pre">extends</span> <span class="pre">%}</span></code></a> を使用する際は、その点プレート内で一番最初のテンプレートタグとして指定する必要があります。それ以外の場合、継承が正しく動作しません。</p>
</li>
<li><p class="first">ベースのテンプレートには <a class="reference internal" href="builtins.html#std-templatetag-block"><code class="xref std std-ttag docutils literal notranslate"><span class="pre">{%</span> <span class="pre">block</span> <span class="pre">%}</span></code></a> タグを多く配置するほどよいです。子テンプレートがすべてのブロックを埋める必要がないことを思い出してください。多くのブロック内に適当なデフォルトを記述しておき、必要なものを後で定義し直せばいいのです。フックは多ければ多いほどいいということです。</p>
</li>
<li><p class="first">もし同じコンテンツを複数のテンプレート内で記述していたら、そのコンテンツを親テンプレートの <code class="docutils literal notranslate"><span class="pre">{%</span> <span class="pre">block</span> <span class="pre">%}</span></code> に移動させるべきかもしれません。</p>
</li>
<li><p class="first">親テンプレートからブロックのコンテンツを取得する必要がある場合、<code class="docutils literal notranslate"><span class="pre">{{</span> <span class="pre">block.super</span> <span class="pre">}}</span></code> が利用できます。親のブロックを完全にオーバーライドせずに、コンテンツを追加したい場合に有用です。<code class="docutils literal notranslate"><span class="pre">{{</span> <span class="pre">block.super</span> <span class="pre">}}</span></code> を使って挿入されたデータは自動的にエスケープされません (<a class="reference external" href="#automatic-html-escaping">next section</a> を参照してください)。これは、必要な場合は親テンプレートですでにエスケープされているからです。</p>
</li>
<li><p class="first">継承元と同じテンプレート名を使うことで、 <a class="reference internal" href="builtins.html#std-templatetag-extends"><code class="xref std std-ttag docutils literal notranslate"><span class="pre">{%</span> <span class="pre">extends</span> <span class="pre">%}</span></code></a> を使ってテンプレートのオーバーライドと同時に継承できます。 <code class="docutils literal notranslate"><span class="pre">{{</span> <span class="pre">block.super</span> <span class="pre">}}</span></code> と組み合わせることで、カスタマイズを最小限に留める強力な手法となります。完全な例は <em>テンプレートのオーバーライド</em> How-to の <a class="reference internal" href="../../howto/overriding-templates.html#extending-an-overridden-template"><span class="std std-ref">オーバーライドされたテンプレートを継承（extend）する</span></a> を参照してください。</p>
</li>
<li><p class="first"><a class="reference internal" href="builtins.html#std-templatetag-block"><code class="xref std std-ttag docutils literal notranslate"><span class="pre">{%</span> <span class="pre">block</span> <span class="pre">%}</span></code></a> の外側でテンプレートタグの <code class="docutils literal notranslate"><span class="pre">as</span></code> 構文を使って作成した変数はブロックの中では使用できません。たとえば、このテンプレートは何もレンダリングしません:</p>
<div class="highlight-html+django notranslate"><div class="highlight"><pre><span></span><span class="cp">{%</span> <span class="k">translate</span> <span class="s2">&quot;Title&quot;</span> <span class="k">as</span> <span class="nv">title</span> <span class="cp">%}</span>
<span class="cp">{%</span> <span class="k">block</span> <span class="nv">content</span> <span class="cp">%}{{</span> <span class="nv">title</span> <span class="cp">}}{%</span> <span class="k">endblock</span> <span class="cp">%}</span>
</pre></div>
</div>
</li>
<li><p class="first">さらに読みやすくするために、オプションで <code class="docutils literal notranslate"><span class="pre">{%</span> <span class="pre">endblock</span> <span class="pre">%}</span></code> タグに <em>名前</em> をつけることができます。たとえば:</p>
<div class="highlight-html+django notranslate"><div class="highlight"><pre><span></span><span class="cp">{%</span> <span class="k">block</span> <span class="nv">content</span> <span class="cp">%}</span>
...
<span class="cp">{%</span> <span class="k">endblock</span> <span class="nv">content</span> <span class="cp">%}</span>
</pre></div>
</div>
<p>大きなテンプレートでは、このテクニックでどの <code class="docutils literal notranslate"><span class="pre">{%</span> <span class="pre">block</span> <span class="pre">%}</span></code> が閉じられているのかが分かりやすくなります。</p>
</li>
<li><p class="first"><a class="reference internal" href="builtins.html#std-templatetag-block"><code class="xref std std-ttag docutils literal notranslate"><span class="pre">{%</span> <span class="pre">block</span> <span class="pre">%}</span></code></a> タグが最初に評価されます。そのため、周囲のタグの真偽に関わらず、ブロックの内容は常に上書きされます。たとえば、このテンプレートは <code class="docutils literal notranslate"><span class="pre">title</span></code> ブロックの内容を常に上書きします:</p>
<div class="highlight-html+django notranslate"><div class="highlight"><pre><span></span><span class="cp">{%</span> <span class="k">if</span> <span class="nv">change_title</span> <span class="cp">%}</span>
    <span class="cp">{%</span> <span class="k">block</span> <span class="nv">title</span> <span class="cp">%}</span>Hello!<span class="cp">{%</span> <span class="k">endblock</span> <span class="nv">title</span> <span class="cp">%}</span>
<span class="cp">{%</span> <span class="k">endif</span> <span class="cp">%}</span>
</pre></div>
</div>
</li>
</ul>
<p>最後に、同じテンプレート内で同じ名前の <a class="reference internal" href="builtins.html#std-templatetag-block"><code class="xref std std-ttag docutils literal notranslate"><span class="pre">block</span></code></a> タグを複数定義することはできないことに留意してください。この制限は、block タグが &quot;両方向に&quot; 働くのが理由です。block タグは埋めるための穴を提供するだけではなく -- <em>親テンプレート</em> 内で穴を埋めるコンテンツを定義します。もし同名の <a class="reference internal" href="builtins.html#std-templatetag-block"><code class="xref std std-ttag docutils literal notranslate"><span class="pre">block</span></code></a> がテンプレート内に 2 つ存在すると、どちらのブロックのコンテンツを使うべきかテンプレートの親が判断できなくなってしまうのです。</p>
</div>
<div class="section" id="s-automatic-html-escaping">
<span id="s-id2"></span><span id="automatic-html-escaping"></span><span id="id2"></span><h2>HTML の自動エスケープ<a class="headerlink" href="#automatic-html-escaping" title="このヘッドラインへのパーマリンク">¶</a></h2>
<p>テンプレートから HTML を生成する際は、変数内の文字が HTML のレンダリング結果に悪影響を与えるというリスクが常に付きまといます。たとえば、テンプレートに以下のような部分がある場合を考えてみましょう:</p>
<div class="highlight-html+django notranslate"><div class="highlight"><pre><span></span>Hello, <span class="cp">{{</span> <span class="nv">name</span> <span class="cp">}}</span>
</pre></div>
</div>
<p>一見、このコードはユーザの名前を表示するだけの無害なものに見えます。しかし次のような値が名前として入力されていれば、何が起きるでしょうか:</p>
<div class="highlight-html+django notranslate"><div class="highlight"><pre><span></span><span class="p">&lt;</span><span class="nt">script</span><span class="p">&gt;</span><span class="nx">alert</span><span class="p">(</span><span class="s1">&#39;hello&#39;</span><span class="p">)&lt;/</span><span class="nt">script</span><span class="p">&gt;</span>
</pre></div>
</div>
<p>この値によって、テンプレートは次のように出力されます:</p>
<div class="highlight-html+django notranslate"><div class="highlight"><pre><span></span>Hello, <span class="p">&lt;</span><span class="nt">script</span><span class="p">&gt;</span><span class="nx">alert</span><span class="p">(</span><span class="s1">&#39;hello&#39;</span><span class="p">)&lt;/</span><span class="nt">script</span><span class="p">&gt;</span>
</pre></div>
</div>
<p>……結果として、ブラウザに JavaScript の警告ボックスをポップアップさせることができてしまいます！</p>
<p>同様に、名前に <code class="docutils literal notranslate"><span class="pre">'&lt;'</span></code> 文字が含まれていたらどうでしょうか:</p>
<div class="highlight-html notranslate"><div class="highlight"><pre><span></span><span class="p">&lt;</span><span class="nt">b</span><span class="p">&gt;</span>username
</pre></div>
</div>
<p>この値によって、テンプレートはこのように出力されます:</p>
<div class="highlight-html+django notranslate"><div class="highlight"><pre><span></span>Hello, <span class="p">&lt;</span><span class="nt">b</span><span class="p">&gt;</span>username
</pre></div>
</div>
<p>これで、以降の Web ページの内容はすべて太字になってしまいます！</p>
<p>ユーザーが入力したデータを無条件に信頼したり、直接 Web ページに挿入したりするべきでないことは明らかです。悪意のあるユーザは、この手の抜け穴を使って悪さをするものだからです。こうしたタイプのセキュリティホールの悪用は、 <a class="reference external" href="https://en.wikipedia.org/wiki/Cross-site_scripting">Cross Site Scripting</a> (XSS) 攻撃と呼ばれています。</p>
<p>この問題を防ぐために、二つの方法があります:</p>
<ul class="simple">
<li>一つは、信頼できない変数は必ず <a class="reference internal" href="builtins.html#std-templatefilter-escape"><code class="xref std std-tfilter docutils literal notranslate"><span class="pre">escape</span></code></a> フィルタ (後で述べます) に通すことです。このフィルタは危害を及ぼす可能性をもつ HTML 文字を無害な文字に変換します。 この方法は初期の数年間において Django のデフォルトとして採用されていました。しかしユーザー、すなわち開発者やテンプレートの作者にとっては、すべてのデータをエスケープすることを忘れぬよう注意しなければならないという負担になるのが問題です。</li>
<li>もう一つは、 Django の自動 HTML エスケープを使うというものです。この節の後半では自動エスケープの仕組みについて述べます。</li>
</ul>
<p>デフォルトでは、Django はすべてのテンプレートの変数タグの出力を自動的にエスケープするよう設定されています。具体的には、以下の 5 つの文字がエスケープされます:</p>
<ul class="simple">
<li><code class="docutils literal notranslate"><span class="pre">&lt;</span></code> を <code class="docutils literal notranslate"><span class="pre">&amp;lt;</span></code> に変換</li>
<li><code class="docutils literal notranslate"><span class="pre">&gt;</span></code> を <code class="docutils literal notranslate"><span class="pre">&amp;gt;</span></code> に変換</li>
<li><code class="docutils literal notranslate"><span class="pre">'</span></code> ( シングルクォート ) を <code class="docutils literal notranslate"><span class="pre">&amp;#x27;</span></code>　に変換</li>
<li><code class="docutils literal notranslate"><span class="pre">&quot;</span></code> ( ダブルクォート ) を <code class="docutils literal notranslate"><span class="pre">&amp;quot;</span></code> に変換</li>
<li><code class="docutils literal notranslate"><span class="pre">&amp;</span></code> を <code class="docutils literal notranslate"><span class="pre">&amp;amp;</span></code> に変換</li>
</ul>
<p>この動作は、デフォルトで適用されていることを重ねて強調しておきます。Django テンプレートシステムを使っているかぎり、あなたはエスケープに関する問題からは守られているのです。</p>
<div class="section" id="s-how-to-turn-it-off">
<span id="how-to-turn-it-off"></span><h3>自動エスケープをオフにする<a class="headerlink" href="#how-to-turn-it-off" title="このヘッドラインへのパーマリンク">¶</a></h3>
<p>サイト単位やテンプレート単位、あるいは変数単位でデータの自動エスケープ機能を無効にしたい場合には、いくつかの方法があります。</p>
<p>どんなときに、自動エスケープをオフにする必要があるでしょうか。テンプレート変数の中身は、生の HTML として出力するように意図されたデータかもしれません。そうした場合にはコンテンツがエスケープされてほしくはないでしょう。たとえば、データベースに HTML を保存していてテンプレートに直接埋め込みたい場合を考えてみましょう。また、 Django のテンプレートシステムを使って、 HTML 以外 のデータ、たとえばメールのメッセージなどを生成したい場合もあるでしょう。</p>
<div class="section" id="s-for-individual-variables">
<span id="for-individual-variables"></span><h4>変数単位での制御<a class="headerlink" href="#for-individual-variables" title="このヘッドラインへのパーマリンク">¶</a></h4>
<p>個々の変数の自動エスケープを無効にするには <a class="reference internal" href="builtins.html#std-templatefilter-safe"><code class="xref std std-tfilter docutils literal notranslate"><span class="pre">safe</span></code></a> フィルタを使用します:</p>
<div class="highlight-html+django notranslate"><div class="highlight"><pre><span></span>This will be escaped: <span class="cp">{{</span> <span class="nv">data</span> <span class="cp">}}</span>
This will not be escaped: <span class="cp">{{</span> <span class="nv">data</span><span class="o">|</span><span class="nf">safe</span> <span class="cp">}}</span>
</pre></div>
</div>
<p><em>safe</em> という言葉は、これ以上エスケープしないよう保護 (safe) するとか、 HTML として解釈しても安全 (safe) であるという意味だと考えてください。 たとえば、<code class="docutils literal notranslate"><span class="pre">data</span></code> に <code class="docutils literal notranslate"><span class="pre">'&lt;b&gt;'</span></code> が入っていた場合、出力は以下のようになります。</p>
<div class="highlight-html+django notranslate"><div class="highlight"><pre><span></span>This will be escaped: <span class="ni">&amp;lt;</span>b<span class="ni">&amp;gt;</span>
This will not be escaped: <span class="p">&lt;</span><span class="nt">b</span><span class="p">&gt;</span>
</pre></div>
</div>
</div>
<div class="section" id="s-for-template-blocks">
<span id="for-template-blocks"></span><h4>テンプレートブロック単位での制御<a class="headerlink" href="#for-template-blocks" title="このヘッドラインへのパーマリンク">¶</a></h4>
<p>テンプレート単位で自動エスケープを制御するには、テンプレート (または テンプレートの一部) を、以下のように <a class="reference internal" href="builtins.html#std-templatetag-autoescape"><code class="xref std std-ttag docutils literal notranslate"><span class="pre">autoescape</span></code></a> タグで囲みます:</p>
<div class="highlight-html+django notranslate"><div class="highlight"><pre><span></span><span class="cp">{%</span> <span class="k">autoescape</span> <span class="nv">off</span> <span class="cp">%}</span>
    Hello <span class="cp">{{</span> <span class="nv">name</span> <span class="cp">}}</span>
<span class="cp">{%</span> <span class="k">endautoescape</span> <span class="cp">%}</span>
</pre></div>
</div>
<p><a class="reference internal" href="builtins.html#std-templatetag-autoescape"><code class="xref std std-ttag docutils literal notranslate"><span class="pre">autoescape</span></code></a> タグは、 <code class="docutils literal notranslate"><span class="pre">on</span></code> または <code class="docutils literal notranslate"><span class="pre">off</span></code> を引数にとります。 テンプレートのある範囲を自動エスケープし、さらにその一部で自動エスケープをオフにしたい場合には、次のようにできます:</p>
<div class="highlight-html+django notranslate"><div class="highlight"><pre><span></span>Auto-escaping is on by default. Hello <span class="cp">{{</span> <span class="nv">name</span> <span class="cp">}}</span>

<span class="cp">{%</span> <span class="k">autoescape</span> <span class="nv">off</span> <span class="cp">%}</span>
    This will not be auto-escaped: <span class="cp">{{</span> <span class="nv">data</span> <span class="cp">}}</span>.

    Nor this: <span class="cp">{{</span> <span class="nv">other_data</span> <span class="cp">}}</span>
    <span class="cp">{%</span> <span class="k">autoescape</span> <span class="nv">on</span> <span class="cp">%}</span>
        Auto-escaping applies again: <span class="cp">{{</span> <span class="nv">name</span> <span class="cp">}}</span>
    <span class="cp">{%</span> <span class="k">endautoescape</span> <span class="cp">%}</span>
<span class="cp">{%</span> <span class="k">endautoescape</span> <span class="cp">%}</span>
</pre></div>
</div>
<p>自動エスケープのタグは、他のブロックタグと同様、タグを設定したテンプレートを継承している他のテンプレートや、 <a class="reference internal" href="builtins.html#std-templatetag-include"><code class="xref std std-ttag docutils literal notranslate"><span class="pre">include</span></code></a> で取り込んだテンプレートでも有効です。次に例を示します。</p>
<div class="literal-block-wrapper docutils container" id="id4">
<div class="code-block-caption"><span class="caption-text"><code class="docutils literal notranslate"><span class="pre">base.html</span></code></span><a class="headerlink" href="#id4" title="このコードへのパーマリンク">¶</a></div>
<div class="highlight-html+django notranslate"><div class="highlight"><pre><span></span><span class="cp">{%</span> <span class="k">autoescape</span> <span class="nv">off</span> <span class="cp">%}</span>
<span class="p">&lt;</span><span class="nt">h1</span><span class="p">&gt;</span><span class="cp">{%</span> <span class="k">block</span> <span class="nv">title</span> <span class="cp">%}{%</span> <span class="k">endblock</span> <span class="cp">%}</span><span class="p">&lt;/</span><span class="nt">h1</span><span class="p">&gt;</span>
<span class="cp">{%</span> <span class="k">block</span> <span class="nv">content</span> <span class="cp">%}</span>
<span class="cp">{%</span> <span class="k">endblock</span> <span class="cp">%}</span>
<span class="cp">{%</span> <span class="k">endautoescape</span> <span class="cp">%}</span>
</pre></div>
</div>
</div>
<div class="literal-block-wrapper docutils container" id="id5">
<div class="code-block-caption"><span class="caption-text"><code class="docutils literal notranslate"><span class="pre">child.html</span></code></span><a class="headerlink" href="#id5" title="このコードへのパーマリンク">¶</a></div>
<div class="highlight-html+django notranslate"><div class="highlight"><pre><span></span><span class="cp">{%</span> <span class="k">extends</span> <span class="s2">&quot;base.html&quot;</span> <span class="cp">%}</span>
<span class="cp">{%</span> <span class="k">block</span> <span class="nv">title</span> <span class="cp">%}</span>This <span class="ni">&amp;amp;</span> that<span class="cp">{%</span> <span class="k">endblock</span> <span class="cp">%}</span>
<span class="cp">{%</span> <span class="k">block</span> <span class="nv">content</span> <span class="cp">%}{{</span> <span class="nv">greeting</span> <span class="cp">}}{%</span> <span class="k">endblock</span> <span class="cp">%}</span>
</pre></div>
</div>
</div>
<p>ベースのテンプレートで自動エスケープが無効化されているので、子テンプレートでも自動エスケープは無効化されます。結果として、 <code class="docutils literal notranslate"><span class="pre">greeting</span></code> 変数の値が <code class="docutils literal notranslate"><span class="pre">&lt;b&gt;Hello!&lt;/b&gt;</span></code> のとき、以下の HTML が出力されます:</p>
<div class="highlight-html+django notranslate"><div class="highlight"><pre><span></span><span class="p">&lt;</span><span class="nt">h1</span><span class="p">&gt;</span>This <span class="ni">&amp;amp;</span> that<span class="p">&lt;/</span><span class="nt">h1</span><span class="p">&gt;</span>
<span class="p">&lt;</span><span class="nt">b</span><span class="p">&gt;</span>Hello!<span class="p">&lt;/</span><span class="nt">b</span><span class="p">&gt;</span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="s-notes">
<span id="notes"></span><h3>備考<a class="headerlink" href="#notes" title="このヘッドラインへのパーマリンク">¶</a></h3>
<p>一般に、テンプレートの作者は自動エスケープをあまり意識する必要はありません。 データをエスケープすべきではない場合を考えたり、データを適切にマークし、テンプレート上でうまく表示されるように考慮するのは、Python 側の開発者 (ビューやカスタムフィルタの開発者)であるべきです。</p>
<p>もしあなたが作成しているテンプレートがどういった状況で使われるのか分からず、自動エスケープが有効かどうかはっきりしない場合には、エスケープの必要な変数全てに <a class="reference internal" href="builtins.html#std-templatefilter-escape"><code class="xref std std-tfilter docutils literal notranslate"><span class="pre">escape</span></code></a> フィルタを追加してください。自動エスケープがオンの場合、 <a class="reference internal" href="builtins.html#std-templatefilter-escape"><code class="xref std std-tfilter docutils literal notranslate"><span class="pre">escape</span></code></a> フィルタがデータ を二重にエスケープするような危険性はありません。 <a class="reference internal" href="builtins.html#std-templatefilter-escape"><code class="xref std std-tfilter docutils literal notranslate"><span class="pre">escape</span></code></a> フィルタは自動エスケープされた変数には影響しなません。</p>
</div>
<div class="section" id="s-string-literals-and-automatic-escaping">
<span id="s-id3"></span><span id="string-literals-and-automatic-escaping"></span><span id="id3"></span><h3>文字列リテラルと自動エスケープ<a class="headerlink" href="#string-literals-and-automatic-escaping" title="このヘッドラインへのパーマリンク">¶</a></h3>
<p>先に説明したように、フィルタの引数は文字列であってもかまいません:</p>
<div class="highlight-html+django notranslate"><div class="highlight"><pre><span></span><span class="cp">{{</span> <span class="nv">data</span><span class="o">|</span><span class="nf">default</span><span class="s2">:&quot;This is a string literal.&quot;</span> <span class="cp">}}</span>
</pre></div>
</div>
<p>文字列リテラルは、すべて自動エスケープ <strong>されずに</strong> テンプレート内に挿入され、 <a class="reference internal" href="builtins.html#std-templatefilter-safe"><code class="xref std std-tfilter docutils literal notranslate"><span class="pre">safe</span></code></a> フィルタを通過したかのように動作します。なぜなら、テンプレートの作者はその文字列リテラルに何が書かれているかは把握していますし、テンプレートが書かれる時点でテキストが正しくエスケープされていることは確認できるからです。</p>
<p>したがって、以下のようにテンプレートを書いてください:</p>
<div class="highlight-html+django notranslate"><div class="highlight"><pre><span></span><span class="cp">{{</span> <span class="nv">data</span><span class="o">|</span><span class="nf">default</span><span class="s2">:&quot;3 &amp;lt; 2&quot;</span> <span class="cp">}}</span>
</pre></div>
</div>
<p>以下のようにはしないでください:</p>
<div class="highlight-html+django notranslate"><div class="highlight"><pre><span></span><span class="cp">{{</span> <span class="nv">data</span><span class="o">|</span><span class="nf">default</span><span class="s2">:&quot;3 &lt; 2&quot;</span> <span class="cp">}}</span>  <span class="c">{# Bad! Don&#39;t do this. #}</span>
</pre></div>
</div>
<p>この事が、変数自身に由来するデータに対して何かを引き起こす恐れはありません。 変数の内容はテンプレート作者の管理外にあり、必要に応じて自動的にエスケープされます。</p>
</div>
</div>
<div class="section" id="s-accessing-method-calls">
<span id="s-template-accessing-methods"></span><span id="accessing-method-calls"></span><span id="template-accessing-methods"></span><h2>メソッドへのアクセス<a class="headerlink" href="#accessing-method-calls" title="このヘッドラインへのパーマリンク">¶</a></h2>
<p>オブジェクトに備わったほとんどのメソッドは、テンプレートの中からでも呼び出すことができます。これはテンプレートからアクセスできる対象は、単にクラスの属性 (フィールド名のように) やビューを通した変数だけにはとどまらないということを意味します。たとえば Django ORM は外部キーに関係するオブジェクトの集合を見つけるために <a class="reference internal" href="../../topics/db/queries.html#topics-db-queries-related"><span class="std std-ref">&quot;entry_set&quot;</span></a> という構文を提供しています。これによって、たとえば &quot;comment&quot; と呼ばれるモデルが外部キーで &quot;task&quot; というモデルに関連づけられている場合、テンプレートは task モデルに添えられたすべての comment に対して、以下のようにアクセスできます。</p>
<div class="highlight-html+django notranslate"><div class="highlight"><pre><span></span><span class="cp">{%</span> <span class="k">for</span> <span class="nv">comment</span> <span class="k">in</span> <span class="nv">task.comment_set.all</span> <span class="cp">%}</span>
    <span class="cp">{{</span> <span class="nv">comment</span> <span class="cp">}}</span>
<span class="cp">{%</span> <span class="k">endfor</span> <span class="cp">%}</span>
</pre></div>
</div>
<p>同じように、 <a class="reference internal" href="../models/querysets.html"><span class="doc">QuerySet</span></a> は、そこに含まれているオブジェクトの個数を数えるため <code class="docutils literal notranslate"><span class="pre">count()</span></code> というメソッドを提供しています。これによって、 task と関連づけられた全てのコメントの数を取得することも出来ます:</p>
<div class="highlight-html+django notranslate"><div class="highlight"><pre><span></span><span class="cp">{{</span> <span class="nv">task.comment_set.all.count</span> <span class="cp">}}</span>
</pre></div>
</div>
<p>モデル自身で明示的に定義したメソッドにもアクセスできます:</p>
<div class="literal-block-wrapper docutils container" id="id6">
<div class="code-block-caption"><span class="caption-text"><code class="docutils literal notranslate"><span class="pre">models.py</span></code></span><a class="headerlink" href="#id6" title="このコードへのパーマリンク">¶</a></div>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">Task</span><span class="p">(</span><span class="n">models</span><span class="o">.</span><span class="n">Model</span><span class="p">):</span>
    <span class="k">def</span> <span class="nf">foo</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="k">return</span> <span class="s2">&quot;bar&quot;</span>
</pre></div>
</div>
</div>
<div class="literal-block-wrapper docutils container" id="id7">
<div class="code-block-caption"><span class="caption-text"><code class="docutils literal notranslate"><span class="pre">template.html</span></code></span><a class="headerlink" href="#id7" title="このコードへのパーマリンク">¶</a></div>
<div class="highlight-html+django notranslate"><div class="highlight"><pre><span></span><span class="cp">{{</span> <span class="nv">task.foo</span> <span class="cp">}}</span>
</pre></div>
</div>
</div>
<p>Django ではテンプレート内でのプログラム的な処理を意図的に制限しているため、テンプレートからメソッドに引数を渡すことはできません。データはビューの中で計算され、テンプレートへは表示のためだけに渡されるべきだからです。</p>
</div>
<div class="section" id="s-custom-tag-and-filter-libraries">
<span id="s-loading-custom-template-libraries"></span><span id="custom-tag-and-filter-libraries"></span><span id="loading-custom-template-libraries"></span><h2>カスタムタグとカスタムフィルタのライブラリ<a class="headerlink" href="#custom-tag-and-filter-libraries" title="このヘッドラインへのパーマリンク">¶</a></h2>
<p>アプリケーションによっては、カスタムのタグやフィルタライブラリを提供しています。これらをテンプレートで使いたい場合、そのアプリケーションが <a class="reference internal" href="../settings.html#std-setting-INSTALLED_APPS"><code class="xref std std-setting docutils literal notranslate"><span class="pre">INSTALLED_APPS</span></code></a> に追加されていることを確認し (以下の例では <code class="docutils literal notranslate"><span class="pre">'django.contrib.humanize'</span></code> が追加されているものとします) 、そしてテンプレート側で <a class="reference internal" href="builtins.html#std-templatetag-load"><code class="xref std std-ttag docutils literal notranslate"><span class="pre">load</span></code></a> タグを使います:</p>
<div class="highlight-html+django notranslate"><div class="highlight"><pre><span></span><span class="cp">{%</span> <span class="k">load</span> <span class="nv">humanize</span> <span class="cp">%}</span>

<span class="cp">{{</span> <span class="m">45000</span><span class="o">|</span><span class="nf">intcomma</span> <span class="cp">}}</span>
</pre></div>
</div>
<p>この例では、 <a class="reference internal" href="builtins.html#std-templatetag-load"><code class="xref std std-ttag docutils literal notranslate"><span class="pre">load</span></code></a> タグは <code class="docutils literal notranslate"><span class="pre">humanize</span></code> という名前のタグライブラリを読み込み、 <code class="docutils literal notranslate"><span class="pre">intcomma</span></code> フィルタを使えるようにしています。 <a class="reference internal" href="../contrib/admin/admindocs.html#module-django.contrib.admindocs" title="django.contrib.admindocs: Django's admin documentation generator."><code class="xref py py-mod docutils literal notranslate"><span class="pre">django.contrib.admindocs</span></code></a> が有効にされている場合、あなたの admin は現在インストールされているアプリケーションのドキュメント文字列を参照してカスタムライブラリの一覧を得ることができます。</p>
<p><a class="reference internal" href="builtins.html#std-templatetag-load"><code class="xref std std-ttag docutils literal notranslate"><span class="pre">load</span></code></a> タグは複数のライブラリ名を同時に読み込めます。ライブラリ名はスペースで区切って下さい:</p>
<div class="highlight-html+django notranslate"><div class="highlight"><pre><span></span><span class="cp">{%</span> <span class="k">load</span> <span class="nv">humanize</span> <span class="nv">i18n</span> <span class="cp">%}</span>
</pre></div>
</div>
<p>カスタムのテンプレートライブラリを作成する方法については、 <a class="reference internal" href="../../howto/custom-template-tags.html"><span class="doc">独自のテンプレートタグとフィルタを作る</span></a> を参照してください。</p>
<div class="section" id="s-custom-libraries-and-template-inheritance">
<span id="custom-libraries-and-template-inheritance"></span><h3>カスタムライブラリとテンプレートの継承<a class="headerlink" href="#custom-libraries-and-template-inheritance" title="このヘッドラインへのパーマリンク">¶</a></h3>
<p>カスタムタグやフィルタライブラリをロードした場合、タグやフィルタは現在のテンプレートだけで利用でき、テンプレート継承パスにおける親テンプレートや子テンプレートでは利用できません。</p>
<p>たとえば <code class="docutils literal notranslate"><span class="pre">foo.html</span></code> に <code class="docutils literal notranslate"><span class="pre">{%</span> <span class="pre">load</span> <span class="pre">humanize</span> <span class="pre">%}</span></code> というタグが入っていても、子テンプレート ( <code class="docutils literal notranslate"><span class="pre">{%</span> <span class="pre">extends</span> <span class="pre">&quot;foo.html&quot;</span> <span class="pre">%}</span></code> を使っているテンプレート) で humanize という名前のテンプレートタグやフィルタを使えるわけではありません。子テンプレート側で対応するには独自に <code class="docutils literal notranslate"><span class="pre">{%</span> <span class="pre">load</span> <span class="pre">humanize</span> <span class="pre">%}</span></code> を入れる必要があります。</p>
<p>これはメンテナンス性と健全性を高めるための仕様です。</p>
<div class="admonition seealso">
<p class="first admonition-title">参考</p>
<dl class="last docutils">
<dt><a class="reference internal" href="index.html"><span class="doc">テンプレートのリファレンス</span></a></dt><dd>組み込みタグ、組み込みフィルタ、代替のテンプレート言語など多くをカバーしています。</dd>
</dl>
</div>
</div>
</div>
</div>


          </div>
        </div>
      </div>
      
        
          <div class="yui-b" id="sidebar">
            
      <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
        <div class="sphinxsidebarwrapper">
  <div>
    <h3><a href="../../contents.html">目次</a></h3>
    <ul>
<li><a class="reference internal" href="#">Django テンプレート言語</a><ul>
<li><a class="reference internal" href="#templates">テンプレート</a></li>
<li><a class="reference internal" href="#variables">変数</a></li>
<li><a class="reference internal" href="#filters">フィルタ</a></li>
<li><a class="reference internal" href="#tags">タグ</a></li>
<li><a class="reference internal" href="#comments">コメント</a></li>
<li><a class="reference internal" href="#template-inheritance">テンプレートの継承</a></li>
<li><a class="reference internal" href="#automatic-html-escaping">HTML の自動エスケープ</a><ul>
<li><a class="reference internal" href="#how-to-turn-it-off">自動エスケープをオフにする</a><ul>
<li><a class="reference internal" href="#for-individual-variables">変数単位での制御</a></li>
<li><a class="reference internal" href="#for-template-blocks">テンプレートブロック単位での制御</a></li>
</ul>
</li>
<li><a class="reference internal" href="#notes">備考</a></li>
<li><a class="reference internal" href="#string-literals-and-automatic-escaping">文字列リテラルと自動エスケープ</a></li>
</ul>
</li>
<li><a class="reference internal" href="#accessing-method-calls">メソッドへのアクセス</a></li>
<li><a class="reference internal" href="#custom-tag-and-filter-libraries">カスタムタグとカスタムフィルタのライブラリ</a><ul>
<li><a class="reference internal" href="#custom-libraries-and-template-inheritance">カスタムライブラリとテンプレートの継承</a></li>
</ul>
</li>
</ul>
</li>
</ul>

  </div>
  <div>
    <h4>前のトピックへ</h4>
    <p class="topless"><a href="index.html"
                          title="前の章へ">テンプレート</a></p>
  </div>
  <div>
    <h4>次のトピックへ</h4>
    <p class="topless"><a href="builtins.html"
                          title="次の章へ">組み込みテンプレートタグとフィルタ</a></p>
  </div>
  <div role="note" aria-label="source link">
    <h3>このページ</h3>
    <ul class="this-page-menu">
      <li><a href="../../_sources/ref/templates/language.txt"
            rel="nofollow">ソースコードを表示</a></li>
    </ul>
   </div>
<div id="searchbox" style="display: none" role="search">
  <h3 id="searchlabel">クイック検索</h3>
    <div class="searchformwrapper">
    <form class="search" action="../../search.html" method="get">
      <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
      <input type="submit" value="検索" />
    </form>
    </div>
</div>
<script>$('#searchbox').show(0);</script>
        </div>
      </div>
              <h3>Last update:</h3>
              <p class="topless">8月 06, 2024</p>
          </div>
        
      
    </div>

    <div id="ft">
      <div class="nav">
    &laquo; <a href="index.html" title="テンプレート">previous</a>
     |
    <a href="../index.html" title="API リファレンス" accesskey="U">up</a>
   |
    <a href="builtins.html" title="組み込みテンプレートタグとフィルタ">next</a> &raquo;</div>
    </div>
  </div>

      <div class="clearer"></div>
    </div>
  </body>
</html>