Skip to content

Commit

Permalink
Fixed #3255 -- Added help_text argument to newforms Field class.
Browse files Browse the repository at this point in the history 
git-svn-id: http://code.djangoproject.com/svn/django/trunk@4440 bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information
@adrianholovaty
adrianholovaty committed Jan 28, 2007
1 parent 83768bf commit cf75fcc
Show file tree
Hide file tree
Showing 4 changed files with 107 additions and 36 deletions.
62 changes: 31 additions & 31 deletions django/newforms/fields.py
View file
Expand Up @@ -35,7 +35,7 @@ class Field(object):
# Tracks each time a Field instance is created. Used to retain order.
creation_counter = 0

def __init__(self, required=True, widget=None, label=None, initial=None):
def __init__(self, required=True, widget=None, label=None, initial=None, help_text=None):
# required -- Boolean that specifies whether the field is required.
# True by default.
# widget -- A Widget class, or instance of a Widget class, that should be
Expand All @@ -47,9 +47,11 @@ def __init__(self, required=True, widget=None, label=None, initial=None):
# field name, if the Field is part of a Form.
# initial -- A value to use in this Field's initial display. This value is
# *not* used as a fallback if data isn't given.
# help_text -- An optional string to use as "help text" for this Field.
if label is not None:
label = smart_unicode(label)
self.required, self.label, self.initial = required, label, initial
self.help_text = help_text
widget = widget or self.widget
if isinstance(widget, type):
widget = widget()
Expand Down Expand Up @@ -85,9 +87,9 @@ def widget_attrs(self, widget):
return {}

class CharField(Field):
def __init__(self, max_length=None, min_length=None, required=True, widget=None, label=None, initial=None):
def __init__(self, max_length=None, min_length=None, *args, **kwargs):
self.max_length, self.min_length = max_length, min_length
super(CharField, self).__init__(required, widget, label, initial)
super(CharField, self).__init__(*args, **kwargs)

def clean(self, value):
"Validates max_length and min_length. Returns a Unicode object."
Expand All @@ -106,9 +108,9 @@ def widget_attrs(self, widget):
return {'maxlength': str(self.max_length)}

class IntegerField(Field):
def __init__(self, max_value=None, min_value=None, required=True, widget=None, label=None, initial=None):
def __init__(self, max_value=None, min_value=None, *args, **kwargs):
self.max_value, self.min_value = max_value, min_value
super(IntegerField, self).__init__(required, widget, label, initial)
super(IntegerField, self).__init__(*args, **kwargs)

