PageRenderTime 12ms CodeModel.GetById 2ms app.highlight 4ms RepoModel.GetById 1ms app.codeStats 0ms

/docs/ref/forms/widgets.txt

https://code.google.com/p/mango-py/
Plain Text | 260 lines | 162 code | 98 blank | 0 comment | 0 complexity | 958bb0ee38e1cf9f18d180edd8c02990 MD5 | raw file
  1=======
  2Widgets
  3=======
  4
  5.. module:: django.forms.widgets
  6   :synopsis: Django's built-in form widgets.
  7
  8.. currentmodule:: django.forms
  9
 10A widget is Django's representation of a HTML input element. The widget
 11handles the rendering of the HTML, and the extraction of data from a GET/POST
 12dictionary that corresponds to the widget.
 13
 14Django provides a representation of all the basic HTML widgets, plus some
 15commonly 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
183Specifying widgets
184------------------
185.. currentmodule:: django.forms
186
187.. attribute:: Form.widget
188
189Whenever you specify a field on a form, Django will use a default widget
190that is appropriate to the type of data that is to be displayed. To find
191which widget is used on which field, see the documentation for the
192built-in Field classes.
193
194However, if you want to use a different widget for a field, you can -
195just 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
204This would specify a form with a comment that uses a larger Textarea widget,
205rather than the default TextInput widget.
206
207Customizing widget instances
208----------------------------
209
210When Django renders a widget as HTML, it only renders the bare minimum
211HTML - Django doesn't add a class definition, or any other widget-specific
212attributes. This means that all 'TextInput' widgets will appear the same
213on your Web page.
214
215If you want to make one widget look different to another, you need to
216specify additional attributes for each widget. When you specify a
217widget, you can provide a list of attributes that will be added to the
218rendered HTML for the widget.
219
220For 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
227This form will include three default TextInput widgets, with default rendering -
228no CSS class, no extra attributes. This means that the input boxes provided for
229each 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
238On a real Web page, you probably don't want every widget to look the same. You
239might want a larger input element for the comment, and you might want the 'name'
240widget to have some special CSS class. To do this, you use the ``attrs``
241argument when creating the widget:
242
243.. attribute:: Widget.attrs
244
245For 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
254Django 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>