#27280: can_order/can_delete documentation examples don't require initial data
-------------------------------------+-------------------------------------
Reporter: Michael | Owner: nobody
Type: | Status: closed
Cleanup/optimization |
Component: Documentation | Version: 1.10
Severity: Normal | Resolution: invalid
Keywords: | Triage Stage:
| Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
Comment (by Marten Kenbeek):
Replying to [comment:13 Michael]:
> Replying to [comment:12 Tim Graham]:
> > Thanks, I updated the wording on the pull request. Feel free to
comment on the pull request if it's still unclear.
>
> Let me comment in this ticket. I would say, the wording is really
unclear:
>
> {{{
> If you use an ``initial`` for displaying a formset, you should pass the
same
> ``initial`` when processing that formset's submission so that the
formset can
> detect which forms were changed by the user. For example, you might have
> something like: ``ArticleFormSet(request.POST, initial=[...])``.
> }}}
>
> 1. If one passes initial, it does not matter that s/he should pass the
same initial again. Maybe one wants just to show initial data.
> 2. To the best of my ability the only case I can imagine when one needs
both initial and data is for has_changed() method. But you are writing
documentation for "Using initial data with a formset" section. Whereas
has_changed() is in "Formset validation" section (by the way, illustrated
not very well, I think).
>
>
The aim of documentation is not just to explain a concept, but also to
show best practices, and these best practices should be used consistently
across all documentation. While it is not always technically necessary to
pass the same initial data when submitting a form or formset, failure to
do so consistently will give surprising behaviour when it ''is''
necessary. A quick look through the code shows that disabled fields
require the initial data on submission to work properly, and that model
formsets need the initial data to determine which forms should be saved
and which shouldn't. I'm sure I've missed a thing or two.
So I completely agree with Tim that the current use of initial in the
documentation shouldn't be changed. If it is confusing, it should be
cleared up by explaining ''why'' the initial data should be passed when
submitting the form. Removing the initial data when submitting the form in
this example will only create more confusion down the line as people copy
the example and expect it to "just work", only to encounter surprising and
incorrect behaviour when building upon that code.
--
Ticket URL: <https://code.djangoproject.com/ticket/27280#comment:14>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.
--
You received this message because you are subscribed to the Google Groups
"Django updates" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to [email protected].
To post to this group, send email to [email protected].
To view this discussion on the web visit
https://groups.google.com/d/msgid/django-updates/064.7daf1915b45cbd66f60199094eb49372%40djangoproject.com.
For more options, visit https://groups.google.com/d/optout.
