Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Fixed #3255 -- Added help_text argument to newforms Field class.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@4440 bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
commit cf75fcc8321b822cb4758d167f1fade56a60ad4f 1 parent 83768bf
Adrian Holovaty authored January 28, 2007
62  django/newforms/fields.py
@@ -35,7 +35,7 @@ class Field(object):
35 35
     # Tracks each time a Field instance is created. Used to retain order.
36 36
     creation_counter = 0
37 37
 
38  
-    def __init__(self, required=True, widget=None, label=None, initial=None):
  38
+    def __init__(self, required=True, widget=None, label=None, initial=None, help_text=None):
39 39
         # required -- Boolean that specifies whether the field is required.
40 40
         #             True by default.
41 41
         # widget -- A Widget class, or instance of a Widget class, that should be
@@ -47,9 +47,11 @@ def __init__(self, required=True, widget=None, label=None, initial=None):
47 47
         #         field name, if the Field is part of a Form.
48 48
         # initial -- A value to use in this Field's initial display. This value is
49 49
         #            *not* used as a fallback if data isn't given.
  50
+        # help_text -- An optional string to use as "help text" for this Field.
50 51
         if label is not None:
51 52
             label = smart_unicode(label)
52 53
         self.required, self.label, self.initial = required, label, initial
  54
+        self.help_text = help_text
53 55
         widget = widget or self.widget
54 56
         if isinstance(widget, type):
55 57
             widget = widget()
@@ -85,9 +87,9 @@ def widget_attrs(self, widget):
85 87
         return {}
86 88
 
87 89
 class CharField(Field):
88  
-    def __init__(self, max_length=None, min_length=None, required=True, widget=None, label=None, initial=None):
  90
+    def __init__(self, max_length=None, min_length=None, *args, **kwargs):
89 91
         self.max_length, self.min_length = max_length, min_length
90  
-        super(CharField, self).__init__(required, widget, label, initial)
  92
+        super(CharField, self).__init__(*args, **kwargs)
91 93
 
92 94
     def clean(self, value):
93 95
         "Validates max_length and min_length. Returns a Unicode object."
@@ -106,9 +108,9 @@ def widget_attrs(self, widget):
106 108
             return {'maxlength': str(self.max_length)}
107 109
 
108 110
 class IntegerField(Field):
109  
-    def __init__(self, max_value=None, min_value=None, required=True, widget=None, label=None, initial=None):
  111
+    def __init__(self, max_value=None, min_value=None, *args, **kwargs):
110 112
         self.max_value, self.min_value = max_value, min_value
111  
-        super(IntegerField, self).__init__(required, widget, label, initial)
  113
+        super(IntegerField, self).__init__(*args, **kwargs)
112 114
 
113 115
     def clean(self, value):
114 116
         """
@@ -137,8 +139,8 @@ def clean(self, value):
137 139
 )
138 140
 
139 141
 class DateField(Field):
140  
-    def __init__(self, input_formats=None, required=True, widget=None, label=None, initial=None):
141  
-        super(DateField, self).__init__(required, widget, label, initial)
  142
+    def __init__(self, input_formats=None, *args, **kwargs):
  143
+        super(DateField, self).__init__(*args, **kwargs)
142 144
         self.input_formats = input_formats or DEFAULT_DATE_INPUT_FORMATS
143 145
 
144 146
     def clean(self, value):
@@ -166,8 +168,8 @@ def clean(self, value):
166 168
 )
167 169
 
168 170
 class TimeField(Field):
169  
-    def __init__(self, input_formats=None, required=True, widget=None, label=None, initial=None):
170  
-        super(TimeField, self).__init__(required, widget, label, initial)
  171
+    def __init__(self, input_formats=None, *args, **kwargs):
  172
+        super(TimeField, self).__init__(*args, **kwargs)
171 173
         self.input_formats = input_formats or DEFAULT_TIME_INPUT_FORMATS
172 174
 
173 175
     def clean(self, value):
@@ -200,8 +202,8 @@ def clean(self, value):
200 202
 )
201 203
 
202 204
 class DateTimeField(Field):
203  
-    def __init__(self, input_formats=None, required=True, widget=None, label=None, initial=None):
204  
-        super(DateTimeField, self).__init__(required, widget, label, initial)
  205
+    def __init__(self, input_formats=None, *args, **kwargs):
  206
+        super(DateTimeField, self).__init__(*args, **kwargs)
205 207
         self.input_formats = input_formats or DEFAULT_DATETIME_INPUT_FORMATS
206 208
 
207 209
     def clean(self, value):
@@ -224,14 +226,13 @@ def clean(self, value):
224 226
         raise ValidationError(gettext(u'Enter a valid date/time.'))
225 227
 
226 228
 class RegexField(Field):
227  
-    def __init__(self, regex, max_length=None, min_length=None, error_message=None,
228  
-            required=True, widget=None, label=None, initial=None):
  229
+    def __init__(self, regex, max_length=None, min_length=None, error_message=None, *args, **kwargs):
229 230
         """
