このドキュメントはDjangoテンプレートシステムの文法を説明しています。もしあなたがもっと技術者的な観点でどう動かすかやどう拡張するかを知りたい場合は、The Django template language: for Python programmers をご覧ください。
\nDjango のテンプレート言語は、パワーと使いやすさのバランスを取るように設計されています。HTMLでの作業に使用されるものが快適に感じられるように設計されているのです。あなたが他のテキストベースのテンプレート言語に対して Smarty や Jinja2 のような露出的な処理を習得しているのなら、Django テンプレートをより身近に感じられるはずです。
\n\nA template is a text file. It can generate any text-based format (HTML, XML,\nCSV, etc.).
\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, and may not\nbe a number. The dot (".") also appears in variable sections, although that\nhas a special meaning, as indicated below. Importantly, you cannot have spaces\nor punctuation 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 を定義することで子テンプレートにオーバーライドさせることができます。
\nLet's look at template inheritance by starting with an example:
\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>\nThis template, which we'll call base.html, defines an HTML skeleton\ndocument that you might use for a two-column page. It's the job of "child"\ntemplates to fill the empty blocks with content.
この例では、block タグにより、子テンプレートが埋めることができる 3 つのブロックが定義されています。block タグの仕事は、テンプレートのこれらの部分が子テンプレートによりオーバーライドされる可能性があることをテンプレートエンジンに伝えることです。
A child template might look like this:
\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" です。
At that point, the template engine will notice the three block tags\nin base.html and replace those blocks with the contents of the child\ntemplate. Depending on the value of blog_entries, the output might look\nlike:
<!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) します。
This approach maximizes code reuse and helps to add items to shared content\nareas, such as section-wide navigation.
\n継承を使用する際のコツをいくつか紹介します:
\nテンプレート内で {% extends %} を使用する際は、その点プレート内で一番最初のテンプレートタグとして指定する必要があります。それ以外の場合、継承が正しく動作しません。
ベースのテンプレートには {% block %} タグを多く配置するほどよいです。子テンプレートがすべてのブロックを埋める必要がないことを思い出してください。多くのブロック内に適当なデフォルトを記述しておき、必要なものを後で定義し直せばいいのです。フックは多ければ多いほどいいということです。
もし同じコンテンツを複数のテンプレート内で記述していたら、そのコンテンツを親テンプレートの {% block %} に移動させるべきかもしれません。
親テンプレートからブロックのコンテンツを取得する必要がある場合、{{ block.super }} が利用できます。親のブロックを完全にオーバーライドせずに、コンテンツを追加したい場合に有用です。{{ block.super }} を使って挿入されたデータは自動的にエスケープされません (next section を参照してください)。これは、必要な場合は親テンプレートですでにエスケープされているからです。
By using the same template name as you are inheriting from,\n{% extends %} can be used to inherit a template at the same\ntime as overriding it. Combined with {{ block.super }}, this can be a\npowerful way to make small customizations. See\nExtending an overridden template in the Overriding templates How-to\nfor a full example.
Variables created outside of a {% block %} using the template\ntag as syntax can't be used inside the block. For example, this template\ndoesn't render anything:
{% translate "Title" as title %}\n{% block content %}{{ title }}{% endblock %}\nFor extra readability, you can optionally give a name to your\n{% endblock %} tag. For example:
{% block content %}\n...\n{% endblock content %}\n大きなテンプレートでは、このテクニックでどの {% block %} が閉じられているのかが分かりやすくなります。
{% block %} tags are evaluated first. That's why the content\nof a block is always overridden, regardless of the truthiness of surrounding\ntags. For example, this template will always override the content of the\ntitle block:
{% if change_title %}\n {% block title %}Hello!{% endblock title %}\n{% endif %}\n最後に、同じテンプレート内で同じ名前の block タグを複数定義することはできないことに留意してください。この制限は、block タグが "両方向に" 働くのが理由です。block タグは埋めるための穴を提供するだけではなく -- 親テンプレート 内で穴を埋めるコンテンツを定義します。もし同名の block がテンプレート内に 2 つ存在すると、どちらのブロックのコンテンツを使うべきかテンプレートの親が判断できなくなってしまうのです。
When generating HTML from templates, there's always a risk that a variable will\ninclude characters that affect the resulting HTML. For example, consider this\ntemplate fragment:
\nHello, {{ name }}\nAt first, this seems like a harmless way to display a user's name, but consider\nwhat would happen if the user entered their name as this:
\n<script>alert('hello')</script>\nWith this name value, the template would be rendered as:
\nHello, <script>alert('hello')</script>\n……結果として、ブラウザに JavaScript の警告ボックスをポップアップさせることができてしまいます!
\n同様に、名前に '<' 文字が含まれていたらどうでしょうか:
<b>username\nThat would result in a rendered template like this:
\nHello, <b>username\n...which, in turn, would result in the remainder of the web page being in bold!
\nClearly, user-submitted data shouldn't be trusted blindly and inserted directly\ninto your web pages, because a malicious user could use this kind of hole to\ndo potentially bad things. This type of security exploit is called a\nCross Site Scripting (XSS) attack.
\nこの問題を防ぐために、二つの方法があります:
\n一つは、信頼できない変数は必ず escape フィルタ (後で述べます) に通すことです。このフィルタは危害を及ぼす可能性をもつ HTML 文字を無害な文字に変換します。 この方法は初期の数年間において Django のデフォルトとして採用されていました。しかしユーザー、すなわち開発者やテンプレートの作者にとっては、すべてのデータをエスケープすることを忘れぬよう注意しなければならないという負担になるのが問題です。
もう一つは、 Django の自動 HTML エスケープを使うというものです。この節の後半では自動エスケープの仕組みについて述べます。
デフォルトでは、Django はすべてのテンプレートの変数タグの出力を自動的にエスケープするよう設定されています。具体的には、以下の 5 つの文字がエスケープされます:
\n< を < に変換
> を > に変換
' (single quote) is converted to '
" ( ダブルクォート ) を " に変換
& を & に変換
この動作は、デフォルトで適用されていることを重ねて強調しておきます。Django テンプレートシステムを使っているかぎり、あなたはエスケープに関する問題からは守られているのです。
\nサイト単位やテンプレート単位、あるいは変数単位でデータの自動エスケープ機能を無効にしたい場合には、いくつかの方法があります。
\nどんなときに、自動エスケープをオフにする必要があるでしょうか。テンプレート変数の中身は、生の HTML として出力するように意図されたデータかもしれません。そうした場合にはコンテンツがエスケープされてほしくはないでしょう。例えば、データベースに HTML を保存していてテンプレートに直接埋め込みたい場合を考えてみましょう。また、 Django のテンプレートシステムを使って、 HTML 以外 のデータ、例えば電子メールメッセージなどを生成したい場合もあるでしょう。
\nTo disable auto-escaping for an individual variable, use the safe\nfilter:
This will be escaped: {{ data }}\nThis will not be escaped: {{ data|safe }}\nThink of safe as shorthand for safe from further escaping or can be\nsafely interpreted as HTML. In this example, if data contains '<b>',\nthe output will be:
This will be escaped: <b>\nThis will not be escaped: <b>\nTo control auto-escaping for a template, wrap the template (or a particular\nsection of the template) in the autoescape tag, like so:
{% autoescape off %}\n Hello {{ name }}\n{% endautoescape %}\nThe autoescape tag takes either on or off as its argument. At\ntimes, you might want to force auto-escaping when it would otherwise be\ndisabled. Here is an example template:
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自動エスケープのタグは、他のブロックタグと同様、タグを設定したテンプレートを継承している他のテンプレートや、 include で取り込んだテンプレートでも有効です。例えば:
base.html{% autoescape off %}\n<h1>{% block title %}{% endblock %}</h1>\n{% block content %}\n{% endblock %}\n{% endautoescape %}\nchild.html{% extends "base.html" %}\n{% block title %}This & that{% endblock %}\n{% block content %}{{ greeting }}{% endblock %}\nBecause auto-escaping is turned off in the base template, it will also be\nturned off in the child template, resulting in the following rendered\nHTML when the greeting variable contains the string <b>Hello!</b>:
<h1>This & that</h1>\n<b>Hello!</b>\n一般に、テンプレートの作者は自動エスケープをあまり意識する必要はありません。 データをエスケープすべきではない場合を考えたり、データを適切にマークし、テンプレート上でうまく表示されるように考慮するのは、Python 側の開発者 (ビューやカスタムフィルタの開発者)であるべきです。
\nもしあなたが作成しているテンプレートがどういった状況で使われるのか分からず、自動エスケープが有効かどうかはっきりしない場合には、エスケープの必要な変数全てに escape フィルタを追加してください。自動エスケープがオンの場合、 escape フィルタがデータ を二重にエスケープするような危険性はありません。 escape フィルタは自動エスケープされた変数には影響しなません。
As we mentioned earlier, filter arguments can be strings:
\n{{ data|default:"This is a string literal." }}\n文字列リテラルは、すべて自動エスケープ**されずに**テンプレート内に挿入され、 safe フィルタを通して渡されたかのように振る舞います。なぜならば、テンプレートの作者はその文字列リテラルに何が書かれているかは把握していますし、テンプレートが書かれる時点でテキストが正しくエスケープされていることは確認できるからです。
This means you would write :
\n{{ data|default:"3 < 2" }}\n...rather than:
\n{{ data|default:"3 < 2" }} {# Bad! Don't do this. #}\nこの事が、変数自身に由来するデータに対して何かを引き起こす恐れはありません。 変数の内容はテンプレート作者の管理外にあり、必要に応じて自動的にエスケープされます。
\nMost method calls attached to objects are also available from within templates.\nThis means that templates have access to much more than just class attributes\n(like field names) and variables passed in from views. For example, the Django\nORM provides the "entry_set" syntax for\nfinding a collection of objects related on a foreign key. Therefore, given\na model called "comment" with a foreign key relationship to a model called\n"task" you can loop through all comments attached to a given task like this:
\n{% for comment in task.comment_set.all %}\n {{ comment }}\n{% endfor %}\nSimilarly, QuerySets provide a count() method\nto count the number of objects they contain. Therefore, you can obtain a count\nof all comments related to the current task with:
{{ task.comment_set.all.count }}\nYou can also access methods you've explicitly defined on your own models:
\nmodels.pyclass Task(models.Model):\n def foo(self):\n return "bar"\ntemplate.html{{ task.foo }}\nDjango ではテンプレート内でのプログラム的な処理を意図的に制限しているため、テンプレートからメソッドに引数を渡すことはできません。データはビューの中で計算され、テンプレートへは表示のためだけに渡されるべきだからです。
\nCertain applications provide custom tag and filter libraries. To access them in\na template, ensure the application is in INSTALLED_APPS (we'd add\n'django.contrib.humanize' for this example), and then use the load\ntag in a template:
{% load humanize %}\n\n{{ 45000|intcomma }}\nこの例では、 load タグは humanize という名前のタグライブラリを読み込み、 intcomma フィルタを使えるようにしています。 django.contrib.admindocs が有効にされている場合、あなたの admin は現在インストールされているアプリケーションのドキュメント文字列を参照してカスタムライブラリの一覧を得ることができます。
The load tag can take multiple library names, separated by spaces.\nExample:
{% load humanize i18n %}\nカスタムのテンプレートライブラリを作成する方法については、 独自のテンプレートタグとフィルタを作る を参照してください。
\nカスタムタグやフィルタライブラリをロードした場合、タグやフィルタは現在のテンプレートだけで利用でき、テンプレート継承パスにおける親テンプレートや子テンプレートでは利用できません。
\n例えば foo.html に {% load humanize %} というタグが入っていても、子テンプレート ( {% extends "foo.html" %} を使っているテンプレート) で humanize という名前のテンプレートタグやフィルタを使えるわけではありません。子テンプレート側で対応するには独自に {% load humanize %} を入れる必要があります。
これはメンテナンス性と健全性を高めるための仕様です。
\n\n