フォームレンダリング 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

New in Django 5.0.

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

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

get_template(template_name)[ソース]

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

render(template_name, context, request=None)[ソース]

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

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

DjangoTemplates

class DjangoTemplates[ソース]

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

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

class DjangoDivFormRenderer

Deprecated since version 5.0.

DjangoTemplates のエイリアス。

Jinja2

class Jinja2[ソース]

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

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

class Jinja2DivFormRenderer

Deprecated since version 5.0.

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: フォームの非フィールド関連または非表示フィールド関連の全エラー。

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

New in Django 5.0.

フィールドテンプレートは、 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 レンダラーを使用する必要があります。その後、フォームテンプレートのオーバーライドは、プロジェクト内の他のテンプレートをオーバーライドする場合と 同様に機能します。

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

New in Django 5.0.

Field.template_name

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

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

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

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