<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Widgets — Django 1.8.19 documentation</title>
<link rel="stylesheet" href="../../_static/default.css" type="text/css" />
<link rel="stylesheet" href="../../_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../../',
VERSION: '1.8.19',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="../../_static/jquery.js"></script>
<script type="text/javascript" src="../../_static/underscore.js"></script>
<script type="text/javascript" src="../../_static/doctools.js"></script>
<link rel="index" title="Index" href="../../genindex.html" />
<link rel="search" title="Search" href="../../search.html" />
<link rel="top" title="Django 1.8.19 documentation" href="../../contents.html" />
<link rel="up" title="Forms" href="index.html" />
<link rel="next" title="Form and field validation" href="validation.html" />
<link rel="prev" title="Formset Functions" href="formsets.html" />
<script type="text/javascript" src="../../templatebuiltins.js"></script>
<script type="text/javascript">
(function($) {
if (!django_template_builtins) {
// templatebuiltins.js missing, do nothing.
return;
}
$(document).ready(function() {
// Hyperlink Django template tags and filters
var base = "../templates/builtins.html";
if (base == "#") {
// Special case for builtins.html itself
base = "";
}
// Tags are keywords, class '.k'
$("div.highlight\\-html\\+django span.k").each(function(i, elem) {
var tagname = $(elem).text();
if ($.inArray(tagname, django_template_builtins.ttags) != -1) {
var fragment = tagname.replace(/_/, '-');
$(elem).html("<a href='" + base + "#" + fragment + "'>" + tagname + "</a>");
}
});
// Filters are functions, class '.nf'
$("div.highlight\\-html\\+django span.nf").each(function(i, elem) {
var filtername = $(elem).text();
if ($.inArray(filtername, django_template_builtins.tfilters) != -1) {
var fragment = filtername.replace(/_/, '-');
$(elem).html("<a href='" + base + "#" + fragment + "'>" + filtername + "</a>");
}
});
});
})(jQuery);
</script>
</head>
<body role="document">
<div class="document">
<div id="custom-doc" class="yui-t6">
<div id="hd">
<h1><a href="../../index.html">Django 1.8.19 documentation</a></h1>
<div id="global-nav">
<a title="Home page" href="../../index.html">Home</a> |
<a title="Table of contents" href="../../contents.html">Table of contents</a> |
<a title="Global index" href="../../genindex.html">Index</a> |
<a title="Module index" href="../../py-modindex.html">Modules</a>
</div>
<div class="nav">
« <a href="formsets.html" title="Formset Functions">previous</a>
|
<a href="../index.html" title="API Reference" accesskey="U">up</a>
|
<a href="validation.html" title="Form and field validation">next</a> »</div>
</div>
<div id="bd">
<div id="yui-main">
<div class="yui-b">
<div class="yui-g" id="ref-forms-widgets">
<div class="section" id="s-module-django.forms.widgets">
<span id="s-widgets"></span><span id="module-django.forms.widgets"></span><span id="widgets"></span><h1>Widgets<a class="headerlink" href="#module-django.forms.widgets" title="Permalink to this headline">¶</a></h1>
<p>A widget is Django’s representation of an HTML input element. The widget
handles the rendering of the HTML, and the extraction of data from a GET/POST
dictionary that corresponds to the widget.</p>
<div class="admonition tip">
<p class="first admonition-title">Tip</p>
<p class="last">Widgets should not be confused with the <a class="reference internal" href="fields.html"><span class="doc">form fields</span></a>.
Form fields deal with the logic of input validation and are used directly
in templates. Widgets deal with rendering of HTML form input elements on
the web page and extraction of raw submitted data. However, widgets do
need to be <a class="reference internal" href="#widget-to-field"><span class="std std-ref">assigned</span></a> to form fields.</p>
</div>
<div class="section" id="s-specifying-widgets">
<span id="s-widget-to-field"></span><span id="specifying-widgets"></span><span id="widget-to-field"></span><h2>Specifying widgets<a class="headerlink" href="#specifying-widgets" title="Permalink to this headline">¶</a></h2>
<p>Whenever you specify a field on a form, Django will use a default widget
that is appropriate to the type of data that is to be displayed. To find
which widget is used on which field, see the documentation about
<a class="reference internal" href="fields.html#built-in-fields"><span class="std std-ref">Built-in Field classes</span></a>.</p>
<p>However, if you want to use a different widget for a field, you can
just use the <a class="reference internal" href="fields.html#django.forms.Field.widget" title="django.forms.Field.widget"><code class="xref py py-attr docutils literal"><span class="pre">widget</span></code></a> argument on the field definition. For
example:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">django</span> <span class="k">import</span> <span class="n">forms</span>
<span class="k">class</span> <span class="nc">CommentForm</span><span class="p">(</span><span class="n">forms</span><span class="o">.</span><span class="n">Form</span><span class="p">):</span>
<span class="n">name</span> <span class="o">=</span> <span class="n">forms</span><span class="o">.</span><span class="n">CharField</span><span class="p">()</span>
<span class="n">url</span> <span class="o">=</span> <span class="n">forms</span><span class="o">.</span><span class="n">URLField</span><span class="p">()</span>
<span class="n">comment</span> <span class="o">=</span> <span class="n">forms</span><span class="o">.</span><span class="n">CharField</span><span class="p">(</span><span class="n">widget</span><span class="o">=</span><span class="n">forms</span><span class="o">.</span><span class="n">Textarea</span><span class="p">)</span>
</pre></div>
</div>
<p>This would specify a form with a comment that uses a larger <a class="reference internal" href="#django.forms.Textarea" title="django.forms.Textarea"><code class="xref py py-class docutils literal"><span class="pre">Textarea</span></code></a>
widget, rather than the default <a class="reference internal" href="#django.forms.TextInput" title="django.forms.TextInput"><code class="xref py py-class docutils literal"><span class="pre">TextInput</span></code></a> widget.</p>
</div>
<div class="section" id="s-setting-arguments-for-widgets">
<span id="setting-arguments-for-widgets"></span><h2>Setting arguments for widgets<a class="headerlink" href="#setting-arguments-for-widgets" title="Permalink to this headline">¶</a></h2>
<p>Many widgets have optional extra arguments; they can be set when defining the
widget on the field. In the following example, the
<a class="reference internal" href="#django.forms.extras.widgets.SelectDateWidget.years" title="django.forms.extras.widgets.SelectDateWidget.years"><code class="xref py py-attr docutils literal"><span class="pre">years</span></code></a> attribute is set
for a <a class="reference internal" href="#django.forms.extras.widgets.SelectDateWidget" title="django.forms.extras.widgets.SelectDateWidget"><code class="xref py py-class docutils literal"><span class="pre">SelectDateWidget</span></code></a>:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">django</span> <span class="k">import</span> <span class="n">forms</span>
<span class="kn">from</span> <span class="nn">django.forms.extras.widgets</span> <span class="k">import</span> <span class="n">SelectDateWidget</span>
<span class="n">BIRTH_YEAR_CHOICES</span> <span class="o">=</span> <span class="p">(</span><span class="s1">'1980'</span><span class="p">,</span> <span class="s1">'1981'</span><span class="p">,</span> <span class="s1">'1982'</span><span class="p">)</span>
<span class="n">FAVORITE_COLORS_CHOICES</span> <span class="o">=</span> <span class="p">(</span>
<span class="p">(</span><span class="s1">'blue'</span><span class="p">,</span> <span class="s1">'Blue'</span><span class="p">),</span>
<span class="p">(</span><span class="s1">'green'</span><span class="p">,</span> <span class="s1">'Green'</span><span class="p">),</span>
<span class="p">(</span><span class="s1">'black'</span><span class="p">,</span> <span class="s1">'Black'</span><span class="p">),</span>
<span class="p">)</span>
<span class="k">class</span> <span class="nc">SimpleForm</span><span class="p">(</span><span class="n">forms</span><span class="o">.</span><span class="n">Form</span><span class="p">):</span>
<span class="n">birth_year</span> <span class="o">=</span> <span class="n">forms</span><span class="o">.</span><span class="n">DateField</span><span class="p">(</span><span class="n">widget</span><span class="o">=</span><span class="n">SelectDateWidget</span><span class="p">(</span><span class="n">years</span><span class="o">=</span><span class="n">BIRTH_YEAR_CHOICES</span><span class="p">))</span>
<span class="n">favorite_colors</span> <span class="o">=</span> <span class="n">forms</span><span class="o">.</span><span class="n">MultipleChoiceField</span><span class="p">(</span><span class="n">required</span><span class="o">=</span><span class="kc">False</span><span class="p">,</span>
<span class="n">widget</span><span class="o">=</span><span class="n">forms</span><span class="o">.</span><span class="n">CheckboxSelectMultiple</span><span class="p">,</span> <span class="n">choices</span><span class="o">=</span><span class="n">FAVORITE_COLORS_CHOICES</span><span class="p">)</span>
</pre></div>
</div>
<p>See the <a class="reference internal" href="#built-in-widgets"><span class="std std-ref">Built-in widgets</span></a> for more information about which widgets
are available and which arguments they accept.</p>
</div>
<div class="section" id="s-widgets-inheriting-from-the-select-widget">
<span id="widgets-inheriting-from-the-select-widget"></span><h2>Widgets inheriting from the Select widget<a class="headerlink" href="#widgets-inheriting-from-the-select-widget" title="Permalink to this headline">¶</a></h2>
<p>Widgets inheriting from the <a class="reference internal" href="#django.forms.Select" title="django.forms.Select"><code class="xref py py-class docutils literal"><span class="pre">Select</span></code></a> widget deal with choices. They
present the user with a list of options to choose from. The different widgets
present this choice differently; the <a class="reference internal" href="#django.forms.Select" title="django.forms.Select"><code class="xref py py-class docutils literal"><span class="pre">Select</span></code></a> widget itself uses a
<code class="docutils literal"><span class="pre"><select></span></code> HTML list representation, while <a class="reference internal" href="#django.forms.RadioSelect" title="django.forms.RadioSelect"><code class="xref py py-class docutils literal"><span class="pre">RadioSelect</span></code></a> uses radio
buttons.</p>
<p><a class="reference internal" href="#django.forms.Select" title="django.forms.Select"><code class="xref py py-class docutils literal"><span class="pre">Select</span></code></a> widgets are used by default on <a class="reference internal" href="fields.html#django.forms.ChoiceField" title="django.forms.ChoiceField"><code class="xref py py-class docutils literal"><span class="pre">ChoiceField</span></code></a> fields. The
choices displayed on the widget are inherited from the <a class="reference internal" href="fields.html#django.forms.ChoiceField" title="django.forms.ChoiceField"><code class="xref py py-class docutils literal"><span class="pre">ChoiceField</span></code></a> and
changing <a class="reference internal" href="fields.html#django.forms.ChoiceField.choices" title="django.forms.ChoiceField.choices"><code class="xref py py-attr docutils literal"><span class="pre">ChoiceField.choices</span></code></a> will update <a class="reference internal" href="#django.forms.Select.choices" title="django.forms.Select.choices"><code class="xref py py-attr docutils literal"><span class="pre">Select.choices</span></code></a>. For
example:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">django</span> <span class="k">import</span> <span class="n">forms</span>
<span class="gp">>>> </span><span class="n">CHOICES</span> <span class="o">=</span> <span class="p">((</span><span class="s1">'1'</span><span class="p">,</span> <span class="s1">'First'</span><span class="p">,),</span> <span class="p">(</span><span class="s1">'2'</span><span class="p">,</span> <span class="s1">'Second'</span><span class="p">,))</span>
<span class="gp">>>> </span><span class="n">choice_field</span> <span class="o">=</span> <span class="n">forms</span><span class="o">.</span><span class="n">ChoiceField</span><span class="p">(</span><span class="n">widget</span><span class="o">=</span><span class="n">forms</span><span class="o">.</span><span class="n">RadioSelect</span><span class="p">,</span> <span class="n">choices</span><span class="o">=</span><span class="n">CHOICES</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">choice_field</span><span class="o">.</span><span class="n">choices</span>
<span class="go">[('1', 'First'), ('2', 'Second')]</span>
<span class="gp">>>> </span><span class="n">choice_field</span><span class="o">.</span><span class="n">widget</span><span class="o">.</span><span class="n">choices</span>
<span class="go">[('1', 'First'), ('2', 'Second')]</span>
<span class="gp">>>> </span><span class="n">choice_field</span><span class="o">.</span><span class="n">widget</span><span class="o">.</span><span class="n">choices</span> <span class="o">=</span> <span class="p">()</span>
<span class="gp">>>> </span><span class="n">choice_field</span><span class="o">.</span><span class="n">choices</span> <span class="o">=</span> <span class="p">((</span><span class="s1">'1'</span><span class="p">,</span> <span class="s1">'First and only'</span><span class="p">,),)</span>
<span class="gp">>>> </span><span class="n">choice_field</span><span class="o">.</span><span class="n">widget</span><span class="o">.</span><span class="n">choices</span>
<span class="go">[('1', 'First and only')]</span>
</pre></div>
</div>
<p>Widgets which offer a <a class="reference internal" href="#django.forms.Select.choices" title="django.forms.Select.choices"><code class="xref py py-attr docutils literal"><span class="pre">choices</span></code></a> attribute can however be used
with fields which are not based on choice – such as a <a class="reference internal" href="fields.html#django.forms.CharField" title="django.forms.CharField"><code class="xref py py-class docutils literal"><span class="pre">CharField</span></code></a> –
but it is recommended to use a <a class="reference internal" href="fields.html#django.forms.ChoiceField" title="django.forms.ChoiceField"><code class="xref py py-class docutils literal"><span class="pre">ChoiceField</span></code></a>-based field when the
choices are inherent to the model and not just the representational widget.</p>
</div>
<div class="section" id="s-customizing-widget-instances">
<span id="customizing-widget-instances"></span><h2>Customizing widget instances<a class="headerlink" href="#customizing-widget-instances" title="Permalink to this headline">¶</a></h2>
<p>When Django renders a widget as HTML, it only renders very minimal markup -
Django doesn’t add class names, or any other widget-specific attributes. This
means, for example, that all <a class="reference internal" href="#django.forms.TextInput" title="django.forms.TextInput"><code class="xref py py-class docutils literal"><span class="pre">TextInput</span></code></a> widgets will appear the same
on your Web pages.</p>
<p>There are two ways to customize widgets: <a class="reference internal" href="#styling-widget-instances"><span class="std std-ref">per widget instance</span></a> and <a class="reference internal" href="#styling-widget-classes"><span class="std std-ref">per widget class</span></a>.</p>
<div class="section" id="s-styling-widget-instances">
<span id="s-id1"></span><span id="styling-widget-instances"></span><span id="id1"></span><h3>Styling widget instances<a class="headerlink" href="#styling-widget-instances" title="Permalink to this headline">¶</a></h3>
<p>If you want to make one widget instance look different from another, you will
need to specify additional attributes at the time when the widget object is
instantiated and assigned to a form field (and perhaps add some rules to your
CSS files).</p>
<p>For example, take the following simple form:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">django</span> <span class="k">import</span> <span class="n">forms</span>
<span class="k">class</span> <span class="nc">CommentForm</span><span class="p">(</span><span class="n">forms</span><span class="o">.</span><span class="n">Form</span><span class="p">):</span>
<span class="n">name</span> <span class="o">=</span> <span class="n">forms</span><span class="o">.</span><span class="n">CharField</span><span class="p">()</span>
<span class="n">url</span> <span class="o">=</span> <span class="n">forms</span><span class="o">.</span><span class="n">URLField</span><span class="p">()</span>
<span class="n">comment</span> <span class="o">=</span> <span class="n">forms</span><span class="o">.</span><span class="n">CharField</span><span class="p">()</span>
</pre></div>
</div>
<p>This form will include three default <a class="reference internal" href="#django.forms.TextInput" title="django.forms.TextInput"><code class="xref py py-class docutils literal"><span class="pre">TextInput</span></code></a> widgets, with default
rendering – no CSS class, no extra attributes. This means that the input boxes
provided for each widget will be rendered exactly the same:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">f</span> <span class="o">=</span> <span class="n">CommentForm</span><span class="p">(</span><span class="n">auto_id</span><span class="o">=</span><span class="kc">False</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">f</span><span class="o">.</span><span class="n">as_table</span><span class="p">()</span>
<span class="go"><tr><th>Name:</th><td><input type="text" name="name" /></td></tr></span>
<span class="go"><tr><th>Url:</th><td><input type="url" name="url"/></td></tr></span>
<span class="go"><tr><th>Comment:</th><td><input type="text" name="comment" /></td></tr></span>
</pre></div>
</div>
<p>On a real Web page, you probably don’t want every widget to look the same. You
might want a larger input element for the comment, and you might want the
‘name’ widget to have some special CSS class. It is also possible to specify
the ‘type’ attribute to take advantage of the new HTML5 input types. To do
this, you use the <a class="reference internal" href="#django.forms.Widget.attrs" title="django.forms.Widget.attrs"><code class="xref py py-attr docutils literal"><span class="pre">Widget.attrs</span></code></a> argument when creating the widget:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">CommentForm</span><span class="p">(</span><span class="n">forms</span><span class="o">.</span><span class="n">Form</span><span class="p">):</span>
<span class="n">name</span> <span class="o">=</span> <span class="n">forms</span><span class="o">.</span><span class="n">CharField</span><span class="p">(</span><span class="n">widget</span><span class="o">=</span><span class="n">forms</span><span class="o">.</span><span class="n">TextInput</span><span class="p">(</span><span class="n">attrs</span><span class="o">=</span><span class="p">{</span><span class="s1">'class'</span><span class="p">:</span> <span class="s1">'special'</span><span class="p">}))</span>
<span class="n">url</span> <span class="o">=</span> <span class="n">forms</span><span class="o">.</span><span class="n">URLField</span><span class="p">()</span>
<span class="n">comment</span> <span class="o">=</span> <span class="n">forms</span><span class="o">.</span><span class="n">CharField</span><span class="p">(</span><span class="n">widget</span><span class="o">=</span><span class="n">forms</span><span class="o">.</span><span class="n">TextInput</span><span class="p">(</span><span class="n">attrs</span><span class="o">=</span><span class="p">{</span><span class="s1">'size'</span><span class="p">:</span> <span class="s1">'40'</span><span class="p">}))</span>
</pre></div>
</div>
<p>Django will then include the extra attributes in the rendered output:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">f</span> <span class="o">=</span> <span class="n">CommentForm</span><span class="p">(</span><span class="n">auto_id</span><span class="o">=</span><span class="kc">False</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">f</span><span class="o">.</span><span class="n">as_table</span><span class="p">()</span>
<span class="go"><tr><th>Name:</th><td><input type="text" name="name" class="special"/></td></tr></span>
<span class="go"><tr><th>Url:</th><td><input type="url" name="url"/></td></tr></span>
<span class="go"><tr><th>Comment:</th><td><input type="text" name="comment" size="40"/></td></tr></span>
</pre></div>
</div>
<p>You can also set the HTML <code class="docutils literal"><span class="pre">id</span></code> using <a class="reference internal" href="#django.forms.Widget.attrs" title="django.forms.Widget.attrs"><code class="xref py py-attr docutils literal"><span class="pre">attrs</span></code></a>. See
<a class="reference internal" href="api.html#django.forms.BoundField.id_for_label" title="django.forms.BoundField.id_for_label"><code class="xref py py-attr docutils literal"><span class="pre">BoundField.id_for_label</span></code></a> for an example.</p>
</div>
<div class="section" id="s-styling-widget-classes">
<span id="s-id2"></span><span id="styling-widget-classes"></span><span id="id2"></span><h3>Styling widget classes<a class="headerlink" href="#styling-widget-classes" title="Permalink to this headline">¶</a></h3>
<p>With widgets, it is possible to add assets (<code class="docutils literal"><span class="pre">css</span></code> and <code class="docutils literal"><span class="pre">javascript</span></code>)
and more deeply customize their appearance and behavior.</p>
<p>In a nutshell, you will need to subclass the widget and either
<a class="reference internal" href="../../topics/forms/media.html#assets-as-a-static-definition"><span class="std std-ref">define a “Media” inner class</span></a> or
<a class="reference internal" href="../../topics/forms/media.html#dynamic-property"><span class="std std-ref">create a “media” property</span></a>.</p>
<p>These methods involve somewhat advanced Python programming and are described in
detail in the <a class="reference internal" href="../../topics/forms/media.html"><span class="doc">Form Assets</span></a> topic guide.</p>
</div>
</div>
<div class="section" id="s-base-widget-classes">
<span id="s-id3"></span><span id="base-widget-classes"></span><span id="id3"></span><h2>Base Widget classes<a class="headerlink" href="#base-widget-classes" title="Permalink to this headline">¶</a></h2>
<p>Base widget classes <a class="reference internal" href="#django.forms.Widget" title="django.forms.Widget"><code class="xref py py-class docutils literal"><span class="pre">Widget</span></code></a> and <a class="reference internal" href="#django.forms.MultiWidget" title="django.forms.MultiWidget"><code class="xref py py-class docutils literal"><span class="pre">MultiWidget</span></code></a> are subclassed by
all the <a class="reference internal" href="#built-in-widgets"><span class="std std-ref">built-in widgets</span></a> and may serve as a
foundation for custom widgets.</p>
<dl class="class">
<dt id="django.forms.Widget">
<em class="property">class </em><code class="descname">Widget</code>(<em>attrs=None</em>)<a class="reference internal" href="../../_modules/django/forms/widgets.html#Widget"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#django.forms.Widget" title="Permalink to this definition">¶</a></dt>
<dd><p>This abstract class cannot be rendered, but provides the basic attribute
<a class="reference internal" href="#django.forms.Widget.attrs" title="django.forms.Widget.attrs"><code class="xref py py-attr docutils literal"><span class="pre">attrs</span></code></a>. You may also implement or override the
<a class="reference internal" href="#django.forms.Widget.render" title="django.forms.Widget.render"><code class="xref py py-meth docutils literal"><span class="pre">render()</span></code></a> method on custom widgets.</p>
<dl class="attribute">
<dt id="django.forms.Widget.attrs">
<code class="descname">attrs</code><a class="headerlink" href="#django.forms.Widget.attrs" title="Permalink to this definition">¶</a></dt>
<dd><p>A dictionary containing HTML attributes to be set on the rendered
widget.</p>
<div class="highlight-pycon"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">django</span> <span class="kn">import</span> <span class="n">forms</span>
<span class="gp">>>> </span><span class="n">name</span> <span class="o">=</span> <span class="n">forms</span><span class="o">.</span><span class="n">TextInput</span><span class="p">(</span><span class="n">attrs</span><span class="o">=</span><span class="p">{</span><span class="s1">'size'</span><span class="p">:</span> <span class="mi">10</span><span class="p">,</span> <span class="s1">'title'</span><span class="p">:</span> <span class="s1">'Your name'</span><span class="p">,})</span>
<span class="gp">>>> </span><span class="n">name</span><span class="o">.</span><span class="n">render</span><span class="p">(</span><span class="s1">'name'</span><span class="p">,</span> <span class="s1">'A name'</span><span class="p">)</span>
<span class="go">'<input title="Your name" type="text" name="name" value="A name" size="10" />'</span>
</pre></div>
</div>
<div class="versionchanged">
<span class="title">Changed in Django 1.8:</span> <p>If you assign a value of <code class="docutils literal"><span class="pre">True</span></code> or <code class="docutils literal"><span class="pre">False</span></code> to an attribute,
it will be rendered as an HTML5 boolean attribute:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">name</span> <span class="o">=</span> <span class="n">forms</span><span class="o">.</span><span class="n">TextInput</span><span class="p">(</span><span class="n">attrs</span><span class="o">=</span><span class="p">{</span><span class="s1">'required'</span><span class="p">:</span> <span class="kc">True</span><span class="p">})</span>
<span class="gp">>>> </span><span class="n">name</span><span class="o">.</span><span class="n">render</span><span class="p">(</span><span class="s1">'name'</span><span class="p">,</span> <span class="s1">'A name'</span><span class="p">)</span>
<span class="go">'<input name="name" type="text" value="A name" required />'</span>
<span class="go">>>></span>
<span class="gp">>>> </span><span class="n">name</span> <span class="o">=</span> <span class="n">forms</span><span class="o">.</span><span class="n">TextInput</span><span class="p">(</span><span class="n">attrs</span><span class="o">=</span><span class="p">{</span><span class="s1">'required'</span><span class="p">:</span> <span class="kc">False</span><span class="p">})</span>
<span class="gp">>>> </span><span class="n">name</span><span class="o">.</span><span class="n">render</span><span class="p">(</span><span class="s1">'name'</span><span class="p">,</span> <span class="s1">'A name'</span><span class="p">)</span>
<span class="go">'<input name="name" type="text" value="A name" />'</span>
</pre></div>
</div>
</div>
</dd></dl>
<dl class="method">
<dt id="django.forms.Widget.render">
<code class="descname">render</code>(<em>name</em>, <em>value</em>, <em>attrs=None</em>)<a class="reference internal" href="../../_modules/django/forms/widgets.html#Widget.render"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#django.forms.Widget.render" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns HTML for the widget, as a Unicode string. This method must be
implemented by the subclass, otherwise <code class="docutils literal"><span class="pre">NotImplementedError</span></code> will be
raised.</p>
<p>The ‘value’ given is not guaranteed to be valid input, therefore
subclass implementations should program defensively.</p>
</dd></dl>
<dl class="method">
<dt id="django.forms.Widget.value_from_datadict">
<code class="descname">value_from_datadict</code>(<em>data</em>, <em>files</em>, <em>name</em>)<a class="reference internal" href="../../_modules/django/forms/widgets.html#Widget.value_from_datadict"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#django.forms.Widget.value_from_datadict" title="Permalink to this definition">¶</a></dt>
<dd><p>Given a dictionary of data and this widget’s name, returns the value
of this widget. <code class="docutils literal"><span class="pre">files</span></code> may contain data coming from
<a class="reference internal" href="../request-response.html#django.http.HttpRequest.FILES" title="django.http.HttpRequest.FILES"><code class="xref py py-attr docutils literal"><span class="pre">request.FILES</span></code></a>. Returns <code class="docutils literal"><span class="pre">None</span></code>
if a value wasn’t provided. Note also that <code class="docutils literal"><span class="pre">value_from_datadict</span></code> may
be called more than once during handling of form data, so if you
customize it and add expensive processing, you should implement some
caching mechanism yourself.</p>
</dd></dl>
</dd></dl>
<dl class="class">
<dt id="django.forms.MultiWidget">
<em class="property">class </em><code class="descname">MultiWidget</code>(<em>widgets</em>, <em>attrs=None</em>)<a class="reference internal" href="../../_modules/django/forms/widgets.html#MultiWidget"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#django.forms.MultiWidget" title="Permalink to this definition">¶</a></dt>
<dd><p>A widget that is composed of multiple widgets.
<a class="reference internal" href="#django.forms.MultiWidget" title="django.forms.MultiWidget"><code class="xref py py-class docutils literal"><span class="pre">MultiWidget</span></code></a> works hand in hand with the
<a class="reference internal" href="fields.html#django.forms.MultiValueField" title="django.forms.MultiValueField"><code class="xref py py-class docutils literal"><span class="pre">MultiValueField</span></code></a>.</p>
<p><a class="reference internal" href="#django.forms.MultiWidget" title="django.forms.MultiWidget"><code class="xref py py-class docutils literal"><span class="pre">MultiWidget</span></code></a> has one required argument:</p>
<dl class="attribute">
<dt id="django.forms.MultiWidget.widgets">
<code class="descname">widgets</code><a class="headerlink" href="#django.forms.MultiWidget.widgets" title="Permalink to this definition">¶</a></dt>
<dd><p>An iterable containing the widgets needed.</p>
</dd></dl>
<p>And one required method:</p>
<dl class="method">
<dt id="django.forms.MultiWidget.decompress">
<code class="descname">decompress</code>(<em>value</em>)<a class="reference internal" href="../../_modules/django/forms/widgets.html#MultiWidget.decompress"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#django.forms.MultiWidget.decompress" title="Permalink to this definition">¶</a></dt>
<dd><p>This method takes a single “compressed” value from the field and
returns a list of “decompressed” values. The input value can be
assumed valid, but not necessarily non-empty.</p>
<p>This method <strong>must be implemented</strong> by the subclass, and since the
value may be empty, the implementation must be defensive.</p>
<p>The rationale behind “decompression” is that it is necessary to “split”
the combined value of the form field into the values for each widget.</p>
<p>An example of this is how <a class="reference internal" href="#django.forms.SplitDateTimeWidget" title="django.forms.SplitDateTimeWidget"><code class="xref py py-class docutils literal"><span class="pre">SplitDateTimeWidget</span></code></a> turns a
<code class="xref py py-class docutils literal"><span class="pre">datetime</span></code> value into a list with date and time split
into two separate values:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">django.forms</span> <span class="k">import</span> <span class="n">MultiWidget</span>
<span class="k">class</span> <span class="nc">SplitDateTimeWidget</span><span class="p">(</span><span class="n">MultiWidget</span><span class="p">):</span>
<span class="c1"># ...</span>
<span class="k">def</span> <span class="nf">decompress</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">value</span><span class="p">):</span>
<span class="k">if</span> <span class="n">value</span><span class="p">:</span>
<span class="k">return</span> <span class="p">[</span><span class="n">value</span><span class="o">.</span><span class="n">date</span><span class="p">(),</span> <span class="n">value</span><span class="o">.</span><span class="n">time</span><span class="p">()</span><span class="o">.</span><span class="n">replace</span><span class="p">(</span><span class="n">microsecond</span><span class="o">=</span><span class="mi">0</span><span class="p">)]</span>
<span class="k">return</span> <span class="p">[</span><span class="kc">None</span><span class="p">,</span> <span class="kc">None</span><span class="p">]</span>
</pre></div>
</div>
<div class="admonition tip">
<p class="first admonition-title">Tip</p>
<p class="last">Note that <a class="reference internal" href="fields.html#django.forms.MultiValueField" title="django.forms.MultiValueField"><code class="xref py py-class docutils literal"><span class="pre">MultiValueField</span></code></a> has a
complementary method <a class="reference internal" href="fields.html#django.forms.MultiValueField.compress" title="django.forms.MultiValueField.compress"><code class="xref py py-meth docutils literal"><span class="pre">compress()</span></code></a>
with the opposite responsibility - to combine cleaned values of
all member fields into one.</p>
</div>
</dd></dl>
<p>Other methods that may be useful to override include:</p>
<dl class="method">
<dt id="django.forms.MultiWidget.render">
<code class="descname">render</code>(<em>name</em>, <em>value</em>, <em>attrs=None</em>)<a class="reference internal" href="../../_modules/django/forms/widgets.html#MultiWidget.render"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#django.forms.MultiWidget.render" title="Permalink to this definition">¶</a></dt>
<dd><p>Argument <code class="docutils literal"><span class="pre">value</span></code> is handled differently in this method from the
subclasses of <a class="reference internal" href="#django.forms.Widget" title="django.forms.Widget"><code class="xref py py-class docutils literal"><span class="pre">Widget</span></code></a> because it has to figure out how to
split a single value for display in multiple widgets.</p>
<p>The <code class="docutils literal"><span class="pre">value</span></code> argument used when rendering can be one of two things:</p>
<ul class="simple">
<li>A <code class="docutils literal"><span class="pre">list</span></code>.</li>
<li>A single value (e.g., a string) that is the “compressed” representation
of a <code class="docutils literal"><span class="pre">list</span></code> of values.</li>
</ul>
<p>If <code class="docutils literal"><span class="pre">value</span></code> is a list, the output of <a class="reference internal" href="#django.forms.MultiWidget.render" title="django.forms.MultiWidget.render"><code class="xref py py-meth docutils literal"><span class="pre">render()</span></code></a> will
be a concatenation of rendered child widgets. If <code class="docutils literal"><span class="pre">value</span></code> is not a
list, it will first be processed by the method
<a class="reference internal" href="#django.forms.MultiWidget.decompress" title="django.forms.MultiWidget.decompress"><code class="xref py py-meth docutils literal"><span class="pre">decompress()</span></code></a> to create the list and then rendered.</p>
<p>When <code class="docutils literal"><span class="pre">render()</span></code> executes its HTML rendering, each value in the list
is rendered with the corresponding widget – the first value is
rendered in the first widget, the second value is rendered in the
second widget, etc.</p>
<p>Unlike in the single value widgets, method <a class="reference internal" href="#django.forms.MultiWidget.render" title="django.forms.MultiWidget.render"><code class="xref py py-meth docutils literal"><span class="pre">render()</span></code></a>
need not be implemented in the subclasses.</p>
</dd></dl>
<dl class="method">
<dt id="django.forms.MultiWidget.format_output">
<code class="descname">format_output</code>(<em>rendered_widgets</em>)<a class="reference internal" href="../../_modules/django/forms/widgets.html#MultiWidget.format_output"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#django.forms.MultiWidget.format_output" title="Permalink to this definition">¶</a></dt>
<dd><p>Given a list of rendered widgets (as strings), returns a Unicode string
representing the HTML for the whole lot.</p>
<p>This hook allows you to format the HTML design of the widgets any way
you’d like.</p>
</dd></dl>
<p>Here’s an example widget which subclasses <a class="reference internal" href="#django.forms.MultiWidget" title="django.forms.MultiWidget"><code class="xref py py-class docutils literal"><span class="pre">MultiWidget</span></code></a> to display
a date with the day, month, and year in different select boxes. This widget
is intended to be used with a <a class="reference internal" href="fields.html#django.forms.DateField" title="django.forms.DateField"><code class="xref py py-class docutils literal"><span class="pre">DateField</span></code></a> rather than
a <a class="reference internal" href="fields.html#django.forms.MultiValueField" title="django.forms.MultiValueField"><code class="xref py py-class docutils literal"><span class="pre">MultiValueField</span></code></a>, thus we have implemented
<a class="reference internal" href="#django.forms.Widget.value_from_datadict" title="django.forms.Widget.value_from_datadict"><code class="xref py py-meth docutils literal"><span class="pre">value_from_datadict()</span></code></a>:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">datetime</span> <span class="k">import</span> <span class="n">date</span>
<span class="kn">from</span> <span class="nn">django.forms</span> <span class="k">import</span> <span class="n">widgets</span>
<span class="k">class</span> <span class="nc">DateSelectorWidget</span><span class="p">(</span><span class="n">widgets</span><span class="o">.</span><span class="n">MultiWidget</span><span class="p">):</span>
<span class="k">def</span> <span class="nf">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">attrs</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>
<span class="c1"># create choices for days, months, years</span>
<span class="c1"># example below, the rest snipped for brevity.</span>
<span class="n">years</span> <span class="o">=</span> <span class="p">[(</span><span class="n">year</span><span class="p">,</span> <span class="n">year</span><span class="p">)</span> <span class="k">for</span> <span class="n">year</span> <span class="ow">in</span> <span class="p">(</span><span class="mi">2011</span><span class="p">,</span> <span class="mi">2012</span><span class="p">,</span> <span class="mi">2013</span><span class="p">)]</span>
<span class="n">_widgets</span> <span class="o">=</span> <span class="p">(</span>
<span class="n">widgets</span><span class="o">.</span><span class="n">Select</span><span class="p">(</span><span class="n">attrs</span><span class="o">=</span><span class="n">attrs</span><span class="p">,</span> <span class="n">choices</span><span class="o">=</span><span class="n">days</span><span class="p">),</span>
<span class="n">widgets</span><span class="o">.</span><span class="n">Select</span><span class="p">(</span><span class="n">attrs</span><span class="o">=</span><span class="n">attrs</span><span class="p">,</span> <span class="n">choices</span><span class="o">=</span><span class="n">months</span><span class="p">),</span>
<span class="n">widgets</span><span class="o">.</span><span class="n">Select</span><span class="p">(</span><span class="n">attrs</span><span class="o">=</span><span class="n">attrs</span><span class="p">,</span> <span class="n">choices</span><span class="o">=</span><span class="n">years</span><span class="p">),</span>
<span class="p">)</span>
<span class="nb">super</span><span class="p">(</span><span class="n">DateSelectorWidget</span><span class="p">,</span> <span class="bp">self</span><span class="p">)</span><span class="o">.</span><span class="n">__init__</span><span class="p">(</span><span class="n">_widgets</span><span class="p">,</span> <span class="n">attrs</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">decompress</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">value</span><span class="p">):</span>
<span class="k">if</span> <span class="n">value</span><span class="p">:</span>
<span class="k">return</span> <span class="p">[</span><span class="n">value</span><span class="o">.</span><span class="n">day</span><span class="p">,</span> <span class="n">value</span><span class="o">.</span><span class="n">month</span><span class="p">,</span> <span class="n">value</span><span class="o">.</span><span class="n">year</span><span class="p">]</span>
<span class="k">return</span> <span class="p">[</span><span class="kc">None</span><span class="p">,</span> <span class="kc">None</span><span class="p">,</span> <span class="kc">None</span><span class="p">]</span>
<span class="k">def</span> <span class="nf">format_output</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">rendered_widgets</span><span class="p">):</span>
<span class="k">return</span> <span class="s1">''</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">rendered_widgets</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">value_from_datadict</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">data</span><span class="p">,</span> <span class="n">files</span><span class="p">,</span> <span class="n">name</span><span class="p">):</span>
<span class="n">datelist</span> <span class="o">=</span> <span class="p">[</span>
<span class="n">widget</span><span class="o">.</span><span class="n">value_from_datadict</span><span class="p">(</span><span class="n">data</span><span class="p">,</span> <span class="n">files</span><span class="p">,</span> <span class="n">name</span> <span class="o">+</span> <span class="s1">'_</span><span class="si">%s</span><span class="s1">'</span> <span class="o">%</span> <span class="n">i</span><span class="p">)</span>
<span class="k">for</span> <span class="n">i</span><span class="p">,</span> <span class="n">widget</span> <span class="ow">in</span> <span class="nb">enumerate</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">widgets</span><span class="p">)]</span>
<span class="k">try</span><span class="p">:</span>
<span class="n">D</span> <span class="o">=</span> <span class="n">date</span><span class="p">(</span>
<span class="n">day</span><span class="o">=</span><span class="nb">int</span><span class="p">(</span><span class="n">datelist</span><span class="p">[</span><span class="mi">0</span><span class="p">]),</span>
<span class="n">month</span><span class="o">=</span><span class="nb">int</span><span class="p">(</span><span class="n">datelist</span><span class="p">[</span><span class="mi">1</span><span class="p">]),</span>
<span class="n">year</span><span class="o">=</span><span class="nb">int</span><span class="p">(</span><span class="n">datelist</span><span class="p">[</span><span class="mi">2</span><span class="p">]),</span>
<span class="p">)</span>
<span class="k">except</span> <span class="ne">ValueError</span><span class="p">:</span>
<span class="k">return</span> <span class="s1">''</span>
<span class="k">else</span><span class="p">:</span>
<span class="k">return</span> <span class="nb">str</span><span class="p">(</span><span class="n">D</span><span class="p">)</span>
</pre></div>
</div>
<p>The constructor creates several <a class="reference internal" href="#django.forms.Select" title="django.forms.Select"><code class="xref py py-class docutils literal"><span class="pre">Select</span></code></a> widgets in a tuple. The
<code class="docutils literal"><span class="pre">super</span></code> class uses this tuple to setup the widget.</p>
<p>The <a class="reference internal" href="#django.forms.MultiWidget.format_output" title="django.forms.MultiWidget.format_output"><code class="xref py py-meth docutils literal"><span class="pre">format_output()</span></code></a> method is fairly vanilla here (in
fact, it’s the same as what’s been implemented as the default for
<code class="docutils literal"><span class="pre">MultiWidget</span></code>), but the idea is that you could add custom HTML between
the widgets should you wish.</p>
<p>The required method <a class="reference internal" href="#django.forms.MultiWidget.decompress" title="django.forms.MultiWidget.decompress"><code class="xref py py-meth docutils literal"><span class="pre">decompress()</span></code></a> breaks up a
<code class="docutils literal"><span class="pre">datetime.date</span></code> value into the day, month, and year values corresponding
to each widget. Note how the method handles the case where <code class="docutils literal"><span class="pre">value</span></code> is
<code class="docutils literal"><span class="pre">None</span></code>.</p>
<p>The default implementation of <a class="reference internal" href="#django.forms.Widget.value_from_datadict" title="django.forms.Widget.value_from_datadict"><code class="xref py py-meth docutils literal"><span class="pre">value_from_datadict()</span></code></a> returns
a list of values corresponding to each <code class="docutils literal"><span class="pre">Widget</span></code>. This is appropriate
when using a <code class="docutils literal"><span class="pre">MultiWidget</span></code> with a <a class="reference internal" href="fields.html#django.forms.MultiValueField" title="django.forms.MultiValueField"><code class="xref py py-class docutils literal"><span class="pre">MultiValueField</span></code></a>,
but since we want to use this widget with a <a class="reference internal" href="fields.html#django.forms.DateField" title="django.forms.DateField"><code class="xref py py-class docutils literal"><span class="pre">DateField</span></code></a>
which takes a single value, we have overridden this method to combine the
data of all the subwidgets into a <code class="docutils literal"><span class="pre">datetime.date</span></code>. The method extracts
data from the <code class="docutils literal"><span class="pre">POST</span></code> dictionary and constructs and validates the date.
If it is valid, we return the string, otherwise, we return an empty string
which will cause <code class="docutils literal"><span class="pre">form.is_valid</span></code> to return <code class="docutils literal"><span class="pre">False</span></code>.</p>
</dd></dl>
</div>
<div class="section" id="s-built-in-widgets">
<span id="s-id4"></span><span id="built-in-widgets"></span><span id="id4"></span><h2>Built-in widgets<a class="headerlink" href="#built-in-widgets" title="Permalink to this headline">¶</a></h2>
<p>Django provides a representation of all the basic HTML widgets, plus some
commonly used groups of widgets in the <code class="docutils literal"><span class="pre">django.forms.widgets</span></code> module,
including <a class="reference internal" href="#text-widgets"><span class="std std-ref">the input of text</span></a>, <a class="reference internal" href="#selector-widgets"><span class="std std-ref">various checkboxes
and selectors</span></a>, <a class="reference internal" href="#file-upload-widgets"><span class="std std-ref">uploading files</span></a>,
and <a class="reference internal" href="#composite-widgets"><span class="std std-ref">handling of multi-valued input</span></a>.</p>
<div class="section" id="s-widgets-handling-input-of-text">
<span id="s-text-widgets"></span><span id="widgets-handling-input-of-text"></span><span id="text-widgets"></span><h3>Widgets handling input of text<a class="headerlink" href="#widgets-handling-input-of-text" title="Permalink to this headline">¶</a></h3>
<p>These widgets make use of the HTML elements <code class="docutils literal"><span class="pre">input</span></code> and <code class="docutils literal"><span class="pre">textarea</span></code>.</p>
<div class="section" id="s-textinput">
<span id="textinput"></span><h4><code class="docutils literal"><span class="pre">TextInput</span></code><a class="headerlink" href="#textinput" title="Permalink to this headline">¶</a></h4>
<dl class="class">
<dt id="django.forms.TextInput">
<em class="property">class </em><code class="descname">TextInput</code><a class="reference internal" href="../../_modules/django/forms/widgets.html#TextInput"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#django.forms.TextInput" title="Permalink to this definition">¶</a></dt>
<dd><p>Text input: <code class="docutils literal"><span class="pre"><input</span> <span class="pre">type="text"</span> <span class="pre">...></span></code></p>
</dd></dl>
</div>
<div class="section" id="s-numberinput">
<span id="numberinput"></span><h4><code class="docutils literal"><span class="pre">NumberInput</span></code><a class="headerlink" href="#numberinput" title="Permalink to this headline">¶</a></h4>
<dl class="class">
<dt id="django.forms.NumberInput">
<em class="property">class </em><code class="descname">NumberInput</code><a class="reference internal" href="../../_modules/django/forms/widgets.html#NumberInput"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#django.forms.NumberInput" title="Permalink to this definition">¶</a></dt>
<dd><p>Text input: <code class="docutils literal"><span class="pre"><input</span> <span class="pre">type="number"</span> <span class="pre">...></span></code></p>
<p>Beware that not all browsers support entering localized numbers in
<code class="docutils literal"><span class="pre">number</span></code> input types. Django itself avoids using them for fields having
their <a class="reference internal" href="fields.html#django.forms.Field.localize" title="django.forms.Field.localize"><code class="xref py py-attr docutils literal"><span class="pre">localize</span></code></a> property set to <code class="docutils literal"><span class="pre">True</span></code>.</p>
</dd></dl>
</div>
<div class="section" id="s-emailinput">
<span id="emailinput"></span><h4><code class="docutils literal"><span class="pre">EmailInput</span></code><a class="headerlink" href="#emailinput" title="Permalink to this headline">¶</a></h4>
<dl class="class">
<dt id="django.forms.EmailInput">
<em class="property">class </em><code class="descname">EmailInput</code><a class="reference internal" href="../../_modules/django/forms/widgets.html#EmailInput"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#django.forms.EmailInput" title="Permalink to this definition">¶</a></dt>
<dd><p>Text input: <code class="docutils literal"><span class="pre"><input</span> <span class="pre">type="email"</span> <span class="pre">...></span></code></p>
</dd></dl>
</div>
<div class="section" id="s-urlinput">
<span id="urlinput"></span><h4><code class="docutils literal"><span class="pre">URLInput</span></code><a class="headerlink" href="#urlinput" title="Permalink to this headline">¶</a></h4>
<dl class="class">
<dt id="django.forms.URLInput">
<em class="property">class </em><code class="descname">URLInput</code><a class="reference internal" href="../../_modules/django/forms/widgets.html#URLInput"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#django.forms.URLInput" title="Permalink to this definition">¶</a></dt>
<dd><p>Text input: <code class="docutils literal"><span class="pre"><input</span> <span class="pre">type="url"</span> <span class="pre">...></span></code></p>
</dd></dl>
</div>
<div class="section" id="s-passwordinput">
<span id="passwordinput"></span><h4><code class="docutils literal"><span class="pre">PasswordInput</span></code><a class="headerlink" href="#passwordinput" title="Permalink to this headline">¶</a></h4>
<dl class="class">
<dt id="django.forms.PasswordInput">
<em class="property">class </em><code class="descname">PasswordInput</code><a class="reference internal" href="../../_modules/django/forms/widgets.html#PasswordInput"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#django.forms.PasswordInput" title="Permalink to this definition">¶</a></dt>
<dd><p>Password input: <code class="docutils literal"><span class="pre"><input</span> <span class="pre">type='password'</span> <span class="pre">...></span></code></p>
<p>Takes one optional argument:</p>
<dl class="attribute">
<dt id="django.forms.PasswordInput.render_value">
<code class="descname">render_value</code><a class="headerlink" href="#django.forms.PasswordInput.render_value" title="Permalink to this definition">¶</a></dt>
<dd><p>Determines whether the widget will have a value filled in when the
form is re-displayed after a validation error (default is <code class="docutils literal"><span class="pre">False</span></code>).</p>
</dd></dl>
</dd></dl>
</div>
<div class="section" id="s-hiddeninput">
<span id="hiddeninput"></span><h4><code class="docutils literal"><span class="pre">HiddenInput</span></code><a class="headerlink" href="#hiddeninput" title="Permalink to this headline">¶</a></h4>
<dl class="class">
<dt id="django.forms.HiddenInput">
<em class="property">class </em><code class="descname">HiddenInput</code><a class="reference internal" href="../../_modules/django/forms/widgets.html#HiddenInput"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#django.forms.HiddenInput" title="Permalink to this definition">¶</a></dt>
<dd><p>Hidden input: <code class="docutils literal"><span class="pre"><input</span> <span class="pre">type='hidden'</span> <span class="pre">...></span></code></p>
<p>Note that there also is a <a class="reference internal" href="#django.forms.MultipleHiddenInput" title="django.forms.MultipleHiddenInput"><code class="xref py py-class docutils literal"><span class="pre">MultipleHiddenInput</span></code></a> widget that
encapsulates a set of hidden input elements.</p>
</dd></dl>
</div>
<div class="section" id="s-dateinput">
<span id="dateinput"></span><h4><code class="docutils literal"><span class="pre">DateInput</span></code><a class="headerlink" href="#dateinput" title="Permalink to this headline">¶</a></h4>
<dl class="class">
<dt id="django.forms.DateInput">
<em class="property">class </em><code class="descname">DateInput</code><a class="reference internal" href="../../_modules/django/forms/widgets.html#DateInput"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#django.forms.DateInput" title="Permalink to this definition">¶</a></dt>
<dd><p>Date input as a simple text box: <code class="docutils literal"><span class="pre"><input</span> <span class="pre">type='text'</span> <span class="pre">...></span></code></p>
<p>Takes same arguments as <a class="reference internal" href="#django.forms.TextInput" title="django.forms.TextInput"><code class="xref py py-class docutils literal"><span class="pre">TextInput</span></code></a>, with one more optional argument:</p>
<dl class="attribute">
<dt id="django.forms.DateInput.format">
<code class="descname">format</code><a class="headerlink" href="#django.forms.DateInput.format" title="Permalink to this definition">¶</a></dt>
<dd><p>The format in which this field’s initial value will be displayed.</p>
</dd></dl>
<p>If no <code class="docutils literal"><span class="pre">format</span></code> argument is provided, the default format is the first
format found in <a class="reference internal" href="../settings.html#std:setting-DATE_INPUT_FORMATS"><code class="xref std std-setting docutils literal"><span class="pre">DATE_INPUT_FORMATS</span></code></a> and respects
<a class="reference internal" href="../../topics/i18n/formatting.html#format-localization"><span class="std std-ref">Format localization</span></a>.</p>
</dd></dl>
</div>
<div class="section" id="s-datetimeinput">
<span id="datetimeinput"></span><h4><code class="docutils literal"><span class="pre">DateTimeInput</span></code><a class="headerlink" href="#datetimeinput" title="Permalink to this headline">¶</a></h4>
<dl class="class">
<dt id="django.forms.DateTimeInput">
<em class="property">class </em><code class="descname">DateTimeInput</code><a class="reference internal" href="../../_modules/django/forms/widgets.html#DateTimeInput"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#django.forms.DateTimeInput" title="Permalink to this definition">¶</a></dt>
<dd><p>Date/time input as a simple text box: <code class="docutils literal"><span class="pre"><input</span> <span class="pre">type='text'</span> <span class="pre">...></span></code></p>
<p>Takes same arguments as <a class="reference internal" href="#django.forms.TextInput" title="django.forms.TextInput"><code class="xref py py-class docutils literal"><span class="pre">TextInput</span></code></a>, with one more optional argument:</p>
<dl class="attribute">
<dt id="django.forms.DateTimeInput.format">
<code class="descname">format</code><a class="headerlink" href="#django.forms.DateTimeInput.format" title="Permalink to this definition">¶</a></dt>
<dd><p>The format in which this field’s initial value will be displayed.</p>
</dd></dl>
<p>If no <code class="docutils literal"><span class="pre">format</span></code> argument is provided, the default format is the first
format found in <a class="reference internal" href="../settings.html#std:setting-DATETIME_INPUT_FORMATS"><code class="xref std std-setting docutils literal"><span class="pre">DATETIME_INPUT_FORMATS</span></code></a> and respects
<a class="reference internal" href="../../topics/i18n/formatting.html#format-localization"><span class="std std-ref">Format localization</span></a>.</p>
</dd></dl>
</div>
<div class="section" id="s-timeinput">
<span id="timeinput"></span><h4><code class="docutils literal"><span class="pre">TimeInput</span></code><a class="headerlink" href="#timeinput" title="Permalink to this headline">¶</a></h4>
<dl class="class">
<dt id="django.forms.TimeInput">
<em class="property">class </em><code class="descname">TimeInput</code><a class="reference internal" href="../../_modules/django/forms/widgets.html#TimeInput"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#django.forms.TimeInput" title="Permalink to this definition">¶</a></dt>
<dd><p>Time input as a simple text box: <code class="docutils literal"><span class="pre"><input</span> <span class="pre">type='text'</span> <span class="pre">...></span></code></p>
<p>Takes same arguments as <a class="reference internal" href="#django.forms.TextInput" title="django.forms.TextInput"><code class="xref py py-class docutils literal"><span class="pre">TextInput</span></code></a>, with one more optional argument:</p>
<dl class="attribute">
<dt id="django.forms.TimeInput.format">
<code class="descname">format</code><a class="headerlink" href="#django.forms.TimeInput.format" title="Permalink to this definition">¶</a></dt>
<dd><p>The format in which this field’s initial value will be displayed.</p>
</dd></dl>
<p>If no <code class="docutils literal"><span class="pre">format</span></code> argument is provided, the default format is the first
format found in <a class="reference internal" href="../settings.html#std:setting-TIME_INPUT_FORMATS"><code class="xref std std-setting docutils literal"><span class="pre">TIME_INPUT_FORMATS</span></code></a> and respects
<a class="reference internal" href="../../topics/i18n/formatting.html#format-localization"><span class="std std-ref">Format localization</span></a>.</p>
</dd></dl>
</div>
<div class="section" id="s-textarea">
<span id="textarea"></span><h4><code class="docutils literal"><span class="pre">Textarea</span></code><a class="headerlink" href="#textarea" title="Permalink to this headline">¶</a></h4>
<dl class="class">
<dt id="django.forms.Textarea">
<em class="property">class </em><code class="descname">Textarea</code><a class="reference internal" href="../../_modules/django/forms/widgets.html#Textarea"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#django.forms.Textarea" title="Permalink to this definition">¶</a></dt>
<dd><p>Text area: <code class="docutils literal"><span class="pre"><textarea>...</textarea></span></code></p>
</dd></dl>
</div>
</div>
<div class="section" id="s-selector-and-checkbox-widgets">
<span id="s-selector-widgets"></span><span id="selector-and-checkbox-widgets"></span><span id="selector-widgets"></span><h3>Selector and checkbox widgets<a class="headerlink" href="#selector-and-checkbox-widgets" title="Permalink to this headline">¶</a></h3>
<div class="section" id="s-checkboxinput">
<span id="checkboxinput"></span><h4><code class="docutils literal"><span class="pre">CheckboxInput</span></code><a class="headerlink" href="#checkboxinput" title="Permalink to this headline">¶</a></h4>
<dl class="class">
<dt id="django.forms.CheckboxInput">
<em class="property">class </em><code class="descname">CheckboxInput</code><a class="reference internal" href="../../_modules/django/forms/widgets.html#CheckboxInput"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#django.forms.CheckboxInput" title="Permalink to this definition">¶</a></dt>
<dd><p>Checkbox: <code class="docutils literal"><span class="pre"><input</span> <span class="pre">type='checkbox'</span> <span class="pre">...></span></code></p>
<p>Takes one optional argument:</p>
<dl class="attribute">
<dt id="django.forms.CheckboxInput.check_test">
<code class="descname">check_test</code><a class="headerlink" href="#django.forms.CheckboxInput.check_test" title="Permalink to this definition">¶</a></dt>
<dd><p>A callable that takes the value of the <code class="docutils literal"><span class="pre">CheckboxInput</span></code> and returns
<code class="docutils literal"><span class="pre">True</span></code> if the checkbox should be checked for that value.</p>
</dd></dl>
</dd></dl>
</div>
<div class="section" id="s-select">
<span id="select"></span><h4><code class="docutils literal"><span class="pre">Select</span></code><a class="headerlink" href="#select" title="Permalink to this headline">¶</a></h4>
<dl class="class">
<dt id="django.forms.Select">
<em class="property">class </em><code class="descname">Select</code><a class="reference internal" href="../../_modules/django/forms/widgets.html#Select"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#django.forms.Select" title="Permalink to this definition">¶</a></dt>
<dd><p>Select widget: <code class="docutils literal"><span class="pre"><select><option</span> <span class="pre">...>...</select></span></code></p>
<dl class="attribute">
<dt id="django.forms.Select.choices">
<code class="descname">choices</code><a class="headerlink" href="#django.forms.Select.choices" title="Permalink to this definition">¶</a></dt>
<dd><p>This attribute is optional when the form field does not have a
<code class="docutils literal"><span class="pre">choices</span></code> attribute. If it does, it will override anything you set
here when the attribute is updated on the <a class="reference internal" href="fields.html#django.forms.Field" title="django.forms.Field"><code class="xref py py-class docutils literal"><span class="pre">Field</span></code></a>.</p>
</dd></dl>
</dd></dl>
</div>
<div class="section" id="s-nullbooleanselect">
<span id="nullbooleanselect"></span><h4><code class="docutils literal"><span class="pre">NullBooleanSelect</span></code><a class="headerlink" href="#nullbooleanselect" title="Permalink to this headline">¶</a></h4>
<dl class="class">
<dt id="django.forms.NullBooleanSelect">
<em class="property">class </em><code class="descname">NullBooleanSelect</code><a class="reference internal" href="../../_modules/django/forms/widgets.html#NullBooleanSelect"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#django.forms.NullBooleanSelect" title="Permalink to this definition">¶</a></dt>
<dd><p>Select widget with options ‘Unknown’, ‘Yes’ and ‘No’</p>
</dd></dl>
</div>
<div class="section" id="s-selectmultiple">
<span id="selectmultiple"></span><h4><code class="docutils literal"><span class="pre">SelectMultiple</span></code><a class="headerlink" href="#selectmultiple" title="Permalink to this headline">¶</a></h4>
<dl class="class">
<dt id="django.forms.SelectMultiple">
<em class="property">class </em><code class="descname">SelectMultiple</code><a class="reference internal" href="../../_modules/django/forms/widgets.html#SelectMultiple"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#django.forms.SelectMultiple" title="Permalink to this definition">¶</a></dt>
<dd><p>Similar to <a class="reference internal" href="#django.forms.Select" title="django.forms.Select"><code class="xref py py-class docutils literal"><span class="pre">Select</span></code></a>, but allows multiple selection:
<code class="docutils literal"><span class="pre"><select</span> <span class="pre">multiple='multiple'>...</select></span></code></p>
</dd></dl>
</div>
<div class="section" id="s-radioselect">
<span id="radioselect"></span><h4><code class="docutils literal"><span class="pre">RadioSelect</span></code><a class="headerlink" href="#radioselect" title="Permalink to this headline">¶</a></h4>
<dl class="class">
<dt id="django.forms.RadioSelect">
<em class="property">class </em><code class="descname">RadioSelect</code><a class="reference internal" href="../../_modules/django/forms/widgets.html#RadioSelect"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#django.forms.RadioSelect" title="Permalink to this definition">¶</a></dt>
<dd><p>Similar to <a class="reference internal" href="#django.forms.Select" title="django.forms.Select"><code class="xref py py-class docutils literal"><span class="pre">Select</span></code></a>, but rendered as a list of radio buttons within
<code class="docutils literal"><span class="pre"><li></span></code> tags:</p>
<div class="highlight-html"><div class="highlight"><pre><span></span><span class="p"><</span><span class="nt">ul</span><span class="p">></span>
<span class="p"><</span><span class="nt">li</span><span class="p">><</span><span class="nt">input</span> <span class="na">type</span><span class="o">=</span><span class="s">'radio'</span> <span class="na">name</span><span class="o">=</span><span class="s">'...'</span><span class="p">></</span><span class="nt">li</span><span class="p">></span>
...
<span class="p"></</span><span class="nt">ul</span><span class="p">></span>
</pre></div>
</div>
<p>For more granular control over the generated markup, you can loop over the
radio buttons in the template. Assuming a form <code class="docutils literal"><span class="pre">myform</span></code> with a field
<code class="docutils literal"><span class="pre">beatles</span></code> that uses a <code class="docutils literal"><span class="pre">RadioSelect</span></code> as its widget:</p>
<div class="highlight-html+django"><div class="highlight"><pre><span></span><span class="cp">{%</span> <span class="k">for</span> <span class="nv">radio</span> <span class="k">in</span> <span class="nv">myform.beatles</span> <span class="cp">%}</span>
<span class="p"><</span><span class="nt">div</span> <span class="na">class</span><span class="o">=</span><span class="s">"myradio"</span><span class="p">></span>
<span class="cp">{{</span> <span class="nv">radio</span> <span class="cp">}}</span>
<span class="p"></</span><span class="nt">div</span><span class="p">></span>
<span class="cp">{%</span> <span class="k">endfor</span> <span class="cp">%}</span>
</pre></div>
</div>
<p>This would generate the following HTML:</p>
<div class="highlight-html"><div class="highlight"><pre><span></span><span class="p"><</span><span class="nt">div</span> <span class="na">class</span><span class="o">=</span><span class="s">"myradio"</span><span class="p">></span>
<span class="p"><</span><span class="nt">label</span> <span class="na">for</span><span class="o">=</span><span class="s">"id_beatles_0"</span><span class="p">><</span><span class="nt">input</span> <span class="na">id</span><span class="o">=</span><span class="s">"id_beatles_0"</span> <span class="na">name</span><span class="o">=</span><span class="s">"beatles"</span> <span class="na">type</span><span class="o">=</span><span class="s">"radio"</span> <span class="na">value</span><span class="o">=</span><span class="s">"john"</span> <span class="p">/></span> John<span class="p"></</span><span class="nt">label</span><span class="p">></span>
<span class="p"></</span><span class="nt">div</span><span class="p">></span>
<span class="p"><</span><span class="nt">div</span> <span class="na">class</span><span class="o">=</span><span class="s">"myradio"</span><span class="p">></span>
<span class="p"><</span><span class="nt">label</span> <span class="na">for</span><span class="o">=</span><span class="s">"id_beatles_1"</span><span class="p">><</span><span class="nt">input</span> <span class="na">id</span><span class="o">=</span><span class="s">"id_beatles_1"</span> <span class="na">name</span><span class="o">=</span><span class="s">"beatles"</span> <span class="na">type</span><span class="o">=</span><span class="s">"radio"</span> <span class="na">value</span><span class="o">=</span><span class="s">"paul"</span> <span class="p">/></span> Paul<span class="p"></</span><span class="nt">label</span><span class="p">></span>
<span class="p"></</span><span class="nt">div</span><span class="p">></span>
<span class="p"><</span><span class="nt">div</span> <span class="na">class</span><span class="o">=</span><span class="s">"myradio"</span><span class="p">></span>
<span class="p"><</span><span class="nt">label</span> <span class="na">for</span><span class="o">=</span><span class="s">"id_beatles_2"</span><span class="p">><</span><span class="nt">input</span> <span class="na">id</span><span class="o">=</span><span class="s">"id_beatles_2"</span> <span class="na">name</span><span class="o">=</span><span class="s">"beatles"</span> <span class="na">type</span><span class="o">=</span><span class="s">"radio"</span> <span class="na">value</span><span class="o">=</span><span class="s">"george"</span> <span class="p">/></span> George<span class="p"></</span><span class="nt">label</span><span class="p">></span>
<span class="p"></</span><span class="nt">div</span><span class="p">></span>
<span class="p"><</span><span class="nt">div</span> <span class="na">class</span><span class="o">=</span><span class="s">"myradio"</span><span class="p">></span>
<span class="p"><</span><span class="nt">label</span> <span class="na">for</span><span class="o">=</span><span class="s">"id_beatles_3"</span><span class="p">><</span><span class="nt">input</span> <span class="na">id</span><span class="o">=</span><span class="s">"id_beatles_3"</span> <span class="na">name</span><span class="o">=</span><span class="s">"beatles"</span> <span class="na">type</span><span class="o">=</span><span class="s">"radio"</span> <span class="na">value</span><span class="o">=</span><span class="s">"ringo"</span> <span class="p">/></span> Ringo<span class="p"></</span><span class="nt">label</span><span class="p">></span>
<span class="p"></</span><span class="nt">div</span><span class="p">></span>
</pre></div>
</div>
<p>That included the <code class="docutils literal"><span class="pre"><label></span></code> tags. To get more granular, you can use each
radio button’s <code class="docutils literal"><span class="pre">tag</span></code>, <code class="docutils literal"><span class="pre">choice_label</span></code> and <code class="docutils literal"><span class="pre">id_for_label</span></code> attributes.
For example, this template...</p>
<div class="highlight-html+django"><div class="highlight"><pre><span></span><span class="cp">{%</span> <span class="k">for</span> <span class="nv">radio</span> <span class="k">in</span> <span class="nv">myform.beatles</span> <span class="cp">%}</span>
<span class="p"><</span><span class="nt">label</span> <span class="na">for</span><span class="o">=</span><span class="s">"</span><span class="cp">{{</span> <span class="nv">radio.id_for_label</span> <span class="cp">}}</span><span class="s">"</span><span class="p">></span>
<span class="cp">{{</span> <span class="nv">radio.choice_label</span> <span class="cp">}}</span>
<span class="p"><</span><span class="nt">span</span> <span class="na">class</span><span class="o">=</span><span class="s">"radio"</span><span class="p">></span><span class="cp">{{</span> <span class="nv">radio.tag</span> <span class="cp">}}</span><span class="p"></</span><span class="nt">span</span><span class="p">></span>
<span class="p"></</span><span class="nt">label</span><span class="p">></span>
<span class="cp">{%</span> <span class="k">endfor</span> <span class="cp">%}</span>
</pre></div>
</div>
<p>...will result in the following HTML:</p>
<div class="highlight-html"><div class="highlight"><pre><span></span><span class="p"><</span><span class="nt">label</span> <span class="na">for</span><span class="o">=</span><span class="s">"id_beatles_0"</span><span class="p">></span>
John
<span class="p"><</span><span class="nt">span</span> <span class="na">class</span><span class="o">=</span><span class="s">"radio"</span><span class="p">><</span><span class="nt">input</span> <span class="na">id</span><span class="o">=</span><span class="s">"id_beatles_0"</span> <span class="na">name</span><span class="o">=</span><span class="s">"beatles"</span> <span class="na">type</span><span class="o">=</span><span class="s">"radio"</span> <span class="na">value</span><span class="o">=</span><span class="s">"john"</span> <span class="p">/></</span><span class="nt">span</span><span class="p">></span>
<span class="p"></</span><span class="nt">label</span><span class="p">></span>
<span class="p"><</span><span class="nt">label</span> <span class="na">for</span><span class="o">=</span><span class="s">"id_beatles_1"</span><span class="p">></span>
Paul
<span class="p"><</span><span class="nt">span</span> <span class="na">class</span><span class="o">=</span><span class="s">"radio"</span><span class="p">><</span><span class="nt">input</span> <span class="na">id</span><span class="o">=</span><span class="s">"id_beatles_1"</span> <span class="na">name</span><span class="o">=</span><span class="s">"beatles"</span> <span class="na">type</span><span class="o">=</span><span class="s">"radio"</span> <span class="na">value</span><span class="o">=</span><span class="s">"paul"</span> <span class="p">/></</span><span class="nt">span</span><span class="p">></span>
<span class="p"></</span><span class="nt">label</span><span class="p">></span>
<span class="p"><</span><span class="nt">label</span> <span class="na">for</span><span class="o">=</span><span class="s">"id_beatles_2"</span><span class="p">></span>
George
<span class="p"><</span><span class="nt">span</span> <span class="na">class</span><span class="o">=</span><span class="s">"radio"</span><span class="p">><</span><span class="nt">input</span> <span class="na">id</span><span class="o">=</span><span class="s">"id_beatles_2"</span> <span class="na">name</span><span class="o">=</span><span class="s">"beatles"</span> <span class="na">type</span><span class="o">=</span><span class="s">"radio"</span> <span class="na">value</span><span class="o">=</span><span class="s">"george"</span> <span class="p">/></</span><span class="nt">span</span><span class="p">></span>
<span class="p"></</span><span class="nt">label</span><span class="p">></span>
<span class="p"><</span><span class="nt">label</span> <span class="na">for</span><span class="o">=</span><span class="s">"id_beatles_3"</span><span class="p">></span>
Ringo
<span class="p"><</span><span class="nt">span</span> <span class="na">class</span><span class="o">=</span><span class="s">"radio"</span><span class="p">><</span><span class="nt">input</span> <span class="na">id</span><span class="o">=</span><span class="s">"id_beatles_3"</span> <span class="na">name</span><span class="o">=</span><span class="s">"beatles"</span> <span class="na">type</span><span class="o">=</span><span class="s">"radio"</span> <span class="na">value</span><span class="o">=</span><span class="s">"ringo"</span> <span class="p">/></</span><span class="nt">span</span><span class="p">></span>
<span class="p"></</span><span class="nt">label</span><span class="p">></span>
</pre></div>
</div>
<p>If you decide not to loop over the radio buttons – e.g., if your template
simply includes <code class="docutils literal"><span class="pre">{{</span> <span class="pre">myform.beatles</span> <span class="pre">}}</span></code> – they’ll be output in a <code class="docutils literal"><span class="pre"><ul></span></code>
with <code class="docutils literal"><span class="pre"><li></span></code> tags, as above.</p>
<p>The outer <code class="docutils literal"><span class="pre"><ul></span></code> container will receive the <code class="docutils literal"><span class="pre">id</span></code> attribute defined on
the widget.</p>
</dd></dl>
<div class="versionchanged">
<span class="title">Changed in Django 1.7:</span> <p>When looping over the radio buttons, the <code class="docutils literal"><span class="pre">label</span></code> and <code class="docutils literal"><span class="pre">input</span></code> tags include
<code class="docutils literal"><span class="pre">for</span></code> and <code class="docutils literal"><span class="pre">id</span></code> attributes, respectively. Each radio button has an
<code class="docutils literal"><span class="pre">id_for_label</span></code> attribute to output the element’s ID.</p>
</div>
</div>
<div class="section" id="s-checkboxselectmultiple">
<span id="checkboxselectmultiple"></span><h4><code class="docutils literal"><span class="pre">CheckboxSelectMultiple</span></code><a class="headerlink" href="#checkboxselectmultiple" title="Permalink to this headline">¶</a></h4>
<dl class="class">
<dt id="django.forms.CheckboxSelectMultiple">
<em class="property">class </em><code class="descname">CheckboxSelectMultiple</code><a class="reference internal" href="../../_modules/django/forms/widgets.html#CheckboxSelectMultiple"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#django.forms.CheckboxSelectMultiple" title="Permalink to this definition">¶</a></dt>
<dd><p>Similar to <a class="reference internal" href="#django.forms.SelectMultiple" title="django.forms.SelectMultiple"><code class="xref py py-class docutils literal"><span class="pre">SelectMultiple</span></code></a>, but rendered as a list of check
buttons:</p>
<div class="highlight-html"><div class="highlight"><pre><span></span><span class="p"><</span><span class="nt">ul</span><span class="p">></span>
<span class="p"><</span><span class="nt">li</span><span class="p">><</span><span class="nt">input</span> <span class="na">type</span><span class="o">=</span><span class="s">'checkbox'</span> <span class="na">name</span><span class="o">=</span><span class="s">'...'</span> <span class="p">></</span><span class="nt">li</span><span class="p">></span>
...
<span class="p"></</span><span class="nt">ul</span><span class="p">></span>
</pre></div>
</div>
<p>The outer <code class="docutils literal"><span class="pre"><ul></span></code> container will receive the <code class="docutils literal"><span class="pre">id</span></code> attribute defined on
the widget.</p>
</dd></dl>
<p>Like <a class="reference internal" href="#django.forms.RadioSelect" title="django.forms.RadioSelect"><code class="xref py py-class docutils literal"><span class="pre">RadioSelect</span></code></a>, you can now loop over the individual checkboxes making
up the lists. See the documentation of <a class="reference internal" href="#django.forms.RadioSelect" title="django.forms.RadioSelect"><code class="xref py py-class docutils literal"><span class="pre">RadioSelect</span></code></a> for more details.</p>
<div class="versionchanged">
<span class="title">Changed in Django 1.7:</span> <p>When looping over the checkboxes, the <code class="docutils literal"><span class="pre">label</span></code> and <code class="docutils literal"><span class="pre">input</span></code> tags include
<code class="docutils literal"><span class="pre">for</span></code> and <code class="docutils literal"><span class="pre">id</span></code> attributes, respectively. Each checkbox has an
<code class="docutils literal"><span class="pre">id_for_label</span></code> attribute to output the element’s ID.</p>
</div>
</div>
</div>
<div class="section" id="s-file-upload-widgets">
<span id="s-id5"></span><span id="file-upload-widgets"></span><span id="id5"></span><h3>File upload widgets<a class="headerlink" href="#file-upload-widgets" title="Permalink to this headline">¶</a></h3>
<div class="section" id="s-fileinput">
<span id="fileinput"></span><h4><code class="docutils literal"><span class="pre">FileInput</span></code><a class="headerlink" href="#fileinput" title="Permalink to this headline">¶</a></h4>
<dl class="class">
<dt id="django.forms.FileInput">
<em class="property">class </em><code class="descname">FileInput</code><a class="reference internal" href="../../_modules/django/forms/widgets.html#FileInput"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#django.forms.FileInput" title="Permalink to this definition">¶</a></dt>
<dd><p>File upload input: <code class="docutils literal"><span class="pre"><input</span> <span class="pre">type='file'</span> <span class="pre">...></span></code></p>
</dd></dl>
</div>
<div class="section" id="s-clearablefileinput">
<span id="clearablefileinput"></span><h4><code class="docutils literal"><span class="pre">ClearableFileInput</span></code><a class="headerlink" href="#clearablefileinput" title="Permalink to this headline">¶</a></h4>
<dl class="class">
<dt id="django.forms.ClearableFileInput">
<em class="property">class </em><code class="descname">ClearableFileInput</code><a class="reference internal" href="../../_modules/django/forms/widgets.html#ClearableFileInput"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#django.forms.ClearableFileInput" title="Permalink to this definition">¶</a></dt>
<dd><p>File upload input: <code class="docutils literal"><span class="pre"><input</span> <span class="pre">type='file'</span> <span class="pre">...></span></code>, with an additional checkbox
input to clear the field’s value, if the field is not required and has
initial data.</p>
</dd></dl>
</div>
</div>
<div class="section" id="s-composite-widgets">
<span id="s-id6"></span><span id="composite-widgets"></span><span id="id6"></span><h3>Composite widgets<a class="headerlink" href="#composite-widgets" title="Permalink to this headline">¶</a></h3>
<div class="section" id="s-multiplehiddeninput">
<span id="multiplehiddeninput"></span><h4><code class="docutils literal"><span class="pre">MultipleHiddenInput</span></code><a class="headerlink" href="#multiplehiddeninput" title="Permalink to this headline">¶</a></h4>
<dl class="class">
<dt id="django.forms.MultipleHiddenInput">
<em class="property">class </em><code class="descname">MultipleHiddenInput</code><a class="reference internal" href="../../_modules/django/forms/widgets.html#MultipleHiddenInput"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#django.forms.MultipleHiddenInput" title="Permalink to this definition">¶</a></dt>
<dd><p>Multiple <code class="docutils literal"><span class="pre"><input</span> <span class="pre">type='hidden'</span> <span class="pre">...></span></code> widgets.</p>
<p>A widget that handles multiple hidden widgets for fields that have a list
of values.</p>
<dl class="attribute">
<dt id="django.forms.MultipleHiddenInput.choices">
<code class="descname">choices</code><a class="headerlink" href="#django.forms.MultipleHiddenInput.choices" title="Permalink to this definition">¶</a></dt>
<dd><p>This attribute is optional when the form field does not have a
<code class="docutils literal"><span class="pre">choices</span></code> attribute. If it does, it will override anything you set
here when the attribute is updated on the <a class="reference internal" href="fields.html#django.forms.Field" title="django.forms.Field"><code class="xref py py-class docutils literal"><span class="pre">Field</span></code></a>.</p>
</dd></dl>
</dd></dl>
</div>
<div class="section" id="s-splitdatetimewidget">
<span id="splitdatetimewidget"></span><h4><code class="docutils literal"><span class="pre">SplitDateTimeWidget</span></code><a class="headerlink" href="#splitdatetimewidget" title="Permalink to this headline">¶</a></h4>
<dl class="class">
<dt id="django.forms.SplitDateTimeWidget">
<em class="property">class </em><code class="descname">SplitDateTimeWidget</code><a class="reference internal" href="../../_modules/django/forms/widgets.html#SplitDateTimeWidget"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#django.forms.SplitDateTimeWidget" title="Permalink to this definition">¶</a></dt>
<dd><p>Wrapper (using <a class="reference internal" href="#django.forms.MultiWidget" title="django.forms.MultiWidget"><code class="xref py py-class docutils literal"><span class="pre">MultiWidget</span></code></a>) around two widgets: <a class="reference internal" href="#django.forms.DateInput" title="django.forms.DateInput"><code class="xref py py-class docutils literal"><span class="pre">DateInput</span></code></a>
for the date, and <a class="reference internal" href="#django.forms.TimeInput" title="django.forms.TimeInput"><code class="xref py py-class docutils literal"><span class="pre">TimeInput</span></code></a> for the time.</p>
<p><code class="docutils literal"><span class="pre">SplitDateTimeWidget</span></code> has two optional attributes:</p>
<dl class="attribute">
<dt id="django.forms.SplitDateTimeWidget.date_format">
<code class="descname">date_format</code><a class="headerlink" href="#django.forms.SplitDateTimeWidget.date_format" title="Permalink to this definition">¶</a></dt>
<dd><p>Similar to <a class="reference internal" href="#django.forms.DateInput.format" title="django.forms.DateInput.format"><code class="xref py py-attr docutils literal"><span class="pre">DateInput.format</span></code></a></p>
</dd></dl>
<dl class="attribute">
<dt id="django.forms.SplitDateTimeWidget.time_format">
<code class="descname">time_format</code><a class="headerlink" href="#django.forms.SplitDateTimeWidget.time_format" title="Permalink to this definition">¶</a></dt>
<dd><p>Similar to <a class="reference internal" href="#django.forms.TimeInput.format" title="django.forms.TimeInput.format"><code class="xref py py-attr docutils literal"><span class="pre">TimeInput.format</span></code></a></p>
</dd></dl>
</dd></dl>
</div>
<div class="section" id="s-splithiddendatetimewidget">
<span id="splithiddendatetimewidget"></span><h4><code class="docutils literal"><span class="pre">SplitHiddenDateTimeWidget</span></code><a class="headerlink" href="#splithiddendatetimewidget" title="Permalink to this headline">¶</a></h4>
<dl class="class">
<dt id="django.forms.SplitHiddenDateTimeWidget">
<em class="property">class </em><code class="descname">SplitHiddenDateTimeWidget</code><a class="reference internal" href="../../_modules/django/forms/widgets.html#SplitHiddenDateTimeWidget"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#django.forms.SplitHiddenDateTimeWidget" title="Permalink to this definition">¶</a></dt>
<dd><p>Similar to <a class="reference internal" href="#django.forms.SplitDateTimeWidget" title="django.forms.SplitDateTimeWidget"><code class="xref py py-class docutils literal"><span class="pre">SplitDateTimeWidget</span></code></a>, but uses <a class="reference internal" href="#django.forms.HiddenInput" title="django.forms.HiddenInput"><code class="xref py py-class docutils literal"><span class="pre">HiddenInput</span></code></a> for
both date and time.</p>
</dd></dl>
</div>
<div class="section" id="s-selectdatewidget">
<span id="selectdatewidget"></span><h4><code class="docutils literal"><span class="pre">SelectDateWidget</span></code><a class="headerlink" href="#selectdatewidget" title="Permalink to this headline">¶</a></h4>
<dl class="class">
<dt id="django.forms.extras.widgets.SelectDateWidget">
<em class="property">class </em><code class="descname">SelectDateWidget</code><a class="reference internal" href="../../_modules/django/forms/extras/widgets.html#SelectDateWidget"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#django.forms.extras.widgets.SelectDateWidget" title="Permalink to this definition">¶</a></dt>
<dd><p>Wrapper around three <a class="reference internal" href="#django.forms.Select" title="django.forms.Select"><code class="xref py py-class docutils literal"><span class="pre">Select</span></code></a> widgets: one each for
month, day, and year. Note that this widget lives in a separate file from
the standard widgets.</p>
<p>Takes several optional arguments:</p>
<dl class="attribute">
<dt id="django.forms.extras.widgets.SelectDateWidget.years">
<code class="descname">years</code><a class="headerlink" href="#django.forms.extras.widgets.SelectDateWidget.years" title="Permalink to this definition">¶</a></dt>
<dd><p>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.</p>
</dd></dl>
<dl class="attribute">
<dt id="django.forms.extras.widgets.SelectDateWidget.months">
<code class="descname">months</code><a class="headerlink" href="#django.forms.extras.widgets.SelectDateWidget.months" title="Permalink to this definition">¶</a></dt>
<dd><div class="versionadded">
<span class="title">New in Django 1.7.</span> </div>
<p>An optional dict of months to use in the “months” select box.</p>
<p>The keys of the dict correspond to the month number (1-indexed) and
the values are the displayed months:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">MONTHS</span> <span class="o">=</span> <span class="p">{</span>
<span class="mi">1</span><span class="p">:</span><span class="n">_</span><span class="p">(</span><span class="s1">'jan'</span><span class="p">),</span> <span class="mi">2</span><span class="p">:</span><span class="n">_</span><span class="p">(</span><span class="s1">'feb'</span><span class="p">),</span> <span class="mi">3</span><span class="p">:</span><span class="n">_</span><span class="p">(</span><span class="s1">'mar'</span><span class="p">),</span> <span class="mi">4</span><span class="p">:</span><span class="n">_</span><span class="p">(</span><span class="s1">'apr'</span><span class="p">),</span>
<span class="mi">5</span><span class="p">:</span><span class="n">_</span><span class="p">(</span><span class="s1">'may'</span><span class="p">),</span> <span class="mi">6</span><span class="p">:</span><span class="n">_</span><span class="p">(</span><span class="s1">'jun'</span><span class="p">),</span> <span class="mi">7</span><span class="p">:</span><span class="n">_</span><span class="p">(</span><span class="s1">'jul'</span><span class="p">),</span> <span class="mi">8</span><span class="p">:</span><span class="n">_</span><span class="p">(</span><span class="s1">'aug'</span><span class="p">),</span>
<span class="mi">9</span><span class="p">:</span><span class="n">_</span><span class="p">(</span><span class="s1">'sep'</span><span class="p">),</span> <span class="mi">10</span><span class="p">:</span><span class="n">_</span><span class="p">(</span><span class="s1">'oct'</span><span class="p">),</span> <span class="mi">11</span><span class="p">:</span><span class="n">_</span><span class="p">(</span><span class="s1">'nov'</span><span class="p">),</span> <span class="mi">12</span><span class="p">:</span><span class="n">_</span><span class="p">(</span><span class="s1">'dec'</span><span class="p">)</span>
<span class="p">}</span>
</pre></div>
</div>
</dd></dl>
<dl class="attribute">
<dt id="django.forms.extras.widgets.SelectDateWidget.empty_label">
<code class="descname">empty_label</code><a class="headerlink" href="#django.forms.extras.widgets.SelectDateWidget.empty_label" title="Permalink to this definition">¶</a></dt>
<dd><div class="versionadded">
<span class="title">New in Django 1.8.</span> </div>
<p>If the <a class="reference internal" href="fields.html#django.forms.DateField" title="django.forms.DateField"><code class="xref py py-class docutils literal"><span class="pre">DateField</span></code></a> is not required,
<a class="reference internal" href="#django.forms.extras.widgets.SelectDateWidget" title="django.forms.extras.widgets.SelectDateWidget"><code class="xref py py-class docutils literal"><span class="pre">SelectDateWidget</span></code></a> will have an empty choice at the top of the
list (which is <code class="docutils literal"><span class="pre">---</span></code> by default). You can change the text of this
label with the <code class="docutils literal"><span class="pre">empty_label</span></code> attribute. <code class="docutils literal"><span class="pre">empty_label</span></code> can be a
<code class="docutils literal"><span class="pre">string</span></code>, <code class="docutils literal"><span class="pre">list</span></code>, or <code class="docutils literal"><span class="pre">tuple</span></code>. When a string is used, all select
boxes will each have an empty choice with this label. If <code class="docutils literal"><span class="pre">empty_label</span></code>
is a <code class="docutils literal"><span class="pre">list</span></code> or <code class="docutils literal"><span class="pre">tuple</span></code> of 3 string elements, the select boxes will
have their own custom label. The labels should be in this order
<code class="docutils literal"><span class="pre">('year_label',</span> <span class="pre">'month_label',</span> <span class="pre">'day_label')</span></code>.</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="c1"># A custom empty label with string</span>
<span class="n">field1</span> <span class="o">=</span> <span class="n">forms</span><span class="o">.</span><span class="n">DateField</span><span class="p">(</span><span class="n">widget</span><span class="o">=</span><span class="n">SelectDateWidget</span><span class="p">(</span><span class="n">empty_label</span><span class="o">=</span><span class="s2">"Nothing"</span><span class="p">))</span>
<span class="c1"># A custom empty label with tuple</span>
<span class="n">field1</span> <span class="o">=</span> <span class="n">forms</span><span class="o">.</span><span class="n">DateField</span><span class="p">(</span>
<span class="n">widget</span><span class="o">=</span><span class="n">SelectDateWidget</span><span class="p">(</span>
<span class="n">empty_label</span><span class="o">=</span><span class="p">(</span><span class="s2">"Choose Year"</span><span class="p">,</span> <span class="s2">"Choose Month"</span><span class="p">,</span> <span class="s2">"Choose Day"</span><span class="p">),</span>
<span class="p">),</span>
<span class="p">)</span>
</pre></div>
</div>
</dd></dl>
</dd></dl>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="yui-b" id="sidebar">
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h3><a href="../../contents.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Widgets</a><ul>
<li><a class="reference internal" href="#specifying-widgets">Specifying widgets</a></li>
<li><a class="reference internal" href="#setting-arguments-for-widgets">Setting arguments for widgets</a></li>
<li><a class="reference internal" href="#widgets-inheriting-from-the-select-widget">Widgets inheriting from the Select widget</a></li>
<li><a class="reference internal" href="#customizing-widget-instances">Customizing widget instances</a><ul>
<li><a class="reference internal" href="#styling-widget-instances">Styling widget instances</a></li>
<li><a class="reference internal" href="#styling-widget-classes">Styling widget classes</a></li>
</ul>
</li>
<li><a class="reference internal" href="#base-widget-classes">Base Widget classes</a></li>
<li><a class="reference internal" href="#built-in-widgets">Built-in widgets</a><ul>
<li><a class="reference internal" href="#widgets-handling-input-of-text">Widgets handling input of text</a><ul>
<li><a class="reference internal" href="#textinput"><code class="docutils literal"><span class="pre">TextInput</span></code></a></li>
<li><a class="reference internal" href="#numberinput"><code class="docutils literal"><span class="pre">NumberInput</span></code></a></li>
<li><a class="reference internal" href="#emailinput"><code class="docutils literal"><span class="pre">EmailInput</span></code></a></li>
<li><a class="reference internal" href="#urlinput"><code class="docutils literal"><span class="pre">URLInput</span></code></a></li>
<li><a class="reference internal" href="#passwordinput"><code class="docutils literal"><span class="pre">PasswordInput</span></code></a></li>
<li><a class="reference internal" href="#hiddeninput"><code class="docutils literal"><span class="pre">HiddenInput</span></code></a></li>
<li><a class="reference internal" href="#dateinput"><code class="docutils literal"><span class="pre">DateInput</span></code></a></li>
<li><a class="reference internal" href="#datetimeinput"><code class="docutils literal"><span class="pre">DateTimeInput</span></code></a></li>
<li><a class="reference internal" href="#timeinput"><code class="docutils literal"><span class="pre">TimeInput</span></code></a></li>
<li><a class="reference internal" href="#textarea"><code class="docutils literal"><span class="pre">Textarea</span></code></a></li>
</ul>
</li>
<li><a class="reference internal" href="#selector-and-checkbox-widgets">Selector and checkbox widgets</a><ul>
<li><a class="reference internal" href="#checkboxinput"><code class="docutils literal"><span class="pre">CheckboxInput</span></code></a></li>
<li><a class="reference internal" href="#select"><code class="docutils literal"><span class="pre">Select</span></code></a></li>
<li><a class="reference internal" href="#nullbooleanselect"><code class="docutils literal"><span class="pre">NullBooleanSelect</span></code></a></li>
<li><a class="reference internal" href="#selectmultiple"><code class="docutils literal"><span class="pre">SelectMultiple</span></code></a></li>
<li><a class="reference internal" href="#radioselect"><code class="docutils literal"><span class="pre">RadioSelect</span></code></a></li>
<li><a class="reference internal" href="#checkboxselectmultiple"><code class="docutils literal"><span class="pre">CheckboxSelectMultiple</span></code></a></li>
</ul>
</li>
<li><a class="reference internal" href="#file-upload-widgets">File upload widgets</a><ul>
<li><a class="reference internal" href="#fileinput"><code class="docutils literal"><span class="pre">FileInput</span></code></a></li>
<li><a class="reference internal" href="#clearablefileinput"><code class="docutils literal"><span class="pre">ClearableFileInput</span></code></a></li>
</ul>
</li>
<li><a class="reference internal" href="#composite-widgets">Composite widgets</a><ul>
<li><a class="reference internal" href="#multiplehiddeninput"><code class="docutils literal"><span class="pre">MultipleHiddenInput</span></code></a></li>
<li><a class="reference internal" href="#splitdatetimewidget"><code class="docutils literal"><span class="pre">SplitDateTimeWidget</span></code></a></li>
<li><a class="reference internal" href="#splithiddendatetimewidget"><code class="docutils literal"><span class="pre">SplitHiddenDateTimeWidget</span></code></a></li>
<li><a class="reference internal" href="#selectdatewidget"><code class="docutils literal"><span class="pre">SelectDateWidget</span></code></a></li>
</ul>
</li>
</ul>
</li>
</ul>
</li>
</ul>
<h3>Browse</h3>
<ul>
<li>Prev: <a href="formsets.html">Formset Functions</a></li>
<li>Next: <a href="validation.html">Form and field validation</a></li>
</ul>
<h3>You are here:</h3>
<ul>
<li>
<a href="../../index.html">Django 1.8.19 documentation</a>
<ul><li><a href="../index.html">API Reference</a>
<ul><li><a href="index.html">Forms</a>
<ul><li>Widgets</li></ul>
</li></ul></li></ul>
</li>
</ul>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../../_sources/ref/forms/widgets.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<form class="search" action="../../search.html" method="get">
<div><input type="text" name="q" /></div>
<div><input type="submit" value="Go" /></div>
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<h3>Last update:</h3>
<p class="topless">Mar 10, 2018</p>
</div>
</div>
<div id="ft">
<div class="nav">
« <a href="formsets.html" title="Formset Functions">previous</a>
|
<a href="../index.html" title="API Reference" accesskey="U">up</a>
|
<a href="validation.html" title="Form and field validation">next</a> »</div>
</div>
</div>
<div class="clearer"></div>
</div>
</body>
</html>