def clean(self, value):
"""
Expand Down Expand Up @@ -137,8 +139,8 @@ def clean(self, value):
)

class DateField(Field):
def __init__(self, input_formats=None, required=True, widget=None, label=None, initial=None):
super(DateField, self).__init__(required, widget, label, initial)
def __init__(self, input_formats=None, *args, **kwargs):
super(DateField, self).__init__(*args, **kwargs)
self.input_formats = input_formats or DEFAULT_DATE_INPUT_FORMATS

def clean(self, value):
Expand Down Expand Up @@ -166,8 +168,8 @@ def clean(self, value):
)

class TimeField(Field):
def __init__(self, input_formats=None, required=True, widget=None, label=None, initial=None):
super(TimeField, self).__init__(required, widget, label, initial)
def __init__(self, input_formats=None, *args, **kwargs):
super(TimeField, self).__init__(*args, **kwargs)
self.input_formats = input_formats or DEFAULT_TIME_INPUT_FORMATS

def clean(self, value):
Expand Down Expand Up @@ -200,8 +202,8 @@ def clean(self, value):
)

class DateTimeField(Field):
def __init__(self, input_formats=None, required=True, widget=None, label=None, initial=None):
super(DateTimeField, self).__init__(required, widget, label, initial)
def __init__(self, input_formats=None, *args, **kwargs):
super(DateTimeField, self).__init__(*args, **kwargs)
self.input_formats = input_formats or DEFAULT_DATETIME_INPUT_FORMATS

def clean(self, value):
Expand All @@ -224,14 +226,13 @@ def clean(self, value):
raise ValidationError(gettext(u'Enter a valid date/time.'))

class RegexField(Field):
def __init__(self, regex, max_length=None, min_length=None, error_message=None,
required=True, widget=None, label=None, initial=None):
def __init__(self, regex, max_length=None, min_length=None, error_message=None, *args, **kwargs):
"""
regex can be either a string or a compiled regular expression object.
error_message is an optional error message to use, if
'Enter a valid value' is too generic for you.
"""
super(RegexField, self).__init__(required, widget, label, initial)
super(RegexField, self).__init__(*args, **kwargs)
if isinstance(regex, basestring):
regex = re.compile(regex)
self.regex = regex
Expand Down Expand Up @@ -263,8 +264,9 @@ def clean(self, value):
r')@(?:[A-Z0-9-]+\.)+[A-Z]{2,6}$', re.IGNORECASE) # domain

class EmailField(RegexField):
def __init__(self, max_length=None, min_length=None, required=True, widget=None, label=None, initial=None):
RegexField.__init__(self, email_re, max_length, min_length, gettext(u'Enter a valid e-mail address.'), required, widget, label, initial)
def __init__(self, max_length=None, min_length=None, *args, **kwargs):
RegexField.__init__(self, email_re, max_length, min_length,
gettext(u'Enter a valid e-mail address.'), *args, **kwargs)

url_re = re.compile(
r'^https?://' # http:// or https://
Expand All @@ -280,9 +282,9 @@ def __init__(self, max_length=None, min_length=None, required=True, widget=None,
URL_VALIDATOR_USER_AGENT = 'Django (http://www.djangoproject.com/)'

class URLField(RegexField):
def __init__(self, max_length=None, min_length=None, required=True, verify_exists=False, widget=None, label=None,
initial=None, validator_user_agent=URL_VALIDATOR_USER_AGENT):
super(URLField, self).__init__(url_re, max_length, min_length, gettext(u'Enter a valid URL.'), required, widget, label, initial)
def __init__(self, max_length=None, min_length=None, verify_exists=False,
validator_user_agent=URL_VALIDATOR_USER_AGENT, *args, **kwargs):
super(URLField, self).__init__(url_re, max_length, min_length, gettext(u'Enter a valid URL.'), *args, **kwargs)
self.verify_exists = verify_exists
self.user_agent = validator_user_agent

Expand Down Expand Up @@ -328,10 +330,8 @@ def clean(self, value):
return {True: True, False: False}.get(value, None)

class ChoiceField(Field):
def __init__(self, choices=(), required=True, widget=Select, label=None, initial=None):
if isinstance(widget, type):
widget = widget()
super(ChoiceField, self).__init__(required, widget, label, initial)
def __init__(self, choices=(), required=True, widget=Select, label=None, initial=None, help_text=None):
super(ChoiceField, self).__init__(required, widget, label, initial, help_text)
self.choices = choices

def _get_choices(self):
Expand Down Expand Up @@ -362,8 +362,8 @@ def clean(self, value):
class MultipleChoiceField(ChoiceField):
hidden_widget = MultipleHiddenInput

def __init__(self, choices=(), required=True, widget=SelectMultiple, label=None, initial=None):
super(MultipleChoiceField, self).__init__(choices, required, widget, label, initial)
def __init__(self, choices=(), required=True, widget=SelectMultiple, label=None, initial=None, help_text=None):
super(MultipleChoiceField, self).__init__(choices, required, widget, label, initial, help_text)

def clean(self, value):
"""
Expand All @@ -390,8 +390,8 @@ class ComboField(Field):
"""
A Field whose clean() method calls multiple Field clean() methods.
"""
def __init__(self, fields=(), required=True, widget=None, label=None, initial=None):
super(ComboField, self).__init__(required, widget, label, initial)
def __init__(self, fields=(), *args, **kwargs):
super(ComboField, self).__init__(*args, **kwargs)
# Set 'required' to False on the individual fields, because the
# required validation will be handled by ComboField, not by those
# individual fields.
Expand Down Expand Up @@ -425,8 +425,8 @@ class MultiValueField(Field):
You'll probably want to use this with MultiWidget.
"""
def __init__(self, fields=(), required=True, widget=None, label=None, initial=None):
super(MultiValueField, self).__init__(required, widget, label, initial)
def __init__(self, fields=(), *args, **kwargs):
super(MultiValueField, self).__init__(*args, **kwargs)
# Set 'required' to False on the individual fields, because the
# required validation will be handled by MultiValueField, not by those
# individual fields.
Expand Down Expand Up @@ -481,9 +481,9 @@ def compress(self, data_list):
raise NotImplementedError('Subclasses must implement this method.')

class SplitDateTimeField(MultiValueField):
def __init__(self, required=True, widget=None, label=None, initial=None):
def __init__(self, *args, **kwargs):
fields = (DateField(), TimeField())
super(SplitDateTimeField, self).__init__(fields, required, widget, label, initial)
super(SplitDateTimeField, self).__init__(fields, *args, **kwargs)

def compress(self, data_list):
if data_list:
Expand Down
14 changes: 9 additions & 5 deletions django/newforms/forms.py
View file
Expand Up @@ -94,7 +94,7 @@ def add_prefix(self, field_name):
"""
return self.prefix and ('%s-%s' % (self.prefix, field_name)) or field_name

