Opened 15 years ago

Closed 15 years ago

Last modified 15 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: no UI/UX: no

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 Tim Graham 15 years ago.

Download all attachments as: .zip

Change History (6)

comment:1 by Tim Graham, 15 years ago

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

comment:2 by Russell Keith-Magee, 15 years ago

Triage Stage: UnreviewedAccepted

by Tim Graham, 15 years ago

Attachment: 12505.diff added

comment:3 by Tim Graham, 15 years ago

Triage Stage: AcceptedReady for checkin

I think the attached patch makes the docs more clear.

comment:4 by Russell Keith-Magee, 15 years ago

Resolution: fixed
Status: newclosed

(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 by Russell Keith-Magee, 15 years ago

(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