Ticket #16264: django-16264.3.diff

File django-16264.3.diff, 16.3 KB (added by bpeschier, 4 years ago)
  • docs/ref/forms/fields.txt

    diff -r b0201f30c3bb docs/ref/forms/fields.txt
    a b  
    278278See the :ref:`format localization <format-localization>` documentation for
    279279more information.
    280280
     281.. _built-in fields:
    281282
    282283Built-in ``Field`` classes
    283284--------------------------
  • docs/ref/forms/widgets.txt

    diff -r b0201f30c3bb docs/ref/forms/widgets.txt
    a b  
    1111handles the rendering of the HTML, and the extraction of data from a GET/POST
    1212dictionary that corresponds to the widget.
    1313
     14Specifying widgets
     15------------------
     16
     17Whenever you specify a field on a form, Django will use a default widget
     18that is appropriate to the type of data that is to be displayed. To find
     19which widget is used on which field, see the documentation about
     20:ref:`built-in fields`.
     21
     22However, if you want to use a different widget for a field, you can
     23just use the :attr:`~Field.widget` argument on the field definition. For example:
     24
     25    .. code-block:: python
     26
     27        from django import forms
     28
     29        class CommentForm(forms.Form):
     30            name = forms.CharField()
     31            url = forms.URLField()
     32            comment = forms.CharField(widget=forms.Textarea)
     33
     34This would specify a form with a comment that uses a larger Textarea widget,
     35rather than the default TextInput widget.
     36
     37
     38Setting arguments for widgets
     39-----------------------------
     40
     41Many widgets have optional extra arguments; they can be set when defining the
     42widget on the field. In this example, the :attr:`~SelectDateWidget.years`
     43attribute is set for a :class:`~django.forms.widgets.extras.SelectDateWidget`:
     44
     45    .. code-block:: python
     46
     47        from django import forms
     48        from django.forms.widgets.extras import SelectDateWidget
     49
     50        YEAR_CHOICES = ('2010', '2009',)
     51        RADIO_CHOICES = (('1','Radio 1',), ('2','Radio 2',),)
     52        CHECKBOX_CHOICES = (('1','The first choice',), ('2','The Second Choice',),)
     53
     54        class SimpleForm(forms.Form):
     55            year = forms.DateField(widget=SelectDateWidget(years=YEAR_CHOICES))
     56            radio = forms.ChoiceField(widget=forms.RadioSelect, choices=RADIO_CHOICES)
     57            checkboxes = forms.MultipleChoiceField(required=False,
     58                widget=forms.CheckboxSelectMultiple, choices=CHECKBOX_CHOICES)
     59
     60The section :ref:`built-in widgets` contains information about which widgets are
     61available and which arguments they accept.
     62
     63
     64Widgets inheriting from the Select widget
     65-----------------------------------------
     66
     67Widgets inheriting from the :class:`Select` widget deal with choices. They present
     68the user with a list of options to choose from. The different widgets present this
     69choice differently; the :class:`Select` widget itself uses a ``<select>`` HTML
     70list representation, while :class:`RadioSelect` uses radio buttons.
     71
     72:class:`Select` widgets are used by default on :class:`ChoiceField` fields. The
     73choices displayed on the widget are inherited from the :class:`ChoiceField` and
     74changing :attr:`ChoiceField.choices` will update :attr:`Select.choices`. For example:
     75
     76    .. code-block:: python
     77
     78        >>> from django import forms
     79        >>> CHOICES = (('1', 'First',), ('2', 'Second',)))
     80        >>> choice = forms.ChoiceField(widget=forms.RadioSelect, choices=CHOICES)
     81        >>> choice.choices
     82        [('1', 'First'), ('2', 'Second')]
     83        >>> choice.widget.choices
     84        [('1', 'First'), ('2', 'Second')]
     85        >>> choice.widget.choices = ()
     86        >>> choice.choices = (('1', 'First and only',),)
     87        >>> choice.widget.choices
     88        [('1', 'First and only')]
     89
     90
     91Widgets which offer a :attr:`~Select.choices` attribute can however be used with
     92fields which are not based on choice - such as a :class:`CharField` - but it is
     93recommended to use a :class:`ChoiceField`-based field when the choices are
     94inherent to the model and not just the representational widget.
     95
     96Customizing widget instances
     97----------------------------
     98
     99When Django renders a widget as HTML, it only renders the bare minimum
     100HTML - Django doesn't add a class definition, or any other widget-specific
     101attributes. This means that all 'TextInput' widgets will appear the same
     102on your Web page.
     103
     104If you want to make one widget look different to another, you need to
     105specify additional attributes for each widget. When you specify a
     106widget, you can provide a list of attributes that will be added to the
     107rendered HTML for the widget.
     108
     109For example, take the following simple form:
     110
     111    .. code-block:: python
     112
     113        from django import forms
     114
     115        class CommentForm(forms.Form):
     116            name = forms.CharField()
     117            url = forms.URLField()
     118            comment = forms.CharField()
     119
     120This form will include three default TextInput widgets, with default rendering -
     121no CSS class, no extra attributes. This means that the input boxes provided for
     122each widget will be rendered exactly the same:
     123
     124    .. code-block:: python
     125
     126        >>> f = CommentForm(auto_id=False)
     127        >>> f.as_table()
     128        <tr><th>Name:</th><td><input type="text" name="name" /></td></tr>
     129        <tr><th>Url:</th><td><input type="text" name="url"/></td></tr>
     130        <tr><th>Comment:</th><td><input type="text" name="comment" /></td></tr>
     131
     132
     133On a real Web page, you probably don't want every widget to look the same. You
     134might want a larger input element for the comment, and you might want the 'name'
     135widget to have some special CSS class. To do this, you use the :attr:`Widget.attrs`
     136argument when creating the widget:
     137
     138For example:
     139
     140    .. code-block:: python
     141
     142        class CommentForm(forms.Form):
     143            name = forms.CharField(
     144                        widget=forms.TextInput(attrs={'class':'special'}))
     145            url = forms.URLField()
     146            comment = forms.CharField(
     147                       widget=forms.TextInput(attrs={'size':'40'}))
     148
     149Django will then include the extra attributes in the rendered output:
     150
     151    .. code-block:: python
     152
     153        >>> f = CommentForm(auto_id=False)
     154        >>> f.as_table()
     155        <tr><th>Name:</th><td><input type="text" name="name" class="special"/></td></tr>
     156        <tr><th>Url:</th><td><input type="text" name="url"/></td></tr>
     157        <tr><th>Comment:</th><td><input type="text" name="comment" size="40"/></td></tr>
     158
     159.. _built-in widgets:
     160
     161Built-in widgets
     162----------------
     163
    14164Django provides a representation of all the basic HTML widgets, plus some
    15165commonly used groups of widgets:
    16166
     167.. class:: Widget
     168
     169    This abstract class cannot be rendered, but provides the basic attribute :attr:`~Widget.attrs`.
     170
     171    .. attribute:: Widget.attrs
     172   
     173        A dictionary containing HTML attributes to be set on the rendered widget.
     174
     175        .. code-block:: python
     176           
     177            >>> name = forms.TextInput(attrs={'size': 10, 'title': 'Your name',})
     178            >>> name.render('name', 'A name')
     179            u'<input title="Your name" type="text" name="name" value="A name" size="10" />'
     180
     181
    17182.. class:: TextInput
    18183
    19184    Text input: ``<input type='text' ...>``
     
    29194        Determines whether the widget will have a value filled in when the
    30195        form is re-displayed after a validation error (default is ``False``).
    31196
    32 .. versionchanged:: 1.3
    33     The default value for
    34     :attr:`~PasswordInput.render_value` was
    35     changed from ``True`` to ``False``
     197        .. versionchanged:: 1.3
     198            The default value for
     199            :attr:`~PasswordInput.render_value` was
     200            changed from ``True`` to ``False``
    36201
    37202.. class:: HiddenInput
    38203
     
    42207
    43208    Multiple ``<input type='hidden' ...>`` widgets.
    44209
     210    A widget that handles multiple hidden widgets for fields that have a list of values.
     211
     212    .. attribute:: MultipleHiddenInput.choices
     213
     214        This attribute is optional when the field does not have a :attr:`~Field.choices`
     215        attribute. If it does, it will override anything you set here when the attribute
     216        is updated on the :class:`Field`.
     217
    45218.. class:: FileInput
    46219
    47220    File upload input: ``<input type='file' ...>``
     
    64237
    65238        The format in which this field's initial value will be displayed.
    66239
    67     If no ``format`` argument is provided, the default format is ``'%Y-%m-%d'``.
     240    If no ``format`` argument is provided, the default format is the first
     241    format found in :setting:`DATE_INPUT_FORMATS` and respects
     242    :ref:`format-localization`.
    68243
    69244.. class:: DateTimeInput
    70245
     
    76251
    77252        The format in which this field's initial value will be displayed.
    78253
    79     If no ``format`` argument is provided, the default format is ``'%Y-%m-%d
    80     %H:%M:%S'``.
     254    If no ``format`` argument is provided, the default format is the first
     255    format found in :setting:`DATETIME_INPUT_FORMATS` and respects
     256    :ref:`format-localization`.
    81257
    82258.. class:: TimeInput
    83259
     
    89265
    90266        The format in which this field's initial value will be displayed.
    91267
    92     If no ``format`` argument is provided, the default format is ``'%H:%M:%S'``.
     268    If no ``format`` argument is provided, the default format is the first
     269    format found in :setting:`TIME_INPUT_FORMATS` and respects
     270    :ref:`format-localization`.
    93271
    94272.. class:: Textarea
    95273
     
    111289
    112290    Select widget: ``<select><option ...>...</select>``
    113291
    114     Requires that your field provides :attr:`~Field.choices`.
     292    .. attribute:: Select.choices
     293
     294        This attribute is optional when the field does not have a :attr:`~Field.choices`
     295        attribute. If it does, it will override anything you set here when the attribute
     296        is updated on the :class:`Field`.
    115297
    116298.. class:: NullBooleanSelect
    117299
     
    119301
    120302.. class:: SelectMultiple
    121303
    122     Select widget allowing multiple selection: ``<select
    123     multiple='multiple'>...</select>``
    124 
    125     Requires that your field provides :attr:`~Field.choices`.
     304    Similar to :class:`Select`, but allows multiple selection:
     305    ``<select multiple='multiple'>...</select>``
    126306
    127307.. class:: RadioSelect
    128308
    129     A list of radio buttons:
     309    Similar to :class:`Select`, but rendered as a list of radio buttons:
    130310
    131311    .. code-block:: html
    132312
     
    135315          ...
    136316        </ul>
    137317
    138     Requires that your field provides :attr:`~Field.choices`.
    139 
    140318.. class:: CheckboxSelectMultiple
    141319
    142     A list of checkboxes:
     320    Similar to :class:`SelectMultiple`, but rendered as a list of check buttons:
    143321
    144322    .. code-block:: html
    145323
     
    150328
    151329.. class:: MultiWidget
    152330
    153     Wrapper around multiple other widgets
     331    Wrapper around multiple other widgets.
     332
     333    Its ``render`` method is different than other widgets', because it has to
     334    figure out how to split a single value for display in multiple widgets.
     335    The ``value`` argument can be one of two things:
     336
     337    * A list.
     338    * A normal value (e.g., a string) that has been "compressed" from
     339      a list of values.
     340
     341    In the second case - i.e., if the value is NOT a list - render() will
     342    first "decompress" the value into a list before rendering it. It does so by
     343    calling the decompress() method, which MultiWidget subclasses must
     344    implement. This method takes a single "compressed" value and returns a
     345    list.
     346
     347    When render() does its HTML rendering, each value in the list is rendered
     348    with the corresponding widget - the first value is rendered in the first
     349    widget, the second value is rendered in the second widget, etc.
     350
     351    Subclasses may implement format_output(), which takes the list of rendered
     352    widgets and returns a string of HTML that formats them any way you'd like.
     353
     354    You'll probably want to use this class with :class:`MultiValueField`.
     355
     356    .. attribute:: widgets
     357
     358        An iterable containing the widgets needed.
    154359
    155360.. class:: SplitDateTimeWidget
    156361
    157     Wrapper around two widgets: ``DateInput`` for the date, and ``TimeInput``
    158     for the time.
     362    Wrapper (using :class:`MultiWidget`) around two widgets: :class:`DateInput`
     363    for the date, and :class:`TimeInput` for the time.
    159364
    160     Takes two optional arguments, ``date_format`` and ``time_format``, which
    161     work just like the ``format`` argument for ``DateInput`` and ``TimeInput``.
     365    ``SplitDateTimeWidget`` has two optional attributes:
    162366
    163 .. currentmodule:: django.forms.extras.widgets
     367    .. attribute:: SplitDateTimeWidget.date_format
     368
     369        Similar to :attr:`DateInput.format`
     370
     371    .. attribute:: SplitDateTimeWidget.time_format
     372
     373        Similar to :attr:`TimeInput.format`
     374
     375
     376.. class:: SplitHiddenDateTimeWidget
     377
     378    Similar to :class:`SplitDateTimeWidget`, but uses :class:`HiddenInput` for
     379    both date and time.
     380
     381.. currentmodule:: django.forms.widgets.extras
    164382
    165383.. class:: SelectDateWidget
    166384
    167     Wrapper around three select widgets: one each for month, day, and year.
     385    Wrapper around three :class:`~django.forms.Select` widgets: one each for month, day, and year.
    168386    Note that this widget lives in a separate file from the standard widgets.
    169387
    170388    Takes one optional argument:
    171389
    172     .. attribute:: List.years
     390    .. attribute:: SelectDateWidget.years
    173391
    174392        An optional list/tuple of years to use in the "year" select box.
    175393        The default is a list containing the current year and the next 9 years.
    176 
    177     .. code-block:: python
    178 
    179         from django.forms.extras.widgets import SelectDateWidget
    180 
    181         date = forms.DateField(widget=SelectDateWidget())
    182 
    183 Specifying widgets
    184 ------------------
    185 .. currentmodule:: django.forms
    186 
    187 .. attribute:: Form.widget
    188 
    189 Whenever you specify a field on a form, Django will use a default widget
    190 that is appropriate to the type of data that is to be displayed. To find
    191 which widget is used on which field, see the documentation for the
    192 built-in Field classes.
    193 
    194 However, if you want to use a different widget for a field, you can -
    195 just use the 'widget' argument on the field definition. For example::
    196 
    197     from django import forms
    198 
    199     class CommentForm(forms.Form):
    200         name = forms.CharField()
    201         url = forms.URLField()
    202         comment = forms.CharField(widget=forms.Textarea)
    203 
    204 This would specify a form with a comment that uses a larger Textarea widget,
    205 rather than the default TextInput widget.
    206 
    207 Customizing widget instances
    208 ----------------------------
    209 
    210 When Django renders a widget as HTML, it only renders the bare minimum
    211 HTML - Django doesn't add a class definition, or any other widget-specific
    212 attributes. This means that all 'TextInput' widgets will appear the same
    213 on your Web page.
    214 
    215 If you want to make one widget look different to another, you need to
    216 specify additional attributes for each widget. When you specify a
    217 widget, you can provide a list of attributes that will be added to the
    218 rendered HTML for the widget.
    219 
    220 For example, take the following simple form::
    221 
    222     class CommentForm(forms.Form):
    223         name = forms.CharField()
    224         url = forms.URLField()
    225         comment = forms.CharField()
    226 
    227 This form will include three default TextInput widgets, with default rendering -
    228 no CSS class, no extra attributes. This means that the input boxes provided for
    229 each widget will be rendered exactly the same::
    230 
    231     >>> f = CommentForm(auto_id=False)
    232     >>> f.as_table()
    233     <tr><th>Name:</th><td><input type="text" name="name" /></td></tr>
    234     <tr><th>Url:</th><td><input type="text" name="url"/></td></tr>
    235     <tr><th>Comment:</th><td><input type="text" name="comment" /></td></tr>
    236 
    237 
    238 On a real Web page, you probably don't want every widget to look the same. You
    239 might want a larger input element for the comment, and you might want the 'name'
    240 widget to have some special CSS class. To do this, you use the ``attrs``
    241 argument when creating the widget:
    242 
    243 .. attribute:: Widget.attrs
    244 
    245 For example::
    246 
    247     class CommentForm(forms.Form):
    248         name = forms.CharField(
    249                     widget=forms.TextInput(attrs={'class':'special'}))
    250         url = forms.URLField()
    251         comment = forms.CharField(
    252                    widget=forms.TextInput(attrs={'size':'40'}))
    253 
    254 Django will then include the extra attributes in the rendered output::
    255 
    256     >>> f = CommentForm(auto_id=False)
    257     >>> f.as_table()
    258     <tr><th>Name:</th><td><input type="text" name="name" class="special"/></td></tr>
    259     <tr><th>Url:</th><td><input type="text" name="url"/></td></tr>
    260     <tr><th>Comment:</th><td><input type="text" name="comment" size="40"/></td></tr>
Back to Top