Ticket #16264: django-16264.diff

File django-16264.diff, 14.6 KB (added by bpeschier, 4 years ago)
  • docs/ref/forms/widgets.txt

    diff -r f7582637764c 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
    14 Django provides a representation of all the basic HTML widgets, plus some
    15 commonly used groups of widgets:
    16 
    17 .. class:: TextInput
    18 
    19     Text input: ``<input type='text' ...>``
    20 
    21 .. class:: PasswordInput
    22 
    23     Password input: ``<input type='password' ...>``
    24 
    25     Takes one optional argument:
    26 
    27     .. attribute:: PasswordInput.render_value
    28 
    29         Determines whether the widget will have a value filled in when the
    30         form is re-displayed after a validation error (default is ``False``).
    31 
    32 .. versionchanged:: 1.3
    33     The default value for
    34     :attr:`~PasswordInput.render_value` was
    35     changed from ``True`` to ``False``
    36 
    37 .. class:: HiddenInput
    38 
    39     Hidden input: ``<input type='hidden' ...>``
    40 
    41 .. class:: MultipleHiddenInput
    42 
    43     Multiple ``<input type='hidden' ...>`` widgets.
    44 
    45 .. class:: FileInput
    46 
    47     File upload input: ``<input type='file' ...>``
    48 
    49 .. class:: ClearableFileInput
    50 
    51     .. versionadded:: 1.3
    52 
    53     File upload input: ``<input type='file' ...>``, with an additional checkbox
    54     input to clear the field's value, if the field is not required and has
    55     initial data.
    56 
    57 .. class:: DateInput
    58 
    59     Date input as a simple text box: ``<input type='text' ...>``
    60 
    61     Takes one optional argument:
    62 
    63     .. attribute:: DateInput.format
    64 
    65         The format in which this field's initial value will be displayed.
    66 
    67     If no ``format`` argument is provided, the default format is ``'%Y-%m-%d'``.
    68 
    69 .. class:: DateTimeInput
    70 
    71     Date/time input as a simple text box: ``<input type='text' ...>``
    72 
    73     Takes one optional argument:
    74 
    75     .. attribute:: DateTimeInput.format
    76 
    77         The format in which this field's initial value will be displayed.
    78 
    79     If no ``format`` argument is provided, the default format is ``'%Y-%m-%d
    80     %H:%M:%S'``.
    81 
    82 .. class:: TimeInput
    83 
    84     Time input as a simple text box: ``<input type='text' ...>``
    85 
    86     Takes one optional argument:
    87 
    88     .. attribute:: TimeInput.format
    89 
    90         The format in which this field's initial value will be displayed.
    91 
    92     If no ``format`` argument is provided, the default format is ``'%H:%M:%S'``.
    93 
    94 .. class:: Textarea
    95 
    96     Text area: ``<textarea>...</textarea>``
    97 
    98 .. class:: CheckboxInput
    99 
    100     Checkbox: ``<input type='checkbox' ...>``
    101 
    102     Takes one optional argument:
    103 
    104     .. attribute:: CheckboxInput.check_test
    105 
    106         A callable that takes the value of the CheckBoxInput
    107         and returns ``True`` if the checkbox should be checked for
    108         that value.
    109 
    110 .. class:: Select
    111 
    112     Select widget: ``<select><option ...>...</select>``
    113 
    114     Requires that your field provides :attr:`~Field.choices`.
    115 
    116 .. class:: NullBooleanSelect
    117 
    118     Select widget with options 'Unknown', 'Yes' and 'No'
    119 
    120 .. class:: SelectMultiple
    121 
    122     Select widget allowing multiple selection: ``<select
    123     multiple='multiple'>...</select>``
    124 
    125     Requires that your field provides :attr:`~Field.choices`.
    126 
    127 .. class:: RadioSelect
    128 
    129     A list of radio buttons:
    130 
    131     .. code-block:: html
    132 
    133         <ul>
    134           <li><input type='radio' ...></li>
    135           ...
    136         </ul>
    137 
    138     Requires that your field provides :attr:`~Field.choices`.
    139 
    140 .. class:: CheckboxSelectMultiple
    141 
    142     A list of checkboxes:
    143 
    144     .. code-block:: html
    145 
    146         <ul>
    147           <li><input type='checkbox' ...></li>
    148           ...
    149         </ul>
    150 
    151 .. class:: MultiWidget
    152 
    153     Wrapper around multiple other widgets
    154 
    155 .. class:: SplitDateTimeWidget
    156 
    157     Wrapper around two widgets: ``DateInput`` for the date, and ``TimeInput``
    158     for the time.
    159 
    160     Takes two optional arguments, ``date_format`` and ``time_format``, which
    161     work just like the ``format`` argument for ``DateInput`` and ``TimeInput``.
    162 
    163 .. currentmodule:: django.forms.extras.widgets
    164 
    165 .. class:: SelectDateWidget
    166 
    167     Wrapper around three select widgets: one each for month, day, and year.
    168     Note that this widget lives in a separate file from the standard widgets.
    169 
    170     Takes one optional argument:
    171 
    172     .. attribute:: List.years
    173 
    174         An optional list/tuple of years to use in the "year" select box.
    175         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 
    18314Specifying widgets
    18415------------------
    185 .. currentmodule:: django.forms
    186 
    187 .. attribute:: Form.widget
    18816
    18917Whenever you specify a field on a form, Django will use a default widget
    19018that is appropriate to the type of data that is to be displayed. To find
    19119which widget is used on which field, see the documentation for the
    19220built-in Field classes.
    19321
    194 However, if you want to use a different widget for a field, you can -
     22However, if you want to use a different widget for a field, you can
    19523just use the 'widget' argument on the field definition. For example::
    19624
    19725    from django import forms
     
    20432This would specify a form with a comment that uses a larger Textarea widget,
    20533rather than the default TextInput widget.
    20634
     35
     36Setting arguments for widgets
     37-----------------------------
     38
     39Some widgets take over arguments from the fields they represent, for example
     40:class:`RadioSelect` or :class:`MultipleChoiceField` will use the choices of
     41the underlying field. Some widgets have optional extra arguments; they can be
     42set when defining the widget on the field. The reference below describes which
     43options can be set.
     44
     45In this example, the years attribute is set for a
     46:class:`django.forms.widgets.extras.SelectDateWidget`: ::
     47
     48    YEAR_CHOICES = ('2010', '2009',)
     49    RADIO_CHOICES = (('1','Radio 1',), ('2','Radio 2',),)
     50    CHECKBOX_CHOICES = (('1','The first choice',), ('2','The Second Choice',),)
     51
     52    class SimpleForm(forms.Form):
     53        radio = forms.ChoiceField(widget=RadioSelect, choices=RADIO_CHOICES)
     54        checkboxes = forms.MultipleChoiceField(required=False,
     55            widget=CheckboxSelectMultiple, choices=CHECKBOX_CHOICES)
     56        date = forms.DateField(widget=SelectDateWidget(years=YEAR_CHOICES))
     57
     58
     59Widgets with choices
     60^^^^^^^^^^^^^^^^^^^^
     61
     62A couple of widgets deal with choices; these are mainly based on the
     63:class:`Select` widget and in most cases "owned" by a field based on
     64:class:`ChoiceField`. The :class:`ChoiceField` dictates what the choices are
     65and resets the choices on the widget everytime they get changed on the field.
     66
     67Widgets which offer a ``choices`` attribute can however be used with fields
     68which are not based on choice, such as a :class:`TextField`, but it is
     69recommended to use a :class:`ChoiceField`-based field when the choices are
     70inherent to the model and not just the representational widget.
     71
    20772Customizing widget instances
    20873----------------------------
    20974
     
    237102
    238103On a real Web page, you probably don't want every widget to look the same. You
    239104might 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``
     105widget to have some special CSS class. To do this, you use the :attr:`Widget.attrs`
    241106argument when creating the widget:
    242107
    243 .. attribute:: Widget.attrs
    244 
    245108For example::
    246109
    247110    class CommentForm(forms.Form):
     
    258121    <tr><th>Name:</th><td><input type="text" name="name" class="special"/></td></tr>
    259122    <tr><th>Url:</th><td><input type="text" name="url"/></td></tr>
    260123    <tr><th>Comment:</th><td><input type="text" name="comment" size="40"/></td></tr>
     124
     125Built-in widgets
     126----------------
     127
     128Django provides a representation of all the basic HTML widgets, plus some
     129commonly used groups of widgets:
     130
     131.. class:: Widget
     132
     133    This abstract class cannot be rendered, but provides the basic attribute :attr:`~Widget.attrs`.
     134
     135    .. attribute:: Widget.attrs
     136   
     137        A dictionary containing HTML attributes to be set on the rendered widget.
     138
     139        .. code-block:: python
     140           
     141            >>> name = forms.TextInput(attrs={'size': 10, 'title': 'Your name',})
     142            >>> name.render('name', 'A name')
     143            u'<input title="Your name" type="text" name="name" value="A name" size="10" />'
     144
     145
     146.. class:: TextInput
     147
     148    Text input: ``<input type='text' ...>``
     149
     150.. class:: PasswordInput
     151
     152    Password input: ``<input type='password' ...>``
     153
     154    Takes one optional argument:
     155
     156    .. attribute:: PasswordInput.render_value
     157
     158        Determines whether the widget will have a value filled in when the
     159        form is re-displayed after a validation error (default is ``False``).
     160
     161        .. versionchanged:: 1.3
     162            The default value for
     163            :attr:`~PasswordInput.render_value` was
     164            changed from ``True`` to ``False``
     165
     166.. class:: HiddenInput
     167
     168    Hidden input: ``<input type='hidden' ...>``
     169
     170.. class:: MultipleHiddenInput
     171
     172    Multiple ``<input type='hidden' ...>`` widgets.
     173
     174    A widget that handles multiple hidden widgets for fields that have a list of values.
     175
     176    .. attribute:: MultipleHiddenInput.choices
     177
     178        This attribute is optional when the field does not have a :attr:`~Field.choices`
     179        attribute. If it does, it will override anything you set here when the attribute
     180        is updated on the :class:`Field`.
     181
     182.. class:: FileInput
     183
     184    File upload input: ``<input type='file' ...>``
     185
     186.. class:: ClearableFileInput
     187
     188    .. versionadded:: 1.3
     189
     190    File upload input: ``<input type='file' ...>``, with an additional checkbox
     191    input to clear the field's value, if the field is not required and has
     192    initial data.
     193
     194.. class:: DateInput
     195
     196    Date input as a simple text box: ``<input type='text' ...>``
     197
     198    Takes one optional argument:
     199
     200    .. attribute:: DateInput.format
     201
     202        The format in which this field's initial value will be displayed.
     203
     204    If no ``format`` argument is provided, the default format is the first
     205    format found in :setting:`DATE_INPUT_FORMATS`.
     206
     207.. class:: DateTimeInput
     208
     209    Date/time input as a simple text box: ``<input type='text' ...>``
     210
     211    Takes one optional argument:
     212
     213    .. attribute:: DateTimeInput.format
     214
     215        The format in which this field's initial value will be displayed.
     216
     217    If no ``format`` argument is provided, the default format is the first
     218    format found in :setting:`DATETIME_INPUT_FORMATS`.
     219
     220.. class:: TimeInput
     221
     222    Time input as a simple text box: ``<input type='text' ...>``
     223
     224    Takes one optional argument:
     225
     226    .. attribute:: TimeInput.format
     227
     228        The format in which this field's initial value will be displayed.
     229
     230    If no ``format`` argument is provided, the default format is the first
     231    format found in :setting:`TIME_INPUT_FORMATS`.
     232
     233.. class:: Textarea
     234
     235    Text area: ``<textarea>...</textarea>``
     236
     237.. class:: CheckboxInput
     238
     239    Checkbox: ``<input type='checkbox' ...>``
     240
     241    Takes one optional argument:
     242
     243    .. attribute:: CheckboxInput.check_test
     244
     245        A callable that takes the value of the CheckBoxInput
     246        and returns ``True`` if the checkbox should be checked for
     247        that value.
     248
     249.. class:: Select
     250
     251    Select widget: ``<select><option ...>...</select>``
     252
     253    .. attribute:: Select.choices
     254
     255        This attribute is optional when the field does not have a :attr:`~Field.choices`
     256        attribute. If it does, it will override anything you set here when the attribute
     257        is updated on the :class:`Field`.
     258
     259.. class:: NullBooleanSelect
     260
     261    Select widget with options 'Unknown', 'Yes' and 'No'
     262
     263.. class:: SelectMultiple
     264
     265    Similar to :class:`Select`, but allows multiple selection:
     266    ``<select multiple='multiple'>...</select>``
     267
     268.. class:: RadioSelect
     269
     270    Similar to :class:`Select`, but rendered as a list of radio buttons:
     271
     272    .. code-block:: html
     273
     274        <ul>
     275          <li><input type='radio' ...></li>
     276          ...
     277        </ul>
     278
     279.. class:: CheckboxSelectMultiple
     280
     281    Similar to :class:`SelectMultiple`, but rendered as a list of check buttons:
     282
     283    .. code-block:: html
     284
     285        <ul>
     286          <li><input type='checkbox' ...></li>
     287          ...
     288        </ul>
     289
     290.. class:: MultiWidget
     291
     292    Wrapper around multiple other widgets.
     293
     294    Its ``render`` method is different than other widgets', because it has to
     295    figure out how to split a single value for display in multiple widgets.
     296    The ``value`` argument can be one of two things:
     297
     298    * A list.
     299    * A normal value (e.g., a string) that has been "compressed" from
     300      a list of values.
     301
     302    In the second case -- i.e., if the value is NOT a list -- render() will
     303    first "decompress" the value into a list before rendering it. It does so by
     304    calling the decompress() method, which MultiWidget subclasses must
     305    implement. This method takes a single "compressed" value and returns a
     306    list.
     307
     308    When render() does its HTML rendering, each value in the list is rendered
     309    with the corresponding widget -- the first value is rendered in the first
     310    widget, the second value is rendered in the second widget, etc.
     311
     312    Subclasses may implement format_output(), which takes the list of rendered
     313    widgets and returns a string of HTML that formats them any way you'd like.
     314
     315    You'll probably want to use this class with :class:`MultiValueField`.
     316
     317    .. attribute:: widgets
     318
     319        An iterable containing the widgets needed.
     320
     321.. class:: SplitDateTimeWidget
     322
     323    Wrapper (using :class:`MultiWidget`) around two widgets: :class:`DateInput`
     324    for the date, and :class:`TimeInput` for the time.
     325
     326    ``SplitDateTimeWidget`` has two optional attributes:
     327
     328    .. attribute:: SplitDateTimeWidget.date_format
     329
     330        Similar to :attr:`DateInput.format`
     331
     332    .. attribute:: SplitDateTimeWidget.time_format
     333
     334        Similar to :attr:`TimeInput.format`
     335
     336
     337.. class:: SplitHiddenDateTimeWidget
     338
     339    Similar to :class:`SplitDateTimeWidget`, but uses :class:`HiddenInput` for
     340    both date and time.
     341
     342.. currentmodule:: django.forms.widgets.extras
     343
     344.. class:: SelectDateWidget
     345
     346    Wrapper around three :class:`~django.forms.Select` widgets: one each for month, day, and year.
     347    Note that this widget lives in a separate file from the standard widgets.
     348
     349    Takes one optional argument:
     350
     351    .. attribute:: SelectDateWidget.years
     352
     353        An optional list/tuple of years to use in the "year" select box.
     354        The default is a list containing the current year and the next 9 years.
Back to Top