[patch] Addition of help_text argument to newforms fields

[Ben Slavin]

Forms often provide additional information related to fields to provide guidance to users.

Example of additional information in forms:

   Username: [__________]
             ex. bsmith
   E-mail:   [__________]
             ex. bob@example.com

Newforms provides the ability to modify the label for form fields, but not to provide further descriptive text. This problem has been brought-up on both the developer and user mailing lists. I propose the addition of a help_text argument for form fields -- this is similar to the argument by the same name for models.

Example of functionality:

>>> class UserRegistration(Form):
...    username = CharField(max_length=10, help_text='Ex. user@example.com')
...    password = CharField(widget=PasswordInput)

>>> p = UserRegistration(auto_id=False)
>>> print p.as_ul()
<li>Username: <input type="text" name="username" maxlength="10" /> Ex. user@example.com</li>
<li>Password: <input type="password" name="password" /> </li>

[Ben Slavin]

[patch] adds help_text for newforms

[Ben Slavin]

I have attached a patch for this ticket.

The changes are:

• All Field types currently in newforms to support the optional help_text argument
• The model_forms tests to comply with new output format (see note below)
• The forms test to comply with new output format (see note below)
• BaseForm in newforms:
  • _html_output now takes two additional arguments: help_row and help_on_separate_row
  • as_table, as_ul, and as_p have been updated to present help_text in their output
• Tests are included
• Documentation is currently included in the tests

Note: Because of formatting, there is now an extra space at the end of as_ul() output for fields that do not have help_text.
The pattern responsible for this space is "<li>%(errors)s%(label)s %(field)s %(help_text)s</li>"

[Thomas Steinacher <tom@…>]

+1 on this.

[Michael Radziej <mir@…>]

Thanks, I like this.

I've spotted a few small gotchas in the patch:

• Why does the patch change the output of as_ul() even without help_text? It adds a space, see (lines 59, 60, 66, 67, ... in tests/modeltests/model_forms/models.py) I don't see a good reason for this, and it also makes the patch in the test section more prone to merge conflicts.

• wheter -> whether (tests/modeltests/model_forms/models.py:2240)

Have you presented this on django-developers? I think this might add a few ideas, e.g. whether people would prefer a different format.

I put this patch as "Needs Design Decision" since all enhancements need to go through this stage.

[Hawkeye]

The extra space is necessary because of the way that formatting hooks work.

We could change the way that formatting is done, but I tried to build upon the existing infrastructure for HTML auto-generation.

I'll take another look at it, but suggestions are certainly welcome.

[Adrian Holovaty]

(In [4440]) Fixed #3255 -- Added help_text argument to newforms Field class.