Source

djangofrdoc / topics / forms / formsets.txt

Full commit
  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
.. _formsets:

Formsets
========

A formset is a layer of abstraction to working with multiple forms on the same
page. It can be best compared to a data grid. Let's say you have the following
form::

    >>> from django import forms
    >>> class ArticleForm(forms.Form):
    ...     title = forms.CharField()
    ...     pub_date = forms.DateField()

You might want to allow the user to create several articles at once. To create
a formset out of an ``ArticleForm`` you would do::

    >>> from django.forms.formsets import formset_factory
    >>> ArticleFormSet = formset_factory(ArticleForm)

You now have created a formset named ``ArticleFormSet``. The formset gives you
the ability to iterate over the forms in the formset and display them as you
would with a regular form::

    >>> formset = ArticleFormSet()
    >>> for form in formset:
    ...     print form.as_table()
    <tr><th><label for="id_form-0-title">Title:</label></th><td><input type="text" name="form-0-title" id="id_form-0-title" /></td></tr>
    <tr><th><label for="id_form-0-pub_date">Pub date:</label></th><td><input type="text" name="form-0-pub_date" id="id_form-0-pub_date" /></td></tr>

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::

    >>> ArticleFormSet = formset_factory(ArticleForm, extra=2)

.. versionchanged:: 1.3

Prior to Django 1.3, formset instances were not iterable. To render
the formset you iterated over the ``forms`` attribute::

    >>> formset = ArticleFormSet()
    >>> for form in formset.forms:
    ...     print form.as_table()

Iterating over ``formset.forms`` will render the forms in the order
they were created. The default formset iterator also renders the forms
in this order, but you can change this order by providing an alternate
implementation for the :meth:`__iter__()` method.

Using initial data with a formset
---------------------------------

Initial data is what drives the main usability of a formset. As shown above
you can define the number of extra forms. What this means is that you are
telling the formset how many additional forms to show in addition to the
number of forms it generates from the initial data. Lets take a look at an
example::

    >>> ArticleFormSet = formset_factory(ArticleForm, extra=2)
    >>> formset = ArticleFormSet(initial=[
    ...     {'title': u'Django is now open source',
    ...      'pub_date': datetime.date.today()},
    ... ])

    >>> for form in formset:
    ...     print form.as_table()
    <tr><th><label for="id_form-0-title">Title:</label></th><td><input type="text" name="form-0-title" value="Django is now open source" id="id_form-0-title" /></td></tr>
    <tr><th><label for="id_form-0-pub_date">Pub date:</label></th><td><input type="text" name="form-0-pub_date" value="2008-05-12" id="id_form-0-pub_date" /></td></tr>
    <tr><th><label for="id_form-1-title">Title:</label></th><td><input type="text" name="form-1-title" id="id_form-1-title" /></td></tr>
    <tr><th><label for="id_form-1-pub_date">Pub date:</label></th><td><input type="text" name="form-1-pub_date" id="id_form-1-pub_date" /></td></tr>
    <tr><th><label for="id_form-2-title">Title:</label></th><td><input type="text" name="form-2-title" id="id_form-2-title" /></td></tr>
    <tr><th><label for="id_form-2-pub_date">Pub date:</label></th><td><input type="text" name="form-2-pub_date" id="id_form-2-pub_date" /></td></tr>

There are now a total of three forms showing above. One for the initial data
that was passed in and two extra forms. Also note that we are passing in a
list of dictionaries as the initial data.

.. seealso::

    :ref:`Creating formsets from models with model formsets <model-formsets>`.

.. _formsets-max-num:

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::

    >>> ArticleFormSet = formset_factory(ArticleForm, extra=2, max_num=1)
    >>> formset = ArticleFormset()
    >>> for form in formset:
    ...     print form.as_table()
    <tr><th><label for="id_form-0-title">Title:</label></th><td><input type="text" name="form-0-title" id="id_form-0-title" /></td></tr>
    <tr><th><label for="id_form-0-pub_date">Pub date:</label></th><td><input type="text" name="form-0-pub_date" id="id_form-0-pub_date" /></td></tr>

.. versionchanged:: 1.2

If the value of ``max_num`` is greater than the number of existing
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``.

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.

Formset validation
------------------

Validation with a formset is almost identical to a regular ``Form``. There is
an ``is_valid`` method on the formset to provide a convenient way to validate
all forms in the formset::

    >>> ArticleFormSet = formset_factory(ArticleForm)
    >>> data = {
    ...     'form-TOTAL_FORMS': u'1',
    ...     'form-INITIAL_FORMS': u'0',
    ...     'form-MAX_NUM_FORMS': u'',
    ... }
    >>> formset = ArticleFormSet(data)
    >>> formset.is_valid()
    True

