#12856: Decide on public API/documentation for form.BoundField attributes
-------------------------------------+-------------------------------------
Reporter: mnbayazit | Owner: nobody
Type: | Status: new
Cleanup/optimization | Component: Forms
Milestone: | Severity: Normal
Version: SVN | Keywords: boundfield required
Resolution: | is_hidden auto_id
Triage Stage: Accepted | Has patch: 1
Needs documentation: 1 | Needs tests: 0
Patch needs improvement: 1 | Easy pickings: 0
UI/UX: 0 |
-------------------------------------+-------------------------------------
Changes (by jsdalton):
* cc: jim.dalton@… (added)
* ui_ux: => 0
* type: New feature => Cleanup/optimization
Comment:
I think a more appropriate place to extend the documentation on
`BoundField` is in the Forms API document:
https://docs.djangoproject.com/en/dev/ref/forms/api/#more-granular-output
. That's not to say we should not extend the Working With Forms docs a
bit, but if I'm a developer and I want to find out more about what
`BoundField` has to offer, Forms API is likely the place I will begin.
In an effort to help push this forward, here is what we have documented
now:
* `class ``BoundField```
* `BoundField.errors`
* `BoundField.css_classes()`
* `BoundField.value()`
Then in Working With Forms the following are documented (albeit as
template output, not explicitly as methods of BoundField).
* `BoundField.label`
* `BoundField.label_tag`
* `BoundField.html_name`
* `BoundField.help_text`
* `BoundField.errors`
* `BoundField.is_hidden`
Here is what is missing (i.e. not covered by either of the above).
* `BoundField.field`
* `BoundField.html_initial_name`
* `BoundField.html_initial_id`
* `BoundField.as_widget()`
* `BoundField.as_text()`
* `BoundField.as_textarea()`
* `BoundField.as_hidden()`
* `BoundField.data`
* `BoundField.auto_id`
* `BoundField.id_for_label`
My two cents:
* It seems like all of the attributes described in working with forms
deserve a mention in Forms API? It strikes me as odd to read the API docs
on a class with no mention of the some of the most important attributes on
it.
* `BoundField.id_for_label` is almost a no brainer for me. If you're doing
granular output, e.g. writing your own label tag, then getting the id is
necessary.
* I've used `BoundField.auto_id`in the past when (I now realize) I should
have been using id_for_label. It might be worth noting that id_for_label
is recommended for template output over auto_id?
* I have no opinion on documenting the `as_*()` functions. Seems
unnecessary to me, they are mostly internal.
* `required` is documented on
https://docs.djangoproject.com/en/dev/ref/forms/fields/ , which is a
different beast IMO. I'd argue the documentation for those should stay
there. Maybe we could put a note with a link to the fields doc?
* Petr's patch adding the field to BoundField might be a good one, but I'm
not sure it belongs here? It strikes me as a separate issue. This seems to
primarily be a ticket related to improving the documentation of existing
fields.
--
Ticket URL: <https://code.djangoproject.com/ticket/12856#comment:10>
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 post to this group, send email to django-updates@googlegroups.com.
To unsubscribe from this group, send email to
django-updates+unsubscr...@googlegroups.com.
For more options, visit this group at
http://groups.google.com/group/django-updates?hl=en.
