フォームレンダリング 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¶
バージョン 5.0 で非推奨.
DjangoTemplates のエイリアス。
Jinja2¶
-
class
Jinja2¶
このレンダラーは DjangoTemplates レンダラーと同じですが、Jinja2 バックエンドを使用します。組み込みウィジェットのテンプレートは django/forms/jinja2 にあり、インストールされたアプリは jinja2 ディレクトリ内にテンプレートを提供できます。
このバックエンドを使用するには、プロジェクトとそのサードパーティアプリのすべてのフォームとウィジェットにJinja2のテンプレートがなければなりません。ウィジェットにJinja2のテンプレートがない場合、自分で提供しない限り、このレンダラーを使用することはできません。例えば、 django.contrib.admin は、Djangoのテンプレートタグを使用しているため、そのウィジェットにJinja2テンプレートを含んでいません。
-
class
Jinja2DivFormRenderer¶
バージョン 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: フォームの非フィールド関連または非表示フィールド関連の全エラー。
フィールドテンプレートで利用可能なコンテキスト¶
フィールドテンプレートは、 BoundField.get_context() からコンテキストを受け取ります。デフォルトでは、フィールドは以下の値を含む辞書を受け取ります:
field:BoundField。
ウィジェットテンプレートで利用可能なコンテキスト¶
Widgetテンプレートは Widget.get_context() からコンテキストを受け取ります。デフォルトでは、ウィジェットはコンテキスト内で単一の値、 widget を受け取ります。これは次のような値を含む辞書です:
namevalueattrsis_hiddentemplate_name
一部のウィジェットは、コンテキストにさらなる情報を追加します。例えば、Input のサブクラスであるすべてのウィジェットは widget['type'] を定義し、MultiWidget はループ目的のために widget['subwidgets'] を定義します。
組み込みのフォームセットテンプレートをオーバーライドする¶
フォームセットテンプレートをオーバーライドするには、TemplatesSetting レンダラーを使用する必要があります。そうすると、フォームセットテンプレートのオーバーライドは、プロジェクト内の他のテンプレートをオーバーライドするのと 同じように行うことができます 。
組み込みのフォームテンプレートをオーバーライドする¶
フォームテンプレートをオーバーライドするには、TemplatesSetting レンダラーを使用する必要があります。その後、フォームテンプレートのオーバーライドは、プロジェクト内の他のテンプレートをオーバーライドする場合と 同様に機能します。
組み込みのフィールドテンプレートをオーバーライドする¶
フィールドテンプレートを上書きするには、 TemplatesSetting レンダラーを使用する必要があります。それから、フィールドテンプレートのオーバーライドは、プロジェクト内の他のテンプレートのオーバーライドと 同じ方法 で機能します。
組み込みのウィジェットテンプレートをオーバーライドする¶
各ウィジェットは、input.html のような値を持つ template_name 属性を持っています。組み込みウィジェットテンプレートは、 django/forms/widgets パスに格納されています。例えば、 django/forms/widgets/input.html を定義することで、 input.html のカスタムテンプレートを提供できます。各ウィジェットのテンプレートの名前については、 ビルトインのウィジェット を参照してください。
ウィジェットテンプレートをオーバーライドするには、 TemplatesSetting レンダラを使用する必要があります。その後、ウィジェットテンプレートのオーバーライドは、プロジェクト内の他のテンプレートをオーバーライドするのと 同じ方法で機能 します。