230 231
         regex can be either a string or a compiled regular expression object.
231 232
         error_message is an optional error message to use, if
232 233
         'Enter a valid value' is too generic for you.
233 234
         """
234  
-        super(RegexField, self).__init__(required, widget, label, initial)
  235
+        super(RegexField, self).__init__(*args, **kwargs)
235 236
         if isinstance(regex, basestring):
236 237
             regex = re.compile(regex)
237 238
         self.regex = regex
@@ -263,8 +264,9 @@ def clean(self, value):
263 264
     r')@(?:[A-Z0-9-]+\.)+[A-Z]{2,6}$', re.IGNORECASE)  # domain
264 265
 
265 266
 class EmailField(RegexField):
266  
-    def __init__(self, max_length=None, min_length=None, required=True, widget=None, label=None, initial=None):
267  
-        RegexField.__init__(self, email_re, max_length, min_length, gettext(u'Enter a valid e-mail address.'), required, widget, label, initial)
  267
+    def __init__(self, max_length=None, min_length=None, *args, **kwargs):
  268
+        RegexField.__init__(self, email_re, max_length, min_length,
  269
+            gettext(u'Enter a valid e-mail address.'), *args, **kwargs)
268 270
 
269 271
 url_re = re.compile(
270 272
     r'^https?://' # http:// or https://
@@ -280,9 +282,9 @@ def __init__(self, max_length=None, min_length=None, required=True, widget=None,
280 282
     URL_VALIDATOR_USER_AGENT = 'Django (http://www.djangoproject.com/)'
281 283
 
282 284
 class URLField(RegexField):
283  
-    def __init__(self, max_length=None, min_length=None, required=True, verify_exists=False, widget=None, label=None,
284  
-            initial=None, validator_user_agent=URL_VALIDATOR_USER_AGENT):
285  
-        super(URLField, self).__init__(url_re, max_length, min_length, gettext(u'Enter a valid URL.'), required, widget, label, initial)
  285
+    def __init__(self, max_length=None, min_length=None, verify_exists=False,
  286
+            validator_user_agent=URL_VALIDATOR_USER_AGENT, *args, **kwargs):
  287
+        super(URLField, self).__init__(url_re, max_length, min_length, gettext(u'Enter a valid URL.'), *args, **kwargs)
286 288
         self.verify_exists = verify_exists
287 289
         self.user_agent = validator_user_agent
288 290
 
@@ -328,10 +330,8 @@ def clean(self, value):
328 330
         return {True: True, False: False}.get(value, None)
329 331
 
330 332
 class ChoiceField(Field):
331  
-    def __init__(self, choices=(), required=True, widget=Select, label=None, initial=None):
332  
-        if isinstance(widget, type):
333  
-            widget = widget()
334  
-        super(ChoiceField, self).__init__(required, widget, label, initial)
  333
+    def __init__(self, choices=(), required=True, widget=Select, label=None, initial=None, help_text=None):
  334
+        super(ChoiceField, self).__init__(required, widget, label, initial, help_text)
335 335
         self.choices = choices
336 336
 
337 337
     def _get_choices(self):
@@ -362,8 +362,8 @@ def clean(self, value):
362 362
 class MultipleChoiceField(ChoiceField):
363 363
     hidden_widget = MultipleHiddenInput
364 364
 
365  
-    def __init__(self, choices=(), required=True, widget=SelectMultiple, label=None, initial=None):
366  
-        super(MultipleChoiceField, self).__init__(choices, required, widget, label, initial)
  365
+    def __init__(self, choices=(), required=True, widget=SelectMultiple, label=None, initial=None, help_text=None):
  366
+        super(MultipleChoiceField, self).__init__(choices, required, widget, label, initial, help_text)
367 367
 
368 368
     def clean(self, value):
369 369
         """
@@ -390,8 +390,8 @@ class ComboField(Field):
390 390
     """
391 391
     A Field whose clean() method calls multiple Field clean() methods.
392 392
     """
393  
-    def __init__(self, fields=(), required=True, widget=None, label=None, initial=None):
394  
-        super(ComboField, self).__init__(required, widget, label, initial)
  393
+    def __init__(self, fields=(), *args, **kwargs):
  394
+        super(ComboField, self).__init__(*args, **kwargs)
395 395
         # Set 'required' to False on the individual fields, because the
396 396
         # required validation will be handled by ComboField, not by those
397 397
         # individual fields.
@@ -425,8 +425,8 @@ class MultiValueField(Field):
425 425
 
426 426
     You'll probably want to use this with MultiWidget.
