<!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">Jan 06, 2019</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>