Debian Codegraph @

docs/ref/forms/widgets.txt

raw
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 an 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 The HTML generated by the built-in widgets uses HTML5 syntax, targeting
15 ``<!DOCTYPE html>``. For example, it uses boolean attributes such as ``checked``
16 rather than the XHTML style of ``checked='checked'``.
17
18 .. tip::
19
20 Widgets should not be confused with the :doc:`form fields </ref/forms/fields>`.
21 Form fields deal with the logic of input validation and are used directly
22 in templates. Widgets deal with rendering of HTML form input elements on
23 the web page and extraction of raw submitted data. However, widgets do
24 need to be :ref:`assigned <widget-to-field>` to form fields.
25
26 .. _widget-to-field:
27
28 Specifying widgets
29 ==================
30
31 Whenever you specify a field on a form, Django will use a default widget
32 that is appropriate to the type of data that is to be displayed. To find
33 which widget is used on which field, see the documentation about
34 :ref:`built-in-fields`.
35
36 However, if you want to use a different widget for a field, you can
37 use the :attr:`~Field.widget` argument on the field definition. For example::
38
39 from django import forms
40
41
42 class CommentForm(forms.Form):
43 name = forms.CharField()
44 url = forms.URLField()
45 comment = forms.CharField(widget=forms.Textarea)
46
47 This would specify a form with a comment that uses a larger :class:`Textarea`
48 widget, rather than the default :class:`TextInput` widget.
49
50 Setting arguments for widgets
51 =============================
52
53 Many widgets have optional extra arguments; they can be set when defining the
54 widget on the field. In the following example, the
55 :attr:`~django.forms.SelectDateWidget.years` attribute is set for a
56 :class:`~django.forms.SelectDateWidget`::
57
58 from django import forms
59
60 BIRTH_YEAR_CHOICES = ["1980", "1981", "1982"]
61 FAVORITE_COLORS_CHOICES = {
62 "blue": "Blue",
63 "green": "Green",
64 "black": "Black",
65 }
66
67
68 class SimpleForm(forms.Form):
69 birth_year = forms.DateField(
70 widget=forms.SelectDateWidget(years=BIRTH_YEAR_CHOICES)
71 )
72 favorite_colors = forms.MultipleChoiceField(
73 required=False,
74 widget=forms.CheckboxSelectMultiple,
75 choices=FAVORITE_COLORS_CHOICES,
76 )
77
78 See the :ref:`built-in widgets` for more information about which widgets
79 are available and which arguments they accept.
80
81 Widgets inheriting from the ``Select`` widget
82 =============================================
83
84 Widgets inheriting from the :class:`Select` widget deal with choices. They
85 present the user with a list of options to choose from. The different widgets
86 present this choice differently; the :class:`Select` widget itself uses a
87 ``<select>`` HTML list representation, while :class:`RadioSelect` uses radio
88 buttons.
89
90 :class:`Select` widgets are used by default on :class:`ChoiceField` fields. The
91 choices displayed on the widget are inherited from the :class:`ChoiceField` and
92 changing :attr:`ChoiceField.choices` will update :attr:`Select.choices`. For
93 example:
94
95 .. code-block:: pycon
96
97 >>> from django import forms
98 >>> CHOICES = {"1": "First", "2": "Second"}
99 >>> choice_field = forms.ChoiceField(widget=forms.RadioSelect, choices=CHOICES)
100 >>> choice_field.choices
101 [('1', 'First'), ('2', 'Second')]
102 >>> choice_field.widget.choices
103 [('1', 'First'), ('2', 'Second')]
104 >>> choice_field.widget.choices = []
105 >>> choice_field.choices = [("1", "First and only")]
106 >>> choice_field.widget.choices
107 [('1', 'First and only')]
108
109 Widgets which offer a :attr:`~Select.choices` attribute can however be used
110 with fields which are not based on choice -- such as a :class:`CharField` --
111 but it is recommended to use a :class:`ChoiceField`-based field when the
112 choices are inherent to the model and not just the representational widget.
113
114 Customizing widget instances
115 ============================
116
117 When Django renders a widget as HTML, it only renders very minimal markup -
118 Django doesn't add class names, or any other widget-specific attributes. This
119 means, for example, that all :class:`TextInput` widgets will appear the same
120 on your web pages.
121
122 There are two ways to customize widgets: :ref:`per widget instance
123 <styling-widget-instances>` and :ref:`per widget class <styling-widget-classes>`.
124
125 .. _styling-widget-instances:
126
127 Styling widget instances
128 ------------------------
129
130 If you want to make one widget instance look different from another, you will
131 need to specify additional attributes at the time when the widget object is
132 instantiated and assigned to a form field (and perhaps add some rules to your
133 CSS files).
134
135 For example, take the following form::
136
137 from django import forms
138
139
140 class CommentForm(forms.Form):
141 name = forms.CharField()
142 url = forms.URLField()
143 comment = forms.CharField()
144
145 This form will include :class:`TextInput` widgets for the name and comment
146 fields, and a :class:`URLInput` widget for the url field. Each has default
147 rendering - no CSS class, no extra attributes:
148
149 .. code-block:: pycon
150
151 >>> f = CommentForm(auto_id=False)
152 >>> print(f)
153 <div>Name:<input type="text" name="name" required></div>
154 <div>Url:<input type="url" name="url" required></div>
155 <div>Comment:<input type="text" name="comment" required></div>
156
157 On a real web page, you probably want to customize this. You might want a
158 larger input element for the comment, and you might want the 'name' widget to
159 have some special CSS class. It is also possible to specify the 'type'
160 attribute to use a different HTML5 input type. To do this, you use the
161 :attr:`Widget.attrs` argument when creating the widget::
162
163 class CommentForm(forms.Form):
164 name = forms.CharField(widget=forms.TextInput(attrs={"class": "special"}))
165 url = forms.URLField()
166 comment = forms.CharField(widget=forms.TextInput(attrs={"size": "40"}))
167
168 You can also modify a widget in the form definition::
169
170 class CommentForm(forms.Form):
171 name = forms.CharField()
172 url = forms.URLField()
173 comment = forms.CharField()
174
175 name.widget.attrs.update({"class": "special"})
176 comment.widget.attrs.update(size="40")
177
178 Or if the field isn't declared directly on the form (such as model form fields),
179 you can use the :attr:`Form.fields` attribute::
180
181 class CommentForm(forms.ModelForm):
182 def __init__(self, *args, **kwargs):
183 super().__init__(*args, **kwargs)
184 self.fields["name"].widget.attrs.update({"class": "special"})
185 self.fields["comment"].widget.attrs.update(size="40")
186
187 Django will then include the extra attributes in the rendered output:
188
189 >>> f = CommentForm(auto_id=False)
190 >>> print(f)
191 <div>Name:<input type="text" name="name" class="special" required></div>
192 <div>Url:<input type="url" name="url" required></div>
193 <div>Comment:<input type="text" name="comment" size="40" required></div>
194
195 You can also set the HTML ``id`` using :attr:`~Widget.attrs`. See
196 :attr:`BoundField.id_for_label` for an example.
197
198 .. _styling-widget-classes:
199
200 Styling widget classes
201 ----------------------
202
203 With widgets, it is possible to add assets (``css`` and ``javascript``)
204 and more deeply customize their appearance and behavior.
205
206 In a nutshell, you will need to subclass the widget and either
207 :ref:`define a "Media" inner class <assets-as-a-static-definition>` or
208 :ref:`create a "media" property <dynamic-property>`.
209
210 These methods involve somewhat advanced Python programming and are described in
211 detail in the :doc:`Form Assets </topics/forms/media>` topic guide.
212
213 .. _base-widget-classes:
214
215 Base widget classes
216 ===================
217
218 Base widget classes :class:`Widget` and :class:`MultiWidget` are subclassed by
219 all the :ref:`built-in widgets <built-in widgets>` and may serve as a
220 foundation for custom widgets.
221
222 ``Widget``
223 ----------
224
225 .. class:: Widget(attrs=None)
226
227 This abstract class cannot be rendered, but provides the basic attribute
228 :attr:`~Widget.attrs`. You may also implement or override the
229 :meth:`~Widget.render()` method on custom widgets.
230
231 .. attribute:: Widget.attrs
232
233 A dictionary containing HTML attributes to be set on the rendered
234 widget.
235
236 .. code-block:: pycon
237
238 >>> from django import forms
239 >>> name = forms.TextInput(attrs={"size": 10, "title": "Your name"})
240 >>> name.render("name", "A name")
241 '<input title="Your name" type="text" name="name" value="A name" size="10">'
242
243 If you assign a value of ``True`` or ``False`` to an attribute,
244 it will be rendered as an HTML5 boolean attribute:
245
246 .. code-block:: pycon
247
248 >>> name = forms.TextInput(attrs={"required": True})
249 >>> name.render("name", "A name")
250 '<input name="name" type="text" value="A name" required>'
251 >>>
252 >>> name = forms.TextInput(attrs={"required": False})
253 >>> name.render("name", "A name")
254 '<input name="name" type="text" value="A name">'
255
256 .. attribute:: Widget.supports_microseconds
257
258 An attribute that defaults to ``True``. If set to ``False``, the
259 microseconds part of :class:`~datetime.datetime` and
260 :class:`~datetime.time` values will be set to ``0``.
261
262 .. method:: format_value(value)
263
264 Cleans and returns a value for use in the widget template. ``value``
265 isn't guaranteed to be valid input, therefore subclass implementations
266 should program defensively.
267
268 .. method:: get_context(name, value, attrs)
269
270 Returns a dictionary of values to use when rendering the widget
271 template. By default, the dictionary contains a single key,
272 ``'widget'``, which is a dictionary representation of the widget
273 containing the following keys:
274
275 * ``'name'``: The name of the field from the ``name`` argument.
276 * ``'is_hidden'``: A boolean indicating whether or not this widget is
277 hidden.
278 * ``'required'``: A boolean indicating whether or not the field for
279 this widget is required.
280 * ``'value'``: The value as returned by :meth:`format_value`.
281 * ``'attrs'``: HTML attributes to be set on the rendered widget. The
282 combination of the :attr:`attrs` attribute and the ``attrs`` argument.
283 * ``'template_name'``: The value of ``self.template_name``.
284
285 ``Widget`` subclasses can provide custom context values by overriding
286 this method.
287
288 .. method:: id_for_label(id_)
289
290 Returns the HTML ID attribute of this widget for use by a ``<label>``,
291 given the ID of the field. Returns an empty string if an ID isn't
292 available.
293
294 This hook is necessary because some widgets have multiple HTML
295 elements and, thus, multiple IDs. In that case, this method should
296 return an ID value that corresponds to the first ID in the widget's
297 tags.
298
299 .. method:: render(name, value, attrs=None, renderer=None)
300
301 Renders a widget to HTML using the given renderer. If ``renderer`` is
302 ``None``, the renderer from the :setting:`FORM_RENDERER` setting is
303 used.
304
305 .. method:: value_from_datadict(data, files, name)
306
307 Given a dictionary of data and this widget's name, returns the value
308 of this widget. ``files`` may contain data coming from
309 :attr:`request.FILES <django.http.HttpRequest.FILES>`. Returns ``None``
310 if a value wasn't provided. Note also that ``value_from_datadict`` may
311 be called more than once during handling of form data, so if you
312 customize it and add expensive processing, you should implement some
313 caching mechanism yourself.
314
315 .. method:: value_omitted_from_data(data, files, name)
316
317 Given ``data`` and ``files`` dictionaries and this widget's name,
318 returns whether or not there's data or files for the widget.
319
320 The method's result affects whether or not a field in a model form
321 :ref:`falls back to its default <topics-modelform-save>`.
322
323 Special cases are :class:`~django.forms.CheckboxInput`,
324 :class:`~django.forms.CheckboxSelectMultiple`, and
325 :class:`~django.forms.SelectMultiple`, which always return
326 ``False`` because an unchecked checkbox and unselected
327 ``<select multiple>`` don't appear in the data of an HTML form
328 submission, so it's unknown whether or not the user submitted a value.
329
330 .. attribute:: Widget.use_fieldset
331
332 An attribute to identify if the widget should be grouped in a
333 ``<fieldset>`` with a ``<legend>`` when rendered. Defaults to ``False``
334 but is ``True`` when the widget contains multiple ``<input>`` tags such as
335 :class:`~django.forms.CheckboxSelectMultiple`,
336 :class:`~django.forms.RadioSelect`,
337 :class:`~django.forms.MultiWidget`,
338 :class:`~django.forms.SplitDateTimeWidget`, and
339 :class:`~django.forms.SelectDateWidget`.
340
341 .. method:: use_required_attribute(initial)
342
343 Given a form field's ``initial`` value, returns whether or not the
344 widget can be rendered with the ``required`` HTML attribute. Forms use
345 this method along with :attr:`Field.required
346 <django.forms.Field.required>` and :attr:`Form.use_required_attribute
347 <django.forms.Form.use_required_attribute>` to determine whether or not
348 to display the ``required`` attribute for each field.
349
350 By default, returns ``False`` for hidden widgets and ``True``
351 otherwise. Special cases are :class:`~django.forms.FileInput` and
352 :class:`~django.forms.ClearableFileInput`, which return ``False`` when
353 ``initial`` is set, and :class:`~django.forms.CheckboxSelectMultiple`,
354 which always returns ``False`` because browser validation would require
355 all checkboxes to be checked instead of at least one.
356
357 Override this method in custom widgets that aren't compatible with
358 browser validation. For example, a WSYSIWG text editor widget backed by
359 a hidden ``textarea`` element may want to always return ``False`` to
360 avoid browser validation on the hidden field.
361
362 ``MultiWidget``
363 ---------------
364
365 .. class:: MultiWidget(widgets, attrs=None)
366
367 A widget that is composed of multiple widgets.
368 :class:`~django.forms.MultiWidget` works hand in hand with the
369 :class:`~django.forms.MultiValueField`.
370
371 :class:`MultiWidget` has one required argument:
372
373 .. attribute:: MultiWidget.widgets
374
375 An iterable containing the widgets needed. For example:
376
377 .. code-block:: pycon
378
379 >>> from django.forms import MultiWidget, TextInput
380 >>> widget = MultiWidget(widgets=[TextInput, TextInput])
381 >>> widget.render("name", ["john", "paul"])
382 '<input type="text" name="name_0" value="john"><input type="text" name="name_1" value="paul">'
383
384 You may provide a dictionary in order to specify custom suffixes for
385 the ``name`` attribute on each subwidget. In this case, for each
386 ``(key, widget)`` pair, the key will be appended to the ``name`` of the
387 widget in order to generate the attribute value. You may provide the
388 empty string (``''``) for a single key, in order to suppress the suffix
389 for one widget. For example:
390
391 .. code-block:: pycon
392
393 >>> widget = MultiWidget(widgets={"": TextInput, "last": TextInput})
394 >>> widget.render("name", ["john", "paul"])
395 '<input type="text" name="name" value="john"><input type="text" name="name_last" value="paul">'
396
397 And one required method:
398
399 .. method:: decompress(value)
400
401 This method takes a single "compressed" value from the field and
402 returns a list of "decompressed" values. The input value can be
403 assumed valid, but not necessarily non-empty.
404
405 This method **must be implemented** by the subclass, and since the
406 value may be empty, the implementation must be defensive.
407
408 The rationale behind "decompression" is that it is necessary to "split"
409 the combined value of the form field into the values for each widget.
410
411 An example of this is how :class:`SplitDateTimeWidget` turns a
412 :class:`~datetime.datetime` value into a list with date and time split
413 into two separate values::
414
415 from django.forms import MultiWidget
416
417
418 class SplitDateTimeWidget(MultiWidget):
419 # ...
420
421 def decompress(self, value):
422 if value:
423 return [value.date(), value.time()]
424 return [None, None]
425
426 .. tip::
427
428 Note that :class:`~django.forms.MultiValueField` has a
429 complementary method :meth:`~django.forms.MultiValueField.compress`
430 with the opposite responsibility - to combine cleaned values of
431 all member fields into one.
432
433 It provides some custom context:
434
435 .. method:: get_context(name, value, attrs)
436
437 In addition to the ``'widget'`` key described in
438 :meth:`Widget.get_context`, ``MultiWidget`` adds a
439 ``widget['subwidgets']`` key.
440
441 These can be looped over in the widget template:
442
443 .. code-block:: html+django
444
445 {% for subwidget in widget.subwidgets %}
446 {% include subwidget.template_name with widget=subwidget %}
447 {% endfor %}
448
449 Here's an example widget which subclasses :class:`MultiWidget` to display
450 a date with the day, month, and year in different select boxes. This widget
451 is intended to be used with a :class:`~django.forms.DateField` rather than
452 a :class:`~django.forms.MultiValueField`, thus we have implemented
453 :meth:`~Widget.value_from_datadict`::
454
455 from datetime import date
456 from django import forms
457
458
459 class DateSelectorWidget(forms.MultiWidget):
460 def __init__(self, attrs=None):
461 days = {day: day for day in range(1, 32)}
462 months = {month: month for month in range(1, 13)}
463 years = {year: year for year in [2018, 2019, 2020]}
464 widgets = [
465 forms.Select(attrs=attrs, choices=days),
466 forms.Select(attrs=attrs, choices=months),
467 forms.Select(attrs=attrs, choices=years),
468 ]
469 super().__init__(widgets, attrs)
470
471 def decompress(self, value):
472 if isinstance(value, date):
473 return [value.day, value.month, value.year]
474 elif isinstance(value, str):
475 year, month, day = value.split("-")
476 return [day, month, year]
477 return [None, None, None]
478
479 def value_from_datadict(self, data, files, name):
480 day, month, year = super().value_from_datadict(data, files, name)
481 # DateField expects a single string that it can parse into a date.
482 return "{}-{}-{}".format(year, month, day)
483
484 The constructor creates several :class:`Select` widgets in a list. The
485 ``super()`` method uses this list to set up the widget.
486
487 The required method :meth:`~MultiWidget.decompress` breaks up a
488 ``datetime.date`` value into the day, month, and year values corresponding
489 to each widget. If an invalid date was selected, such as the non-existent
490 30th February, the :class:`~django.forms.DateField` passes this method a
491 string instead, so that needs parsing. The final ``return`` handles when
492 ``value`` is ``None``, meaning we don't have any defaults for our
493 subwidgets.
494
495 The default implementation of :meth:`~Widget.value_from_datadict` returns a
496 list of values corresponding to each ``Widget``. This is appropriate when
497 using a ``MultiWidget`` with a :class:`~django.forms.MultiValueField`. But
498 since we want to use this widget with a :class:`~django.forms.DateField`,
499 which takes a single value, we have overridden this method. The
500 implementation here combines the data from the subwidgets into a string in
501 the format that :class:`~django.forms.DateField` expects.
502
503 .. _built-in widgets:
504
505 Built-in widgets
506 ================
507
508 Django provides a representation of all the basic HTML widgets, plus some
509 commonly used groups of widgets in the ``django.forms.widgets`` module,
510 including :ref:`the input of text <text-widgets>`, :ref:`various checkboxes
511 and selectors <selector-widgets>`, :ref:`uploading files <file-upload-widgets>`,
512 and :ref:`handling of multi-valued input <composite-widgets>`.
513
514 .. _text-widgets:
515
516 Widgets handling input of text
517 ------------------------------
518
519 These widgets make use of the HTML elements ``input`` and ``textarea``.
520
521 ``TextInput``
522 ~~~~~~~~~~~~~
523
524 .. class:: TextInput
525
526 * ``input_type``: ``'text'``
527 * ``template_name``: ``'django/forms/widgets/text.html'``
528 * Renders as: ``<input type="text" ...>``
529
530 ``NumberInput``
531 ~~~~~~~~~~~~~~~
532
533 .. class:: NumberInput
534
535 * ``input_type``: ``'number'``
536 * ``template_name``: ``'django/forms/widgets/number.html'``
537 * Renders as: ``<input type="number" ...>``
538
539 Beware that not all browsers support entering localized numbers in
540 ``number`` input types. Django itself avoids using them for fields having
541 their :attr:`~django.forms.Field.localize` property set to ``True``.
542
543 ``EmailInput``
544 ~~~~~~~~~~~~~~
545
546 .. class:: EmailInput
547
548 * ``input_type``: ``'email'``
549 * ``template_name``: ``'django/forms/widgets/email.html'``
550 * Renders as: ``<input type="email" ...>``
551
552 ``URLInput``
553 ~~~~~~~~~~~~
554
555 .. class:: URLInput
556
557 * ``input_type``: ``'url'``
558 * ``template_name``: ``'django/forms/widgets/url.html'``
559 * Renders as: ``<input type="url" ...>``
560
561 ``ColorInput``
562 ~~~~~~~~~~~~~~
563
564 .. versionadded:: 5.2
565
566 .. class:: ColorInput
567
568 * ``input_type``: ``'color'``
569 * ``template_name``:``'django/forms/widgets/color.html'``
570 * Renders as: ``<input type="color" ...>``
571
572 ``SearchInput``
573 ~~~~~~~~~~~~~~~
574
575 .. versionadded:: 5.2
576
577 .. class:: SearchInput
578
579 * ``input_type``: ``'search'``
580 * ``template_name``: ``'django/forms/widgets/search.html'``
581 * Renders as: ``<input type="search" ...>``
582
583 ``TelInput``
584 ~~~~~~~~~~~~
585
586 .. versionadded:: 5.2
587
588 .. class:: TelInput
589
590 * ``input_type``: ``'tel'``
591 * ``template_name``: ``'django/forms/widgets/tel.html'``
592 * Renders as: ``<input type="tel" ...>``
593
594 Browsers perform no client-side validation by default because telephone
595 number formats vary so much around the world. You can add some by setting
596 ``pattern``, ``minlength``, or ``maxlength`` in the :attr:`Widget.attrs`
597 argument.
598
599 Additionally, you can add server-side validation to your form field with a
600 validator like :class:`~django.core.validators.RegexValidator` or via
601 third-party packages, such as :pypi:`django-phonenumber-field`.
602
603 ``PasswordInput``
604 ~~~~~~~~~~~~~~~~~
605
606 .. class:: PasswordInput
607
608 * ``input_type``: ``'password'``
609 * ``template_name``: ``'django/forms/widgets/password.html'``
610 * Renders as: ``<input type="password" ...>``
611
612 Takes one optional argument:
613
614 .. attribute:: PasswordInput.render_value
615
616 Determines whether the widget will have a value filled in when the
617 form is re-displayed after a validation error (default is ``False``).
618
619 ``HiddenInput``
620 ~~~~~~~~~~~~~~~
621
622 .. class:: HiddenInput
623
624 * ``input_type``: ``'hidden'``
625 * ``template_name``: ``'django/forms/widgets/hidden.html'``
626 * Renders as: ``<input type="hidden" ...>``
627
628 Note that there also is a :class:`MultipleHiddenInput` widget that
629 encapsulates a set of hidden input elements.
630
631 ``DateInput``
632 ~~~~~~~~~~~~~
633
634 .. class:: DateInput
635
636 * ``input_type``: ``'text'``
637 * ``template_name``: ``'django/forms/widgets/date.html'``
638 * Renders as: ``<input type="text" ...>``
639
640 Takes same arguments as :class:`TextInput`, with one more optional argument:
641
642 .. attribute:: DateInput.format
643
644 The format in which this field's initial value will be displayed.
645
646 If no ``format`` argument is provided, the default format is the first
647 format found in :setting:`DATE_INPUT_FORMATS` and respects
648 :doc:`/topics/i18n/formatting`. ``%U``, ``%W``, and ``%j`` formats are not
649 supported by this widget.
650
651 ``DateTimeInput``
652 ~~~~~~~~~~~~~~~~~
653
654 .. class:: DateTimeInput
655
656 * ``input_type``: ``'text'``
657 * ``template_name``: ``'django/forms/widgets/datetime.html'``
658 * Renders as: ``<input type="text" ...>``
659
660 Takes same arguments as :class:`TextInput`, with one more optional argument:
661
662 .. attribute:: DateTimeInput.format
663
664 The format in which this field's initial value will be displayed.
665
666 If no ``format`` argument is provided, the default format is the first
667 format found in :setting:`DATETIME_INPUT_FORMATS` and respects
668 :doc:`/topics/i18n/formatting`. ``%U``, ``%W``, and ``%j`` formats are not
669 supported by this widget.
670
671 By default, the microseconds part of the time value is always set to ``0``.
672 If microseconds are required, use a subclass with the
673 :attr:`~Widget.supports_microseconds` attribute set to ``True``.
674
675 ``TimeInput``
676 ~~~~~~~~~~~~~
677
678 .. class:: TimeInput
679
680 * ``input_type``: ``'text'``
681 * ``template_name``: ``'django/forms/widgets/time.html'``
682 * Renders as: ``<input type="text" ...>``
683
684 Takes same arguments as :class:`TextInput`, with one more optional argument:
685
686 .. attribute:: TimeInput.format
687
688 The format in which this field's initial value will be displayed.
689
690 If no ``format`` argument is provided, the default format is the first
691 format found in :setting:`TIME_INPUT_FORMATS` and respects
692 :doc:`/topics/i18n/formatting`.
693
694 For the treatment of microseconds, see :class:`DateTimeInput`.
695
696 ``Textarea``
697 ~~~~~~~~~~~~
698
699 .. class:: Textarea
700
701 * ``template_name``: ``'django/forms/widgets/textarea.html'``
702 * Renders as: ``<textarea>...</textarea>``
703
704 .. _selector-widgets:
705
706 Selector and checkbox widgets
707 -----------------------------
708
709 These widgets make use of the HTML elements ``<select>``,
710 ``<input type="checkbox">``, and ``<input type="radio">``.
711
712 Widgets that render multiple choices have an ``option_template_name`` attribute
713 that specifies the template used to render each choice. For example, for the
714 :class:`Select` widget, ``select_option.html`` renders the ``<option>`` for a
715 ``<select>``.
716
717 ``CheckboxInput``
718 ~~~~~~~~~~~~~~~~~
719
720 .. class:: CheckboxInput
721
722 * ``input_type``: ``'checkbox'``
723 * ``template_name``: ``'django/forms/widgets/checkbox.html'``
724 * Renders as: ``<input type="checkbox" ...>``
725
726 Takes one optional argument:
727
728 .. attribute:: CheckboxInput.check_test
729
730 A callable that takes the value of the ``CheckboxInput`` and returns
731 ``True`` if the checkbox should be checked for that value.
732
733 ``Select``
734 ~~~~~~~~~~
735
736 .. class:: Select
737
738 * ``template_name``: ``'django/forms/widgets/select.html'``
739 * ``option_template_name``: ``'django/forms/widgets/select_option.html'``
740 * Renders as: ``<select><option ...>...</select>``
741
742 .. attribute:: Select.choices
743
744 This attribute is optional when the form field does not have a
745 ``choices`` attribute. If it does, it will override anything you set
746 here when the attribute is updated on the :class:`Field`.
747
748 ``NullBooleanSelect``
749 ~~~~~~~~~~~~~~~~~~~~~
750
751 .. class:: NullBooleanSelect
752
753 * ``template_name``: ``'django/forms/widgets/select.html'``
754 * ``option_template_name``: ``'django/forms/widgets/select_option.html'``
755
756 Select widget with options 'Unknown', 'Yes' and 'No'
757
758 ``SelectMultiple``
759 ~~~~~~~~~~~~~~~~~~
760
761 .. class:: SelectMultiple
762
763 * ``template_name``: ``'django/forms/widgets/select.html'``
764 * ``option_template_name``: ``'django/forms/widgets/select_option.html'``
765
766 Similar to :class:`Select`, but allows multiple selection:
767 ``<select multiple>...</select>``
768
769 ``RadioSelect``
770 ~~~~~~~~~~~~~~~
771
772 .. class:: RadioSelect
773
774 * ``template_name``: ``'django/forms/widgets/radio.html'``
775 * ``option_template_name``: ``'django/forms/widgets/radio_option.html'``
776
777 Similar to :class:`Select`, but rendered as a list of radio buttons within
778 ``<div>`` tags:
779
780 .. code-block:: html
781
782 <div>
783 <div><input type="radio" name="..."></div>
784 ...
785 </div>
786
787 For more granular control over the generated markup, you can loop over the
788 radio buttons in the template. Assuming a form ``myform`` with a field
789 ``beatles`` that uses a ``RadioSelect`` as its widget:
790
791 .. code-block:: html+django
792
793 <fieldset>
794 <legend>{{ myform.beatles.label }}</legend>
795 {% for radio in myform.beatles %}
796 <div class="myradio">
797 {{ radio }}
798 </div>
799 {% endfor %}
800 </fieldset>
801
802 This would generate the following HTML:
803
804 .. code-block:: html
805
806 <fieldset>
807 <legend>Radio buttons</legend>
808 <div class="myradio">
809 <label for="id_beatles_0"><input id="id_beatles_0" name="beatles" type="radio" value="john" required> John</label>
810 </div>
811 <div class="myradio">
812 <label for="id_beatles_1"><input id="id_beatles_1" name="beatles" type="radio" value="paul" required> Paul</label>
813 </div>
814 <div class="myradio">
815 <label for="id_beatles_2"><input id="id_beatles_2" name="beatles" type="radio" value="george" required> George</label>
816 </div>
817 <div class="myradio">
818 <label for="id_beatles_3"><input id="id_beatles_3" name="beatles" type="radio" value="ringo" required> Ringo</label>
819 </div>
820 </fieldset>
821
822 That included the ``<label>`` tags. To get more granular, you can use each
823 radio button's ``tag``, ``choice_label`` and ``id_for_label`` attributes.
824 For example, this template...
825
826 .. code-block:: html+django
827
828 <fieldset>
829 <legend>{{ myform.beatles.label }}</legend>
830 {% for radio in myform.beatles %}
831 <label for="{{ radio.id_for_label }}">
832 {{ radio.choice_label }}
833 <span class="radio">{{ radio.tag }}</span>
834 </label>
835 {% endfor %}
836 </fieldset>
837
838 ...will result in the following HTML:
839
840 .. code-block:: html
841
842 <fieldset>
843 <legend>Radio buttons</legend>
844 <label for="id_beatles_0">
845 John
846 <span class="radio"><input id="id_beatles_0" name="beatles" type="radio" value="john" required></span>
847 </label>
848 <label for="id_beatles_1">
849 Paul
850 <span class="radio"><input id="id_beatles_1" name="beatles" type="radio" value="paul" required></span>
851 </label>
852 <label for="id_beatles_2">
853 George
854 <span class="radio"><input id="id_beatles_2" name="beatles" type="radio" value="george" required></span>
855 </label>
856 <label for="id_beatles_3">
857 Ringo
858 <span class="radio"><input id="id_beatles_3" name="beatles" type="radio" value="ringo" required></span>
859 </label>
860 </fieldset>
861
862 If you decide not to loop over the radio buttons -- e.g., if your template
863 includes ``{{ myform.beatles }}`` -- they'll be output in a ``<div>`` with
864 ``<div>`` tags, as above.
865
866 The outer ``<div>`` container receives the ``id`` attribute of the widget,
867 if defined, or :attr:`BoundField.auto_id` otherwise.
868
869 When looping over the radio buttons, the ``label`` and ``input`` tags include
870 ``for`` and ``id`` attributes, respectively. Each radio button has an
871 ``id_for_label`` attribute to output the element's ID.
872
873 ``CheckboxSelectMultiple``
874 ~~~~~~~~~~~~~~~~~~~~~~~~~~
875
876 .. class:: CheckboxSelectMultiple
877
878 * ``template_name``: ``'django/forms/widgets/checkbox_select.html'``
879 * ``option_template_name``: ``'django/forms/widgets/checkbox_option.html'``
880
881 Similar to :class:`SelectMultiple`, but rendered as a list of checkboxes:
882
883 .. code-block:: html
884
885 <div>
886 <div><input type="checkbox" name="..." ></div>
887 ...
888 </div>
889
890 The outer ``<div>`` container receives the ``id`` attribute of the widget,
891 if defined, or :attr:`BoundField.auto_id` otherwise.
892
893 Like :class:`RadioSelect`, you can loop over the individual checkboxes for the
894 widget's choices. Unlike :class:`RadioSelect`, the checkboxes won't include the
895 ``required`` HTML attribute if the field is required because browser validation
896 would require all checkboxes to be checked instead of at least one.
897
898 When looping over the checkboxes, the ``label`` and ``input`` tags include
899 ``for`` and ``id`` attributes, respectively. Each checkbox has an
900 ``id_for_label`` attribute to output the element's ID.
901
902 .. _file-upload-widgets:
903
904 File upload widgets
905 -------------------
906
907 ``FileInput``
908 ~~~~~~~~~~~~~
909
910 .. class:: FileInput
911
912 * ``template_name``: ``'django/forms/widgets/file.html'``
913 * Renders as: ``<input type="file" ...>``
914
915 ``ClearableFileInput``
916 ~~~~~~~~~~~~~~~~~~~~~~
917
918 .. class:: ClearableFileInput
919
920 * ``template_name``: ``'django/forms/widgets/clearable_file_input.html'``
921 * Renders as: ``<input type="file" ...>`` with an additional checkbox
922 input to clear the field's value, if the field is not required and has
923 initial data.
924
925 .. _composite-widgets:
926
927 Composite widgets
928 -----------------
929
930 ``MultipleHiddenInput``
931 ~~~~~~~~~~~~~~~~~~~~~~~
932
933 .. class:: MultipleHiddenInput
934
935 * ``template_name``: ``'django/forms/widgets/multiple_hidden.html'``
936 * Renders as: multiple ``<input type="hidden" ...>`` tags
937
938 A widget that handles multiple hidden widgets for fields that have a list
939 of values.
940
941 ``SplitDateTimeWidget``
942 ~~~~~~~~~~~~~~~~~~~~~~~
943
944 .. class:: SplitDateTimeWidget
945
946 * ``template_name``: ``'django/forms/widgets/splitdatetime.html'``
947
948 Wrapper (using :class:`MultiWidget`) around two widgets: :class:`DateInput`
949 for the date, and :class:`TimeInput` for the time. Must be used with
950 :class:`SplitDateTimeField` rather than :class:`DateTimeField`.
951
952 ``SplitDateTimeWidget`` has several optional arguments:
953
954 .. attribute:: SplitDateTimeWidget.date_format
955
956 Similar to :attr:`DateInput.format`
957
958 .. attribute:: SplitDateTimeWidget.time_format
959
960 Similar to :attr:`TimeInput.format`
961
962 .. attribute:: SplitDateTimeWidget.date_attrs
963 .. attribute:: SplitDateTimeWidget.time_attrs
964
965 Similar to :attr:`Widget.attrs`. A dictionary containing HTML
966 attributes to be set on the rendered :class:`DateInput` and
967 :class:`TimeInput` widgets, respectively. If these attributes aren't
968 set, :attr:`Widget.attrs` is used instead.
969
970 ``SplitHiddenDateTimeWidget``
971 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
972
973 .. class:: SplitHiddenDateTimeWidget
974
975 * ``template_name``: ``'django/forms/widgets/splithiddendatetime.html'``
976
977 Similar to :class:`SplitDateTimeWidget`, but uses :class:`HiddenInput` for
978 both date and time.
979
980 ``SelectDateWidget``
981 ~~~~~~~~~~~~~~~~~~~~
982
983 .. class:: SelectDateWidget
984
985 * ``template_name``: ``'django/forms/widgets/select_date.html'``
986
987 Wrapper around three :class:`~django.forms.Select` widgets: one each for
988 month, day, and year.
989
990 Takes several optional arguments:
991
992 .. attribute:: SelectDateWidget.years
993
994 An optional list/tuple of years to use in the "year" select box.
995 The default is a list containing the current year and the next 9 years.
996
997 .. attribute:: SelectDateWidget.months
998
999 An optional dict of months to use in the "months" select box.
1000
1001 The keys of the dict correspond to the month number (1-indexed) and
1002 the values are the displayed months::
1003
1004 MONTHS = {
1005 1: _("jan"),
1006 2: _("feb"),
1007 3: _("mar"),
1008 4: _("apr"),
1009 5: _("may"),
1010 6: _("jun"),
1011 7: _("jul"),
1012 8: _("aug"),
1013 9: _("sep"),
1014 10: _("oct"),
1015 11: _("nov"),
1016 12: _("dec"),
1017 }
1018
1019 .. attribute:: SelectDateWidget.empty_label
1020
1021 If the :class:`~django.forms.DateField` is not required,
1022 :class:`SelectDateWidget` will have an empty choice at the top of the
1023 list (which is ``---`` by default). You can change the text of this
1024 label with the ``empty_label`` attribute. ``empty_label`` can be a
1025 ``string``, ``list``, or ``tuple``. When a string is used, all select
1026 boxes will each have an empty choice with this label. If ``empty_label``
1027 is a ``list`` or ``tuple`` of 3 string elements, the select boxes will
1028 have their own custom label. The labels should be in this order
1029 ``('year_label', 'month_label', 'day_label')``.
1030
1031 .. code-block:: python
1032
1033 # A custom empty label with string
1034 field1 = forms.DateField(widget=SelectDateWidget(empty_label="Nothing"))
1035
1036 # A custom empty label with tuple
1037 field1 = forms.DateField(
1038 widget=SelectDateWidget(
1039 empty_label=("Choose Year", "Choose Month", "Choose Day"),
1040 ),
1041 )