Opened 7 years ago

Closed 15 months 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: master
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)

bound-field-required.diff (1.5 KB) - added by Petr Marhoun <petr.marhoun@…> 6 years ago.

Download all attachments as: .zip

Change History (18)

comment:1 Changed 7 years ago by Russell Keith-Magee

Component: DocumentationForms
Triage Stage: UnreviewedAccepted

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.

comment:2 in reply to:  1 Changed 7 years ago by 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.

Changed 6 years ago by Petr Marhoun <petr.marhoun@…>

Attachment: bound-field-required.diff added

comment:3 Changed 6 years ago by Petr Marhoun <petr.marhoun@…>

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

comment:4 in reply to:  1 Changed 6 years ago by Ramiro Morales

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 Changed 6 years ago by Ramiro Morales

Has patch: set
Needs documentation: set
Patch needs improvement: set

comment:6 Changed 6 years ago by 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.

comment:7 Changed 6 years ago by Luke Plant

Type: New feature

comment:8 Changed 6 years ago by Luke Plant

Severity: Normal

comment:9 Changed 6 years ago by Aymeric Augustin

Easy pickings: unset

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

comment:10 Changed 5 years ago by Jim Dalton

Cc: jim.dalton@… added
Type: New featureCleanup/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_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 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.
Last edited 5 years ago by Jim Dalton (previous) (diff)

comment:11 Changed 3 years ago by Tim Graham

Component: FormsDocumentation

comment:12 Changed 16 months ago by Moritz Sichert

Has patch: unset
Owner: changed from nobody to Moritz Sichert
Patch needs improvement: unset
Status: newassigned

comment:13 Changed 16 months ago by Moritz Sichert

Has patch: set
Needs documentation: unset

comment:14 Changed 16 months ago by Tim Graham

Patch needs improvement: set

comment:15 Changed 16 months ago by Moritz Sichert

Patch needs improvement: unset

Updated PR

comment:16 Changed 15 months ago by Tim Graham

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.

comment:17 Changed 15 months ago by Tim Graham <timograham@…>

Resolution: fixed
Status: assignedclosed

In 2f53d34:

Fixed #12856 -- Documented BoundField API.

Note: See TracTickets for help on using tickets.
Back to Top