```
もし、`max_num` の値が初期データ内に存在するオブジェクトの合計より大きい場合、 `extra` を上限として空のフォームがフォームセットに追加されます。 フォームの合計の長さは `max_num` を超えることはできません。例えば、`extra=2` と `max_num=2`、そしてフォームセットが 1 つの `initial` 項目で初期化される場合、この初期項目のフォームと 1 つの空のフォームが表示されます。
初期データ内の項目数が `max_num` を超える場合、`max_num` の値に関わらず全ての初期データのフォームが表示され、追加フォームは 1 つも表示されません。例えば、`extra=3` と `max_num=1`、そしてフォームセットが 2 つの初期項目で初期化される場合、2 つのフォームが初期データとともに表示されます。
`max_num` の値が `None` (デフォルト) だった場合、表示されるフォームの上限は大きな数になります (1000)。この数は、実際には制限がないと見なせるでしょう。
デフォルトでは、`max_num` はいくつのフォームが表示されるかだけに影響し、バリデーションには影響しません。`validate_max=True` が [`formset_factory()`](/ja/2.0/ref/forms/formsets/#django.forms.formsets.formset_factory) に渡される場合は、`max_num` はバリデーションに影響します。[validate\_max](#validate-max) をご覧ください。
## フォームセットのバリデーション
フォームセットのバリデーションは、普通の `Form` とほぼ同じです。フォームセットにも `is_valid` メソッドがあり、フォームセット内の全てのフォームを簡単に検証できます。
```
>>> from django.forms import formset_factory
>>> from myapp.forms import ArticleForm
>>> ArticleFormSet = formset_factory(ArticleForm)
>>> data = {
... 'form-TOTAL_FORMS': '1',
... 'form-INITIAL_FORMS': '0',
... 'form-MAX_NUM_FORMS': '',
... }
>>> formset = ArticleFormSet(data)
>>> formset.is_valid()
True
```
この例では、フォームセットにデータを渡さなかったので、有効なフォームを返しています。フォームセットは賢くて、データの変更されなかったフォームを無視してくれます。不適切な記事を提供しようとすると、以下のようになります。
```
>>> data = {
... 'form-TOTAL_FORMS': '2',
... 'form-INITIAL_FORMS': '0',
... 'form-MAX_NUM_FORMS': '',
... 'form-0-title': 'Test',
... 'form-0-pub_date': '1904-06-16',
... 'form-1-title': 'Test',
... 'form-1-pub_date': '', # <-- this date is missing but required
... }
>>> formset = ArticleFormSet(data)
>>> formset.is_valid()
False
>>> formset.errors
[{}, {'pub_date': ['This field is required.']}]
```
見て分かるように、 `formset.errors` はリストで、 そのエントリーはフォームセット内のフォームと一致します。 バリデーションは、2 つのフォームそれぞれに働いて、2 つ目の項目にエラーメッセージが表示されています。
通常の `Form` を使うときとまったく同じように、フォームセットのフォーム内のそれぞれのフィールドは、ブラウザのバリデーションのための `maxlength` のような HTML 属性を含むことができます。ただし、フォームセットのフォームフィールドは、`required` 属性を含みません。これは、フォームを追加したり削除するときにバリデーションが正しく働かない可能性があるためです。
#### `BaseFormSet.total_error_count()`
フォームセット内にいくつのエラーがあるかを確かめるためには、`total_error_count` メソッドが使えます。
```
>>> # Using the previous example
>>> formset.errors
[{}, {'pub_date': ['This field is required.']}]
>>> len(formset.errors)
2
>>> formset.total_error_count()
1
```
また、フォームに入力されたデータと初期データが異なっているかどうかもチェックできます (たとえば、フォームがデータなしで送信された場合など)。
```
>>> data = {
... 'form-TOTAL_FORMS': '1',
... 'form-INITIAL_FORMS': '0',
... 'form-MAX_NUM_FORMS': '',
... 'form-0-title': '',
... 'form-0-pub_date': '',
... }
>>> formset = ArticleFormSet(data)
>>> formset.has_changed()
False
```
### `ManagementForm` を理解する
上記のフォームセットのデータで必要とされた追加のデータ (`form-TOTAL_FORMS`, `form-INITIAL_FORMS` そして `form-MAX_NUM_FORMS`) に気付いているかもしれません。 このデータは `ManagementForm` に必要です。 このフォームは、formsetに含まれているフォームのコレクションを管理するためにformsetによって使用されます。 この管理データを提供しない場合、例外が発生します。
```
>>> data = {
... 'form-0-title': 'Test',
... 'form-0-pub_date': '',
... }
>>> formset = ArticleFormSet(data)
>>> formset.is_valid()
Traceback (most recent call last):
...
django.forms.utils.ValidationError: ['ManagementForm data is missing or has been tampered with']
```
これは、表示されているフォームインスタンスの数を追跡するために使用されます。 JavaScriptを使用して新しいフォームを追加する場合は、フォームのカウントフィールドもインクリメントする必要があります。 一方、既存のオブジェクトの削除を許可するためにJavaScriptを使用している場合は、`POST` データに `form-#-DELETE` を含めることで、削除対象のマークが適切に削除されていることを確認する必要があります。 すべてのフォームがそれにかかわらず `POST` データに存在することが期待されます。
ManagementFormは、フォームセット自体の属性として使用できます。 テンプレートでフォームセットをレンダリングするときは、`{{ my_formset.management_form }}` (my\_formsetは適切な名前に置き換えます)をレンダリングすることで、すべての管理データを含めることができます。
### `total_form_count` and `initial_form_count`
`BaseFormSet` has a couple of methods that are closely related to the
`ManagementForm`, `total_form_count` and `initial_form_count`.
`total_form_count` returns the total number of forms in this formset.
`initial_form_count` returns the number of forms in the formset that were
pre-filled, and is also used to determine how many forms are required. You
will probably never need to override either of these methods, so please be
sure you understand what they do before doing so.
### `empty_form`
`BaseFormSet` provides an additional attribute `empty_form` which returns
a form instance with a prefix of `__prefix__` for easier use in dynamic
forms with JavaScript.
### Custom formset validation
A formset has a `clean` method similar to the one on a `Form` class. This
is where you define your own validation that works at the formset level:
```
>>> from django.forms import BaseFormSet
>>> from django.forms import formset_factory
>>> from myapp.forms import ArticleForm
>>> class BaseArticleFormSet(BaseFormSet):
... def clean(self):
... """Checks that no two articles have the same title."""
... if any(self.errors):
... # Don't bother validating the formset unless each form is valid on its own
... return
... titles = []
... for form in self.forms:
... title = form.cleaned_data['title']
... if title in titles:
... raise forms.ValidationError("Articles in a set must have distinct titles.")
... titles.append(title)
>>> ArticleFormSet = formset_factory(ArticleForm, formset=BaseArticleFormSet)
>>> data = {
... 'form-TOTAL_FORMS': '2',
... 'form-INITIAL_FORMS': '0',
... 'form-MAX_NUM_FORMS': '',
... 'form-0-title': 'Test',
... 'form-0-pub_date': '1904-06-16',
... 'form-1-title': 'Test',
... 'form-1-pub_date': '1912-06-23',
... }
>>> formset = ArticleFormSet(data)
>>> formset.is_valid()
False
>>> formset.errors
[{}, {}]
>>> formset.non_form_errors()
['Articles in a set must have distinct titles.']
```
The formset `clean` method is called after all the `Form.clean` methods
have been called. The errors will be found using the `non_form_errors()`
method on the formset.
## Validating the number of forms in a formset
Django provides a couple ways to validate the minimum or maximum number of
submitted forms. Applications which need more customizable validation of the
number of forms should use custom formset validation.
### `validate_max`
If `validate_max=True` is passed to
[`formset_factory()`](/ja/2.0/ref/forms/formsets/#django.forms.formsets.formset_factory), validation will also check
that the number of forms in the data set, minus those marked for
deletion, is less than or equal to `max_num`.
```
>>> from django.forms import formset_factory
>>> from myapp.forms import ArticleForm
>>> ArticleFormSet = formset_factory(ArticleForm, max_num=1, validate_max=True)
>>> data = {
... 'form-TOTAL_FORMS': '2',
... 'form-INITIAL_FORMS': '0',
... 'form-MIN_NUM_FORMS': '',
... 'form-MAX_NUM_FORMS': '',
... 'form-0-title': 'Test',
... 'form-0-pub_date': '1904-06-16',
... 'form-1-title': 'Test 2',
... 'form-1-pub_date': '1912-06-23',
... }
>>> formset = ArticleFormSet(data)
>>> formset.is_valid()
False
>>> formset.errors
[{}, {}]
>>> formset.non_form_errors()
['Please submit 1 or fewer forms.']
```
`validate_max=True` validates against `max_num` strictly even if
`max_num` was exceeded because the amount of initial data supplied was
excessive.
> **Note**
>
> Regardless of `validate_max`, if the number of forms in a data set
> exceeds `max_num` by more than 1000, then the form will fail to validate
> as if `validate_max` were set, and additionally only the first 1000
> forms above `max_num` will be validated. The remainder will be
> truncated entirely. This is to protect against memory exhaustion attacks
> using forged POST requests.
### `validate_min`
If `validate_min=True` is passed to
[`formset_factory()`](/ja/2.0/ref/forms/formsets/#django.forms.formsets.formset_factory), validation will also check
that the number of forms in the data set, minus those marked for
deletion, is greater than or equal to `min_num`.
```
>>> from django.forms import formset_factory
>>> from myapp.forms import ArticleForm
>>> ArticleFormSet = formset_factory(ArticleForm, min_num=3, validate_min=True)
>>> data = {
... 'form-TOTAL_FORMS': '2',
... 'form-INITIAL_FORMS': '0',
... 'form-MIN_NUM_FORMS': '',
... 'form-MAX_NUM_FORMS': '',
... 'form-0-title': 'Test',
... 'form-0-pub_date': '1904-06-16',
... 'form-1-title': 'Test 2',
... 'form-1-pub_date': '1912-06-23',
... }
>>> formset = ArticleFormSet(data)
>>> formset.is_valid()
False
>>> formset.errors
[{}, {}]
>>> formset.non_form_errors()
['Please submit 3 or more forms.']
```
## Dealing with ordering and deletion of forms
The [`formset_factory()`](/ja/2.0/ref/forms/formsets/#django.forms.formsets.formset_factory) provides two optional
parameters `can_order` and `can_delete` to help with ordering of forms in
formsets and deletion of forms from a formset.
### `can_order`
#### `BaseFormSet.can_order`
デフォルト値: `False`
Lets you create a formset with the ability to order:
```
>>> from django.forms import formset_factory
>>> from myapp.forms import ArticleForm
>>> ArticleFormSet = formset_factory(ArticleForm, can_order=True)
>>> formset = ArticleFormSet(initial=[
... {'title': 'Article #1', 'pub_date': datetime.date(2008, 5, 10)},
... {'title': 'Article #2', 'pub_date': datetime.date(2008, 5, 11)},
... ])
>>> for form in formset:
... print(form.as_table())
```
This adds an additional field to each form. This new field is named `ORDER`
and is an `forms.IntegerField`. For the forms that came from the initial
data it automatically assigned them a numeric value. Let's look at what will
happen when the user changes these values:
```
>>> data = {
... 'form-TOTAL_FORMS': '3',
... 'form-INITIAL_FORMS': '2',
... 'form-MAX_NUM_FORMS': '',
... 'form-0-title': 'Article #1',
... 'form-0-pub_date': '2008-05-10',
... 'form-0-ORDER': '2',
... 'form-1-title': 'Article #2',
... 'form-1-pub_date': '2008-05-11',
... 'form-1-ORDER': '1',
... 'form-2-title': 'Article #3',
... 'form-2-pub_date': '2008-05-01',
... 'form-2-ORDER': '0',
... }
>>> formset = ArticleFormSet(data, initial=[
... {'title': 'Article #1', 'pub_date': datetime.date(2008, 5, 10)},
... {'title': 'Article #2', 'pub_date': datetime.date(2008, 5, 11)},
... ])
>>> formset.is_valid()
True
>>> for form in formset.ordered_forms:
... print(form.cleaned_data)
{'pub_date': datetime.date(2008, 5, 1), 'ORDER': 0, 'title': 'Article #3'}
{'pub_date': datetime.date(2008, 5, 11), 'ORDER': 1, 'title': 'Article #2'}
{'pub_date': datetime.date(2008, 5, 10), 'ORDER': 2, 'title': 'Article #1'}
```
### `can_delete`
#### `BaseFormSet.can_delete`
デフォルト値: `False`
Lets you create a formset with the ability to select forms for deletion:
```
>>> from django.forms import formset_factory
>>> from myapp.forms import ArticleForm
>>> ArticleFormSet = formset_factory(ArticleForm, can_delete=True)
>>> formset = ArticleFormSet(initial=[
... {'title': 'Article #1', 'pub_date': datetime.date(2008, 5, 10)},
... {'title': 'Article #2', 'pub_date': datetime.date(2008, 5, 11)},
... ])
>>> for form in formset:
... print(form.as_table())
```
Similar to `can_order` this adds a new field to each form named `DELETE`
and is a `forms.BooleanField`. When data comes through marking any of the
delete fields you can access them with `deleted_forms`:
```
>>> data = {
... 'form-TOTAL_FORMS': '3',
... 'form-INITIAL_FORMS': '2',
... 'form-MAX_NUM_FORMS': '',
... 'form-0-title': 'Article #1',
... 'form-0-pub_date': '2008-05-10',
... 'form-0-DELETE': 'on',
... 'form-1-title': 'Article #2',
... 'form-1-pub_date': '2008-05-11',
... 'form-1-DELETE': '',
... 'form-2-title': '',
... 'form-2-pub_date': '',
... 'form-2-DELETE': '',
... }
>>> formset = ArticleFormSet(data, initial=[
... {'title': 'Article #1', 'pub_date': datetime.date(2008, 5, 10)},
... {'title': 'Article #2', 'pub_date': datetime.date(2008, 5, 11)},
... ])
>>> [form.cleaned_data for form in formset.deleted_forms]
[{'DELETE': True, 'pub_date': datetime.date(2008, 5, 10), 'title': 'Article #1'}]
```
If you are using a [`ModelFormSet`](/ja/2.0/topics/forms/modelforms/#django.forms.models.BaseModelFormSet),
model instances for deleted forms will be deleted when you call
`formset.save()`.
If you call `formset.save(commit=False)`, objects will not be deleted
automatically. You'll need to call `delete()` on each of the
[`formset.deleted_objects`](/ja/2.0/topics/forms/modelforms/#django.forms.models.BaseModelFormSet.deleted_objects) to actually delete
them:
```
>>> instances = formset.save(commit=False)
>>> for obj in formset.deleted_objects:
... obj.delete()
```
On the other hand, if you are using a plain `FormSet`, it's up to you to
handle `formset.deleted_forms`, perhaps in your formset's `save()` method,
as there's no general notion of what it means to delete a form.
## Adding additional fields to a formset
If you need to add additional fields to the formset this can be easily
accomplished. The formset base class provides an `add_fields` method. You
can simply override this method to add your own fields or even redefine the
default fields/attributes of the order and deletion fields:
```
>>> from django.forms import BaseFormSet
>>> from django.forms import formset_factory
>>> from myapp.forms import ArticleForm
>>> class BaseArticleFormSet(BaseFormSet):
... def add_fields(self, form, index):
... super().add_fields(form, index)
... form.fields["my_field"] = forms.CharField()
>>> ArticleFormSet = formset_factory(ArticleForm, formset=BaseArticleFormSet)
>>> formset = ArticleFormSet()
>>> for form in formset:
... print(form.as_table())
```
## Passing custom parameters to formset forms
Sometimes your form class takes custom parameters, like `MyArticleForm`.
You can pass this parameter when instantiating the formset:
```
>>> from django.forms import BaseFormSet
>>> from django.forms import formset_factory
>>> from myapp.forms import ArticleForm
>>> class MyArticleForm(ArticleForm):
... def __init__(self, *args, user, **kwargs):
... self.user = user
... super().__init__(*args, **kwargs)
>>> ArticleFormSet = formset_factory(MyArticleForm)
>>> formset = ArticleFormSet(form_kwargs={'user': request.user})
```
The `form_kwargs` may also depend on the specific form instance. The formset
base class provides a `get_form_kwargs` method. The method takes a single
argument - the index of the form in the formset. The index is `None` for the
[empty\_form](#empty-form):
```
>>> from django.forms import BaseFormSet
>>> from django.forms import formset_factory
>>> class BaseArticleFormSet(BaseFormSet):
... def get_form_kwargs(self, index):
... kwargs = super().get_form_kwargs(index)
... kwargs['custom_kwarg'] = index
... return kwargs
```
## Customizing a formset's prefix
In the rendered HTML, formsets include a prefix on each field's name. By
default, the prefix is `'form'`, but it can be customized using the formset's
`prefix` argument.
For example, in the default case, you might see:
```html
```
But with `ArticleFormset(prefix='article')` that becomes:
```html
```
This is useful if you want to [use more than one formset in a view](#multiple-formsets-in-view).
## Using a formset in views and templates
Using a formset inside a view is as easy as using a regular `Form` class.
The only thing you will want to be aware of is making sure to use the
management form inside the template. Let's look at a sample view:
```
from django.forms import formset_factory
from django.shortcuts import render
from myapp.forms import ArticleForm
def manage_articles(request):
ArticleFormSet = formset_factory(ArticleForm)
if request.method == 'POST':
formset = ArticleFormSet(request.POST, request.FILES)
if formset.is_valid():
# do something with the formset.cleaned_data
pass
else:
formset = ArticleFormSet()
return render(request, 'manage_articles.html', {'formset': formset})
```
The `manage_articles.html` template might look like this:
```html+django
```
However there's a slight shortcut for the above by letting the formset itself
deal with the management form:
```html+django
```
The above ends up calling the `as_table` method on the formset class.
### Manually rendered `can_delete` and `can_order`
If you manually render fields in the template, you can render
`can_delete` parameter with `{{ form.DELETE }}`:
```html+django
```
Similarly, if the formset has the ability to order (`can_order=True`), it is
possible to render it with `{{ form.ORDER }}`.
### Using more than one formset in a view
You are able to use more than one formset in a view if you like. Formsets
borrow much of its behavior from forms. With that said you are able to use
`prefix` to prefix formset form field names with a given value to allow
more than one formset to be sent to a view without name clashing. Lets take
a look at how this might be accomplished:
```
from django.forms import formset_factory
from django.shortcuts import render
from myapp.forms import ArticleForm, BookForm
def manage_articles(request):
ArticleFormSet = formset_factory(ArticleForm)
BookFormSet = formset_factory(BookForm)
if request.method == 'POST':
article_formset = ArticleFormSet(request.POST, request.FILES, prefix='articles')
book_formset = BookFormSet(request.POST, request.FILES, prefix='books')
if article_formset.is_valid() and book_formset.is_valid():
# do something with the cleaned_data on the formsets.
pass
else:
article_formset = ArticleFormSet(prefix='articles')
book_formset = BookFormSet(prefix='books')
return render(request, 'manage_articles.html', {
'article_formset': article_formset,
'book_formset': book_formset,
})
```
You would then render the formsets as normal. It is important to point out
that you need to pass `prefix` on both the POST and non-POST cases so that
it is rendered and processed correctly.
Each formset's [prefix](#formset-prefix) replaces the default `form`
prefix that's added to each field's `name` and `id` HTML attributes.