Opened 6 years ago

Closed 5 years ago

Last modified 5 years ago

#12505 closed (fixed)

Formsets: Misleading documentation

Reported by: Andreas Owned by: nobody
Component: Documentation Version: 1.1
Severity: Keywords: formset
Cc: Triage Stage: Ready for checkin
Has patch: no Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: UI/UX:

Description

The example of the documentation at <http://docs.djangoproject.com/en/dev/topics/forms/formsets/#using-initial-data-with-a-formset> is maybe not optimal to explain how the 'extra' and 'initial' parameters of a formset work together. It looks like the total number of forms is always extra + 1 (in fact, 'extra' somehow suggests the additional number of forms with respect to a standard, single form). Then, it looks like these forms are filled with the content of the dicts in the initial_list.
Even though the correct behaviour is described in the text, this is easily overread, since usually the examples are the best documentation ;-)
If you'd provide in the example for example 'extra=1' and then pass a list with two dicts as 'initial', I think the behaviour would be more obvious.
We were just struggling over an hour until we got it.

Attachments (1)

12505.diff (806 bytes) - added by timo 5 years ago.

Download all attachments as: .zip

Change History (6)

comment:1 Changed 6 years ago by timo

  • Needs documentation unset
  • Needs tests unset
  • Patch needs improvement unset

I believe the extra parameter describes how many blank forms to show. #12515 describes the confusion in a slightly different way.

comment:2 Changed 6 years ago by russellm

  • Triage Stage changed from Unreviewed to Accepted

Changed 5 years ago by timo

comment:3 Changed 5 years ago by timo

  • Triage Stage changed from Accepted to Ready for checkin

I think the attached patch makes the docs more clear.

comment:4 Changed 5 years ago by russellm

  • Resolution set to fixed
  • Status changed from new to closed

(In [13218]) Fixed #12505 -- Clarified the use of the extra argument in formsets. Thanks to Andreas for the report, and timo for the draft patch.

comment:5 Changed 5 years ago by russellm

(In [13223]) [1.1.X] Fixed #12505 -- Clarified the use of the extra argument in formsets. Thanks to Andreas for the report, and timo for the draft patch.

Backport of r13218 from trunk.

Note: See TracTickets for help on using tickets.
Back to Top