427 427
     """
428  
-    def __init__(self, fields=(), required=True, widget=None, label=None, initial=None):
429  
-        super(MultiValueField, self).__init__(required, widget, label, initial)
  428
+    def __init__(self, fields=(), *args, **kwargs):
  429
+        super(MultiValueField, self).__init__(*args, **kwargs)
430 430
         # Set 'required' to False on the individual fields, because the
431 431
         # required validation will be handled by MultiValueField, not by those
432 432
         # individual fields.
@@ -481,9 +481,9 @@ def compress(self, data_list):
481 481
         raise NotImplementedError('Subclasses must implement this method.')
482 482
 
483 483
 class SplitDateTimeField(MultiValueField):
484  
-    def __init__(self, required=True, widget=None, label=None, initial=None):
  484
+    def __init__(self, *args, **kwargs):
485 485
         fields = (DateField(), TimeField())
486  
-        super(SplitDateTimeField, self).__init__(fields, required, widget, label, initial)
  486
+        super(SplitDateTimeField, self).__init__(fields, *args, **kwargs)
487 487
 
488 488
     def compress(self, data_list):
489 489
         if data_list:
14  django/newforms/forms.py
@@ -94,7 +94,7 @@ def add_prefix(self, field_name):
94 94
         """
95 95
         return self.prefix and ('%s-%s' % (self.prefix, field_name)) or field_name
96 96
 
97  
-    def _html_output(self, normal_row, error_row, row_ender, errors_on_separate_row):
  97
+    def _html_output(self, normal_row, error_row, row_ender, help_text_html, errors_on_separate_row):
98 98
         "Helper function for outputting HTML. Used by as_table(), as_ul(), as_p()."
99 99
         top_errors = self.non_field_errors() # Errors that should be displayed above all fields.
100 100
         output, hidden_fields = [], []
@@ -109,7 +109,11 @@ def _html_output(self, normal_row, error_row, row_ender, errors_on_separate_row)
109 109
                 if errors_on_separate_row and bf_errors:
110 110
                     output.append(error_row % bf_errors)
111 111
                 label = bf.label and bf.label_tag(escape(bf.label + ':')) or ''
112  
-                output.append(normal_row % {'errors': bf_errors, 'label': label, 'field': unicode(bf)})
  112
+                if field.help_text:
  113
+                    help_text = help_text_html % field.help_text
  114
+                else:
  115
+                    help_text = u''
  116
+                output.append(normal_row % {'errors': bf_errors, 'label': label, 'field': unicode(bf), 'help_text': help_text})
113 117
         if top_errors:
114 118
             output.insert(0, error_row % top_errors)
115 119
         if hidden_fields: # Insert any hidden fields in the last row.
@@ -124,15 +128,15 @@ def _html_output(self, normal_row, error_row, row_ender, errors_on_separate_row)
124 128
 
125 129
     def as_table(self):
126 130
         "Returns this form rendered as HTML <tr>s -- excluding the <table></table>."
127  
-        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)
  131
+        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)
128 132
 
129 133
     def as_ul(self):
130 134
         "Returns this form rendered as HTML <li>s -- excluding the <ul></ul>."
131  
-        return self._html_output(u'<li>%(errors)s%(label)s %(field)s</li>', u'<li>%s</li>', '</li>', False)
  135
+        return self._html_output(u'<li>%(errors)s%(label)s %(field)s%(help_text)s</li>', u'<li>%s</li>', '</li>', u' %s', False)
132 136
 
133 137
     def as_p(self):
134 138
         "Returns this form rendered as HTML <p>s."
135  
-        return self._html_output(u'<p>%(label)s %(field)s</p>', u'<p>%s</p>', '</p>', True)
  139
+        return self._html_output(u'<p>%(label)s %(field)s%(help_text)s</p>', u'<p>%s</p>', '</p>', u' %s', True)
136 140
 
137 141
     def non_field_errors(self):
