Ticket #16264: django-16264.2.diff

File django-16264.2.diff, 15.4 KB (added by Bas Peschier, 13 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
     41Some widgets take over arguments from the fields they represent, for example
     42:class:`RadioSelect` or :class:`MultipleChoiceField` will use the choices of
     43the underlying field. Some widgets have optional extra arguments; they can be
     44set when defining the widget on the field. The reference below describes which
     45options can be set.
     46
     47In this example, the :attr:`SelectDateWidget.years` attribute is set for a
     48:class:`~django.forms.widgets.extras.SelectDateWidget`:
     49
     50    .. code-block:: python
     51
     52        from django import forms
     53        from django.forms.widgets.extras import SelectDateWidget
     54
     55        YEAR_CHOICES = ('2010', '2009',)
     56        RADIO_CHOICES = (('1','Radio 1',), ('2','Radio 2',),)
     57        CHECKBOX_CHOICES = (('1','The first choice',), ('2','The Second Choice',),)
     58
     59        class SimpleForm(forms.Form):
     60            radio = forms.ChoiceField(widget=forms.RadioSelect, choices=RADIO_CHOICES)
     61            checkboxes = forms.MultipleChoiceField(required=False,
     62                widget=forms.CheckboxSelectMultiple, choices=CHECKBOX_CHOICES)
     63            date = forms.DateField(widget=SelectDateWidget(years=YEAR_CHOICES))
     64
     65
     66Widgets with choices
     67^^^^^^^^^^^^^^^^^^^^
     68
     69Widgets based on the :class:`Select` widget deal with choices. In the default
     70case these are "owned" by a field based on :class:`ChoiceField`. The
     71:class:`ChoiceField` dictates what the choices are and resets the choices on
     72the widget everytime they get changed on the field.
     73
     74Widgets which offer a ``choices`` attribute can however be used with fields
     75which are not based on choice - such as a :class:`TextField` - but it is
     76recommended to use a :class:`ChoiceField`-based field when the choices are
     77inherent to the model and not just the representational widget.
     78
     79Customizing widget instances
     80----------------------------
     81
     82When Django renders a widget as HTML, it only renders the bare minimum
     83HTML - Django doesn't add a class definition, or any other widget-specific
     84attributes. This means that all 'TextInput' widgets will appear the same
     85on your Web page.
     86
     87If you want to make one widget look different to another, you need to
     88specify additional attributes for each widget. When you specify a
     89widget, you can provide a list of attributes that will be added to the
     90rendered HTML for the widget.
     91
     92For example, take the following simple form:
     93
     94    .. code-block:: python
     95
     96        from django import forms
     97
     98        class CommentForm(forms.Form):
     99            name = forms.CharField()
     100            url = forms.URLField()
     101            comment = forms.CharField()
     102
     103This form will include three default TextInput widgets, with default rendering -
     104no CSS class, no extra attributes. This means that the input boxes provided for
     105each widget will be rendered exactly the same:
     106
     107    .. code-block:: python
     108
     109        >>> f = CommentForm(auto_id=False)
     110        >>> f.as_table()
     111        <tr><th>Name:</th><td><input type="text" name="name" /></td></tr>
     112        <tr><th>Url:</th><td><input type="text" name="url"/></td></tr>
     113        <tr><th>Comment:</th><td><input type="text" name="comment" /></td></tr>
     114
     115
     116On a real Web page, you probably don't want every widget to look the same. You
     117might want a larger input element for the comment, and you might want the 'name'
     118widget to have some special CSS class. To do this, you use the :attr:`Widget.attrs`
     119argument when creating the widget:
     120
     121For example:
     122
     123    .. code-block:: python
     124
     125        class CommentForm(forms.Form):
     126            name = forms.CharField(
     127                        widget=forms.TextInput(attrs={'class':'special'}))
     128            url = forms.URLField()
     129            comment = forms.CharField(
     130                       widget=forms.TextInput(attrs={'size':'40'}))
     131
     132Django will then include the extra attributes in the rendered output:
     133
     134    .. code-block:: python
     135
     136        >>> f = CommentForm(auto_id=False)
     137        >>> f.as_table()
     138        <tr><th>Name:</th><td><input type="text" name="name" class="special"/></td></tr>
     139        <tr><th>Url:</th><td><input type="text" name="url"/></td></tr>
     140        <tr><th>Comment:</th><td><input type="text" name="comment" size="40"/></td></tr>
     141
     142Built-in widgets
     143----------------
     144
    14145Django provides a representation of all the basic HTML widgets, plus some
    15146commonly used groups of widgets:
    16147
     148.. class:: Widget
     149
     150    This abstract class cannot be rendered, but provides the basic attribute :attr:`~Widget.attrs`.
     151
     152    .. attribute:: Widget.attrs
     153   
     154        A dictionary containing HTML attributes to be set on the rendered widget.
     155
     156        .. code-block:: python
     157           
     158            >>> name = forms.TextInput(attrs={'size': 10, 'title': 'Your name',})
     159            >>> name.render('name', 'A name')
     160            u'<input title="Your name" type="text" name="name" value="A name" size="10" />'
     161
     162
    17163.. class:: TextInput
    18164
    19165    Text input: ``<input type='text' ...>``
    … …  
    29175        Determines whether the widget will have a value filled in when the
    30176        form is re-displayed after a validation error (default is ``False``).
    31177
    32 .. versionchanged:: 1.3
    33     The default value for
    34     :attr:`~PasswordInput.render_value` was
    35     changed from ``True`` to ``False``
     178        .. versionchanged:: 1.3
     179            The default value for
     180            :attr:`~PasswordInput.render_value` was
     181            changed from ``True`` to ``False``
    36182
    37183.. class:: HiddenInput
    38184
    … …  
    42188
    43189    Multiple ``<input type='hidden' ...>`` widgets.
    44190
     191    A widget that handles multiple hidden widgets for fields that have a list of values.
     192
     193    .. attribute:: MultipleHiddenInput.choices
     194
     195        This attribute is optional when the field does not have a :attr:`~Field.choices`
     196        attribute. If it does, it will override anything you set here when the attribute
     197        is updated on the :class:`Field`.
     198
    45199.. class:: FileInput
    46200
    47201    File upload input: ``<input type='file' ...>``
    … …  
    64218
    65219        The format in which this field's initial value will be displayed.
    66220
    67     If no ``format`` argument is provided, the default format is ``'%Y-%m-%d'``.
     221    If no ``format`` argument is provided, the default format is the first
     222    format found in :setting:`DATE_INPUT_FORMATS`.
    68223
    69224.. class:: DateTimeInput
    70225
    … …  
    76231
    77232        The format in which this field's initial value will be displayed.
    78233
    79     If no ``format`` argument is provided, the default format is ``'%Y-%m-%d
    80     %H:%M:%S'``.
     234    If no ``format`` argument is provided, the default format is the first
     235    format found in :setting:`DATETIME_INPUT_FORMATS`.
    81236
    82237.. class:: TimeInput
    83238
    … …  
    89244
    90245        The format in which this field's initial value will be displayed.
    91246
    92     If no ``format`` argument is provided, the default format is ``'%H:%M:%S'``.
     247    If no ``format`` argument is provided, the default format is the first
     248    format found in :setting:`TIME_INPUT_FORMATS`.
    93249
    94250.. class:: Textarea
    95251
    … …  
    111267
    112268    Select widget: ``<select><option ...>...</select>``
    113269
    114     Requires that your field provides :attr:`~Field.choices`.
     270    .. attribute:: Select.choices
     271
     272        This attribute is optional when the field does not have a :attr:`~Field.choices`
     273        attribute. If it does, it will override anything you set here when the attribute
     274        is updated on the :class:`Field`.
    115275
    116276.. class:: NullBooleanSelect
    117277
    … …  
    119279
    120280.. class:: SelectMultiple
    121281
    122     Select widget allowing multiple selection: ``<select
    123     multiple='multiple'>...</select>``
    124 
    125     Requires that your field provides :attr:`~Field.choices`.
     282    Similar to :class:`Select`, but allows multiple selection:
     283    ``<select multiple='multiple'>...</select>``
    126284
    127285.. class:: RadioSelect
    128286
    129     A list of radio buttons:
     287    Similar to :class:`Select`, but rendered as a list of radio buttons:
    130288
    131289    .. code-block:: html
    132290
    … …  
    135293          ...
    136294        </ul>
    137295
    138     Requires that your field provides :attr:`~Field.choices`.
    139 
    140296.. class:: CheckboxSelectMultiple
    141297
    142     A list of checkboxes:
     298    Similar to :class:`SelectMultiple`, but rendered as a list of check buttons:
    143299
    144300    .. code-block:: html
    145301
    … …  
    150306
    151307.. class:: MultiWidget
    152308
    153     Wrapper around multiple other widgets
     309    Wrapper around multiple other widgets.
     310
     311    Its ``render`` method is different than other widgets', because it has to
     312    figure out how to split a single value for display in multiple widgets.
     313    The ``value`` argument can be one of two things:
     314
     315    * A list.
     316    * A normal value (e.g., a string) that has been "compressed" from
     317      a list of values.
     318
     319    In the second case - i.e., if the value is NOT a list - render() will
     320    first "decompress" the value into a list before rendering it. It does so by
     321    calling the decompress() method, which MultiWidget subclasses must
     322    implement. This method takes a single "compressed" value and returns a
     323    list.
     324
     325    When render() does its HTML rendering, each value in the list is rendered
     326    with the corresponding widget - the first value is rendered in the first
     327    widget, the second value is rendered in the second widget, etc.
     328
     329    Subclasses may implement format_output(), which takes the list of rendered
     330    widgets and returns a string of HTML that formats them any way you'd like.
     331
     332    You'll probably want to use this class with :class:`MultiValueField`.
     333
     334    .. attribute:: widgets
     335
     336        An iterable containing the widgets needed.
    154337
    155338.. class:: SplitDateTimeWidget
    156339
    157     Wrapper around two widgets: ``DateInput`` for the date, and ``TimeInput``
    158     for the time.
     340    Wrapper (using :class:`MultiWidget`) around two widgets: :class:`DateInput`
     341    for the date, and :class:`TimeInput` for the time.
    159342
    160     Takes two optional arguments, ``date_format`` and ``time_format``, which
    161     work just like the ``format`` argument for ``DateInput`` and ``TimeInput``.
     343    ``SplitDateTimeWidget`` has two optional attributes:
    162344
    163 .. currentmodule:: django.forms.extras.widgets
     345    .. attribute:: SplitDateTimeWidget.date_format
     346
     347        Similar to :attr:`DateInput.format`
     348
     349    .. attribute:: SplitDateTimeWidget.time_format
     350
     351        Similar to :attr:`TimeInput.format`
     352
     353
     354.. class:: SplitHiddenDateTimeWidget
     355
     356    Similar to :class:`SplitDateTimeWidget`, but uses :class:`HiddenInput` for
     357    both date and time.
     358
     359.. currentmodule:: django.forms.widgets.extras
    164360
    165361.. class:: SelectDateWidget
    166362
    167     Wrapper around three select widgets: one each for month, day, and year.
     363    Wrapper around three :class:`~django.forms.Select` widgets: one each for month, day, and year.
    168364    Note that this widget lives in a separate file from the standard widgets.
    169365
    170366    Takes one optional argument:
    171367
    172     .. attribute:: List.years
     368    .. attribute:: SelectDateWidget.years
    173369
    174370        An optional list/tuple of years to use in the "year" select box.
    175371        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