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