|
@@ -32,8 +32,8 @@ would with a regular form::
|
|
|
|
|
|
As you can see it only displayed one empty form. The number of empty forms
|
|
|
that is displayed is controlled by the ``extra`` parameter. By default,
|
|
|
-``formset_factory`` defines one extra form; the following example will
|
|
|
-display two blank forms::
|
|
|
+:func:`~django.forms.formsets.formset_factory` defines one extra form; the
|
|
|
+following example will display two blank forms::
|
|
|
|
|
|
>>> ArticleFormSet = formset_factory(ArticleForm, extra=2)
|
|
|
|
|
@@ -84,8 +84,9 @@ list of dictionaries as the initial data.
|
|
|
Limiting the maximum number of forms
|
|
|
------------------------------------
|
|
|
|
|
|
-The ``max_num`` parameter to ``formset_factory`` gives you the ability to
|
|
|
-limit the maximum number of empty forms the formset will display::
|
|
|
+The ``max_num`` parameter to :func:`~django.forms.formsets.formset_factory`
|
|
|
+gives you the ability to limit the maximum number of empty forms the formset
|
|
|
+will display::
|
|
|
|
|
|
>>> ArticleFormSet = formset_factory(ArticleForm, extra=2, max_num=1)
|
|
|
>>> formset = ArticleFormSet()
|
|
@@ -101,6 +102,20 @@ so long as the total number of forms does not exceed ``max_num``.
|
|
|
A ``max_num`` value of ``None`` (the default) puts a high limit on the number
|
|
|
of forms displayed (1000). In practice this is equivalent to no limit.
|
|
|
|
|
|
+If the number of forms in the initial data exceeds ``max_num``, all initial
|
|
|
+data forms will be displayed regardless. (No extra forms will be displayed.)
|
|
|
+
|
|
|
+By default, ``max_num`` only affects how many forms are displayed and does not
|
|
|
+affect validation. If ``validate_max=True`` is passed to the
|
|
|
+:func:`~django.forms.formsets.formset_factory`, then ``max_num`` will affect
|
|
|
+validation. See :ref:`validate_max`.
|
|
|
+
|
|
|
+.. versionchanged:: 1.6
|
|
|
+ The ``validate_max`` parameter was added to
|
|
|
+ :func:`~django.forms.formsets.formset_factory`. Also, the behavior of
|
|
|
+ ``FormSet`` was brought in line with that of ``ModelFormSet`` so that it
|
|
|
+ displays initial data regardless of ``max_num``.
|
|
|
+
|
|
|
Formset validation
|
|
|
------------------
|
|
|
|
|
@@ -248,14 +263,59 @@ 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.
|
|
|
|
|
|
+.. _validate_max:
|
|
|
+
|
|
|
+Validating the number of forms in a formset
|
|
|
+-------------------------------------------
|
|
|
+
|
|
|
+If ``validate_max=True`` is passed to
|
|
|
+:func:`~django.forms.formsets.formset_factory`, validation will also check
|
|
|
+that the number of forms in the data set is less than or equal to ``max_num``.
|
|
|
+
|
|
|
+ >>> ArticleFormSet = formset_factory(ArticleForm, max_num=1, validate_max=True)
|
|
|
+ >>> data = {
|
|
|
+ ... 'form-TOTAL_FORMS': u'2',
|
|
|
+ ... 'form-INITIAL_FORMS': u'0',
|
|
|
+ ... 'form-MAX_NUM_FORMS': u'',
|
|
|
+ ... 'form-0-title': u'Test',
|
|
|
+ ... 'form-0-pub_date': u'1904-06-16',
|
|
|
+ ... 'form-1-title': u'Test 2',
|
|
|
+ ... 'form-1-pub_date': u'1912-06-23',
|
|
|
+ ... }
|
|
|
+ >>> formset = ArticleFormSet(data)
|
|
|
+ >>> formset.is_valid()
|
|
|
+ False
|
|
|
+ >>> formset.errors
|
|
|
+ [{}, {}]
|
|
|
+ >>> formset.non_form_errors()
|
|
|
+ [u'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.
|
|
|
+
|
|
|
+Applications which need more customizable validation of the number of forms
|
|
|
+should use custom formset validation.
|
|
|
+
|
|
|
+.. 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.
|
|
|
+
|
|
|
+.. versionchanged:: 1.6
|
|
|
+ The ``validate_max`` parameter was added to
|
|
|
+ :func:`~django.forms.formsets.formset_factory`.
|
|
|
+
|
|
|
Dealing with ordering and deletion of forms
|
|
|
-------------------------------------------
|
|
|
|
|
|
-Common use cases with a formset is dealing with ordering and deletion of the
|
|
|
-form instances. This has been dealt with for you. The ``formset_factory``
|
|
|
-provides two optional parameters ``can_order`` and ``can_delete`` that will do
|
|
|
-the extra work of adding the extra fields and providing simpler ways of
|
|
|
-getting to that data.
|
|
|
+The :func:`~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``
|
|
|
~~~~~~~~~~~~~
|