Django

Code

Changeset 4440

Show
Ignore:
Timestamp:
01/28/07 16:10:04 (2 years ago)
Author:
adrian
Message:

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

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • django/trunk/django/newforms/fields.py

    r4411 r4440  
    3636    creation_counter = 0 
    3737 
    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): 
    3939        # required -- Boolean that specifies whether the field is required. 
    4040        #             True by default. 
    …… 
    4848        # initial -- A value to use in this Field's initial display. This value is 
    4949        #            *not* used as a fallback if data isn't given. 
     50        # help_text -- An optional string to use as "help text" for this Field. 
    5051        if label is not None: 
    5152            label = smart_unicode(label) 
    5253        self.required, self.label, self.initial = required, label, initial 
     54        self.help_text = help_text 
    5355        widget = widget or self.widget 
    5456        if isinstance(widget, type): 
    …… 
    8688 
    8789class 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): 
    8991        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) 
    9193 
    9294    def clean(self, value): 
    …… 
    107109 
    108110class 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): 
    110112        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) 
    112114 
    113115    def clean(self, value): 
    …… 
    138140 
    139141class 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) 
    142144        self.input_formats = input_formats or DEFAULT_DATE_INPUT_FORMATS 
    143145 
    …… 
    167169 
    168170class 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) 
    171173        self.input_formats = input_formats or DEFAULT_TIME_INPUT_FORMATS 
    172174 
    …… 
    201203 
    202204class 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) 
    205207        self.input_formats = input_formats or DEFAULT_DATETIME_INPUT_FORMATS 
    206208 
    …… 
    225227 
    226228class 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): 
    229230        """ 
    230231        regex can be either a string or a compiled regular expression object. 
    …… 
    232233        'Enter a valid value' is too generic for you. 
    233234        """ 
    234         super(RegexField, self).__init__(required, widget, label, initial) 
     235        super(RegexField, self).__init__(*args, **kwargs) 
    235236        if isinstance(regex, basestring): 
    236237            regex = re.compile(regex) 
    …… 
    264265 
    265266class 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) 
    268270 
    269271url_re = re.compile( 
    …… 
    281283 
    282284class 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) 
    286288        self.verify_exists = verify_exists 
    287289        self.user_agent = validator_user_agent 
    …… 
    329331 
    330332class 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) 
    335335        self.choices = choices 
    336336 
    …… 
    363363    hidden_widget = MultipleHiddenInput 
    364364 
    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) 
    367367 
    368368    def clean(self, value): 
    …… 
    391391    A Field whose clean() method calls multiple Field clean() methods. 
    392392    """ 
    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) 
    395395        # Set 'required' to False on the individual fields, because the 
    396396        # required validation will be handled by ComboField, not by those 
    …… 
    426426    You'll probably want to use this with MultiWidget. 
    427427    """ 
    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) 
    430430        # Set 'required' to False on the individual fields, because the 
    431431        # required validation will be handled by MultiValueField, not by those 
    …… 
    482482 
    483483class SplitDateTimeField(MultiValueField): 
    484     def __init__(self, required=True, widget=None, label=None, initial=None): 
     484    def __init__(self, *args, **kwargs): 
    485485        fields = (DateField(), TimeField()) 
    486         super(SplitDateTimeField, self).__init__(fields, required, widget, label, initial) 
     486        super(SplitDateTimeField, self).__init__(fields, *args, **kwargs) 
    487487 
    488488    def compress(self, data_list): 

  • django/trunk/django/newforms/forms.py

    r4437 r4440  
    9595        return self.prefix and ('%s-%s' % (self.prefix, field_name)) or field_name 
    9696 
    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): 
    9898        "Helper function for outputting HTML. Used by as_table(), as_ul(), as_p()." 
    9999        top_errors = self.non_field_errors() # Errors that should be displayed above all fields. 
    …… 
    110110                    output.append(error_row % bf_errors) 
    111111                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}) 
    113117        if top_errors: 
    114118            output.insert(0, error_row % top_errors) 
    …… 
    125129    def as_table(self): 
    126130        "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) 
    128132 
    129133    def as_ul(self): 
    130134        "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) 
    132136 
    133137    def as_p(self): 
    134138        "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) 
    136140 
    137141    def non_field_errors(self): 

  • django/trunk/docs/newforms.txt

    r4409 r4440  
    740740rendering this ``Field``. See _`Widgets` below for more information. 
    741741 
     742``help_text`` 
     743~~~~~~~~~~~~~ 
     744 
     745The ``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 
     749Here's a full example ``Form`` that implements ``help_text`` for two of its 
     750fields. 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 
    742774Dynamic initial values 
    743775---------------------- 

  • django/trunk/tests/regressiontests/forms/tests.py

    r4438 r4440  
    26112611<li>Password: <input type="password" name="password" /></li> 
    26122612 
     2613# Help text ################################################################### 
     2614 
     2615You can specify descriptive text for a field by using the 'help_text' argument 
     2616to 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 
     2631The 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 
     2637help_text is not displayed for hidden fields. It can be used for documentation 
     2638purposes, 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 
    26132648# Forms with prefixes ######################################################### 
    26142649