Opened 15 years ago
Closed 9 years ago
#12856 closed Cleanup/optimization (fixed)
Decide on public API/documentation for form.BoundField attributes
Reported by: | mnbayazit | Owned by: | Moritz Sichert |
---|---|---|---|
Component: | Documentation | Version: | dev |
Severity: | Normal | Keywords: | boundfield required is_hidden auto_id 1.9 |
Cc: | jim.dalton@… | Triage Stage: | Accepted |
Has patch: | yes | Needs documentation: | no |
Needs tests: | no | Patch needs improvement: | yes |
Easy pickings: | no | UI/UX: | no |
Description
On http://docs.djangoproject.com/en/dev/topics/forms/#looping-over-the-form-s-fields it would have been helpful to know about field.field.required
and field.auto_id
. Are there other undocumented tags too?
Attachments (1)
Change History (18)
follow-ups: 2 4 comment:1 by , 15 years ago
Component: | Documentation → Forms |
---|---|
Triage Stage: | Unreviewed → Accepted |
comment:2 by , 15 years ago
Replying to russellm:
Essentially, any attribute of BoundField (including any attributes of those attributes) will be technically visible in the template, and there are quite a few undocumented attributes. I'm not sure we want to document them all, as some of them are internals - auto_id probably falls into this category. However required should probably be on that list. In fact - it should probably be fixed by making it available as field.is_required, in the same way that field.is_hidden is available. A general review of these attributes is probably called for.
I found auto_id
to be necessary if I wanted to put stuff (like a colon) inside the label tag. I don't think it should be internal.
by , 14 years ago
Attachment: | bound-field-required.diff added |
---|
comment:3 by , 14 years ago
Added patch which implements BoundField.required (with tests, without documentation).
comment:4 by , 14 years ago
Keywords: | boundfield required is_hidden auto_id added |
---|---|
Summary: | Missing form.field tags? → Decide on public API/documentation for form.BoundField attributes |
Replying to russellm:
Essentially, any attribute of BoundField (including any attributes of those attributes) will be technically visible in the template, and there are quite a few undocumented attributes. I'm not sure we want to document them all, as some of them are internals - auto_id probably falls into this category
BoundField.auto_id
is used in admin templates, so it probably should be public too.
comment:5 by , 14 years ago
Has patch: | set |
---|---|
Needs documentation: | set |
Patch needs improvement: | set |
comment:6 by , 14 years ago
FYI we added a id_for_label
attribute (a wrapper around the field widget's id_for_label
class method) to BoundField in r15452.
comment:7 by , 14 years ago
Type: | → New feature |
---|
comment:8 by , 14 years ago
Severity: | → Normal |
---|
comment:9 by , 13 years ago
Easy pickings: | unset |
---|
#16125 was a duplicate. The tickets suggests some fields that should be documented in priority.
comment:10 by , 13 years ago
Cc: | added |
---|---|
Type: | New feature → Cleanup/optimization |
UI/UX: | unset |
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
required
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.
comment:11 by , 11 years ago
Component: | Forms → Documentation |
---|
comment:12 by , 9 years ago
Has patch: | unset |
---|---|
Owner: | changed from | to
Patch needs improvement: | unset |
Status: | new → assigned |
comment:13 by , 9 years ago
Has patch: | set |
---|---|
Needs documentation: | unset |
comment:14 by , 9 years ago
Patch needs improvement: | set |
---|
comment:16 by , 9 years ago
Keywords: | 1.9 added |
---|---|
Patch needs improvement: | set |
There's one outstanding question related to documenting a method that may not need to be depending on the results of template widget rendering, but otherwise this is in good shape for 1.9.
Essentially, any attribute of BoundField (including any attributes of those attributes) will be technically visible in the template, and there are quite a few undocumented attributes. I'm not sure we want to document them all, as some of them are internals - auto_id probably falls into this category. However required should probably be on that list. In fact - it should probably be fixed by making it available as field.is_required, in the same way that field.is_hidden is available. A general review of these attributes is probably called for.