ModelFormLink to this heading#データベース中心のアプリケーションを作成している場合、Django モデルに密接にマップするフォームを使うことになるでしょう。例えば、BlogComment モデルを持っていて、閲覧者がコメントを送信できるフォームを作成したくなったとしましょう。この場合、すでにモデル内にフィールドが定義されているので、フォーム内にフィールドタイプを改めて定義するのは冗長でしょう。
このためDjango には、Django モデルから Form クラスを生成できるようなヘルパークラスを用意してあります。
例えば次のようにします:
\n>>> from django.forms import ModelForm\n>>> from myapp.models import Article\n\n# Create the form class.\n>>> class ArticleForm(ModelForm):\n... class Meta:\n... model = Article\n... fields = ["pub_date", "headline", "content", "reporter"]\n...\n\n# Creating a form to add an article.\n>>> form = ArticleForm()\n\n# Creating a form to change an existing article.\n>>> article = Article.objects.get(pk=1)\n>>> form = ArticleForm(instance=article)\n生成された Form クラスは、指定された全てのモデルフィールドに対して、fields 属性で指定された順番でフォームフィールドを有します。
各モデルフィールドは、対応するデフォルトのフォームフィールドを持ちます。例えば、モデル上の CharField はフォーム上で CharField として表現されます。モデル ManyToManyField は MultipleChoiceField として表現されます。 以下は、各フィールドの対応表です:
モデルフィールド | \nフォームフィールド | \n
|---|---|
| \n | フォーム上では表示されません。 | \n
| \n | フォーム上では表示されません。 | \n
| \n |
| \n
| \n |
| \n
| \n |
| \n
| \n |
| \n
| \n | \n |
| \n | \n |
| \n | \n |
| \n | \n |
| \n | \n |
| \n | \n |
| \n | \n |
| \n | \n |
| \n |
| \n
| \n | \n |
| \n | \n |
| \n
| \n
| \n | \n |
| \n | \n |
| \n |
| \n
| \n | \n |
| \n | \n |
| \n | \n |
| \n | \n |
| \n | フォーム上では表示されません。 | \n
| \n | \n |
| \n |
| \n
| \n | \n |
| \n | \n |
| \n | \n |
お気付きかもしれませんが、 ForeignKey と ManyToManyField の 2 つのモデルフィールドは特殊なケースとなります:
ForeignKey は django.forms.ModelChoiceField によって表現され、モデルの QuerySet を選択肢として持つ ChoiceField です。
ManyToManyField は django.forms.ModelMultipleChoiceField によって表現され、モデルの QuerySet を選択肢として持つ MultipleChoiceField です。
加えて、生成されたフォームフィールドはそれぞれ以下の通り属性がセットされます:
\nモデルフィールドに blank=True が設定されている場合、フォームフィールド上で required が False にセットされます。それ以外の場合は required=True となります。
フォームフィールドの label はモデルフィールドの verbose_name の最初の文字を大文字にしたものがセットされます。
フォームフィールドの help_text はモデルフィールドの help_text がセットされます。
モデルフィールドに choices が設定されている場合、フォームフィールドの widget は Select にセットされ、選択肢にはモデルフィールドの choices が使われます。通常、選択肢には空欄の選択肢が追加され、デフォルトで選択されることになります。フィールドが required の場合、ユーザは選択肢を選ぶ必要があります。モデルフィールドに blank=False および明示的な default 値が設定されている場合、空欄の選択肢は表示されません (代わりに default 値が選択された状態で表示されます) 。
与えられたモデルフィールドに対して使われるフォームフィールドをオーバーライドすることもできます。後述の Overriding the default fields を参照してください。
\n以下のような一連のモデルを考えていきましょう:
\nfrom django.db import models\nfrom django.forms import ModelForm\n\nTITLE_CHOICES = {\n "MR": "Mr.",\n "MRS": "Mrs.",\n "MS": "Ms.",\n}\n\n\nclass Author(models.Model):\n name = models.CharField(max_length=100)\n title = models.CharField(max_length=3, choices=TITLE_CHOICES)\n birth_date = models.DateField(blank=True, null=True)\n\n def __str__(self):\n return self.name\n\n\nclass Book(models.Model):\n name = models.CharField(max_length=100)\n authors = models.ManyToManyField(Author)\n\n\nclass AuthorForm(ModelForm):\n class Meta:\n model = Author\n fields = ["name", "title", "birth_date"]\n\n\nclass BookForm(ModelForm):\n class Meta:\n model = Book\n fields = ["name", "authors"]\nこれらのモデルでは、上記の ModelForm サブクラスはおおむね以下と同等と言えます (唯一の違いは save() メソッドで、これからすぐ説明します):
from django import forms\n\n\nclass AuthorForm(forms.Form):\n name = forms.CharField(max_length=100)\n title = forms.CharField(\n max_length=3,\n widget=forms.Select(choices=TITLE_CHOICES),\n )\n birth_date = forms.DateField(required=False)\n\n\nclass BookForm(forms.Form):\n name = forms.CharField(max_length=100)\n authors = forms.ModelMultipleChoiceField(queryset=Author.objects.all())\nModelForm の検証 (バリデーション)Link to this heading#ModelForm のバリデーションには、以下の 2 つのステップが存在します:
通常のフォームのバリデーションと同じように、モデルフォームのバリデーションは is_valid() が呼ばれたときや errors 属性にアクセスしたとき、暗黙的に実行されます。また、実際にはあまり使うメソッドではありませんが、明示的に full_clean() を呼んだときにもバリデーションが実行されます。
Model バリデーション (Model.full_clean()) は、フォームバリデーションのステップ内でフォームの clean() メソッドが呼ばれたすぐ直後に実行されます。
clean() メソッドをオーバーライドするLink to this heading#通常のフォームと同じ方法でモデルフォーム上の clean() メソッドをオーバーライドして、バリデーションの動作を追加できます。
モデルのオブジェクトに付属したモデルフォームのインスタンスは、instance 属性を持ち、メソッドが特定のモデルのインスタンスにアクセスできるようにします。
バリデーションプロセスの一部として、ModelForm フォーム上で対応するフィールドを持つモデルのそれぞれのフィールドの clean() メソッドを呼び出します。モデルフィールドを除外した場合、これらのフィールドに対してはバリデーションが実行されません。フィールドのクリーニングとバリデーションの詳しい働き方については、フォームバリデーション ドキュメントを参照してください。
モデルの clean() メソッドは一意性のチェックがされる前に呼び出されます。モデルの clean() フックのより詳しい情報については、オブジェクトのバリデーションを行う を参照してください。
error_messages のレンダリングを考えるLink to this heading#フォームフィールド や フォーム Meta のレベルで定義されたエラーメッセージは、常に モデルフィールド のレベルで定義されたエラーメッセージより優先されます。
モデルフィールド で定義されたエラーメッセージは、モデルバリデーション のステップの間に ValidationError が発生したときに、対応するエラーメッセージがフォームのレベルで定義されていない場合にのみ使用されます。
NON_FIELD_ERRORS キーを Meta クラス内の error_messages ディクショナリに追加することで、モデルバリデーションによって発生する NON_FIELD_ERRORS に対するエラーメッセージをオーバーライドできます。
from django.core.exceptions import NON_FIELD_ERRORS\nfrom django.forms import ModelForm\n\n\nclass ArticleForm(ModelForm):\n class Meta:\n error_messages = {\n NON_FIELD_ERRORS: {\n "unique_together": "%(model_name)s's %(field_labels)s are not unique.",\n }\n }\nsave() メソッドLink to this heading#全ての ModelForm は save() メソッドも持っています。このメソッドは、フォームに結びつけられたデータからデータベースオブジェクトを生成して保存します。ModelForm のサブクラスはキーワード引数 instance として既存のモデルインスタンスを受け取ることができます; これが指定されると、save() はそのインスタンスを更新するようになります。 指定されない場合は、save() は指定されたモデルの新しいインスタンスを生成します:
>>> from myapp.models import Article\n>>> from myapp.forms import ArticleForm\n\n# Create a form instance from POST data.\n>>> f = ArticleForm(request.POST)\n\n# Save a new Article object from the form's data.\n>>> new_article = f.save()\n\n# Create a form to edit an existing Article, but use\n# POST data to populate the form.\n>>> a = Article.objects.get(pk=1)\n>>> f = ArticleForm(request.POST, instance=a)\n>>> f.save()\nフォームが バリデーションされていない 場合、save() を呼び出すと、form.errors をチェックすることでこれを行います。フォーム内のデータが適正ではない場合は ValueError が発生します -- 例えば、form.errors が True だと評価された場合です。
オプションのフィールドがフォームのデータに表示されない場合、結果のモデルインスタンスはモデルフィールドの default を使用します。この動作は、 CheckboxInput, CheckboxSelectMultiple, または SelectMultiple (または value_omitted_from_data() メソッドが常に False を返すカスタムウィジェット) を使用するフィールドには適用されません。チェックされていないチェックボックスと、選択されていない <select multiple> は HTML フォーム送信のデータには表示されないからです。 API を設計していて、これらのウィジェットを使用するフィールドのデフォルトのフォールバック動作が必要な場合は、カスタムフォームフィールドまたはウィジェットを使用します。
この save() には、省略可能な commit キーワード引数があり、True ないし False を取ります。save() を commit=False で呼び出した場合、データベースにまだ保存されていないオブジェクトを返します。この場合、結果のモデルインスタンスで save() を呼び出すかどうかはあなた次第です。これは、保存前にオブジェクトで独自のプロセスを実行したい場合、もしくは特別な モデル保存オプション を使いたい場合に有用です。 commit はデフォルトでは True です。
commit=False を使う際のもう 1 つの副作用は、モデルに他のモデルとの多対多の関係がある場合に見られます。フォームを save するときにモデルに多対多の関係があり commit=False を指定した場合、Django は多対多の関係に対してフォームのデータを即座に保存することができません。これは、インスタンスがデータベース上に存在するようになるまで、インスタンスに対して多対多のデータを保存することが不可能だからです。
この問題を扱うために、commit=False を使ったフォームを save するたびに、Django は save_m2m() メソッドをあなたの ModelForm サブクラスに追加します。フォームによって生成されたインスタンスを手動で save した後に、多対多のフォームデータを保存するには save_m2m() を実行します。例えば:
# Create a form instance with POST data.\n>>> f = AuthorForm(request.POST)\n\n# Create, but don't save the new author instance.\n>>> new_author = f.save(commit=False)\n\n# Modify the author in some way.\n>>> new_author.some_field = "some_value"\n\n# Save the new instance.\n>>> new_author.save()\n\n# Now, save the many-to-many data for the form.\n>>> f.save_m2m()\nsave_m2m() を呼び出す必要があるのは save(commit=False) を使ったときだけです。フォーム上で save() を使用すると、多対多のデータを含むすべてのデータが保存されます。 たとえば:
# Create a form instance with POST data.\n>>> a = Author()\n>>> f = AuthorForm(request.POST, instance=a)\n\n# Create and save the new author instance. There's no need to do anything else.\n>>> new_author = f.save()\nsave() と save_m2m() メソッドのほかは、ModelForm は forms のフォームとまったく同じ方法で動作します。例えば、is_valid() メソッドは妥当性をチェックするために使用される、is_multipart() メソッドはフォームがマルチパートのファイルアップロードを必要とするかどうかを (ゆえに request.FILES がフォームに渡される必要があるかどうかも) 決める、などです。詳しくは アップロードされたファイルをフォームにバインドする を参照してください。
fields 属性を使って、フォームで編集すべき全てのフィールドを明示的に指定することを強くお勧めします。そうしないと、フォームで予期せず特定のフィールドを設定できるようになり、セキュリティ上の問題が発生しやすくなります。特に新しいフィールドがモデルに追加されたときに起こりがちです。フォームのレンダリング方法によっては、Webページで問題が目に見えないことさえあります。
別のアプローチとしては、すべてのフィールドを自動的に含めるか、一部のフィールドだけを削除する方法があります。この基本的なアプローチは安全性がかなり低いことが知られており、主要なウェブサイトで深刻な悪用が行われています (GitHub など)。
\nしかし、これらのセキュリティ上の懸念があなたに当てはまらないと保証できる場合には、2 つのショートカットが利用可能です:
\nfields 属性に、特殊な値 '__all__' をセットして、モデル内の全てのフィールドが使われるように指定します。例えば:
from django.forms import ModelForm\n\n\nclass AuthorForm(ModelForm):\n class Meta:\n model = Author\n fields = "__all__"\nModelForm の中の Meta クラスの exclude 属性に、フォームから除外されるフィールドのリストをセットします。
例:
\nclass PartialAuthorForm(ModelForm):\n class Meta:\n model = Author\n exclude = ["title"]\nAuthor モデルは 3 つのフィールド name、title、birth_date を持っているため、これで name と birth_date がフォームに表示されることになります。
このどちらかが使われた場合、フォーム内で表示されるフィールドの順番はモデル内でフィールドが定義された順番となり、ManyToManyField インスタンスは最後に表示されます。
加えて、Django は以下のルールも適用します: モデルフィールドで editable=False をセットした場合、ModelForm を通じて生成された 全ての フォームはそのフィールドを含みません。
前述の Field types テーブルで説明したとおり、デフォルトのフィールドタイプは実用的なデフォルトです。モデルに DateField がある場合、フォーム内で DateField として表示したいことでしょう。しかし、ModelForm では、与えられたモデルに足してフォームフィールドを変更する柔軟性があります。
フィールドに対して独自のウィジェットを指定するには、内部の Meta クラスの widgets を使用してください。これは、フィールド名としジェットのクラスやインスタンスをマッピングするディクショナリです。
例えば、Authoer の name 属性に対する CharField を、デフォルトの <input type="text"> の代わりに <textarea> で表示したい場合、フィールドのウィジェットをオーバーライドします:
from django.forms import ModelForm, Textarea\nfrom myapp.models import Author\n\n\nclass AuthorForm(ModelForm):\n class Meta:\n model = Author\n fields = ["name", "title", "birth_date"]\n widgets = {\n "name": Textarea(attrs={"cols": 80, "rows": 20}),\n }\nwidgets 辞書はウィジェットのインスタンス（例: Textarea(...) ）またはクラス（例: Textarea）を受け付けます。空でない choices 属性を持つモデルフィールドでは widgets 辞書は無視されることに注意してください。この場合、フォームフィールドをオーバーライドして別のウィジェットを使用する必要があります。
同様に、フィールドをさらにカスタマイズしたい場合、内部の Meta クラスの labels、help_texts、error_messages と言った属性を指定できます。
例えば、name フィールドに対する文字列に直面する全てのユーザの文章をカスタマイズしたい場合:
from django.utils.translation import gettext_lazy as _\n\n\nclass AuthorForm(ModelForm):\n class Meta:\n model = Author\n fields = ["name", "title", "birth_date"]\n labels = {\n "name": _("Writer"),\n }\n help_texts = {\n "name": _("Some useful help text."),\n }\n error_messages = {\n "name": {\n "max_length": _("This writer's name is too long."),\n },\n }\nまた、 field_classes や formfield_callback を指定して、フォームがインスタンス化するフィールドのタイプをカスタマイズすることもできます。
例えば、slug フィールドに対して MySlugFormField を使いたい場合、以下のようにできます:
from django.forms import ModelForm\nfrom myapp.models import Article\n\n\nclass ArticleForm(ModelForm):\n class Meta:\n model = Article\n fields = ["pub_date", "headline", "content", "reporter", "slug"]\n field_classes = {\n "slug": MySlugFormField,\n }\nもしくは:
\nfrom django.forms import ModelForm\nfrom myapp.models import Article\n\n\ndef formfield_for_dbfield(db_field, **kwargs):\n if db_field.name == "slug":\n return MySlugFormField()\n return db_field.formfield(**kwargs)\n\n\nclass ArticleForm(ModelForm):\n class Meta:\n model = Article\n fields = ["pub_date", "headline", "content", "reporter", "slug"]\n formfield_callback = formfield_for_dbfield\n最後に、フィールドを完全に -- タイプ、バリデータ、必須かどうかなどを含めて -- コントロールしたい場合、通常の Form で行うのと同じようにフィールドを宣言的に指定することで実現できます。
フィールドのバリデータを指定したい場合、フィールドを宣言的に定義して validators パラメータを設定することで実現できます:
from django.forms import CharField, ModelForm\nfrom myapp.models import Article\n\n\nclass ArticleForm(ModelForm):\n slug = CharField(validators=[validate_slug])\n\n class Meta:\n model = Article\n fields = ["pub_date", "headline", "content", "reporter", "slug"]\nデフォルトでは、ModelForm 内のフィールドはデータをローカライズしません。フィールドのデータをローカライズするには、Meta クラスの localized_fields 属性が使用できます。
>>> from django.forms import ModelForm\n>>> from myapp.models import Author\n>>> class AuthorForm(ModelForm):\n... class Meta:\n... model = Author\n... localized_fields = ['birth_date']\nlocalized_fields が特殊な値 '__all__' にセットされた場合、全てのフィールドがローカライズされます。
基本的なフォームと同様に、 ModelForms を継承して拡張したり再利用したりすることができます。これは、モデルから派生した多くのフォームで使用するために、親クラスに追加フィールドや追加メソッドを宣言する必要がある場合に便利です。たとえば、以前の ArticleForm クラスを使います:
>>> class EnhancedArticleForm(ArticleForm):\n... def clean_pub_date(self): ...\n...\nこれは ArticleForm と同じように動作するフォームを作成しますが、pub_date フィールドのバリデーションとクリーニングが追加されます。
Meta.fields や Meta.exclude のリストを変更したい場合は、親の Meta インナークラスをサブクラス化することもできます:
>>> class RestrictedArticleForm(EnhancedArticleForm):\n... class Meta(ArticleForm.Meta):\n... exclude = ["body"]\n...\nこれは EnhancedArticleForm からの追加メソッドを追加し、1つのフィールドを削除するようにオリジナルの ArticleForm.Meta を修正します。
ただ、注意すべき点がいくつかあります。
\n通常の Python の名前解決ルールが適用されます。内部クラス Meta を宣言している基底クラスが複数ある場合、最初のものだけが使用されます。つまり、子クラスの Meta が存在する場合はそれが使用され、そうでない場合は最初の親の Meta などが使用されます。
Form と ModelForm の両方から同時に継承することは可能ですが、必ず ModelForm が MRO (Method Resolution Order) の中で最初に現れるようにする必要があります。なぜなら、これらのクラスは異なるメタクラスに依存しており、一つのクラスは一つのメタクラスしか持つことができないからです。
親クラスから継承した Field を宣言的に削除するには、サブクラスで名前を None に設定します。
このテクニックを使用できるのは、親クラスによって宣言的に定義されたフィールドからオプトアウトする場合のみです。 ModelForm メタクラスがデフォルトフィールドを生成するのを防ぐことはできません。デフォルトのフィールドからオプトアウトするには、 使うフィールドを選択する を参照してください。
通常のフォームと同様に、フォームのインスタンスを作成する際に initial パラメータを指定することで、フォームの初期データを指定できます。この方法で指定された初期値は、フォームフィールドからの初期値と、アタッチされたモデルインスタンスからの値の両方を上書きします。たとえば、下記のようにします:
>>> article = Article.objects.get(pk=1)\n>>> article.headline\n'My headline'\n>>> form = ArticleForm(initial={"headline": "Initial headline"}, instance=article)\n>>> form["headline"].value()\n'Initial headline'\nクラス定義ではなく、スタンドアロン関数 modelform_factory() を使って、与えられたモデルからフォームを作成することもできます。あまりカスタマイズをしないなら、こちらの方が便利でしょう:
>>> from django.forms import modelform_factory\n>>> from myapp.models import Book\n>>> BookForm = modelform_factory(Book, fields=["author", "title"])\nこれは既存のフォームを修正するためにも使用できます。たとえば、指定されたフィールドに使用するウィジェットを指定できます:
\n>>> from django.forms import Textarea\n>>> Form = modelform_factory(Book, form=BookForm, widgets={"title": Textarea()})\n含むフィールドは fields や exclude のキーワード引数、もしくは ModelForm 内部の Meta クラスの対応する属性を使って指定できます。ModelForm 使うフィールドを選択する ドキュメントを参照してください。
... 特定のフィールドのローカライズを有効にすることもできます:
\n>>> Form = modelform_factory(Author, form=AuthorForm, localized_fields=["birth_date"])\n通常のフォームセット のように、 Django は Django モデルでの作業をより便利にするために、いくつかの拡張 フォームセットクラスを提供しています。上の Author モデルを再利用してみましょう:
>>> from django.forms import modelformset_factory\n>>> from myapp.models import Author\n>>> AuthorFormSet = modelformset_factory(Author, fields=["name", "title"])\nfields を使用すると、フォームセットが指定されたフィールドだけを使うように制限されます。または、除外するフィールドを指定する "オプトアウト" アプローチをとることもできます:
>>> AuthorFormSet = modelformset_factory(Author, exclude=["birth_date"])\nこれは Author モデルに関連付けられたデータを扱うことができるフォームセットを作成します。通常のフォームセットと同じように動作します:
>>> formset = AuthorFormSet()\n>>> print(formset)\n<input type="hidden" name="form-TOTAL_FORMS" value="1" id="id_form-TOTAL_FORMS"><input type="hidden" name="form-INITIAL_FORMS" value="0" id="id_form-INITIAL_FORMS"><input type="hidden" name="form-MIN_NUM_FORMS" value="0" id="id_form-MIN_NUM_FORMS"><input type="hidden" name="form-MAX_NUM_FORMS" value="1000" id="id_form-MAX_NUM_FORMS">\n<div><label for="id_form-0-name">Name:</label><input id="id_form-0-name" type="text" name="form-0-name" maxlength="100"></div>\n<div><label for="id_form-0-title">Title:</label><select name="form-0-title" id="id_form-0-title">\n<option value="" selected>---------</option>\n<option value="MR">Mr.</option>\n<option value="MRS">Mrs.</option>\n<option value="MS">Ms.</option>\n</select><input type="hidden" name="form-0-id" id="id_form-0-id"></div>\nデフォルトでは、モデルからフォームセットを作成する場合、フォームセットはモデル内のすべてのオブジェクトを含むクエリセットを使用します (例 Author.objects.all()) 。 queryset 引数を使用することで、この動作をオーバーライドできます:
>>> formset = AuthorFormSet(queryset=Author.objects.filter(name__startswith="O"))\nもしくは、__init__ の中で self.queryset をセットするサブクラスを作成できます:
from django.forms import BaseModelFormSet\nfrom myapp.models import Author\n\n\nclass BaseAuthorFormSet(BaseModelFormSet):\n def __init__(self, *args, **kwargs):\n super().__init__(*args, **kwargs)\n self.queryset = Author.objects.filter(name__startswith="O")\nそして、ファクトリ関数に BaseAuthorFormSet クラスを渡します:
>>> AuthorFormSet = modelformset_factory(\n... Author, fields=["name", "title"], formset=BaseAuthorFormSet\n... )\n既存のモデルのインスタンスを 一切 含まないフォームセットを返したい場合は、空の QuerySet を指定します:
\n>>> AuthorFormSet(queryset=Author.objects.none())\nデフォルトでは、 modelformset_factory を使うと、 modelform_factory() を使ってモデルフォームが作成されます。多くの場合、カスタムモデルフォームを指定すると便利です。たとえば、カスタムバリデーションを持つカスタムモデルフォームを作成できます:
class AuthorForm(forms.ModelForm):\n class Meta:\n model = Author\n fields = ["name", "title"]\n\n def clean_name(self):\n # custom validation for the name field\n ...\n次に、モデルフォームをファクトリ関数に渡します:
\nAuthorFormSet = modelformset_factory(Author, form=AuthorForm)\n必ずしもカスタムモデルフォームを定義する必要はありません。 modelformset_factory 関数には modelform_factory に渡されるいくつかの引数があります。以下で説明します。
widgets を使って、フォームで使用するウィジェットを指定するLink to this heading#パラメータ widgets を使うことで、特定のフィールドに対して ModelForm のウィジェットクラスをカスタマイズするための値の辞書を指定できます。これは ModelForm の内部 Meta クラスの widgets 辞書と同じように動作します:
>>> AuthorFormSet = modelformset_factory(\n... Author,\n... fields=["name", "title"],\n... widgets={"name": Textarea(attrs={"cols": 80, "rows": 20})},\n... )\nlocalized_fields でフィールドのローカライズを有効にするLink to this heading#localized_fields パラメータを使って、フォームのフィールドのローカライズを有効にできます。
>>> AuthorFormSet = modelformset_factory(\n... Author, fields=['name', 'title', 'birth_date'],\n... localized_fields=['birth_date'])\nlocalized_fields が特殊な値 '__all__' にセットされた場合、全てのフィールドがローカライズされます。
通常のフォームセットと同様に、 modelformset_factory() によって返されるモデルフォームセットクラスをインスタンス化する際に initial パラメータを指定することで、 初期データ をフォームセット内のフォームに指定できます。しかし、モデルフォームセットでは、初期値は既存のモデルインスタンスにアタッチされていない余分なフォームにだけ適用されます。もし initial の長さが余分なフォームの数を超えた場合、余分な初期データは無視されます。初期データを持つ余分なフォームがユーザーによって変更されなかった場合、それらはバリデーションも保存もされません。
ModelForm と同様に、データをモデルオブジェクトとして保存できます。これはフォームセットの save() メソッドで行います:
# Create a formset instance with POST data.\n>>> formset = AuthorFormSet(request.POST)\n\n# Assuming all is valid, save the data.\n>>> instances = formset.save()\nsave() メソッドはデータベースに保存されたインスタンスを返します。指定したインスタンスのデータがバインドされたデータで変更されなかった場合、そのインスタンスはデータベースに保存されず、戻り値 (上記の例では instances) にも含まれません。
フォームにフィールドがない場合 (例えば除外されている場合など)、これらのフィールドは save() メソッドではセットされません。通常の ModelForms にも適用されるこの制限についての詳細は Selecting the fields to use を参照してください。
未保存のモデルインスタンスを返すには commit=False を渡します:
# don't save to the database\n>>> instances = formset.save(commit=False)\n>>> for instance in instances:\n... # do something with instance\n... instance.save()\n...\nこれにより、データベースに保存する前にインスタンスにデータを付加できます。フォームセットに ManyToManyField が含まれている場合は、 formset.save_m2m() を呼び出して、多対多のリレーションシップが適切に保存されるようにする必要があります。
save() を呼び出すと、モデルのフォームセットにはフォームセットの変更を表す3つの新しい属性が追加されます:
通常のフォームセットと同様に、 modelformset_factory() の max_num と extra パラメータを使って、表示される追加のフォームの数を制限できます。
max_num は既存のオブジェクトが表示されないようにするものではありません:
>>> Author.objects.order_by("name")\n<QuerySet [<Author: Charles Baudelaire>, <Author: Paul Verlaine>, <Author: Walt Whitman>]>\n\n>>> AuthorFormSet = modelformset_factory(Author, fields=["name"], max_num=1)\n>>> formset = AuthorFormSet(queryset=Author.objects.order_by("name"))\n>>> [x.name for x in formset.get_queryset()]\n['Charles Baudelaire', 'Paul Verlaine', 'Walt Whitman']\nまた、 extra=0 は新しいモデルインスタンスの作成を妨げるものではありません。 JavaScriptでフォームを追加 したり、追加のPOSTデータを送信したりすることができます。この方法については 新しいオブジェクトの作成を防ぐ を参照してください。
もし max_num の値が既存の関連オブジェクトの数よりも大きい場合、フォームの総数が max_num を超えない限り、最大 extra 個の空白のフォームがフォームセットに追加されます:
>>> AuthorFormSet = modelformset_factory(Author, fields=["name"], max_num=4, extra=2)\n>>> formset = AuthorFormSet(queryset=Author.objects.order_by("name"))\n>>> for form in formset:\n... print(form)\n...\n<div><label for="id_form-0-name">Name:</label><input id="id_form-0-name" type="text" name="form-0-name" value="Charles Baudelaire" maxlength="100"><input type="hidden" name="form-0-id" value="1" id="id_form-0-id"></div>\n<div><label for="id_form-1-name">Name:</label><input id="id_form-1-name" type="text" name="form-1-name" value="Paul Verlaine" maxlength="100"><input type="hidden" name="form-1-id" value="3" id="id_form-1-id"></div>\n<div><label for="id_form-2-name">Name:</label><input id="id_form-2-name" type="text" name="form-2-name" value="Walt Whitman" maxlength="100"><input type="hidden" name="form-2-id" value="2" id="id_form-2-id"></div>\n<div><label for="id_form-3-name">Name:</label><input id="id_form-3-name" type="text" name="form-3-name" maxlength="100"><input type="hidden" name="form-3-id" id="id_form-3-id"></div>\nmax_num の値が None (デフォルト) だった場合、表示されるフォームの上限は大きな数になります (1000)。この数は、実際には制限がないと見なせるでしょう。
edit_only パラメータを使用すると、新しいオブジェクトを作成しないようにすることができます:
>>> AuthorFormSet = modelformset_factory(\n... Author,\n... fields=["name", "title"],\n... edit_only=True,\n... )\nここでは、フォームセットは既存の Author インスタンスのみを編集します。他のオブジェクトは作成も編集もされません。
モデルのフォームセットはフォームセットにとても似ています。例えば、Author モデルのインスタンスを編集するフォームセットを表示したいとしましょう:
from django.forms import modelformset_factory\nfrom django.shortcuts import render\nfrom myapp.models import Author\n\n\ndef manage_authors(request):\n AuthorFormSet = modelformset_factory(Author, fields=["name", "title"])\n if request.method == "POST":\n formset = AuthorFormSet(request.POST, request.FILES)\n if formset.is_valid():\n formset.save()\n # do something.\n else:\n formset = AuthorFormSet()\n return render(request, "manage_authors.html", {"formset": formset})\n見てのとおり、モデルフォームセットのビューロジックは、「通常の」フォームセットと大きく異なるものではありません。唯一の違いは、 formset.save() を呼び出してデータをデータベースに保存できることです。(これは上記の フォームセット内のオブジェクトを保存する で説明しています)。
ModelFormSet の clean() をオーバーライドするLink to this heading#モデルフォームの ModelForms と同様に、デフォルトでは ModelFormSet の clean() メソッドは、フォームセット内のアイテムがモデルのユニーク制約 (unique, unique_together または unique_for_date|month|year) に違反していないことを検証します。 もし ModelFormSet の clean() メソッドをオーバーライドし、この検証を維持したい場合は、親クラスの clean メソッドを呼び出す必要があります:
from django.forms import BaseModelFormSet\n\n\nclass MyModelFormSet(BaseModelFormSet):\n def clean(self):\n super().clean()\n # example custom validation across forms in the formset\n for form in self.forms:\n # your custom formset validation\n ...\nまた、このステップに到達するまでに、各 Form に対して個別のモデルインスタンスが既に作成されていることに注意してください。 form.cleaned_data の値を変更するだけでは、保存された値に影響を与えることはできません。 ModelFormSet.clean() の値を変更したい場合は、 form.instance を変更する必要があります:
from django.forms import BaseModelFormSet\n\n\nclass MyModelFormSet(BaseModelFormSet):\n def clean(self):\n super().clean()\n\n for form in self.forms:\n name = form.cleaned_data["name"].upper()\n form.cleaned_data["name"] = name\n # update the instance value.\n form.instance.name = name\n前述のように、モデルのフォームセットで使われるデフォルトのクエリセットはオーバーライドできます:
\nfrom django.forms import modelformset_factory\nfrom django.shortcuts import render\nfrom myapp.models import Author\n\n\ndef manage_authors(request):\n AuthorFormSet = modelformset_factory(Author, fields=["name", "title"])\n queryset = Author.objects.filter(name__startswith="O")\n if request.method == "POST":\n formset = AuthorFormSet(\n request.POST,\n request.FILES,\n queryset=queryset,\n )\n if formset.is_valid():\n formset.save()\n # Do something.\n else:\n formset = AuthorFormSet(queryset=queryset)\n return render(request, "manage_authors.html", {"formset": formset})\nこの例では POST と GET の両方で queryset 引数を渡していることに注意してください。
Django テンプレートでフォームセットをレンダリングするには 3 つの方法があります。
\n1つめは、フォームセットにほとんどの作業を任せる方法です:
\n<form method="post">\n {{ formset }}\n</form>\n2 つめは、フォームセットを手動でレンダリングして、フォーム自身に処理させる方法です:
\n<form method="post">\n {{ formset.management_form }}\n {% for form in formset %}\n {{ form }}\n {% endfor %}\n</form>\n手動でフォームをレンダリングする場合は、必ず上記のように管理フォームをレンダリングしてください。 管理フォームのドキュメント を参照してください。
\n3 つめは、各フィールドを手動でレンダリングする方法です:
\n<form method="post">\n {{ formset.management_form }}\n {% for form in formset %}\n {% for field in form %}\n {{ field.label_tag }} {{ field }}\n {% endfor %}\n {% endfor %}\n</form>\nこの3つめのメソッドを使用し、 {% for %} ループでフィールドをイテレートしない場合、主キーフィールドをレンダリングする必要があります。たとえば、モデルの name フィールドと age フィールドをレンダリングする場合、以下のようにします:
<form method="post">\n {{ formset.management_form }}\n {% for form in formset %}\n {{ form.id }}\n <ul>\n <li>{{ form.name }}</li>\n <li>{{ form.age }}</li>\n </ul>\n {% endfor %}\n</form>\n明示的に {{ form.id }} をレンダリングする必要があることに注意してください。これにより、POST の場合のモデルのフォームセットが正しく動作するようになります。(この例では id という主キーを想定しています。もし id という名前ではない独自の主キーを明示的に定義している場合は、それが確実にレンダリングされるようにしてください)。
インラインフォームセットは、モデルフォームセット上の小さな抽象化レイヤーです。これを使うと、外部キーで関連するオブジェクトを操作することが簡単になります。以下の 2 つのモデルがあるとします:
\nfrom django.db import models\n\n\nclass Author(models.Model):\n name = models.CharField(max_length=100)\n\n\nclass Book(models.Model):\n author = models.ForeignKey(Author, on_delete=models.CASCADE)\n title = models.CharField(max_length=100)\n特定の著者の本を編集できるフォームセットを作成したい場合、下記のように書くことができます:
\n>>> from django.forms import inlineformset_factory\n>>> BookFormSet = inlineformset_factory(Author, Book, fields=["title"])\n>>> author = Author.objects.get(name="Mike Royko")\n>>> formset = BookFormSet(instance=author)\nBookFormSet の prefix は 'book_set' (<model name>_set) です。ただし、 Book の Author への ForeignKey に related_name がある場合、その名前が代わりに使用されます。
InlineFormSet のメソッドをオーバーライドするLink to this heading#InlineFormSet のメソッドをオーバーライドするには、 BaseModelFormSet ではなく、 BaseInlineFormSet をサブクラス化します。
例えば、 clean() をオーバーライドするとします:
from django.forms import BaseInlineFormSet\n\n\nclass CustomInlineFormSet(BaseInlineFormSet):\n def clean(self):\n super().clean()\n # example custom validation across forms in the formset\n for form in self.forms:\n # your custom formset validation\n ...\nModelFormSet の clean() をオーバーライドする も参照してください。
\nそして、インラインフォームセットを作成するときに、オプションの引数 formset を渡します:
>>> from django.forms import inlineformset_factory\n>>> BookFormSet = inlineformset_factory(\n... Author, Book, fields=["title"], formset=CustomInlineFormSet\n... )\n>>> author = Author.objects.get(name="Mike Royko")\n>>> formset = BookFormSet(instance=author)\n同じモデルが 1 つよりも多くの外部キーを持っている場合、 fk_name を使い手動で曖昧さを解消しなければなりません。例として、次のモデルについて考えます:
class Friendship(models.Model):\n from_friend = models.ForeignKey(\n Friend,\n on_delete=models.CASCADE,\n related_name="from_friends",\n )\n to_friend = models.ForeignKey(\n Friend,\n on_delete=models.CASCADE,\n related_name="friends",\n )\n length_in_months = models.IntegerField()\nこれを解決するには、 inlineformset_factory() に fk_name を使用します:
>>> FriendshipFormSet = inlineformset_factory(\n... Friend, Friendship, fk_name="from_friend", fields=["to_friend", "length_in_months"]\n... )\nモデルに紐付いたオブジェクトを編集する機能をユーザーに提供するビューを作るには、こうします:
\ndef manage_books(request, author_id):\n author = Author.objects.get(pk=author_id)\n BookInlineFormSet = inlineformset_factory(Author, Book, fields=["title"])\n if request.method == "POST":\n formset = BookInlineFormSet(request.POST, request.FILES, instance=author)\n if formset.is_valid():\n formset.save()\n # Do something. Should generally end with a redirect. For example:\n return HttpResponseRedirect(author.get_absolute_url())\n else:\n formset = BookInlineFormSet(instance=author)\n return render(request, "manage_books.html", {"formset": formset})\nPOST と GET いずれにおいても instance を渡していることに注目してください
inlineformset_factory は modelformset_factory を使っており、多くの引数は modelformset_factory に渡されます。これは modelformset_factory と同様に、 widgets 引数を渡すことができることを意味しています。詳細は、上記 Specifying widgets to use in the form with widgets を参照してください。