Opened 8 years ago

Closed 8 years ago

#3255 closed enhancement (fixed)

[patch] Addition of help_text argument to newforms fields

Reported by: Ben Slavin Owned by: adrian
Component: Forms Version:
Severity: normal Keywords:
Cc: Triage Stage: Design decision needed
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: yes
Easy pickings: UI/UX:

Description

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>

Attachments (1)

newforms-help_text.diff (39.2 KB) - added by Ben Slavin 8 years ago.
[patch] adds help_text for newforms

Download all attachments as: .zip

Change History (7)

Changed 8 years ago by Ben Slavin

[patch] adds help_text for newforms

comment:1 Changed 8 years ago by 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>"

comment:2 Changed 8 years ago by Thomas Steinacher <tom@…>

+1 on this.

comment:3 Changed 8 years ago by ramiro <rm0 _at_ gmx.net>

  • Summary changed from Addition of help_text argument to newforms fields to [patch] Addition of help_text argument to newforms fields

comment:4 Changed 8 years ago by Michael Radziej <mir@…>

  • Patch needs improvement set
  • Triage Stage changed from Unreviewed to Design decision needed

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.

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

comment:6 Changed 8 years ago by adrian

  • Resolution set to fixed
  • Status changed from new to closed

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

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