|
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> |