1 =======

     2 Widgets

     3 =======

     4 

     5 .. module:: django.forms.widgets

     6    :synopsis: Django's built-in form widgets.

     7    

     8 .. currentmodule:: django.forms

     9 

    10 A widget is Django's representation of a HTML input element. The widget

    11 handles the rendering of the HTML, and the extraction of data from a GET/POST

    12 dictionary that corresponds to the widget.

    13 

    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 ``True``).

    31 

    32 .. class:: HiddenInput

    33 

    34     Hidden input: ``<input type='hidden' ...>``

    35 

    36 .. class:: MultipleHiddenInput

    37 

    38     Multiple ``<input type='hidden' ...>`` widgets.

    39 

    40 .. class:: FileInput

    41 

    42     File upload input: ``<input type='file' ...>``

    43 

    44 .. class:: DateInput

    45 

    46     .. versionadded:: 1.1

    47 

    48     Date input as a simple text box: ``<input type='text' ...>``

    49 

    50     Takes one optional argument:

    51     

    52     .. attribute:: DateInput.format

    53 

    54         The format in which this field's initial value will be displayed.

    55 

    56     If no ``format`` argument is provided, the default format is ``'%Y-%m-%d'``.

    57 

    58 .. class:: DateTimeInput

    59 

    60     .. versionadded:: 1.0

    61 

    62     Date/time input as a simple text box: ``<input type='text' ...>``

    63 

    64     Takes one optional argument:

    65     

    66     .. attribute:: DateTimeInput.format

    67     

    68         The format in which this field's initial value will be displayed.

    69     

    70     If no ``format`` argument is provided, the default format is ``'%Y-%m-%d

    71     %H:%M:%S'``.

    72 

    73 .. class:: TimeInput

    74 

    75     Time input as a simple text box: ``<input type='text' ...>``

    76 

    77     Takes one optional argument:

    78     

    79     .. attribute:: TimeInput.format

    80     

    81         The format in which this field's initial value will be displayed.

    82     

    83     If no ``format`` argument is provided, the default format is ``'%H:%M:%S'``.

    84 

    85     .. versionchanged:: 1.1

    86        The ``format`` argument was not supported in Django 1.0.

    87 

    88 .. class:: Textarea

    89 

    90     Text area: ``<textarea>...</textarea>``

    91 

    92 .. class:: CheckboxInput

    93 

    94     Checkbox: ``<input type='checkbox' ...>``

    95 

    96     Takes one optional argument:

    97 

    98     .. attribute:: CheckboxInput.check_test

    99      

   100         A callable that takes the value of the CheckBoxInput 

   101         and returns ``True`` if the checkbox should be checked for

   102         that value. 

   103 

   104 .. class:: Select

   105 

   106     Select widget: ``<select><option ...>...</select>``

   107     

   108     Requires that your field provides :attr:`~Field.choices`.

   109 

   110 .. class:: NullBooleanSelect

   111 

   112     Select widget with options 'Unknown', 'Yes' and 'No'

   113 

   114 .. class:: SelectMultiple

   115 

   116     Select widget allowing multiple selection: ``<select

   117     multiple='multiple'>...</select>``

   118 

   119     Requires that your field provides :attr:`~Field.choices`.

   120 

   121 .. class:: RadioSelect

   122 

   123     A list of radio buttons:

   124     

   125     .. code-block:: html

   126     

   127         <ul>

   128           <li><input type='radio' ...></li>

   129           ...

   130         </ul>

   131         

   132     Requires that your field provides :attr:`~Field.choices`.

   133 

   134 .. class:: CheckboxSelectMultiple

   135 

   136     A list of checkboxes:

   137     

   138     .. code-block:: html

   139     

   140         <ul>

   141           <li><input type='checkbox' ...></li>

   142           ...

   143         </ul>

   144 

   145 .. class:: MultiWidget

   146 

   147     Wrapper around multiple other widgets

   148 

   149 .. class:: SplitDateTimeWidget

   150 

   151     Wrapper around two widgets: ``DateInput`` for the date, and ``TimeInput``

   152     for the time.

   153 

   154     Takes two optional arguments, ``date_format`` and ``time_format``, which

   155     work just like the ``format`` argument for ``DateInput`` and ``TimeInput``.

   156     

   157     .. versionchanged:: 1.1

   158        The ``date_format`` and ``time_format`` arguments were not supported in Django 1.0.

   159 

   160 .. class:: SelectDateWidget

   161 

   162     Wrapper around three select widgets: one each for month, day, and year.

   163     Note that this widget lives in a separate file from the standard widgets.

   164 

   165     .. code-block:: python

   166 

   167         from django.forms.extras.widgets import SelectDateWidget

   168 

   169         date = forms.DateField(widget=SelectDateWidget())

   170 

   171 Specifying widgets

   172 ------------------

   173 

   174 .. attribute:: Form.widget

   175 

   176 Whenever you specify a field on a form, Django will use a default widget

   177 that is appropriate to the type of data that is to be displayed. To find

   178 which widget is used on which field, see the documentation for the

   179 built-in Field classes.

   180 

   181 However, if you want to use a different widget for a field, you can -

   182 just use the 'widget' argument on the field definition. For example::

   183 

   184     from django import forms

   185 

   186     class CommentForm(forms.Form):

   187         name = forms.CharField()

   188         url = forms.URLField()

   189         comment = forms.CharField(widget=forms.Textarea)

   190 

   191 This would specify a form with a comment that uses a larger Textarea widget,

   192 rather than the default TextInput widget.

   193 

   194 Customizing widget instances

   195 ----------------------------

   196 

   197 When Django renders a widget as HTML, it only renders the bare minimum

   198 HTML - Django doesn't add a class definition, or any other widget-specific

   199 attributes. This means that all 'TextInput' widgets will appear the same

   200 on your Web page.

   201 

   202 If you want to make one widget look different to another, you need to

   203 specify additional attributes for each widget. When you specify a

   204 widget, you can provide a list of attributes that will be added to the

   205 rendered HTML for the widget.

   206 

   207 For example, take the following simple form::

   208 

   209     class CommentForm(forms.Form):

   210         name = forms.CharField()

   211         url = forms.URLField()

   212         comment = forms.CharField()

   213 

   214 This form will include three default TextInput widgets, with default rendering -

   215 no CSS class, no extra attributes. This means that the input boxes provided for

   216 each widget will be rendered exactly the same::

   217 

   218     >>> f = CommentForm(auto_id=False)

   219     >>> f.as_table()

   220     <tr><th>Name:</th><td><input type="text" name="name" /></td></tr>

   221     <tr><th>Url:</th><td><input type="text" name="url"/></td></tr>

   222     <tr><th>Comment:</th><td><input type="text" name="comment" /></td></tr>

   223 

   224 

   225 On a real Web page, you probably don't want every widget to look the same. You

   226 might want a larger input element for the comment, and you might want the 'name'

   227 widget to have some special CSS class. To do this, you use the ``attrs``

   228 argument when creating the widget:

   229 

   230 .. attribute:: Widget.attrs

   231 

   232 For example::

   233 

   234     class CommentForm(forms.Form):

   235         name = forms.CharField(

   236                     widget=forms.TextInput(attrs={'class':'special'}))

   237         url = forms.URLField()

   238         comment = forms.CharField(

   239                    widget=forms.TextInput(attrs={'size':'40'}))

   240 

   241 Django will then include the extra attributes in the rendered output::

   242 

   243     >>> f = CommentForm(auto_id=False)

   244     >>> f.as_table()

   245     <tr><th>Name:</th><td><input type="text" name="name" class="special"/></td></tr>

   246     <tr><th>Url:</th><td><input type="text" name="url"/></td></tr>

   247     <tr><th>Comment:</th><td><input type="text" name="comment" size="40"/></td></tr>