diff --git a/docs/topics/forms/modelforms.txt b/docs/topics/forms/modelforms.txt
index c48680b60f..a56a47f848 100644
--- a/docs/topics/forms/modelforms.txt
+++ b/docs/topics/forms/modelforms.txt
@@ -665,7 +665,7 @@ There are a couple of things to note, however.
You can only use this technique to opt out from a field defined declaratively
by a parent class; it won't prevent the ``ModelForm`` metaclass from generating
a default field. To opt-out from default fields, see
- :ref:`controlling-fields-with-fields-and-exclude`.
+ :ref:`modelforms-selecting-fields`.
.. _modelforms-factory:
@@ -710,7 +710,19 @@ reuse the ``Author`` model from above::
>>> from django.forms.models import modelformset_factory
>>> from myapp.models import Author
- >>> AuthorFormSet = modelformset_factory(Author)
+ >>> AuthorFormSet = modelformset_factory(Author, fields=('name', 'title'))
+
+Using ``fields`` restricts the formset to use only the given fields.
+Alternatively, you can take an "opt-out" approach, specifying which fields to
+exclude::
+
+ >>> AuthorFormSet = modelformset_factory(Author, exclude=('birth_date',))
+
+.. versionchanged:: 1.8
+
+ In older versions, omitting both ``fields`` and ``exclude`` resulted in
+ a formset with all the model's fields. Doing this now raises an
+ :exc:`~django.core.exceptions.ImproperlyConfigured` exception.
This will create a formset that is capable of working with the data associated
with the ``Author`` model. It works just like a regular formset::
@@ -724,8 +736,7 @@ with the ``Author`` model. It works just like a regular formset::
<option value="MR">Mr.</option>
<option value="MRS">Mrs.</option>
<option value="MS">Ms.</option>
- </select></td></tr>
- <tr><th><label for="id_form-0-birth_date">Birth date:</label></th><td><input type="text" name="form-0-birth_date" id="id_form-0-birth_date" /><input type="hidden" name="form-0-id" id="id_form-0-id" /></td></tr>
+ </select><input type="hidden" name="form-0-id" id="id_form-0-id" /></td></tr>
.. note::
@@ -757,7 +768,8 @@ Alternatively, you can create a subclass that sets ``self.queryset`` in
Then, pass your ``BaseAuthorFormSet`` class to the factory function::
- >>> AuthorFormSet = modelformset_factory(Author, formset=BaseAuthorFormSet)
+ >>> AuthorFormSet = modelformset_factory(
+ ... Author, fields=('name', 'title'), formset=BaseAuthorFormSet)
If you want to return a formset that doesn't include *any* pre-existing
instances of the model, you can specify an empty QuerySet::
@@ -789,22 +801,6 @@ It is not always necessary to define a custom model form. The
``modelformset_factory`` function has several arguments which are
passed through to ``modelform_factory``, which are described below.
-.. _controlling-fields-with-fields-and-exclude:
-
-Controlling which fields are used with ``fields`` and ``exclude``
------------------------------------------------------------------
-
-By default, a model formset uses all fields in the model that are not marked
-with ``editable=False``. However, this can be overridden at the formset level::
-
- >>> AuthorFormSet = modelformset_factory(Author, fields=('name', 'title'))
-
-Using ``fields`` restricts the formset to use only the given fields.
-Alternatively, you can take an "opt-out" approach, specifying which fields to
-exclude::
-
- >>> AuthorFormSet = modelformset_factory(Author, exclude=('birth_date',))
-
Specifying widgets to use in the form with ``widgets``
------------------------------------------------------
@@ -814,7 +810,8 @@ works the same way as the ``widgets`` dictionary on the inner ``Meta``
class of a ``ModelForm`` works::
>>> AuthorFormSet = modelformset_factory(
- ... Author, widgets={'name': Textarea(attrs={'cols': 80, 'rows': 20})
+ ... Author, fields=('name', 'title'),
+ ... widgets={'name': Textarea(attrs={'cols': 80, 'rows': 20})})
Enabling localization for fields with ``localized_fields``
----------------------------------------------------------
@@ -823,7 +820,8 @@ Using the ``localized_fields`` parameter, you can enable localization for
fields in the form.
>>> AuthorFormSet = modelformset_factory(
- ... Author, localized_fields=('value',))
+ ... Author, fields=('name', 'title', 'birth_date'),
+ ... localized_fields=('birth_date',))
If ``localized_fields`` is set to the special value ``'__all__'``, all fields
will be localized.
@@ -900,7 +898,7 @@ extra forms displayed.
>>> Author.objects.order_by('name')
[<Author: Charles Baudelaire>, <Author: Paul Verlaine>, <Author: Walt Whitman>]
- >>> AuthorFormSet = modelformset_factory(Author, max_num=1)
+ >>> AuthorFormSet = modelformset_factory(Author, fields=('name',), max_num=1)
>>> formset = AuthorFormSet(queryset=Author.objects.order_by('name'))
>>> [x.name for x in formset.get_queryset()]
['Charles Baudelaire', 'Paul Verlaine', 'Walt Whitman']
@@ -909,7 +907,7 @@ If the value of ``max_num`` is greater than the number of existing related
objects, up to ``extra`` additional blank forms will be added to the formset,
so long as the total number of forms does not exceed ``max_num``::
- >>> AuthorFormSet = modelformset_factory(Author, max_num=4, extra=2)
+ >>> AuthorFormSet = modelformset_factory(Author, fields=('name',), max_num=4, extra=2)
>>> formset = AuthorFormSet(queryset=Author.objects.order_by('name'))
>>> for form in formset:
... print(form.as_table())
@@ -932,7 +930,7 @@ formset to edit ``Author`` model instances::
from myapp.models import Author
def manage_authors(request):
- AuthorFormSet = modelformset_factory(Author)
+ AuthorFormSet = modelformset_factory(Author, fields=('name', 'title'))
if request.method == 'POST':
formset = AuthorFormSet(request.POST, request.FILES)
if formset.is_valid():
@@ -1000,7 +998,7 @@ formset::
from myapp.models import Author
def manage_authors(request):
- AuthorFormSet = modelformset_factory(Author)
+ AuthorFormSet = modelformset_factory(Author, fields=('name', 'title'))
if request.method == "POST":
formset = AuthorFormSet(request.POST, request.FILES,
queryset=Author.objects.filter(name__startswith='O'))
@@ -1100,7 +1098,7 @@ If you want to create a formset that allows you to edit books belonging to
a particular author, you could do this::
>>> from django.forms.models import inlineformset_factory
- >>> BookFormSet = inlineformset_factory(Author, Book)
+ >>> BookFormSet = inlineformset_factory(Author, Book, fields=('title',))
>>> author = Author.objects.get(name='Mike Royko')
>>> formset = BookFormSet(instance=author)
@@ -1139,7 +1137,8 @@ Then when you create your inline formset, pass in the optional argument
``formset``::
>>> from django.forms.models import inlineformset_factory
- >>> BookFormSet = inlineformset_factory(Author, Book, formset=CustomInlineFormSet)
+ >>> BookFormSet = inlineformset_factory(Author, Book, fields=('title',),
+ ... formset=CustomInlineFormSet)
>>> author = Author.objects.get(name='Mike Royko')
>>> formset = BookFormSet(instance=author)
@@ -1151,14 +1150,15 @@ need to resolve the ambiguity manually using ``fk_name``. For example, consider
the following model::
class Friendship(models.Model):
- from_friend = models.ForeignKey(Friend)
- to_friend = models.ForeignKey(Friend)
+ from_friend = models.ForeignKey(Friend, related_name='from_friends')
+ to_friend = models.ForeignKey(Friend, related_name='friends')
length_in_months = models.IntegerField()
To resolve this, you can use ``fk_name`` to
:func:`~django.forms.models.inlineformset_factory`::
- >>> FriendshipFormSet = inlineformset_factory(Friend, Friendship, fk_name="from_friend")
+ >>> FriendshipFormSet = inlineformset_factory(Friend, Friendship, fk_name='from_friend',
+ ... fields=('to_friend', 'length_in_months'))
Using an inline formset in a view
---------------------------------
@@ -1168,7 +1168,7 @@ of a model. Here's how you can do that::
def manage_books(request, author_id):
author = Author.objects.get(pk=author_id)
- BookInlineFormSet = inlineformset_factory(Author, Book)
+ BookInlineFormSet = inlineformset_factory(Author, Book, fields=('title',))
if request.method == "POST":
formset = BookInlineFormSet(request.POST, request.FILES, instance=author)
if formset.is_valid():