diff --git a/django/forms/formsets.py b/django/forms/formsets.py
index dcd2f01..0c53006 100644
--- a/django/forms/formsets.py
+++ b/django/forms/formsets.py
@@ -16,6 +16,7 @@ __all__ = ('BaseFormSet', 'all_valid')
TOTAL_FORM_COUNT = 'TOTAL_FORMS'
INITIAL_FORM_COUNT = 'INITIAL_FORMS'
MAX_NUM_FORM_COUNT = 'MAX_NUM_FORMS'
+MIN_NUM_FORM_COUNT = 'MIN_NUM_FORMS'
ORDERING_FIELD_NAME = 'ORDER'
DELETION_FIELD_NAME = 'DELETE'
@@ -29,6 +30,7 @@ class ManagementForm(Form):
self.base_fields[TOTAL_FORM_COUNT] = IntegerField(widget=HiddenInput)
self.base_fields[INITIAL_FORM_COUNT] = IntegerField(widget=HiddenInput)
self.base_fields[MAX_NUM_FORM_COUNT] = IntegerField(required=False, widget=HiddenInput)
+ self.base_fields[MIN_NUM_FORM_COUNT] = IntegerField(required=False, widget=HiddenInput)
super(ManagementForm, self).__init__(*args, **kwargs)
class BaseFormSet(StrAndUnicode):
@@ -77,7 +79,8 @@ class BaseFormSet(StrAndUnicode):
form = ManagementForm(auto_id=self.auto_id, prefix=self.prefix, initial={
TOTAL_FORM_COUNT: self.total_form_count(),
INITIAL_FORM_COUNT: self.initial_form_count(),
- MAX_NUM_FORM_COUNT: self.max_num
+ MAX_NUM_FORM_COUNT: self.max_num,
+ MIN_NUM_FORM_COUNT: self.min_num
})
return form
management_form = property(_management_form)
@@ -95,6 +98,9 @@ class BaseFormSet(StrAndUnicode):
total_forms = initial_forms
elif total_forms > self.max_num >= 0:
total_forms = self.max_num
+
+ total_forms = max(total_forms, self.min_num)
+
return total_forms
def initial_form_count(self):
@@ -358,13 +364,17 @@ class BaseFormSet(StrAndUnicode):
return mark_safe(u'\n'.join([unicode(self.management_form), forms]))
def formset_factory(form, formset=BaseFormSet, extra=1, can_order=False,
- can_delete=False, max_num=None):
+ can_delete=False, max_num=None, min_num=None):
"""Return a FormSet for the given form class."""
+ if not None in (max_num, min_num) and max_num < min_num:
+ raise ValueError('max_num cannot be smaller than min_num')
+
attrs = {'form': form, 'extra': extra,
'can_order': can_order, 'can_delete': can_delete,
- 'max_num': max_num}
+ 'max_num': max_num, 'min_num': min_num }
return type(form.__name__ + 'FormSet', (formset,), attrs)
+
def all_valid(formsets):
"""Returns true if every formset in formsets is valid."""
valid = True
diff --git a/docs/topics/forms/formsets.txt b/docs/topics/forms/formsets.txt
index b524c24..9a91182 100644
--- a/docs/topics/forms/formsets.txt
+++ b/docs/topics/forms/formsets.txt
@@ -112,6 +112,36 @@ A ``max_num`` value of ``None`` (the default) puts no limit on the number of
forms displayed. Please note that the default value of ``max_num`` was changed
from ``0`` to ``None`` in version 1.2 to allow ``0`` as a valid value.
+.. _formsets-min-num:
+
+Ensuring the minimum number of forms
+------------------------------------
+
+The ``min_num`` parameter to ``formset_factory`` gives you the ability to make
+sure that at least a certain number of forms will be displayed::
+
+ >>> ArticleFormSet = formset_factory(ArticleForm, min_num=2)
+ >>> formset = ArticleFormset(initial=[
+ ... {'title': u'Django is now open source',
+ ... 'pub_date': datetime.date.today(),}
+ ... ])
+
+ >>> for form in formset:
+ ... print form.as_table()
+
+
+
+
+
+.. versionchanged:: 1.4
+
+If the value of ``min_num`` is greater than the number of elements that would
+be displayed normally (including extra forms), additional blank forms will be
+added to the formset.
+
+If ``min_num`` is greater than ``max_num``, ``ValueError`` will be raised by
+``formset_factory`` function.
+
Formset validation
------------------
diff --git a/tests/regressiontests/forms/tests/formsets.py b/tests/regressiontests/forms/tests/formsets.py
index 05ef978..957f04b 100644
--- a/tests/regressiontests/forms/tests/formsets.py
+++ b/tests/regressiontests/forms/tests/formsets.py
@@ -47,7 +47,7 @@ class FormsFormsetTestCase(TestCase):
# for adding data. By default, it displays 1 blank form. It can display more,
# but we'll look at how to do so later.
formset = ChoiceFormSet(auto_id=False, prefix='choices')
- self.assertHTMLEqual(str(formset), """
+ self.assertHTMLEqual(str(formset), """
Choice:
Votes:
""")
@@ -646,6 +646,52 @@ class FormsFormsetTestCase(TestCase):
self.assertTrue(formset.is_valid())
self.assertEqual(formset.non_form_errors(), [])
+ def test_appending_min_forms(self):
+ # Ensuring the minimum number of forms ########################################
+ # Base case for min_num.
+
+ # When not passed, min_num will take its default value of None, i.e. no required
+ # forms, only controller by the value of the extra parameter.
+
+ initial = [ dict(name='Pony') ]
+ LimitedFavoriteDrinkFormSet = formset_factory(FavoriteDrinkForm, extra=0, min_num=1)
+ formset = LimitedFavoriteDrinkFormSet()
+
+ self.assertHTMLEqual('\n'.join(str(form) for form in formset.forms), """
""")
+
+ LimitedFavoriteDrinkFormSet = formset_factory(FavoriteDrinkForm, extra=0, min_num=2)
+ formset = LimitedFavoriteDrinkFormSet(initial=initial)
+
+ self.assertHTMLEqual('\n'.join(str(form) for form in formset.forms), """
+
""")
+
+ LimitedFavoriteDrinkFormSet = formset_factory(FavoriteDrinkForm, extra=0, min_num=1)
+ formset = LimitedFavoriteDrinkFormSet(initial=initial)
+
+ self.assertHTMLEqual('\n'.join(str(form) for form in formset.forms), """
""")
+
+ LimitedFavoriteDrinkFormSet = formset_factory(FavoriteDrinkForm, extra=1, min_num=1)
+ formset = LimitedFavoriteDrinkFormSet(initial=initial)
+
+ self.assertHTMLEqual('\n'.join(str(form) for form in formset.forms), """
+
""")
+
+ LimitedFavoriteDrinkFormSet = formset_factory(FavoriteDrinkForm, extra=1, min_num=1, max_num=1)
+ formset = LimitedFavoriteDrinkFormSet(initial=initial)
+
+ self.assertHTMLEqual('\n'.join(str(form) for form in formset.forms), """