def _html_output(self, normal_row, error_row, row_ender, errors_on_separate_row):
def _html_output(self, normal_row, error_row, row_ender, help_text_html, errors_on_separate_row):
"Helper function for outputting HTML. Used by as_table(), as_ul(), as_p()."
top_errors = self.non_field_errors() # Errors that should be displayed above all fields.
output, hidden_fields = [], []
Expand All @@ -109,7 +109,11 @@ def _html_output(self, normal_row, error_row, row_ender, errors_on_separate_row)
if errors_on_separate_row and bf_errors:
output.append(error_row % bf_errors)
label = bf.label and bf.label_tag(escape(bf.label + ':')) or ''
output.append(normal_row % {'errors': bf_errors, 'label': label, 'field': unicode(bf)})
if field.help_text:
help_text = help_text_html % field.help_text
else:
help_text = u''
output.append(normal_row % {'errors': bf_errors, 'label': label, 'field': unicode(bf), 'help_text': help_text})
if top_errors:
output.insert(0, error_row % top_errors)
if hidden_fields: # Insert any hidden fields in the last row.
Expand All @@ -124,15 +128,15 @@ def _html_output(self, normal_row, error_row, row_ender, errors_on_separate_row)

def as_table(self):
"Returns this form rendered as HTML <tr>s -- excluding the <table></table>."
return self._html_output(u'<tr><th>%(label)s</th><td>%(errors)s%(field)s</td></tr>', u'<tr><td colspan="2">%s</td></tr>', '</td></tr>', False)
return self._html_output(u'<tr><th>%(label)s</th><td>%(errors)s%(field)s%(help_text)s</td></tr>', u'<tr><td colspan="2">%s</td></tr>', '</td></tr>', u'<br />%s', False)

def as_ul(self):
"Returns this form rendered as HTML <li>s -- excluding the <ul></ul>."
return self._html_output(u'<li>%(errors)s%(label)s %(field)s</li>', u'<li>%s</li>', '</li>', False)
return self._html_output(u'<li>%(errors)s%(label)s %(field)s%(help_text)s</li>', u'<li>%s</li>', '</li>', u' %s', False)

def as_p(self):
"Returns this form rendered as HTML <p>s."
return self._html_output(u'<p>%(label)s %(field)s</p>', u'<p>%s</p>', '</p>', True)
return self._html_output(u'<p>%(label)s %(field)s%(help_text)s</p>', u'<p>%s</p>', '</p>', u' %s', True)