138 142
         """
32  docs/newforms.txt
@@ -739,6 +739,38 @@ validation if a particular field's value is not given. ``initial`` values are
739 739
 The ``widget`` argument lets you specify a ``Widget`` class to use when
740 740
 rendering this ``Field``. See _`Widgets` below for more information.
741 741
 
  742
+``help_text``
  743
+~~~~~~~~~~~~~
  744
+
  745
+The ``help_text`` argument lets you specify descriptive text for this
  746
+``Field``. If you provide ``help_text``, it will be displayed next to the
  747
+``Field`` when the ``Field`` is rendered in a ``Form``.
  748
+
  749
+Here's a full example ``Form`` that implements ``help_text`` for two of its
  750
+fields. We've specified ``auto_id=False`` to simplify the output::
  751
+
  752
+    >>> class HelpTextContactForm(forms.Form):
  753
+    ...     subject = forms.CharField(max_length=100, help_text='100 characters max.')
  754
+    ...     message = forms.CharField()
  755
+    ...     sender = forms.EmailField(help_text='A valid e-mail address, please.')
  756
+    ...     cc_myself = forms.BooleanField()
  757
+    >>> f = HelpTextContactForm(auto_id=False)
  758
+    >>> print f.as_table()
  759
+    <tr><th>Subject:</th><td><input type="text" name="subject" maxlength="100" /><br />100 characters max.</td></tr>
  760
+    <tr><th>Message:</th><td><input type="text" name="message" /></td></tr>
  761
+    <tr><th>Sender:</th><td><input type="text" name="sender" /><br />A valid e-mail address, please.</td></tr>
  762
+    <tr><th>Cc myself:</th><td><input type="checkbox" name="cc_myself" /></td></tr>
  763
+    >>> print f.as_ul()
  764
+    <li>Subject: <input type="text" name="subject" maxlength="100" /> 100 characters max.</li>
  765
+    <li>Message: <input type="text" name="message" /></li>
  766
+    <li>Sender: <input type="text" name="sender" /> A valid e-mail address, please.</li>
  767
+    <li>Cc myself: <input type="checkbox" name="cc_myself" /></li>
  768
+    >>> print f.as_p()
  769
+    <p>Subject: <input type="text" name="subject" maxlength="100" /> 100 characters max.</p>
  770
+    <p>Message: <input type="text" name="message" /></p>
  771
+    <p>Sender: <input type="text" name="sender" /> A valid e-mail address, please.</p>
  772
+    <p>Cc myself: <input type="checkbox" name="cc_myself" /></p>
  773
+
742 774
 Dynamic initial values
743 775
 ----------------------
744 776
 
35  tests/regressiontests/forms/tests.py
@@ -2610,6 +2610,41 @@
2610 2610
 <li>Username: <input type="text" name="username" value="babik" maxlength="10" /></li>
2611 2611
 <li>Password: <input type="password" name="password" /></li>
2612 2612
 
  2613
+# Help text ###################################################################
  2614
+
  2615
+You can specify descriptive text for a field by using the 'help_text' argument
  2616
+to a Field class. This help text is displayed when a Form is rendered.
  2617
+>>> class UserRegistration(Form):
  2618
+...    username = CharField(max_length=10, help_text='e.g., user@example.com')
  2619
+...    password = CharField(widget=PasswordInput, help_text='Choose wisely.')
  2620
+>>> p = UserRegistration(auto_id=False)
  2621
+>>> print p.as_ul()
  2622
+<li>Username: <input type="text" name="username" maxlength="10" /> e.g., user@example.com</li>
  2623
+<li>Password: <input type="password" name="password" /> Choose wisely.</li>
  2624
+>>> print p.as_p()
  2625
+<p>Username: <input type="text" name="username" maxlength="10" /> e.g., user@example.com</p>
  2626
+<p>Password: <input type="password" name="password" /> Choose wisely.</p>
  2627
+>>> print p.as_table()
  2628
+<tr><th>Username:</th><td><input type="text" name="username" maxlength="10" /><br />e.g., user@example.com</td></tr>
  2629
+<tr><th>Password:</th><td><input type="password" name="password" /><br />Choose wisely.</td></tr>
  2630
+
  2631
+The help text is displayed whether or not data is provided for the form.
  2632
+>>> p = UserRegistration({'username': u'foo'}, auto_id=False)
  2633
+>>> print p.as_ul()
  2634
+<li>Username: <input type="text" name="username" value="foo" maxlength="10" /> e.g., user@example.com</li>
  2635
+<li><ul class="errorlist"><li>This field is required.</li></ul>Password: <input type="password" name="password" /> Choose wisely.</li>
  2636
+
  2637
+help_text is not displayed for hidden fields. It can be used for documentation
  2638
+purposes, though.
  2639
+>>> class UserRegistration(Form):
  2640
+...    username = CharField(max_length=10, help_text='e.g., user@example.com')
  2641
+...    password = CharField(widget=PasswordInput)
  2642
+...    next = CharField(widget=HiddenInput, initial='/', help_text='Redirect destination')
  2643
+>>> p = UserRegistration(auto_id=False)
  2644
+>>> print p.as_ul()
  2645
+<li>Username: <input type="text" name="username" maxlength="10" /> e.g., user@example.com</li>
  2646
+<li>Password: <input type="password" name="password" /><input type="hidden" name="next" value="/" /></li>
  2647
+
2613 2648
 # Forms with prefixes #########################################################
2614 2649
 
2615 2650
 Sometimes it's necessary to have multiple forms display on the same HTML page,

0 notes on commit cf75fcc

Please sign in to comment.
Something went wrong with that request. Please try again.