# Django 4.1.8.dev20230308103347 ドキュメント

# テンプレート

Django はウェブフレームワークなので、HTML を動的に生成する便利な手段が必要でした。最も一般的なアプローチは、テンプレートに頼ることです。テンプレートには、出力したい HTML を書いた静的な部分と、動的なコンテンツを挿入する方法を書いた特別な構文の部分からなります。テンプレートを使って HTML ページを作るハンズオンの例については、チュートリアル 3 を見てください。

A Django project can be configured with one or several template engines (or even zero if you don't use templates). Django ships built-in backends for its own template system, creatively called the Django template language (DTL), and for the popular alternative Jinja2. Backends for other template languages may be available from third-parties. You can also write your own custom backend, see Custom template backend

Django は、バックエンドにかかわらず使用できる、テンプレートの読み込みとレンダリングのための標準の API を定義しています。読み込みのパートでは、指定された名前からテンプレートを探し、テンプレートを前処理し、通常はメモリ上のデータに変換します。レンダリングのパートでは、テンプレートの中にコンテキストデータを埋め込み、最終的な文字列を返します。

Django template language はDjango 用のテンプレートシステムです。Django 1.8 までは、ビルトインのオプションしか選択できませんでした。小さな癖もありますが、とても良いテンプレートライブラリです。他のバックエンドを無理して選択しなければならない特別な理由がない限り、DTL を使用することをおすすめします。アプリケーションを書いてテンプレートを配布しようと考えている場合は、特にそうです。たとえば、Django のテンプレートを含んでいる django.contrib.admin のような contrib アプリは、DTL を使用しています。

歴史的な理由により、テンプレートエンジンの一般的なサポートと Django テンプレート言語の実装は、両方とも `django.template` 名前空間に定義されています。

警告

テンプレートシステムは、信頼できないテンプレートの作者に対しては安全ではありません。たとえば、サイトではユーザー自身がテンプレートを送信できるようにしてはなりません。テンプレートの作者は XSS 攻撃と同様のことが可能になり、テンプレート変数の属性にアクセスして、秘密にしなければならない情報にアクセスできてしまう可能性があるからです。

## Django テンプレート言語

### 構文

このセクションについて

このセクションで紹介するのは、Django テンプレート言語の構文の概要です。詳細については、 language syntax reference をご覧ください。

A Django template is a text document or a Python string marked-up using the Django template language. Some constructs are recognized and interpreted by the template engine. The main ones are variables and tags.

テンプレートは、コンテキストともにレンダリングされます。レンダリングでは、変数が見つかると、コンテキスト内に記録された変数の値に置換され、タグが実行されます。それ以外の文字列は、そのまま出力されます。

Django テンプレート言語の構文は、4つの構成要素に分類できます。

#### 変数

A variable outputs a value from the context, which is a dict-like object mapping keys to values.

Variables are surrounded by `{{` and `}}` like this:

    My first name is {{ first_name }}. My last name is {{ last_name }}.

With a context of `{'first_name': 'John', 'last_name': 'Doe'}`, this template renders to:

    My first name is John. My last name is Doe.

Dictionary lookup, attribute lookup and list-index lookups are implemented with a dot notation:

    {{ my_dict.key }}
    {{ my_object.attribute }}
    {{ my_list.0 }}

If a variable resolves to a callable, the template system will call it with no arguments and use its result instead of the callable.

#### タグ

Tags provide arbitrary logic in the rendering process.

This definition is deliberately vague. For example, a tag can output content, serve as a control structure e.g. an "if" statement or a "for" loop, grab content from a database, or even enable access to other template tags.

Tags are surrounded by `{%` and `%}` like this:

    {% csrf_token %}

Most tags accept arguments:

    {% cycle 'odd' 'even' %}

Some tags require beginning and ending tags:

    {% if user.is_authenticated %}Hello, {{ user.username }}.{% endif %}

A reference of built-in tags is available as well as instructions for writing custom tags.

#### フィルタ

Filters transform the values of variables and tag arguments.

They look like this:

    {{ django|title }}

With a context of `{'django': 'the web framework for perfectionists with deadlines'}`, this template renders to:

    The Web Framework For Perfectionists With Deadlines

Some filters take an argument:

    {{ my_date|date:"Y-m-d" }}

A reference of built-in filters is available as well as instructions for writing custom filters.

#### コメント

Comments look like this:

    {# this won't be rendered #}

A `{% comment %}` tag provides multi-line comments.

### コンポーネント

このセクションについて

このセクションで紹介するのは、Django テンプレート言語の API の概要です。詳細については、API reference をご覧ください。

#### エンジン

`django.template.Engine` encapsulates an instance of the Django template system. The main reason for instantiating an `Engine` directly is to use the Django template language outside of a Django project.

`django.template.backends.django.DjangoTemplates` is a thin wrapper adapting `django.template.Engine` to Django's template backend API.

#### テンプレート

`django.template.Template` represents a compiled template. Templates are obtained with `Engine.get_template()` or `Engine.from_string()`.

Likewise `django.template.backends.django.Template` is a thin wrapper adapting `django.template.Template` to the common template API.

#### コンテキスト

`django.template.Context` holds some metadata in addition to the context data. It is passed to `Template.render()` for rendering a template.

`django.template.RequestContext` is a subclass of `Context` that stores the current `HttpRequest` and runs template context processors.

The common API doesn't have an equivalent concept. Context data is passed in a plain `dict` and the current `HttpRequest` is passed separately if needed.

#### ローダー

テンプレートローダーが責任を持つのは、テンプレートの検索、テンプレートの読み込み、`Template` オブジェクトを返すことです。

Django はいくつかの ビルトインのテンプレートローダー を提供していて、 custom template loaders をサポートしています。

#### コンテキストプロセッサ

コンテキストプロセッサは、現在の `HttpRequest` を引数としておけとり、データの `dict` をレンダリングコンテキストに追加して返します。

Their main use is to add common data shared by all templates to the context without repeating code in every view.

Django provides many built-in context processors, and you can implement your own additional context processors, too.

## テンプレートエンジンのサポート

### 設定

テンプレートエンジンは、`TEMPLATES` で設定できます。ここには、各エンジンに対する設定のリストを設定します。デフォルト値は空リストです。`startproject` コマンドで生成された `settings.py` には、以下のように便利な値がいくつか設定されます。

    TEMPLATES = [
        {
            'BACKEND': 'django.template.backends.django.DjangoTemplates',
            'DIRS': [],
            'APP_DIRS': True,
            'OPTIONS': {
                # ... some options here ...
            },
        },
    ]

`BACKEND` は、Django テンプレートバックエンド API を実装したテンプレートエンジンのクラスへの、ドット区切りの Python path です。ビルトインのバックエンドは、`django.template.backends.django.DjangoTemplates` と `django.template.backends.jinja2.Jinja2` です。

ほとんどのエンジンはファイルからテンプレートを読み込むため、各エンジンのトップレベルの設定には次の2つの設定があります。

- `DIRS` には、エンジンがテンプレートのソースファイルを検索するディレクトリのリストを、検索順に定義します。
- `APP_DIRS` には、エンジンがインストールしたアプリケーション内のテンプレートを検索するべきかどうかを指定します。各バックエンドは、アプリケーション内でテンプレートを保存するべきサブディレクトリ名として、慣習的な名前を定義しています。

めったにないことですが、同じバックエンドの複数のインスタンスを、オプションだけ変えて設定することも可能です。その場合、各エンジンに対して、`NAME` にユニークな名前を設定しなければなりません。

`OPTIONS` には、バックエンド特有の設定を書きます。

### 使い方

`django.template.loader` モジュールは、テンプレートを読み込むための2つの関数を定義しています。

`get_template`(template_name, using=None)

  この関数は、指定した名前のテンプレートを読み込み、`Template` オブジェクトを返します。

  The exact type of the return value depends on the backend that loaded the template. Each backend has its own `Template` class.

  `get_template()` tries each template engine in order until one succeeds. If the template cannot be found, it raises `TemplateDoesNotExist`. If the template is found but contains invalid syntax, it raises `TemplateSyntaxError`.

  How templates are searched and loaded depends on each engine's backend and configuration.

  If you want to restrict the search to a particular template engine, pass the engine's `NAME` in the `using` argument.

`select_template`(template_name_list, using=None)

  `select_template()` は `get_template()` に似ていますが、1つのテンプレート名の代わりにテンプレート名のリストを取ります。各名前のテンプレートを順番に探し、最初に見つかったテンプレートを返します。

If loading a template fails, the following two exceptions, defined in `django.template`, may be raised:

exception `TemplateDoesNotExist`(msg, tried=None, backend=None, chain=None)

  This exception is raised when a template cannot be found. It accepts the following optional arguments for populating the template postmortem on the debug page:

  `backend`
    The template backend instance from which the exception originated.
  `tried`
    A list of sources that were tried when finding the template. This is formatted as a list of tuples containing `(origin, status)`, where `origin` is an origin-like object and `status` is a string with the reason the template wasn't found.
  `chain`
    A list of intermediate `TemplateDoesNotExist` exceptions raised when trying to load a template. This is used by functions, such as `get_template()`, that try to load a given template from multiple engines.

exception `TemplateSyntaxError`(msg)

  This exception is raised when a template was found but contains errors.

`Template` objects returned by `get_template()` and `select_template()` must provide a `render()` method with the following signature:

`Template.``render`(context=None, request=None)

  与えられたコンテキストを用いて、このテンプレートをレンダリングします。

  `context` を指定する場合は、`dict` でなければなりません。もし指定しなければ、エンジンは空のコンテキストでレンダリングします。

  `request` を指定する場合は、`HttpRequest` でなければなりません。テンプレートエンジンは、テンプレート内では、このインスタンスと CSRF トークンを使用できるようにする必要があります。そのための実装はバックエンドに依存します。

以下に、検索アルゴリズムの例を示します。この例の場合、`TEMPLATES` 設定は次のようになっています。

    TEMPLATES = [
        {
            'BACKEND': 'django.template.backends.django.DjangoTemplates',
            'DIRS': [
                '/home/html/example.com',
                '/home/html/default',
            ],
        },
        {
            'BACKEND': 'django.template.backends.jinja2.Jinja2',
            'DIRS': [
                '/home/html/jinja2',
            ],
        },
    ]

`get_template('story_detail.html')` を呼び出した場合、Django は次の順番にファイルを探します。

- `/home/html/example.com/story_detail.html` (`'django'` エンジン)
- `/home/html/default/story_detail.html` (`'django'` エンジン)
- `/home/html/jinja2/story_detail.html` (`'jinja2'` エンジン)

`select_template(['story_253_detail.html', 'story_detail.html'])` を呼び出した場合、Djangoは以下の順番にファイルを探します。

- `/home/html/example.com/story_253_detail.html` (`'django'` エンジン)
- `/home/html/default/story_253_detail.html` (`'django'` エンジン)
- `/home/html/jinja2/story_253_detail.html` (`'jinja2'` エンジン)
- `/home/html/example.com/story_detail.html` (`'django'` エンジン)
- `/home/html/default/story_detail.html` (`'django'` エンジン)
- `/home/html/jinja2/story_detail.html` (`'jinja2'` エンジン)

Django がテンプレートを発見したら、その時点で探索は停止します。

ヒント

You can use `select_template()` for flexible template loading. For example, if you've written a news story and want some stories to have custom templates, use something like `select_template(['story_%s_detail.html' % story.id, 'story_detail.html'])`. That'll allow you to use a custom template for an individual story, with a fallback template for stories that don't have custom templates.

It's possible -- and preferable -- to organize templates in subdirectories inside each directory containing templates. The convention is to make a subdirectory for each Django app, with subdirectories within those subdirectories as needed.

Do this for your own sanity. Storing all templates in the root level of a single directory gets messy.

To load a template that's within a subdirectory, use a slash, like so:

    get_template('news/story_detail.html')

Using the same `TEMPLATES` option as above, this will attempt to load the following templates:

- `/home/html/example.com/news/story_detail.html` (`'django'` engine)
- `/home/html/default/news/story_detail.html` (`'django'` engine)
- `/home/html/jinja2/news/story_detail.html` (`'jinja2'` engine)

In addition, to cut down on the repetitive nature of loading and rendering templates, Django provides a shortcut function which automates the process.

`render_to_string`(template_name, context=None, request=None, using=None)

  `render_to_string()` loads a template like `get_template()` and calls its `render()` method immediately. It takes the following arguments.

  `template_name`
    The name of the template to load and render. If it's a list of template names, Django uses `select_template()` instead of `get_template()` to find the template.
  `context`
    A `dict` to be used as the template's context for rendering.
  `request`
    An optional `HttpRequest` that will be available during the template's rendering process.
  `using`
    An optional template engine `NAME`. The search for the template will be restricted to that engine.

  Usage example:

      from django.template.loader import render_to_string
      rendered = render_to_string('my_template.html', {'foo': 'bar'})

See also the `render()` shortcut which calls `render_to_string()` and feeds the result into an `HttpResponse` suitable for returning from a view.

Finally, you can use configured engines directly:

`engines`

  Template engines are available in `django.template.engines`:

      from django.template import engines

      django_engine = engines['django']
      template = django_engine.from_string("Hello {{ name }}!")

  The lookup key — `'django'` in this example — is the engine's `NAME`.

### Built-in backends

class `DjangoTemplates`

Set `BACKEND` to `'django.template.backends.django.DjangoTemplates'` to configure a Django template engine.

When `APP_DIRS` is `True`, `DjangoTemplates` engines look for templates in the `templates` subdirectory of installed applications. This generic name was kept for backwards-compatibility.

`DjangoTemplates` engines accept the following `OPTIONS`:

- `'autoescape'`: a boolean that controls whether HTML autoescaping is enabled.

  It defaults to `True`.

  警告

  Only set it to `False` if you're rendering non-HTML templates!

- `'context_processors'`: a list of dotted Python paths to callables that are used to populate the context when a template is rendered with a request. These callables take a request object as their argument and return a `dict` of items to be merged into the context.

  It defaults to an empty list.

  See `RequestContext` for more information.

- `'debug'`: a boolean that turns on/off template debug mode. If it is `True`, the fancy error page will display a detailed report for any exception raised during template rendering. This report contains the relevant snippet of the template with the appropriate line highlighted.

  It defaults to the value of the `DEBUG` setting.

- `'loaders'`: a list of dotted Python paths to template loader classes. Each `Loader` class knows how to import templates from a particular source. Optionally, a tuple can be used instead of a string. The first item in the tuple should be the `Loader` class name, and subsequent items are passed to the `Loader` during initialization.

  The default depends on the values of `DIRS` and `APP_DIRS`.

  See Loader types for details.

- `'string_if_invalid'`: the output, as a string, that the template system should use for invalid (e.g. misspelled) variables.

  It defaults to an empty string.

  See How invalid variables are handled for details.

- `'file_charset'`: the charset used to read template files on disk.

  It defaults to `'utf-8'`.

- `'libraries'`: A dictionary of labels and dotted Python paths of template tag modules to register with the template engine. This can be used to add new libraries or provide alternate labels for existing ones. For example:

      OPTIONS={
          'libraries': {
              'myapp_tags': 'path.to.myapp.tags',
              'admin.urls': 'django.contrib.admin.templatetags.admin_urls',
          },
      }

  Libraries can be loaded by passing the corresponding dictionary key to the `{% load %}` tag.

- `'builtins'`: A list of dotted Python paths of template tag modules to add to built-ins. For example:

      OPTIONS={
          'builtins': ['myapp.builtins'],
      }

  Tags and filters from built-in libraries can be used without first calling the `{% load %}` tag.

class `Jinja2`

Requires Jinja2 to be installed:

/ 

    $ python -m pip install Jinja2

    ...\> py -m pip install Jinja2

Set `BACKEND` to `'django.template.backends.jinja2.Jinja2'` to configure a Jinja2 engine.

When `APP_DIRS` is `True`, `Jinja2` engines look for templates in the `jinja2` subdirectory of installed applications.

The most important entry in `OPTIONS` is `'environment'`. It's a dotted Python path to a callable returning a Jinja2 environment. It defaults to `'jinja2.Environment'`. Django invokes that callable and passes other options as keyword arguments. Furthermore, Django adds defaults that differ from Jinja2's for a few options:

- `'autoescape'`: `True`
- `'loader'`: a loader configured for `DIRS` and `APP_DIRS`
- `'auto_reload'`: `settings.DEBUG`
- `'undefined'`: `DebugUndefined if settings.DEBUG else Undefined`

`Jinja2` engines also accept the following `OPTIONS`:

- `'context_processors'`: a list of dotted Python paths to callables that are used to populate the context when a template is rendered with a request. These callables take a request object as their argument and return a `dict` of items to be merged into the context.

  It defaults to an empty list.

  Using context processors with Jinja2 templates is discouraged.

  Context processors are useful with Django templates because Django templates don't support calling functions with arguments. Since Jinja2 doesn't have that limitation, it's recommended to put the function that you would use as a context processor in the global variables available to the template using `jinja2.Environment` as described below. You can then call that function in the template:

      {{ function(request) }}

  Some Django templates context processors return a fixed value. For Jinja2 templates, this layer of indirection isn't necessary since you can add constants directly in `jinja2.Environment`.

  The original use case for adding context processors for Jinja2 involved:

  - Making an expensive computation that depends on the request.
  - Needing the result in every template.
  - Using the result multiple times in each template.

  Unless all of these conditions are met, passing a function to the template is more in line with the design of Jinja2.

The default configuration is purposefully kept to a minimum. If a template is rendered with a request (e.g. when using `render()`), the `Jinja2` backend adds the globals `request`, `csrf_input`, and `csrf_token` to the context. Apart from that, this backend doesn't create a Django-flavored environment. It doesn't know about Django filters and tags. In order to use Django-specific APIs, you must configure them into the environment.

For example, you can create `myproject/jinja2.py` with this content:

    from django.templatetags.static import static
    from django.urls import reverse

    from jinja2 import Environment

    def environment(**options):
        env = Environment(**options)
        env.globals.update({
            'static': static,
            'url': reverse,
        })
        return env

and set the `'environment'` option to `'myproject.jinja2.environment'`.

Then you could use the following constructs in Jinja2 templates:

    <img src="{{ static('path/to/company-logo.png') }}" alt="Company Logo">

    <a href="{{ url('admin:index') }}">Administration</a>

The concepts of tags and filters exist both in the Django template language and in Jinja2 but they're used differently. Since Jinja2 supports passing arguments to callables in templates, many features that require a template tag or filter in Django templates can be achieved by calling a function in Jinja2 templates, as shown in the example above. Jinja2's global namespace removes the need for template context processors. The Django template language doesn't have an equivalent of Jinja2 tests.