# Django 5.2.8 ドキュメント

# フォームレンダリング API

Djangoのフォームウィジェットは、Djangoの テンプレートエンジンシステム を使用してレンダリングされます。

フォームのレンダリングプロセスは、いくつかのレベルでカスタマイズできます:

- ウィジェットはカスタムテンプレート名を指定できます。

- フォームとウィジェットは、カスタムレンダラークラスを指定できます。

- ウィジェットのテンプレートはプロジェクトによって上書きできます。(再利用可能なアプリケーションは通常、組込みテンプレートを上書きすべきではありません。なぜなら、それがプロジェクトのカスタムテンプレートと競合する可能性があるからです。)

## 低レベルのレンダリングAPI

フォームテンプレートのレンダリングは、カスタマイズ可能なレンダラークラスによって制御されます。カスタムレンダラーは、`FORM_RENDERER` 設定を更新することによって指定できます。デフォルトでは `'``django.forms.renderers.DjangoTemplates``'` になっています。

カスタムフォームレンダラーを指定し、`form_template_name` をオーバーライドすることで、プロジェクト全体のデフォルトフォームマークアップを一か所から調整できます。

`Form.default_renderer` 属性を設定するか、または `Form.render()` や `Widget.render()` のメソッドの `renderer` 引数を使用することで、フォームごとやウィジェットごとにカスタムレンダラーを提供することもできます。

マッチングポイントは、formset のレンダリングに適用されます。詳細は、ビューとテンプレートでフォームセットを使う を参照してください。

組み込みのテンプレートフォームレンダラ のいずれかを使用するか、独自のものを実装してください。カスタムレンダラは、`render(template_name, context, request=None)` メソッドを実装する必要があります。レンダリングされたテンプレート(文字列として)を返すか、 `TemplateDoesNotExist` を発生させるべきです。

class BaseRenderer

  組み込みフォームレンダラーの基底クラスです。

  form_template_name

    フォームをレンダリングするために使用するテンプレートのデフォルト名です。

    デフォルトは `"django/forms/div.html"` テンプレートです。

  formset_template_name

    フォームセットをレンダリングするために使用するテンプレートのデフォルト名。

    デフォルトは `"django/forms/formsets/div.html"` テンプレートです。

  field_template_name

    `BoundField` をレンダリングするために使用されるテンプレートのデフォルト名。

    デフォルトは `"django/forms/field.html"` です。

  bound_field_class
    New in Django 5.2.

    プロジェクト全体でフォームフィールドを表現するために使用されるデフォルトのクラスです。

    `BoundField` クラスのデフォルト。

    このデフォルトクラスは、フォームごとに `Form.bound_field_class` を、フィールドごとに `Field.bound_field_class` を指定することで、さらにカスタマイズできます。

  get_template(template_name)

    サブクラスは、適切なテンプレート検索ロジックを持つようにこのメソッドを実装しなければなりません。

  render(template_name, context, request=None)

    指定されたテンプレートをレンダリングします。存在しない場合は、 `TemplateDoesNotExist` を発生させます。

## 組み込みのテンプレートフォームレンダラー

### `DjangoTemplates`

class DjangoTemplates

このレンダラーは、 (`TEMPLATES` 設定で構成されているものとは接続されていない) 独立した `DjangoTemplates` エンジンを使用しています。まず django/forms/templates にある組み込みのフォームテンプレートディレクトリからテンプレートを読み込み、次に `app_directories` ローダーを使用してインストール済みアプリのテンプレートディレクトリから読み込みます。

カスタマイズを施した `TEMPLATES` 設定からテンプレートをレンダリングしたい場合、例えばコンテキストプロセッサなどを使用するには、`TemplatesSetting` レンダラーを使用してください。

### `Jinja2`

class Jinja2

このレンダラーは `DjangoTemplates` レンダラーと同じですが、`Jinja2` バックエンドを使用します。組み込みウィジェットのテンプレートは django/forms/jinja2 にあり、インストールされたアプリは `jinja2` ディレクトリ内にテンプレートを提供できます。

このバックエンドを使用するには、プロジェクトとそのサードパーティアプリのすべてのフォームとウィジェットにJinja2のテンプレートがなければなりません。ウィジェットにJinja2のテンプレートがない場合、自分で提供しない限り、このレンダラーを使用することはできません。例えば、 `django.contrib.admin` は、Djangoのテンプレートタグを使用しているため、そのウィジェットにJinja2テンプレートを含んでいません。

