Form インスタンスには、データに**くくりつけられた** ものと くくりつけられていない ものがあります。
データに くくりつけられた Form インスタンスは、そのデータを検証したり、HTMLフォームとしてレンダリングしてHTMLに表示することができます。
くくりつけられていない Form インスタンスは、データを検証することができません（なぜなら、検証するデータがないから！）が、空のフォームをHTMLとしてレンダリングすることは可能です。
くくりつけられていない Form インスタンスを作るには、クラスをインスタンス化します:
>>> f = ContactForm()\nデータをフォームにくくりつけるには、データをディクショナリとして Form クラスのコンストラクタの第1引数に渡します:
>>> data = {'subject': 'hello',\n... 'message': 'Hi there',\n... 'sender': 'foo@example.com',\n... 'cc_myself': True}\n>>> f = ContactForm(data)\nこのディクショナリでは、キーは Form の属性に対応するフィールド名で、値は検証したいデータです。これらはふつう文字列ですが、文字列でなければならないという決まりはありません; あとですぐ見るように、渡すデータの型は Field によって決まります。
フォームインスタンスがくくりつけられているかいないかを実行中に見分けたい場合は、フォームの is_bount 属性の値を使用します:
>>> f = ContactForm()\n>>> f.is_bound\nFalse\n>>> f = ContactForm({'subject': 'hello'})\n>>> f.is_bound\nTrue\n空のディクショナリを渡した場合は、空のデータをもつ くくりつけられた フォームインスタンスになることに注意してください:
\n>>> f = ContactForm({})\n>>> f.is_bound\nTrue\nForm インスタンスの中のデータを書き換える方法はありません。一度 Form インスタンスを作成したら、データを持っていようがいまいが、それはイミュータブルだと考えてください。もし、bound な Form インスタンスのデータをなんとかして変更したかったり、unbound な Form インスタンスにデータをくくりつけたいような場合は、 Form インスタンスを新たに作成します。
相互に関連のあるフィールドに対して独自のバリデーションを追加する必要がある場合、Form 上で clean() を実装してください。具体的な使用方法は 互いに依存するフィールドをクリーニングして検証する を参照してください。
Form オブジェクトの最重要タスクは、データを検証することです。bound な Form インスタンスにおいて、is_valid() メソッドを呼び出してバリデーションを実行し、データが有効だったかどうかを示す真偽値を返してください:
>>> data = {'subject': 'hello',\n... 'message': 'Hi there',\n... 'sender': 'foo@example.com',\n... 'cc_myself': True}\n>>> f = ContactForm(data)\n>>> f.is_valid()\nTrue\n無効なデータを試してみましょう。この例では、subject が空白で (すべてのフィールドはデフォルトで必須なのでラーとなります) sender が無効なメールアドレスです:
>>> data = {'subject': '',\n... 'message': 'Hi there',\n... 'sender': 'invalid email address',\n... 'cc_myself': True}\n>>> f = ContactForm(data)\n>>> f.is_valid()\nFalse\nエラーメッセージのディクショナリを使用するには、errors 属性にアクセスしてください:
>>> f.errors\n{'sender': ['Enter a valid email address.'], 'subject': ['This field is required.']}\nこのディクショナリでは、キーはフィールド名、値はエラーメッセージを表す文字列のリストです。エラーメッセージがリストに格納されるのは、1 つのフィールドに複数のエラーメッセージがある可能性があるからです。
\nis_valid() を呼び出す前に errors にアクセスすることもできます。フォームのデータは、最初に is_valid() を呼び出したり errors にアクセスすることで検証されます。
バリデーションのルーチンは、errors や call is_valid() を何度呼び出しても 1 度だけ呼び出されます。これが意味するのは、もしバリデーションが副作用を持っている場合、その副作用は 1 度だけ発生すると言うことです。
フィールドとオリジナルの ValidationError インスタンスをマッピングする dict を返します。
>>> f.errors.as_data()\n{'sender': [ValidationError(['Enter a valid email address.'])],\n'subject': [ValidationError(['This field is required.'])]}\ncode によりエラーを特定する必要があるときはこのメソッドを使用してください。これによって、エラーメッセージの上書きや、エラーが存在するときのビューでの独自のロジックが作成できるようになります。独自のフォーマット (例えば XML) でシリアライズするためにも使えます; 例えば as_json() は as_data() を利用しています。
as_data() の必要性は、後方互換性に起因します。以前は ValidationError インスタンスは 描画された エラーメッセージが Form.errors ディクショナリに追加されると同時に消失していました。できれば Form.errors が ValidationError インスタンスを保持し、as_ プレフィクスを伴うメソッドがエラーを描画できるのが理想でしたが、Form.errors 内の描画されたエラーメッセージを受け取る可能性があるコードを壊さないために、逆の実装にしなくてはなりませんでした。
Returns the errors serialized as JSON.
\n>>> f.errors.as_json()\n{"sender": [{"message": "Enter a valid email address.", "code": "invalid"}],\n"subject": [{"message": "This field is required.", "code": "required"}]}\nBy default, as_json() does not escape its output. If you are using it for\nsomething like AJAX requests to a form view where the client interprets the\nresponse and inserts errors into the page, you'll want to be sure to escape the\nresults on the client-side to avoid the possibility of a cross-site scripting\nattack. You can do this in JavaScript with element.textContent = errorText\nor with jQuery's $(el).text(errorText) (rather than its .html()\nfunction).
If for some reason you don't want to use client-side escaping, you can also\nset escape_html=True and error messages will be escaped so you can use them\ndirectly in HTML.
Returns the errors as a dictionary suitable for serializing to JSON.\nForm.errors.as_json() returns serialized JSON, while this returns the\nerror data before it's serialized.
The escape_html parameter behaves as described in\nForm.errors.as_json().
This method allows adding errors to specific fields from within the\nForm.clean() method, or from outside the form altogether; for instance\nfrom a view.
field 引数にはエラーを追加したいフィールド名を指定します。この値が None の場合、 Form.non_field_errors() によって返されるようなフィールドによらないエラーとして扱われます。
フォームエラーを定義するときのベストプラクティスとして、 error 引数は文字列もしくは、できれば ValidationError のインスタンスを指定します。フォームエラーの定義時のベストプラクティスについては、 ValidationError を発生させる を参照してください。
Form.add_error() は cleaned_data からフィールドを自動的に削除してしまうことに注意してください。
このメソッドは指定したフィールドが特定の code のエラーを持つか否かを真偽値で返します。code が None の場合、そのフィールドにエラーが一つもない場合に True を返します。
フィールドによらないエラー (non-field errors) の有無を確認したい場合は、field 引数に NON_FIELD_ERRORS を渡します。
このメソッドは Form.errors から、特定のフィールドに関連付けられていないエラーのリストを返します。これには、 Form.clean() で発生された ValidationError と、 Form.add_error(None, "...") で追加されたエラーが含まれます。
データのないフォームを検証することに意味はありませんが、念のため、くくりつけられていないフォームでは何が起こるかを記しておきます:
\n>>> f = ContactForm()\n>>> f.is_valid()\nFalse\n>>> f.errors\n{}\ninitial を使うことで、実行時にフォームの初期値を設定することができます。たとえば、 username フォームを埋めるのに、現在のセッションの username を使うことができます。
このためには、 Form の initial 引数を使います。この引数を渡す場合、フィールド名と初期値をマッピングしたディクショナリで渡します。渡すのは初期値を設定したいフィールドだけです; すべてのフィールドを指定する必要はありません。例えば:
>>> f = ContactForm(initial={'subject': 'Hi there!'})\nこれらの値はくくりつけられていないフォームにたんに表示されるだけです。値が入力されなかった場合の予備値として使われることはありません。
\nもし Field の中で initial が定義されていて、 加えて Form をインスタンス化する際に initial を引数にインクルードする場合、後者が優先されます。この例では、 initial がフィールドとフォームインスタンスの両方で指定されていますが、後者が優先されます:
>>> from django import forms\n>>> class CommentForm(forms.Form):\n... name = forms.CharField(initial='class')\n... url = forms.URLField()\n... comment = forms.CharField()\n>>> f = CommentForm(initial={'name': 'instance'}, auto_id=False)\n>>> print(f)\n<tr><th>Name:</th><td><input type="text" name="name" value="instance" required></td></tr>\n<tr><th>Url:</th><td><input type="url" name="url" required></td></tr>\n<tr><th>Comment:</th><td><input type="text" name="comment" required></td></tr>\nReturns the initial data for a form field. It retrieves the data from\nForm.initial if present, otherwise trying Field.initial.\nCallable values are evaluated.
It is recommended to use BoundField.initial over\nget_initial_for_field() because BoundField.initial has a\nsimpler interface. Also, unlike get_initial_for_field(),\nBoundField.initial caches its values. This is useful especially when\ndealing with callables whose return values can change (e.g. datetime.now or\nuuid.uuid4):
>>> import uuid\n>>> class UUIDCommentForm(CommentForm):\n... identifier = forms.UUIDField(initial=uuid.uuid4)\n>>> f = UUIDCommentForm()\n>>> f.get_initial_for_field(f.fields['identifier'], 'identifier')\nUUID('972ca9e4-7bfe-4f5b-af7d-07b3aa306334')\n>>> f.get_initial_for_field(f.fields['identifier'], 'identifier')\nUUID('1b411fab-844e-4dec-bd4f-e9b0495f04d0')\n>>> # Using BoundField.initial, for comparison\n>>> f['identifier'].initial\nUUID('28a09c59-5f00-4ed9-9179-a3b074fa9c30')\n>>> f['identifier'].initial\nUUID('28a09c59-5f00-4ed9-9179-a3b074fa9c30')\nフォームデータが初期値から変更されたかどうかをチェックしたい場合は、 has_changed() メソッドを使います。
>>> data = {'subject': 'hello',\n... 'message': 'Hi there',\n... 'sender': 'foo@example.com',\n... 'cc_myself': True}\n>>> f = ContactForm(data, initial=data)\n>>> f.has_changed()\nFalse\nフォームが送信された場合、比較ができるようにフォームを再構築して元のデータを提供します:
\n>>> f = ContactForm(request.POST, initial=data)\n>>> f.has_changed()\nhas_changed() は、 request.POST が initial で提供されたデータと異なる場合、 True を返し、同じであれば False を返します。この結果は、それぞれのフィールドで Field.has_changed() を呼ぶことで計算されます。
changed_data 属性は、フォームにくくりつけられたデータ (ふつうは request.POST) の値が initial で提供されたものと異なるとき、そのフィールド名のリストを返します。データが変更されていない場合は、空のリストを返します。
>>> f = ContactForm(request.POST, initial=data)\n>>> if f.has_changed():\n... print("The following fields changed: %s" % ", ".join(f.changed_data))\n>>> f.changed_data\n['subject', 'message']\nForm のフィールドには、その fields 属性を通してアクセスすることができます:
>>> for row in f.fields.values(): print(row)\n...\n<django.forms.fields.CharField object at 0x7ffaac632510>\n<django.forms.fields.URLField object at 0x7ffaac632f90>\n<django.forms.fields.CharField object at 0x7ffaac3aa050>\n>>> f.fields['name']\n<django.forms.fields.CharField object at 0x7ffaac6324d0>\nForm インスタンスのフィールドは今ある状態から変更することができます:
>>> f.as_table().split('\\n')[0]\n'<tr><th>Name:</th><td><input name="name" type="text" value="instance" required></td></tr>'\n>>> f.fields['name'].label = "Username"\n>>> f.as_table().split('\\n')[0]\n'<tr><th>Username:</th><td><input name="name" type="text" value="instance" required></td></tr>'\nbase_fields 属性は変更しないように気をつけてください。なぜなら、同じ Python プロセス内であとに続くすべての ContactForm に影響を与えることになるためです。
>>> f.base_fields['name'].label = "Username"\n>>> another_f = CommentForm(auto_id=False)\n>>> another_f.as_table().split('\\n')[0]\n'<tr><th>Username:</th><td><input name="name" type="text" value="class" required></td></tr>'\nForm クラスのそれぞれのフィールドは、データの検証のみならず、データの "cleaning" -- 整合性のある形式に正規化すること -- にも責任を持ちます。これは素晴らしい機能です。なぜなら、様々な形式で入力されるフィールドのデータから、いつでも整合性のある出力が得られるようになるからです。
たとえば、 DateField はインプットを Python の datetime.date オブジェクトに正規化します。たとえ '1994-07-15' という形式の文字列で渡そうが、 datetime.date オブジェクトを渡そうが、他の様々な形式で渡そうが、それが検証にパスする限り DateField はいつも datetime.date オブジェクトに正規化します。
あるデータのセットに対して、いちど Form インスタンスを作成して検証したら、cleaned_data 属性を通してクリーンなデータにアクセスすることができます:
>>> data = {'subject': 'hello',\n... 'message': 'Hi there',\n... 'sender': 'foo@example.com',\n... 'cc_myself': True}\n>>> f = ContactForm(data)\n>>> f.is_valid()\nTrue\n>>> f.cleaned_data\n{'cc_myself': True, 'message': 'Hi there', 'sender': 'foo@example.com', 'subject': 'hello'}\nCharField や EmailField といったテキストベースのフィールドは、入力を文字列に正規化します。暗黙的な文字エンコードの挙動については、後のドキュメントでカバーします。
データが検証をパス しなかった 場合、 cleaned_data ディクショナリは検証にパスしたフィールドだけを含みます。
>>> data = {'subject': '',\n... 'message': 'Hi there',\n... 'sender': 'invalid email address',\n... 'cc_myself': True}\n>>> f = ContactForm(data)\n>>> f.is_valid()\nFalse\n>>> f.cleaned_data\n{'cc_myself': True, 'message': 'Hi there'}\ncleaned_data いつも、 Form で定義されたフィールド だけ をキーとして持ちます。たとえ Form を定義するときに余分なデータを渡していたとしても無視されます。この例では、いくつかの余分なフィールドを ContactForm コンストラクタに渡していますが、 cleaned_data はフォームのフィールドしか持っていません:
>>> data = {'subject': 'hello',\n... 'message': 'Hi there',\n... 'sender': 'foo@example.com',\n... 'cc_myself': True,\n... 'extra_field_1': 'foo',\n... 'extra_field_2': 'bar',\n... 'extra_field_3': 'baz'}\n>>> f = ContactForm(data)\n>>> f.is_valid()\nTrue\n>>> f.cleaned_data # Doesn't contain extra_field_1, etc.\n{'cc_myself': True, 'message': 'Hi there', 'sender': 'foo@example.com', 'subject': 'hello'}\nForm が検証をパスした場合、 cleaned_data は、省略可能なフィールドに値が入っていなかったとしても、 すべての フィールドのキーと値をインクルードします。この例では、データディクショナリは nick_name フィールドに値をインクルードしていませんが、 cleaned_data には空の値を伴ってインクルードされています:
>>> from django import forms\n>>> class OptionalPersonForm(forms.Form):\n... first_name = forms.CharField()\n... last_name = forms.CharField()\n... nick_name = forms.CharField(required=False)\n>>> data = {'first_name': 'John', 'last_name': 'Lennon'}\n>>> f = OptionalPersonForm(data)\n>>> f.is_valid()\nTrue\n>>> f.cleaned_data\n{'nick_name': '', 'first_name': 'John', 'last_name': 'Lennon'}\n上の例では、 cleaned_data 中の nick_name の値には空の文字列がセットされています。これは、 nick_name が CharField であり、 CharField は空の値を空の文字列として扱うからです。それぞれのフィールドタイプは、それぞれの 空の 値が何であるか知っています -- たとえば、 DateField では空の文字列の代わりに None です。それぞれのフィールドの挙動の完全な詳細は、あとの "Built-in Field classes" セクションにある "Empty value" ノートを見てください。
特定のいくつかの (フォーム名に基づく) フォームフィールドまたは (さまざまなフィールドの組み合わせを考えて) フォーム全体に対しての検証を行うコードを書くことも可能です。これについての詳細は、 フォームとフィールドの検証 を見てください。
\nForm オブジェクトの 2 番目のタスクは、それ自身をHTMLとしてレンダリングすることです。そうするには print します:
>>> f = ContactForm()\n>>> print(f)\n<tr><th><label for="id_subject">Subject:</label></th><td><input id="id_subject" type="text" name="subject" maxlength="100" required></td></tr>\n<tr><th><label for="id_message">Message:</label></th><td><input type="text" name="message" id="id_message" required></td></tr>\n<tr><th><label for="id_sender">Sender:</label></th><td><input type="email" name="sender" id="id_sender" required></td></tr>\n<tr><th><label for="id_cc_myself">Cc myself:</label></th><td><input type="checkbox" name="cc_myself" id="id_cc_myself"></td></tr>\nフォームがデータにくくりつけられている場合、 HTML アウトプットはデータを適切にインクルードします。たとえば、フィールドタイプが <input type="text"> で表される場合、データは value 属性に入ります。フィールドが <input type="checkbox"> で表される場合、それが適当なであれば HTML は checked をインクルードします:
>>> data = {'subject': 'hello',\n... 'message': 'Hi there',\n... 'sender': 'foo@example.com',\n... 'cc_myself': True}\n>>> f = ContactForm(data)\n>>> print(f)\n<tr><th><label for="id_subject">Subject:</label></th><td><input id="id_subject" type="text" name="subject" maxlength="100" value="hello" required></td></tr>\n<tr><th><label for="id_message">Message:</label></th><td><input type="text" name="message" id="id_message" value="Hi there" required></td></tr>\n<tr><th><label for="id_sender">Sender:</label></th><td><input type="email" name="sender" id="id_sender" value="foo@example.com" required></td></tr>\n<tr><th><label for="id_cc_myself">Cc myself:</label></th><td><input type="checkbox" name="cc_myself" id="id_cc_myself" checked></td></tr>\nデフォルトのアウトプットは <tr> をそれぞれのフィールドに伴う 2 カラムの HTML テーブルです。注意点としては:
柔軟性のため、アウトプットは <table> </table> タグをインクルードしません。また、 <form> </form> タグや <input type="submit"> タグもインクルードされません。これらはあなたの仕事です。
それぞれのフィールドタイプはデフォルトの HTML 表現を持っています。 CharField は <input type="text"> で、 EmailField は <input type="email"> で表現され、BooleanField(null=False) は <input type="checkbox"> で表現されます。これらは単なる実用的なデフォルトであり、あるフィールドにどの HTML を使うかは、すぐ後で説明するウィジェットを使って指定することができます。
HTML のそれぞれのタグの name は、 ContactForm クラスの属性名から直接とられます。
それぞれのフィールドのテキストラベル、たとえば 'Subject:', 'Message:' , 'Cc myself:' は、フィールド名のアンダースコアをスペースに変換し、頭文字を大文字に変換して生成されます。これらもまた単なる実用的なデフォルトです; 手動でラベルを指定することもできます。
それぞれのテキストラベルは HTML <label> タグで囲まれており、 id を通して適切なフォームフィールドを指しています。id は、フィールド名に 'id_' を前置することで生成されます。id 属性と <label> タグは、ベストプラクティスに従ってデフォルトでアウトプットにインクルードされますが、この挙動も変更することができます。
The output uses HTML5 syntax, targeting <!DOCTYPE html>. For example,\nit uses boolean attributes such as checked rather than the XHTML style\nof checked='checked'.
<table> アウトプットがフォームを print したときのデフォルトではあるものの、他のアウトプットスタイルも利用可能です。それぞれのスタイルはフォームオブジェクトのメソッドとして利用可能で、それぞれのメソッドは文字列を返します。
template_nameLink to this heading#The name of a template that is going to be rendered if the form is cast into a\nstring, e.g. via print(form) or in a template via {{ form }}. By\ndefault this template is 'django/forms/default.html', which is a proxy for\n'django/forms/table.html'. The template can be changed per form by\noverriding the template_name attribute or more generally by overriding the\ndefault template, see also Overriding built-in form templates.
template_name_labelLink to this heading#The template used to render a field's <label>, used when calling\nBoundField.label_tag(). Can be changed per form by overriding this\nattribute or more generally by overriding the default template, see also\nOverriding built-in form templates.
as_p()Link to this heading#as_p() renders the form using the template assigned to the forms\ntemplate_name_p attribute, by default this template is\n'django/forms/p.html'. This template renders the form as a series of\n<p> tags, with each <p> containing one field:
>>> f = ContactForm()\n>>> f.as_p()\n'<p><label for="id_subject">Subject:</label> <input id="id_subject" type="text" name="subject" maxlength="100" required></p>\\n<p><label for="id_message">Message:</label> <input type="text" name="message" id="id_message" required></p>\\n<p><label for="id_sender">Sender:</label> <input type="text" name="sender" id="id_sender" required></p>\\n<p><label for="id_cc_myself">Cc myself:</label> <input type="checkbox" name="cc_myself" id="id_cc_myself"></p>'\n>>> print(f.as_p())\n<p><label for="id_subject">Subject:</label> <input id="id_subject" type="text" name="subject" maxlength="100" required></p>\n<p><label for="id_message">Message:</label> <input type="text" name="message" id="id_message" required></p>\n<p><label for="id_sender">Sender:</label> <input type="email" name="sender" id="id_sender" required></p>\n<p><label for="id_cc_myself">Cc myself:</label> <input type="checkbox" name="cc_myself" id="id_cc_myself"></p>\nas_ul()Link to this heading#as_ul() renders the form using the template assigned to the forms\ntemplate_name_ul attribute, by default this template is\n'django/forms/ul.html'. This template renders the form as a series of\n<li> tags, with each <li> containing one field. It does not include\nthe <ul> or </ul>, so that you can specify any HTML attributes on the\n<ul> for flexibility:
>>> f = ContactForm()\n>>> f.as_ul()\n'<li><label for="id_subject">Subject:</label> <input id="id_subject" type="text" name="subject" maxlength="100" required></li>\\n<li><label for="id_message">Message:</label> <input type="text" name="message" id="id_message" required></li>\\n<li><label for="id_sender">Sender:</label> <input type="email" name="sender" id="id_sender" required></li>\\n<li><label for="id_cc_myself">Cc myself:</label> <input type="checkbox" name="cc_myself" id="id_cc_myself"></li>'\n>>> print(f.as_ul())\n<li><label for="id_subject">Subject:</label> <input id="id_subject" type="text" name="subject" maxlength="100" required></li>\n<li><label for="id_message">Message:</label> <input type="text" name="message" id="id_message" required></li>\n<li><label for="id_sender">Sender:</label> <input type="email" name="sender" id="id_sender" required></li>\n<li><label for="id_cc_myself">Cc myself:</label> <input type="checkbox" name="cc_myself" id="id_cc_myself"></li>\nas_table()Link to this heading#Finally, as_table() renders the form using the template assigned to the\nforms template_name_table attribute, by default this template is\n'django/forms/table.html'. This template outputs the form as an HTML\n<table>:
>>> f = ContactForm()\n>>> f.as_table()\n'<tr><th><label for="id_subject">Subject:</label></th><td><input id="id_subject" type="text" name="subject" maxlength="100" required></td></tr>\\n<tr><th><label for="id_message">Message:</label></th><td><input type="text" name="message" id="id_message" required></td></tr>\\n<tr><th><label for="id_sender">Sender:</label></th><td><input type="email" name="sender" id="id_sender" required></td></tr>\\n<tr><th><label for="id_cc_myself">Cc myself:</label></th><td><input type="checkbox" name="cc_myself" id="id_cc_myself"></td></tr>'\n>>> print(f)\n<tr><th><label for="id_subject">Subject:</label></th><td><input id="id_subject" type="text" name="subject" maxlength="100" required></td></tr>\n<tr><th><label for="id_message">Message:</label></th><td><input type="text" name="message" id="id_message" required></td></tr>\n<tr><th><label for="id_sender">Sender:</label></th><td><input type="email" name="sender" id="id_sender" required></td></tr>\n<tr><th><label for="id_cc_myself">Cc myself:</label></th><td><input type="checkbox" name="cc_myself" id="id_cc_myself"></td></tr>\nget_context()Link to this heading#Return context for form rendering in a template.
\nThe available context is:
\nform: The bound form.
fields: All bound fields, except the hidden fields.
hidden_fields: All hidden bound fields.
errors: All non field related or hidden field related form errors.
render()Link to this heading#The render method is called by __str__ as well as the\nForm.as_table(), Form.as_p(), and Form.as_ul() methods.\nAll arguments are optional and default to:
template_name: Form.template_name
context: Value returned by Form.get_context()
renderer: Value returned by Form.default_renderer
必須フォームやエラーのあるフォームの行を装飾するのはとても一般的です。たとえば、必須フォームの行は太字にしたり、エラーであれば赤色にしたくなることもあるでしょう。
\nForm クラスには、必須フォームやエラーのあるフォームに class 属性を追加するためのいくつかのフックを用意しています。具体的には、 Form.error_css_class 属性や Form.required_css_class 属性をセットします:
from django import forms\n\nclass ContactForm(forms.Form):\n error_css_class = 'error'\n required_css_class = 'required'\n\n # ... and the rest of your fields here\nいったん設定すれば、それらの行は "error" クラスや "required" クラスが必要に応じて追加されます。HTMLはこのようになるでしょう:
>>> f = ContactForm(data)\n>>> print(f.as_table())\n<tr class="required"><th><label class="required" for="id_subject">Subject:</label> ...\n<tr class="required"><th><label class="required" for="id_message">Message:</label> ...\n<tr class="required error"><th><label class="required" for="id_sender">Sender:</label> ...\n<tr><th><label for="id_cc_myself">Cc myself:<label> ...\n>>> f['subject'].label_tag()\n<label class="required" for="id_subject">Subject:</label>\n>>> f['subject'].label_tag(attrs={'class': 'foo'})\n<label for="id_subject" class="foo required">Subject:</label>\nフォームの renderer を指定します。デフォルトは None で、 FORM_RENDERER 設定で指定されたデフォルトのレンダラーを使用することを意味します。
これはクラスの属性としてフォーム定義の際に設定するもしくは、Form.__init__() に renderer 引数を使うことで設定します。たとえば:
from django import forms\n\nclass MyForm(forms.Form):\n default_renderer = MyRenderer()\nもしくは:
\nform = MyForm(renderer=MyRenderer())\nas_p(), as_ul(), as_table() ショートカットでは、フィールドはフォームクラスで定義した順序で表示されます。たとえば、 ContactForm の例では、フィールドは subject, message, sender, cc_myself の順で定義されます。 HTML アウトプットの順序を変更するには、クラスの中で定義する順序を変えます。
順序のカスタマイズには、ほかにもいくつかの方法があります:
\nBy default Form.field_order=None, which retains the order in which you\ndefine the fields in your form class. If field_order is a list of field\nnames, the fields are ordered as specified by the list and remaining fields are\nappended according to the default order. Unknown field names in the list are\nignored. This makes it possible to disable a field in a subclass by setting it\nto None without having to redefine ordering.
Form に Form.field_order 引数を使うことで、フィールドの順序をオーバーライドすることもできます。 Form の中で field_order が定義されていて、 かつ Form をインスタンス化する際に field_order をインクルードする場合、後者の field_order が優先されます。
また、 order_fields() に field_order と同様のフィールド名のリストを用いて、いつでもフィールドの順序を変更することができます。
bound な Form オブジェクトをレンダリングしたとき、フォームの検証がまだ行われていない場合は自動的に検証が行われ、 HTML アウトプットの該当フィールドの近くに検証エラーが <ul class="errorlist"> として含まれます。個別のエラーメッセージの表示位置は、使用されているアウトプットメソッドに依存します:
>>> data = {'subject': '',\n... 'message': 'Hi there',\n... 'sender': 'invalid email address',\n... 'cc_myself': True}\n>>> f = ContactForm(data, auto_id=False)\n>>> print(f.as_table())\n<tr><th>Subject:</th><td><ul class="errorlist"><li>This field is required.</li></ul><input type="text" name="subject" maxlength="100" required></td></tr>\n<tr><th>Message:</th><td><input type="text" name="message" value="Hi there" required></td></tr>\n<tr><th>Sender:</th><td><ul class="errorlist"><li>Enter a valid email address.</li></ul><input type="email" name="sender" value="invalid email address" required></td></tr>\n<tr><th>Cc myself:</th><td><input checked type="checkbox" name="cc_myself"></td></tr>\n>>> print(f.as_ul())\n<li><ul class="errorlist"><li>This field is required.</li></ul>Subject: <input type="text" name="subject" maxlength="100" required></li>\n<li>Message: <input type="text" name="message" value="Hi there" required></li>\n<li><ul class="errorlist"><li>Enter a valid email address.</li></ul>Sender: <input type="email" name="sender" value="invalid email address" required></li>\n<li>Cc myself: <input checked type="checkbox" name="cc_myself"></li>\n>>> print(f.as_p())\n<p><ul class="errorlist"><li>This field is required.</li></ul></p>\n<p>Subject: <input type="text" name="subject" maxlength="100" required></p>\n<p>Message: <input type="text" name="message" value="Hi there" required></p>\n<p><ul class="errorlist"><li>Enter a valid email address.</li></ul></p>\n<p>Sender: <input type="email" name="sender" value="invalid email address" required></p>\n<p>Cc myself: <input checked type="checkbox" name="cc_myself"></p>\nBy default, forms use django.forms.utils.ErrorList to format validation\nerrors. ErrorList is a list like object where initlist is the\nlist of errors. In addition this class has the following attributes and\nmethods.
The CSS classes to be used when rendering the error list. Any provided\nclasses are added to the default errorlist class.
Specifies the renderer to use for ErrorList.\nDefaults to None which means to use the default renderer\nspecified by the FORM_RENDERER setting.
The name of the template used when calling __str__ or\nrender(). By default this is\n'django/forms/errors/list/default.html' which is a proxy for the\n'ul.html' template.
The name of the template used when calling as_text(). By default\nthis is 'django/forms/errors/list/text.html'. This template renders\nthe errors as a list of bullet points.
The name of the template used when calling as_ul(). By default\nthis is 'django/forms/errors/list/ul.html'. This template renders\nthe errors in <li> tags with a wrapping <ul> with the CSS\nclasses as defined by error_class.
Return context for rendering of errors in a template.
\nThe available context is:
\nerrors : A list of the errors.
error_class : A string of CSS classes.
The render method is called by __str__ as well as by the\nas_ul() method.
All arguments are optional and will default to:
\ntemplate_name: Value returned by template_name
context: Value returned by get_context()
renderer: Value returned by renderer
Renders the error list using the template defined by\ntemplate_name_text.
Renders the error list using the template defined by\ntemplate_name_ul.
If you'd like to customize the rendering of errors this can be achieved by\noverriding the template_name attribute or more generally by\noverriding the default template, see also\nOverriding built-in form templates.
as_p(), as_ul(), as_table() メソッドはショートカットです -- フォームオブジェクトを表示する唯一の方法ではありません。
Form インスタンスのひとつのフィールドを HTML として表示したり、その属性にアクセスするのに使います。
このオブジェクトの __str__() メソッドは、このフィールドの HTML を表示します。
ひとつの BoundField を引き出すには、フォームにフィールド名をキーとしたディクショナリルックアップ構文を使います:
>>> form = ContactForm()\n>>> print(form['subject'])\n<input id="id_subject" type="text" name="subject" maxlength="100" required>\nすべての BoundField オブジェクトを引き出すには、フォームを iterate します:
>>> form = ContactForm()\n>>> for boundfield in form: print(boundfield)\n<input id="id_subject" type="text" name="subject" maxlength="100" required>\n<input type="text" name="message" id="id_message" required>\n<input type="email" name="sender" id="id_sender" required>\n<input type="checkbox" name="cc_myself" id="id_cc_myself">\nフィールドごとのアウトプットは、フォームオブジェクトの auto_id 設定を受け取ります:
>>> f = ContactForm(auto_id=False)\n>>> print(f['message'])\n<input type="text" name="message" required>\n>>> f = ContactForm(auto_id='id_%s')\n>>> print(f['message'])\n<input type="text" name="message" id="id_message" required>\nBoundField の属性一覧Link to this heading#この BoundField の HTML ID 属性。 Form.auto_id が False であれば、空の文字列を返します。
このプロパティは、ウィジェットの value_from_datadict() メソッドをによって抽出された BoundField のデータを返し、データが無い場合は None を返します:
>>> unbound_form = ContactForm()\n>>> print(unbound_form['subject'].data)\nNone\n>>> bound_form = ContactForm(data={'subject': 'My Subject'})\n>>> print(bound_form['subject'].data)\nMy Subject\nprint された際、 HTML で <ul class="errorlist"> として表示される list-like object です。
>>> data = {'subject': 'hi', 'message': '', 'sender': '', 'cc_myself': ''}\n>>> f = ContactForm(data, auto_id=False)\n>>> print(f['message'])\n<input type="text" name="message" required>\n>>> f['message'].errors\n['This field is required.']\n>>> print(f['message'].errors)\n<ul class="errorlist"><li>This field is required.</li></ul>\n>>> f['subject'].errors\n[]\n>>> print(f['subject'].errors)\n\n>>> str(f['subject'].errors)\n''\nこの BoundField がラップしているフォームクラスの Field インスタンス。
この BoundField がくくりつけられている Form インスタンス。
フィールドの help_text 。
The name that will be used in the widget's HTML name attribute. It takes\nthe form prefix into account.
Use this property to render the ID of this field. For example, if you are\nmanually constructing a <label> in your template (despite the fact that\nlabel_tag() will do this for you):
<label for="{{ form.my_field.id_for_label }}">...</label>{{ my_field }}\nBy default, this will be the field's name prefixed by id_\n("id_my_field" for the example above). You may modify the ID by setting\nattrs on the field's widget. For example,\ndeclaring a field like this:
my_field = forms.CharField(widget=forms.TextInput(attrs={'id': 'myFIELD'}))\nand using the template above, would render something like:
\n<label for="myFIELD">...</label><input id="myFIELD" type="text" name="my_field" required>\nUse BoundField.initial to retrieve initial data for a form field.\nIt retrieves the data from Form.initial if present, otherwise\ntrying Field.initial. Callable values are evaluated. See\nInitial form values for more examples.
BoundField.initial caches its return value, which is useful\nespecially when dealing with callables whose return values can change (e.g.\ndatetime.now or uuid.uuid4):
>>> from datetime import datetime\n>>> class DatedCommentForm(CommentForm):\n... created = forms.DateTimeField(initial=datetime.now)\n>>> f = DatedCommentForm()\n>>> f['created'].initial\ndatetime.datetime(2021, 7, 27, 9, 5, 54)\n>>> f['created'].initial\ndatetime.datetime(2021, 7, 27, 9, 5, 54)\nUsing BoundField.initial is recommended over\nget_initial_for_field().
Returns True if this BoundField's widget is\nhidden.
The label of the field. This is used in\nlabel_tag().
The name of this field in the form:
\n>>> f = ContactForm()\n>>> print(f['subject'].name)\nsubject\n>>> print(f['message'].name)\nmessage\nReturns the lowercased class name of the wrapped field's widget, with any\ntrailing input or widget removed. This may be used when building\nforms where the layout is dependent upon the widget type. For example:
{% for field in form %}\n {% if field.widget_type == 'checkbox' %}\n # render one way\n {% else %}\n # render another way\n {% endif %}\n{% endfor %}\nBoundFieldLink to this heading#Returns a string of HTML for representing this as an <input type="hidden">.
**kwargs are passed to as_widget().
This method is primarily used internally. You should use a widget instead.
\nRenders the field by rendering the passed widget, adding any HTML\nattributes passed as attrs. If no widget is specified, then the\nfield's default widget will be used.
only_initial is used by Django internals and should not be set\nexplicitly.
When you use Django's rendering shortcuts, CSS classes are used to\nindicate required form fields or fields that contain errors. If you're\nmanually rendering a form, you can access these CSS classes using the\ncss_classes method:
>>> f = ContactForm(data={'message': ''})\n>>> f['message'].css_classes()\n'required'\nIf you want to provide some additional classes in addition to the\nerror and required classes that may be required, you can provide\nthose classes as an argument:
\n>>> f = ContactForm(data={'message': ''})\n>>> f['message'].css_classes('foo bar')\n'foo bar required'\nRenders a label tag for the form field using the template specified by\nForm.template_name_label.
The available context is:
\nfield: This instance of the BoundField.
contents: By default a concatenated string of\nBoundField.label and Form.label_suffix (or\nField.label_suffix, if set). This can be overridden by the\ncontents and label_suffix arguments.
attrs: A dict containing for,\nForm.required_css_class, and id. id is generated by the\nfield's widget attrs or BoundField.auto_id. Additional\nattributes can be provided by the attrs argument.
use_tag: A boolean which is True if the label has an id.\nIf False the default template omits the <label> tag.
To separately render the label tag of a form field, you can call its\nlabel_tag() method:
>>> f = ContactForm(data={'message': ''})\n>>> print(f['message'].label_tag())\n<label for="id_message">Message:</label>\nIf you'd like to customize the rendering this can be achieved by overriding\nthe Form.template_name_label attribute or more generally by\noverriding the default template, see also\nOverriding built-in form templates.
Use this method to render the raw value of this field as it would be rendered\nby a Widget:
>>> initial = {'subject': 'welcome'}\n>>> unbound_form = ContactForm(initial=initial)\n>>> bound_form = ContactForm(data={'subject': 'hi'}, initial=initial)\n>>> print(unbound_form['subject'].value())\nwelcome\n>>> print(bound_form['subject'].value())\nhi\nBoundFieldLink to this heading#If you need to access some additional information about a form field in a\ntemplate and using a subclass of Field isn't\nsufficient, consider also customizing BoundField.
A custom form field can override get_bound_field():
Takes an instance of Form and the name of the field.\nThe return value will be used when accessing the field in a template. Most\nlikely it will be an instance of a subclass of\nBoundField.
If you have a GPSCoordinatesField, for example, and want to be able to\naccess additional information about the coordinates in a template, this could\nbe implemented as follows:
class GPSCoordinatesBoundField(BoundField):\n @property\n def country(self):\n """\n Return the country the coordinates lie in or None if it can't be\n determined.\n """\n value = self.value()\n if value:\n return get_country_from_coordinates(value)\n else:\n return None\n\nclass GPSCoordinatesField(Field):\n def get_bound_field(self, form, field_name):\n return GPSCoordinatesBoundField(form, self, field_name)\nNow you can access the country in a template with\n{{ form.coordinates.country }}.
Dealing with forms that have FileField and ImageField fields\nis a little more complicated than a normal form.
Firstly, in order to upload files, you'll need to make sure that your\n<form> element correctly defines the enctype as\n"multipart/form-data":
<form enctype="multipart/form-data" method="post" action="/foo/">\nSecondly, when you use the form, you need to bind the file data. File\ndata is handled separately to normal form data, so when your form\ncontains a FileField and ImageField, you will need to specify\na second argument when you bind your form. So if we extend our\nContactForm to include an ImageField called mugshot, we\nneed to bind the file data containing the mugshot image:
# Bound form with an image field\n>>> from django.core.files.uploadedfile import SimpleUploadedFile\n>>> data = {'subject': 'hello',\n... 'message': 'Hi there',\n... 'sender': 'foo@example.com',\n... 'cc_myself': True}\n>>> file_data = {'mugshot': SimpleUploadedFile('face.jpg', <file data>)}\n>>> f = ContactFormWithMugshot(data, file_data)\nIn practice, you will usually specify request.FILES as the source\nof file data (just like you use request.POST as the source of\nform data):
# Bound form with an image field, data from the request\n>>> f = ContactFormWithMugshot(request.POST, request.FILES)\nConstructing an unbound form is the same as always -- omit both form data and\nfile data:
\n# Unbound form with an image field\n>>> f = ContactFormWithMugshot()\nIf you're writing reusable views or templates, you may not know ahead of time\nwhether your form is a multipart form or not. The is_multipart() method\ntells you whether the form requires multipart encoding for submission:
>>> f = ContactFormWithMugshot()\n>>> f.is_multipart()\nTrue\nHere's an example of how you might use this in a template:
\n{% if form.is_multipart %}\n <form enctype="multipart/form-data" method="post" action="/foo/">\n{% else %}\n <form method="post" action="/foo/">\n{% endif %}\n{{ form }}\n</form>\nIf you have multiple Form classes that share fields, you can use\nsubclassing to remove redundancy.
When you subclass a custom Form class, the resulting subclass will\ninclude all fields of the parent class(es), followed by the fields you define\nin the subclass.
In this example, ContactFormWithPriority contains all the fields from\nContactForm, plus an additional field, priority. The ContactForm\nfields are ordered first:
>>> class ContactFormWithPriority(ContactForm):\n... priority = forms.CharField()\n>>> f = ContactFormWithPriority(auto_id=False)\n>>> print(f.as_ul())\n<li>Subject: <input type="text" name="subject" maxlength="100" required></li>\n<li>Message: <input type="text" name="message" required></li>\n<li>Sender: <input type="email" name="sender" required></li>\n<li>Cc myself: <input type="checkbox" name="cc_myself"></li>\n<li>Priority: <input type="text" name="priority" required></li>\nIt's possible to subclass multiple forms, treating forms as mixins. In this\nexample, BeatleForm subclasses both PersonForm and InstrumentForm\n(in that order), and its field list includes the fields from the parent\nclasses:
>>> from django import forms\n>>> class PersonForm(forms.Form):\n... first_name = forms.CharField()\n... last_name = forms.CharField()\n>>> class InstrumentForm(forms.Form):\n... instrument = forms.CharField()\n>>> class BeatleForm(InstrumentForm, PersonForm):\n... haircut_type = forms.CharField()\n>>> b = BeatleForm(auto_id=False)\n>>> print(b.as_ul())\n<li>First name: <input type="text" name="first_name" required></li>\n<li>Last name: <input type="text" name="last_name" required></li>\n<li>Instrument: <input type="text" name="instrument" required></li>\n<li>Haircut type: <input type="text" name="haircut_type" required></li>\nIt's possible to declaratively remove a Field inherited from a parent class\nby setting the name of the field to None on the subclass. For example:
>>> from django import forms\n\n>>> class ParentForm(forms.Form):\n... name = forms.CharField()\n... age = forms.IntegerField()\n\n>>> class ChildForm(ParentForm):\n... name = None\n\n>>> list(ChildForm().fields)\n['age']\nYou can put several Django forms inside one <form> tag. To give each\nForm its own namespace, use the prefix keyword argument:
>>> mother = PersonForm(prefix="mother")\n>>> father = PersonForm(prefix="father")\n>>> print(mother.as_ul())\n<li><label for="id_mother-first_name">First name:</label> <input type="text" name="mother-first_name" id="id_mother-first_name" required></li>\n<li><label for="id_mother-last_name">Last name:</label> <input type="text" name="mother-last_name" id="id_mother-last_name" required></li>\n>>> print(father.as_ul())\n<li><label for="id_father-first_name">First name:</label> <input type="text" name="father-first_name" id="id_father-first_name" required></li>\n<li><label for="id_father-last_name">Last name:</label> <input type="text" name="father-last_name" id="id_father-last_name" required></li>\nThe prefix can also be specified on the form class:
\n>>> class PersonForm(forms.Form):\n... ...\n... prefix = 'person'\n