def non_field_errors(self):
"""
Expand Down
32 changes: 32 additions & 0 deletions docs/newforms.txt
View file
Expand Up @@ -739,6 +739,38 @@ validation if a particular field's value is not given. ``initial`` values are
The ``widget`` argument lets you specify a ``Widget`` class to use when
rendering this ``Field``. See _`Widgets` below for more information.

``help_text``
~~~~~~~~~~~~~

The ``help_text`` argument lets you specify descriptive text for this
``Field``. If you provide ``help_text``, it will be displayed next to the
``Field`` when the ``Field`` is rendered in a ``Form``.

Here's a full example ``Form`` that implements ``help_text`` for two of its
fields. We've specified ``auto_id=False`` to simplify the output::

>>> class HelpTextContactForm(forms.Form):
... subject = forms.CharField(max_length=100, help_text='100 characters max.')
... message = forms.CharField()
... sender = forms.EmailField(help_text='A valid e-mail address, please.')
... cc_myself = forms.BooleanField()
>>> f = HelpTextContactForm(auto_id=False)
>>> print f.as_table()
<tr><th>Subject:</th><td><input type="text" name="subject" maxlength="100" /><br />100 characters max.</td></tr>
<tr><th>Message:</th><td><input type="text" name="message" /></td></tr>
<tr><th>Sender:</th><td><input type="text" name="sender" /><br />A valid e-mail address, please.</td></tr>
<tr><th>Cc myself:</th><td><input type="checkbox" name="cc_myself" /></td></tr>
>>> print f.as_ul()
<li>Subject: <input type="text" name="subject" maxlength="100" /> 100 characters max.</li>
<li>Message: <input type="text" name="message" /></li>
<li>Sender: <input type="text" name="sender" /> A valid e-mail address, please.</li>
<li>Cc myself: <input type="checkbox" name="cc_myself" /></li>
>>> print f.as_p()
<p>Subject: <input type="text" name="subject" maxlength="100" /> 100 characters max.</p>
<p>Message: <input type="text" name="message" /></p>
<p>Sender: <input type="text" name="sender" /> A valid e-mail address, please.</p>
<p>Cc myself: <input type="checkbox" name="cc_myself" /></p>

Dynamic initial values
----------------------

Expand Down
35 changes: 35 additions & 0 deletions tests/regressiontests/forms/tests.py
View file
Expand Up @@ -2610,6 +2610,41 @@
<li>Username: <input type="text" name="username" value="babik" maxlength="10" /></li>
<li>Password: <input type="password" name="password" /></li>
# Help text ###################################################################
You can specify descriptive text for a field by using the 'help_text' argument
to a Field class. This help text is displayed when a Form is rendered.
>>> class UserRegistration(Form):
... username = CharField(max_length=10, help_text='e.g., user@example.com')
... password = CharField(widget=PasswordInput, help_text='Choose wisely.')
>>> p = UserRegistration(auto_id=False)
>>> print p.as_ul()
<li>Username: <input type="text" name="username" maxlength="10" /> e.g., user@example.com</li>
<li>Password: <input type="password" name="password" /> Choose wisely.</li>
>>> print p.as_p()
<p>Username: <input type="text" name="username" maxlength="10" /> e.g., user@example.com</p>
<p>Password: <input type="password" name="password" /> Choose wisely.</p>
>>> print p.as_table()
<tr><th>Username:</th><td><input type="text" name="username" maxlength="10" /><br />e.g., user@example.com</td></tr>
<tr><th>Password:</th><td><input type="password" name="password" /><br />Choose wisely.</td></tr>
The help text is displayed whether or not data is provided for the form.
>>> p = UserRegistration({'username': u'foo'}, auto_id=False)
>>> print p.as_ul()
<li>Username: <input type="text" name="username" value="foo" maxlength="10" /> e.g., user@example.com</li>
<li><ul class="errorlist"><li>This field is required.</li></ul>Password: <input type="password" name="password" /> Choose wisely.</li>
help_text is not displayed for hidden fields. It can be used for documentation
purposes, though.
>>> class UserRegistration(Form):
... username = CharField(max_length=10, help_text='e.g., user@example.com')
... password = CharField(widget=PasswordInput)
... next = CharField(widget=HiddenInput, initial='/', help_text='Redirect destination')
>>> p = UserRegistration(auto_id=False)
>>> print p.as_ul()
<li>Username: <input type="text" name="username" maxlength="10" /> e.g., user@example.com</li>
<li>Password: <input type="password" name="password" /><input type="hidden" name="next" value="/" /></li>
# Forms with prefixes #########################################################
Sometimes it's necessary to have multiple forms display on the same HTML page,
Expand Down

0 comments on commit cf75fcc

Please sign in to comment.