We passed in no data to the formset which is resulting in a valid form. The
formset is smart enough to ignore extra forms that were not changed. If we
provide an invalid article::

    >>> 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',
    ...     'form-1-pub_date': u'', # <-- this date is missing but required
    ... }
    >>> formset = ArticleFormSet(data)
    >>> formset.is_valid()
    False
    >>> formset.errors
    [{}, {'pub_date': [u'This field is required.']}]

As we can see, ``formset.errors`` is a list whose entries correspond to the
forms in the formset. Validation was performed for each of the two forms, and
the expected error message appears for the second item.

.. _understanding-the-managementform:

Understanding the ManagementForm
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

You may have noticed the additional data (``form-TOTAL_FORMS``,
``form-INITIAL_FORMS`` and ``form-MAX_NUM_FORMS``) that was required
in the formset's data above. This data is required for the
``ManagementForm``. This form is used by the formset to manage the
collection of forms contained in the formset. If you don't provide
this management data, an exception will be raised::

    >>> data = {
    ...     'form-0-title': u'Test',
    ...     'form-0-pub_date': u'',
    ... }
    >>> formset = ArticleFormSet(data)
    Traceback (most recent call last):
    ...
    django.forms.util.ValidationError: [u'ManagementForm data is missing or has been tampered with']

It is used to keep track of how many form instances are being displayed. If
you are adding new forms via JavaScript, you should increment the count fields
in this form as well.

The management form is available as an attribute of the formset
itself. When rendering a formset in a template, you can include all
the management data by rendering ``{{ my_formset.management_form }}``
(substituting the name of your formset as appropriate).

``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.

.. versionadded:: 1.2

