Decide on public API/documentation for form.BoundField attributes

[mnbayazit]

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?

[Russell Keith-Magee]

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.

[mnbayazit]

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.

[Petr Marhoun <petr.marhoun@…>]

Added patch which implements BoundField.required (with tests, without documentation).

[Ramiro Morales]

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.

[anonymous]

FYI we added a id_for_label attribute (a wrapper around the field widget's id_for_label class method) to BoundField in r15452.

[Aymeric Augustin]

#16125 was a duplicate. The tickets suggests some fields that should be documented in priority.

[Jim Dalton]

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_idin 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.

[Moritz Sichert]

Added PR: ​https://github.com/django/django/pull/5123

[Moritz Sichert]

Updated PR

[Tim Graham]

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.

[Tim Graham <timograham@…>]

In 2f53d34:

Fixed #12856 -- Documented BoundField API.