### `TemplatesSetting`

class TemplatesSetting

このレンダラーは、フォームとウィジェットのテンプレートの取得方法を完全に制御できます。これは、 `get_template()` を使用して、 `TEMPLATES` 設定で構成されている内容に基づいてテンプレートを見つけます。

このレンダラーを組み込みテンプレートと一緒に使用するには, 次のいずれかが必要です:

- `INSTALLED_APPS` に `'django.forms'` が含まれていて、少なくとも一つのエンジンが `APP_DIRS=True` に設定されている必要があります。

- テンプレートエンジンの `DIRS` に組み込みテンプレートディレクトリを追加します。そのパスを生成するには次のようにします:

      import django

      django.__path__[0] + "/forms/templates"  # or '/forms/jinja2'

このレンダラーを使用するには、プロジェクトが必要とするフォームテンプレートが見つかるようにする必要があります。

## フォームセットテンプレートで利用可能なコンテキスト

フォームセットテンプレートは、 `BaseFormSet.get_context()` からコンテキストを受け取ります。デフォルトでは、フォームセットは以下の値を含む辞書を受け取ります:

- `formset`: フォームセットのインスタンス。

## フォームテンプレートで利用可能なコンテキスト

フォームテンプレートは、 `Form.get_context()` からコンテキストを受け取ります。デフォルトでは、フォームは次の値を持つ辞書を受け取ります。

- `form`: バインドされたフォーム。

- `fields`: 隠されたフィールドを除く、すべてのバインドされたフィールド。

- `hidden_fields`: すべての隠されたバインドフィールド。

- `errors`: フォームの非フィールド関連または非表示フィールド関連の全エラー。

## フィールドテンプレートで利用可能なコンテキスト

フィールドテンプレートは、 `BoundField.get_context()` からコンテキストを受け取ります。デフォルトでは、フィールドは以下の値を含む辞書を受け取ります:

- `field`: `BoundField` 。

## ウィジェットテンプレートで利用可能なコンテキスト

Widgetテンプレートは `Widget.get_context()` からコンテキストを受け取ります。デフォルトでは、ウィジェットはコンテキスト内で単一の値、 `widget` を受け取ります。これは次のような値を含む辞書です:

- `name`

- `value`

- `attrs`

- `is_hidden`

- `template_name`

一部のウィジェットは、コンテキストにさらなる情報を追加します。例えば、`Input` のサブクラスであるすべてのウィジェットは `widget['type']` を定義し、`MultiWidget` はループ目的のために `widget['subwidgets']` を定義します。

## 組み込みのフォームセットテンプレートをオーバーライドする

`BaseFormSet.template_name`

フォームセットテンプレートをオーバーライドするには、`TemplatesSetting` レンダラーを使用する必要があります。そうすると、フォームセットテンプレートのオーバーライドは、プロジェクト内の他のテンプレートをオーバーライドするのと 同じように行うことができます 。

## 組み込みのフォームテンプレートをオーバーライドする

`Form.template_name`

フォームテンプレートをオーバーライドするには、`TemplatesSetting` レンダラーを使用する必要があります。その後、フォームテンプレートのオーバーライドは、プロジェクト内の他のテンプレートをオーバーライドする場合と 同様に機能します。

## 組み込みのフィールドテンプレートをオーバーライドする

`Field.template_name`

フィールドテンプレートを上書きするには、 `TemplatesSetting` レンダラーを使用する必要があります。それから、フィールドテンプレートのオーバーライドは、プロジェクト内の他のテンプレートのオーバーライドと 同じ方法 で機能します。

## 組み込みのウィジェットテンプレートをオーバーライドする

各ウィジェットは、`input.html` のような値を持つ `template_name` 属性を持っています。組み込みウィジェットテンプレートは、 `django/forms/widgets` パスに格納されています。例えば、 `django/forms/widgets/input.html` を定義することで、 `input.html` のカスタムテンプレートを提供できます。各ウィジェットのテンプレートの名前については、 ビルトインのウィジェット を参照してください。

ウィジェットテンプレートをオーバーライドするには、 `TemplatesSetting` レンダラを使用する必要があります。その後、ウィジェットテンプレートのオーバーライドは、プロジェクト内の他のテンプレートをオーバーライドするのと 同じ方法で機能 します。