``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.formsets import BaseFormSet

    >>> 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 i in range(0, self.total_form_count()):
    ...             form = self.forms[i]
    ...             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': 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',
    ...     'form-1-pub_date': u'1912-06-23',
    ... }
    >>> formset = ArticleFormSet(data)
    >>> formset.is_valid()
    False
    >>> formset.errors
    [{}, {}]
    >>> formset.non_form_errors()
    [u'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.

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.

``can_order``
~~~~~~~~~~~~~

Default: ``False``

Lets create a formset with the ability to order::

    >>> ArticleFormSet = formset_factory(ArticleForm, can_order=True)
    >>> formset = ArticleFormSet(initial=[
    ...     {'title': u'Article #1', 'pub_date': datetime.date(2008, 5, 10)},
    ...     {'title': u'Article #2', 'pub_date': datetime.date(2008, 5, 11)},
    ... ])
    >>> for form in formset:
    ...     print form.as_table()
    <tr><th><label for="id_form-0-title">Title:</label></th><td><input type="text" name="form-0-title" value="Article #1" id="id_form-0-title" /></td></tr>
    <tr><th><label for="id_form-0-pub_date">Pub date:</label></th><td><input type="text" name="form-0-pub_date" value="2008-05-10" id="id_form-0-pub_date" /></td></tr>
    <tr><th><label for="id_form-0-ORDER">Order:</label></th><td><input type="text" name="form-0-ORDER" value="1" id="id_form-0-ORDER" /></td></tr>
    <tr><th><label for="id_form-1-title">Title:</label></th><td><input type="text" name="form-1-title" value="Article #2" id="id_form-1-title" /></td></tr>
    <tr><th><label for="id_form-1-pub_date">Pub date:</label></th><td><input type="text" name="form-1-pub_date" value="2008-05-11" id="id_form-1-pub_date" /></td></tr>
    <tr><th><label for="id_form-1-ORDER">Order:</label></th><td><input type="text" name="form-1-ORDER" value="2" id="id_form-1-ORDER" /></td></tr>
    <tr><th><label for="id_form-2-title">Title:</label></th><td><input type="text" name="form-2-title" id="id_form-2-title" /></td></tr>
    <tr><th><label for="id_form-2-pub_date">Pub date:</label></th><td><input type="text" name="form-2-pub_date" id="id_form-2-pub_date" /></td></tr>
    <tr><th><label for="id_form-2-ORDER">Order:</label></th><td><input type="text" name="form-2-ORDER" id="id_form-2-ORDER" /></td></tr>

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. Lets look at what will
happen when the user changes these values::

    >>> data = {
    ...     'form-TOTAL_FORMS': u'3',
    ...     'form-INITIAL_FORMS': u'2',
    ...     'form-MAX_NUM_FORMS': u'',
    ...     'form-0-title': u'Article #1',
    ...     'form-0-pub_date': u'2008-05-10',
    ...     'form-0-ORDER': u'2',
    ...     'form-1-title': u'Article #2',
    ...     'form-1-pub_date': u'2008-05-11',
    ...     'form-1-ORDER': u'1',
    ...     'form-2-title': u'Article #3',
    ...     'form-2-pub_date': u'2008-05-01',
    ...     'form-2-ORDER': u'0',
    ... }

    >>> formset = ArticleFormSet(data, initial=[
    ...     {'title': u'Article #1', 'pub_date': datetime.date(2008, 5, 10)},
    ...     {'title': u'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': u'Article #3'}
    {'pub_date': datetime.date(2008, 5, 11), 'ORDER': 1, 'title': u'Article #2'}
    {'pub_date': datetime.date(2008, 5, 10), 'ORDER': 2, 'title': u'Article #1'}

``can_delete``
~~~~~~~~~~~~~~

Default: ``False``

Lets create a formset with the ability to delete::

    >>> ArticleFormSet = formset_factory(ArticleForm, can_delete=True)
    >>> formset = ArticleFormSet(initial=[
    ...     {'title': u'Article #1', 'pub_date': datetime.date(2008, 5, 10)},
    ...     {'title': u'Article #2', 'pub_date': datetime.date(2008, 5, 11)},
    ... ])
    >>> for form in formset:
    ....    print form.as_table()
    <input type="hidden" name="form-TOTAL_FORMS" value="3" id="id_form-TOTAL_FORMS" /><input type="hidden" name="form-INITIAL_FORMS" value="2" id="id_form-INITIAL_FORMS" /><input type="hidden" name="form-MAX_NUM_FORMS" id="id_form-MAX_NUM_FORMS" />
    <tr><th><label for="id_form-0-title">Title:</label></th><td><input type="text" name="form-0-title" value="Article #1" id="id_form-0-title" /></td></tr>
    <tr><th><label for="id_form-0-pub_date">Pub date:</label></th><td><input type="text" name="form-0-pub_date" value="2008-05-10" id="id_form-0-pub_date" /></td></tr>
    <tr><th><label for="id_form-0-DELETE">Delete:</label></th><td><input type="checkbox" name="form-0-DELETE" id="id_form-0-DELETE" /></td></tr>
    <tr><th><label for="id_form-1-title">Title:</label></th><td><input type="text" name="form-1-title" value="Article #2" id="id_form-1-title" /></td></tr>
    <tr><th><label for="id_form-1-pub_date">Pub date:</label></th><td><input type="text" name="form-1-pub_date" value="2008-05-11" id="id_form-1-pub_date" /></td></tr>
    <tr><th><label for="id_form-1-DELETE">Delete:</label></th><td><input type="checkbox" name="form-1-DELETE" id="id_form-1-DELETE" /></td></tr>
    <tr><th><label for="id_form-2-title">Title:</label></th><td><input type="text" name="form-2-title" id="id_form-2-title" /></td></tr>
    <tr><th><label for="id_form-2-pub_date">Pub date:</label></th><td><input type="text" name="form-2-pub_date" id="id_form-2-pub_date" /></td></tr>
    <tr><th><label for="id_form-2-DELETE">Delete:</label></th><td><input type="checkbox" name="form-2-DELETE" id="id_form-2-DELETE" /></td></tr>

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': u'3',
    ...     'form-INITIAL_FORMS': u'2',
    ...     'form-MAX_NUM_FORMS': u'',
    ...     'form-0-title': u'Article #1',
    ...     'form-0-pub_date': u'2008-05-10',
    ...     'form-0-DELETE': u'on',
    ...     'form-1-title': u'Article #2',
    ...     'form-1-pub_date': u'2008-05-11',
    ...     'form-1-DELETE': u'',
    ...     'form-2-title': u'',
    ...     'form-2-pub_date': u'',
    ...     'form-2-DELETE': u'',
    ... }

    >>> formset = ArticleFormSet(data, initial=[
    ...     {'title': u'Article #1', 'pub_date': datetime.date(2008, 5, 10)},
    ...     {'title': u'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': u'Article #1'}]

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::

    >>> class BaseArticleFormSet(BaseFormSet):
    ...     def add_fields(self, form, index):
    ...         super(BaseArticleFormSet, self).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()
    <tr><th><label for="id_form-0-title">Title:</label></th><td><input type="text" name="form-0-title" id="id_form-0-title" /></td></tr>
    <tr><th><label for="id_form-0-pub_date">Pub date:</label></th><td><input type="text" name="form-0-pub_date" id="id_form-0-pub_date" /></td></tr>
    <tr><th><label for="id_form-0-my_field">My field:</label></th><td><input type="text" name="form-0-my_field" id="id_form-0-my_field" /></td></tr>

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:

.. code-block:: python

    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_to_response('manage_articles.html', {'formset': formset})

The ``manage_articles.html`` template might look like this:

.. code-block:: html+django

    <form method="post" action="">
        {{ formset.management_form }}
        <table>
            {% for form in formset %}
            {{ form }}
            {% endfor %}
        </table>
    </form>

However the above can be slightly shortcutted and let the formset itself deal
with the management form:

.. code-block:: html+django

    <form method="post" action="">
        <table>
            {{ formset }}
        </table>
    </form>

The above ends up calling the ``as_table`` method on the formset class.

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:

.. code-block:: python

    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_to_response('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.