Code

Opened 4 years ago

Last modified 13 months ago

#12856 new Cleanup/optimization

Decide on public API/documentation for form.BoundField attributes

Reported by: mnbayazit Owned by: nobody
Component: Documentation Version: master
Severity: Normal Keywords: boundfield required is_hidden auto_id
Cc: jim.dalton@… Triage Stage: Accepted
Has patch: yes Needs documentation: yes
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@…> 4 years ago.

Download all attachments as: .zip

Change History (12)

comment:1 follow-ups: Changed 4 years ago by russellm

  • Component changed from Documentation to Forms
  • Needs documentation unset
  • Needs tests unset
  • Patch needs improvement unset
  • Triage Stage changed from Unreviewed to Accepted

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 4 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 4 years ago by Petr Marhoun <petr.marhoun@…>

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

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

comment:4 in reply to: ↑ 1 Changed 4 years ago by ramiro

  • Keywords boundfield required is_hidden auto_id added
  • Summary changed from Missing form.field tags? to 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 4 years ago by ramiro

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

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

  • Type set to New feature

comment:8 Changed 3 years ago by lukeplant

  • Severity set to Normal

comment:9 Changed 3 years ago by aaugustin

  • Easy pickings unset

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

comment:10 Changed 3 years ago by jsdalton

  • Cc jim.dalton@… added
  • Type changed from New feature to 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_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 3 years ago by jsdalton (previous) (diff)

comment:11 Changed 13 months ago by timo

  • Component changed from Forms to Documentation

Add Comment

Modify Ticket

Change Properties
<Author field>
Action
as new
The owner will be changed from nobody to anonymous. Next status will be 'assigned'
as The resolution will be set. Next status will be 'closed'
Author


E-mail address and user name can be saved in the Preferences.

 
Note: See TracTickets for help on using tickets.