https://docs.djangoproject.com/en/1.8/ref/forms/widgets/
Built-in widgets¶
Django provides a representation of all the basic HTML widgets, plus some commonly used groups of widgets in thedjango.forms.widgets module, including the input of text, various checkboxes and selectors, uploading files, andhandling of multi-valued input.
Widgets handling input of text¶
These widgets make use of the HTML elements input and textarea.
NumberInput¶
PasswordInput¶
DateInput¶
-
class
DateInput
¶
-
Date input as a simple text box: <input type='text' ...>
Takes same arguments as TextInput, with one more optional argument:
-
format
¶
-
The format in which this field’s initial value will be displayed.
If no format argument is provided, the default format is the first format found in DATE_INPUT_FORMATS and respectsFormat localization.
-
DateTimeInput¶
-
class
DateTimeInput
¶
-
Date/time input as a simple text box: <input type='text' ...>
Takes same arguments as TextInput, with one more optional argument:
-
format
¶
-
The format in which this field’s initial value will be displayed.
If no format argument is provided, the default format is the first format found in DATETIME_INPUT_FORMATS and respects Format localization.
-
TimeInput¶
-
class
TimeInput
¶
-
Time input as a simple text box: <input type='text' ...>
Takes same arguments as TextInput, with one more optional argument:
-
format
¶
-
The format in which this field’s initial value will be displayed.
If no format argument is provided, the default format is the first format found in TIME_INPUT_FORMATS and respectsFormat localization.
-
Selector and checkbox widgets¶
CheckboxInput¶
Select¶
SelectMultiple¶
RadioSelect¶
-
class
RadioSelect
¶
-
Similar to Select, but rendered as a list of radio buttons within <li> tags:
<ul> <li><input type='radio' name='...'></li> ... </ul>
For more granular control over the generated markup, you can loop over the radio buttons in the template. Assuming a form myform with a field beatles that uses a RadioSelect as its widget:
{% for radio in myform.beatles %} <div class="myradio"> {{ radio }} </div> {% endfor %}
This would generate the following HTML:
<div class="myradio"> <label for="id_beatles_0"><input id="id_beatles_0" name="beatles" type="radio" value="john" /> John</label> </div> <div class="myradio"> <label for="id_beatles_1"><input id="id_beatles_1" name="beatles" type="radio" value="paul" /> Paul</label> </div> <div class="myradio"> <label for="id_beatles_2"><input id="id_beatles_2" name="beatles" type="radio" value="george" /> George</label> </div> <div class="myradio"> <label for="id_beatles_3"><input id="id_beatles_3" name="beatles" type="radio" value="ringo" /> Ringo</label> </div>
That included the <label> tags. To get more granular, you can use each radio button’s tag, choice_label andid_for_label attributes. For example, this template...
{% for radio in myform.beatles %} <label for="{{ radio.id_for_label }}"> {{ radio.choice_label }} <span class="radio">{{ radio.tag }}</span> </label> {% endfor %}
...will result in the following HTML:
<label for="id_beatles_0"> John <span class="radio"><input id="id_beatles_0" name="beatles" type="radio" value="john" /></span> </label> <label for="id_beatles_1"> Paul <span class="radio"><input id="id_beatles_1" name="beatles" type="radio" value="paul" /></span> </label> <label for="id_beatles_2"> George <span class="radio"><input id="id_beatles_2" name="beatles" type="radio" value="george" /></span> </label> <label for="id_beatles_3"> Ringo <span class="radio"><input id="id_beatles_3" name="beatles" type="radio" value="ringo" /></span> </label>
If you decide not to loop over the radio buttons – e.g., if your template simply includes {{ myform.beatles }} – they’ll be output in a <ul> with <li> tags, as above.
The outer <ul> container will receive the id attribute defined on the widget.
When looping over the radio buttons, the label and input tags include for and id attributes, respectively. Each radio button has an id_for_label attribute to output the element’s ID.
CheckboxSelectMultiple¶
-
class
CheckboxSelectMultiple
¶
-
Similar to SelectMultiple, but rendered as a list of check buttons:
<ul> <li><input type='checkbox' name='...' ></li> ... </ul>
The outer <ul> container will receive the id attribute defined on the widget.
Like RadioSelect, you can now loop over the individual checkboxes making up the lists. See the documentation ofRadioSelect for more details.
When looping over the checkboxes, the label and input tags include for and id attributes, respectively. Each checkbox has an id_for_label attribute to output the element’s ID.
File upload widgets¶
Composite widgets¶
SplitDateTimeWidget¶
-
class
SplitDateTimeWidget
¶
-
Wrapper (using MultiWidget) around two widgets: DateInput for the date, and TimeInput for the time.
SplitDateTimeWidget has two optional attributes:
-
date_format
¶
-
Similar to DateInput.format
-
time_format
¶
-
Similar to TimeInput.format
-
SelectDateWidget¶
-
class
SelectDateWidget
[source]
¶
-
Wrapper around three Select widgets: one each for month, day, and year. Note that this widget lives in a separate file from the standard widgets.
Takes several optional arguments:
-
years
¶
-
An optional list/tuple of years to use in the “year” select box. The default is a list containing the current year and the next 9 years.
-
months
¶
-
New in Django 1.7.
An optional dict of months to use in the “months” select box.
The keys of the dict correspond to the month number (1-indexed) and the values are the displayed months:
MONTHS = { 1:_('jan'), 2:_('feb'), 3:_('mar'), 4:_('apr'), 5:_('may'), 6:_('jun'), 7:_('jul'), 8:_('aug'), 9:_('sep'), 10:_('oct'), 11:_('nov'), 12:_('dec') }
-
empty_label
¶
-
New in Django 1.8.
If the DateField is not required, SelectDateWidget will have an empty choice at the top of the list (which is ---by default). You can change the text of this label with the empty_label attribute. empty_label can be a string,list, or tuple. When a string is used, all select boxes will each have an empty choice with this label. Ifempty_label is a list or tuple of 3 string elements, the select boxes will have their own custom label. The labels should be in this order ('year_label', 'month_label', 'day_label').
# A custom empty label with string field1 = forms.DateField(widget=SelectDateWidget(empty_label="Nothing")) # A custom empty label with tuple field1 = forms.DateField( widget=SelectDateWidget( empty_label=("Choose Year", "Choose Month", "Choose Day"), ), )
-