<!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="X-UA-Compatible" content="IE=Edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>The Forms API — Django 1.11.20 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" id="documentation_options" data-url_root="../../" src="../../_static/documentation_options.js"></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>
<script type="text/javascript" src="../../_static/language_data.js"></script>
<link rel="index" title="Index" href="../../genindex.html" />
<link rel="search" title="Search" href="../../search.html" />
<link rel="next" title="Form fields" href="fields.html" />
<link rel="prev" title="Forms" href="index.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>
<div class="document">
<div id="custom-doc" class="yui-t6">
<div id="hd">
<h1><a href="../../index.html">Django 1.11.20 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="index.html" title="Forms">previous</a>
|
<a href="../index.html" title="API Reference" accesskey="U">up</a>
|
<a href="fields.html" title="Form fields">next</a> »</div>
</div>
<div id="bd">
<div id="yui-main">
<div class="yui-b">
<div class="yui-g" id="ref-forms-api">
<div class="section" id="s-module-django.forms">
<span id="s-the-forms-api"></span><span id="module-django.forms"></span><span id="the-forms-api"></span><h1>The Forms API<a class="headerlink" href="#module-django.forms" title="Permalink to this headline">¶</a></h1>
<div class="admonition-about-this-document admonition">
<p class="first admonition-title">About this document</p>
<p class="last">This document covers the gritty details of Django’s forms API. You should
read the <a class="reference internal" href="../../topics/forms/index.html"><span class="doc">introduction to working with forms</span></a>
first.</p>
</div>
<div class="section" id="s-bound-and-unbound-forms">
<span id="s-ref-forms-api-bound-unbound"></span><span id="bound-and-unbound-forms"></span><span id="ref-forms-api-bound-unbound"></span><h2>Bound and unbound forms<a class="headerlink" href="#bound-and-unbound-forms" title="Permalink to this headline">¶</a></h2>
<p>A <a class="reference internal" href="#django.forms.Form" title="django.forms.Form"><code class="xref py py-class docutils literal notranslate"><span class="pre">Form</span></code></a> instance is either <strong>bound</strong> to a set of data, or <strong>unbound</strong>.</p>
<ul class="simple">
<li>If it’s <strong>bound</strong> to a set of data, it’s capable of validating that data
and rendering the form as HTML with the data displayed in the HTML.</li>
<li>If it’s <strong>unbound</strong>, it cannot do validation (because there’s no data to
validate!), but it can still render the blank form as HTML.</li>
</ul>
<dl class="class">
<dt id="django.forms.Form">
<em class="property">class </em><code class="descname">Form</code><a class="reference internal" href="../../_modules/django/forms/forms.html#Form"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#django.forms.Form" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<p>To create an unbound <a class="reference internal" href="#django.forms.Form" title="django.forms.Form"><code class="xref py py-class docutils literal notranslate"><span class="pre">Form</span></code></a> instance, simply instantiate the class:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">f</span> <span class="o">=</span> <span class="n">ContactForm</span><span class="p">()</span>
</pre></div>
</div>
<p>To bind data to a form, pass the data as a dictionary as the first parameter to
your <a class="reference internal" href="#django.forms.Form" title="django.forms.Form"><code class="xref py py-class docutils literal notranslate"><span class="pre">Form</span></code></a> class constructor:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">data</span> <span class="o">=</span> <span class="p">{</span><span class="s1">'subject'</span><span class="p">:</span> <span class="s1">'hello'</span><span class="p">,</span>
<span class="gp">... </span> <span class="s1">'message'</span><span class="p">:</span> <span class="s1">'Hi there'</span><span class="p">,</span>
<span class="gp">... </span> <span class="s1">'sender'</span><span class="p">:</span> <span class="s1">'foo@example.com'</span><span class="p">,</span>
<span class="gp">... </span> <span class="s1">'cc_myself'</span><span class="p">:</span> <span class="kc">True</span><span class="p">}</span>
<span class="gp">>>> </span><span class="n">f</span> <span class="o">=</span> <span class="n">ContactForm</span><span class="p">(</span><span class="n">data</span><span class="p">)</span>
</pre></div>
</div>
<p>In this dictionary, the keys are the field names, which correspond to the
attributes in your <a class="reference internal" href="#django.forms.Form" title="django.forms.Form"><code class="xref py py-class docutils literal notranslate"><span class="pre">Form</span></code></a> class. The values are the data you’re trying to
validate. These will usually be strings, but there’s no requirement that they be
strings; the type of data you pass depends on the <a class="reference internal" href="fields.html#django.forms.Field" title="django.forms.Field"><code class="xref py py-class docutils literal notranslate"><span class="pre">Field</span></code></a>, as we’ll see
in a moment.</p>
<dl class="attribute">
<dt id="django.forms.Form.is_bound">
<code class="descclassname">Form.</code><code class="descname">is_bound</code><a class="headerlink" href="#django.forms.Form.is_bound" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<p>If you need to distinguish between bound and unbound form instances at runtime,
check the value of the form’s <a class="reference internal" href="#django.forms.Form.is_bound" title="django.forms.Form.is_bound"><code class="xref py py-attr docutils literal notranslate"><span class="pre">is_bound</span></code></a> attribute:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">f</span> <span class="o">=</span> <span class="n">ContactForm</span><span class="p">()</span>
<span class="gp">>>> </span><span class="n">f</span><span class="o">.</span><span class="n">is_bound</span>
<span class="go">False</span>
<span class="gp">>>> </span><span class="n">f</span> <span class="o">=</span> <span class="n">ContactForm</span><span class="p">({</span><span class="s1">'subject'</span><span class="p">:</span> <span class="s1">'hello'</span><span class="p">})</span>
<span class="gp">>>> </span><span class="n">f</span><span class="o">.</span><span class="n">is_bound</span>
<span class="go">True</span>
</pre></div>
</div>
<p>Note that passing an empty dictionary creates a <em>bound</em> form with empty data:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">f</span> <span class="o">=</span> <span class="n">ContactForm</span><span class="p">({})</span>
<span class="gp">>>> </span><span class="n">f</span><span class="o">.</span><span class="n">is_bound</span>
<span class="go">True</span>
</pre></div>
</div>
<p>If you have a bound <a class="reference internal" href="#django.forms.Form" title="django.forms.Form"><code class="xref py py-class docutils literal notranslate"><span class="pre">Form</span></code></a> instance and want to change the data somehow,
or if you want to bind an unbound <a class="reference internal" href="#django.forms.Form" title="django.forms.Form"><code class="xref py py-class docutils literal notranslate"><span class="pre">Form</span></code></a> instance to some data, create
another <a class="reference internal" href="#django.forms.Form" title="django.forms.Form"><code class="xref py py-class docutils literal notranslate"><span class="pre">Form</span></code></a> instance. There is no way to change data in a
<a class="reference internal" href="#django.forms.Form" title="django.forms.Form"><code class="xref py py-class docutils literal notranslate"><span class="pre">Form</span></code></a> instance. Once a <a class="reference internal" href="#django.forms.Form" title="django.forms.Form"><code class="xref py py-class docutils literal notranslate"><span class="pre">Form</span></code></a> instance has been created, you
should consider its data immutable, whether it has data or not.</p>
</div>
<div class="section" id="s-using-forms-to-validate-data">
<span id="using-forms-to-validate-data"></span><h2>Using forms to validate data<a class="headerlink" href="#using-forms-to-validate-data" title="Permalink to this headline">¶</a></h2>
<dl class="method">
<dt id="django.forms.Form.clean">
<code class="descclassname">Form.</code><code class="descname">clean</code>()<a class="headerlink" href="#django.forms.Form.clean" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<p>Implement a <code class="docutils literal notranslate"><span class="pre">clean()</span></code> method on your <code class="docutils literal notranslate"><span class="pre">Form</span></code> when you must add custom
validation for fields that are interdependent. See
<a class="reference internal" href="validation.html#validating-fields-with-clean"><span class="std std-ref">Cleaning and validating fields that depend on each other</span></a> for example usage.</p>
<dl class="method">
<dt id="django.forms.Form.is_valid">
<code class="descclassname">Form.</code><code class="descname">is_valid</code>()<a class="headerlink" href="#django.forms.Form.is_valid" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<p>The primary task of a <a class="reference internal" href="#django.forms.Form" title="django.forms.Form"><code class="xref py py-class docutils literal notranslate"><span class="pre">Form</span></code></a> object is to validate data. With a bound
<a class="reference internal" href="#django.forms.Form" title="django.forms.Form"><code class="xref py py-class docutils literal notranslate"><span class="pre">Form</span></code></a> instance, call the <a class="reference internal" href="#django.forms.Form.is_valid" title="django.forms.Form.is_valid"><code class="xref py py-meth docutils literal notranslate"><span class="pre">is_valid()</span></code></a> method to run validation
and return a boolean designating whether the data was valid:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">data</span> <span class="o">=</span> <span class="p">{</span><span class="s1">'subject'</span><span class="p">:</span> <span class="s1">'hello'</span><span class="p">,</span>
<span class="gp">... </span> <span class="s1">'message'</span><span class="p">:</span> <span class="s1">'Hi there'</span><span class="p">,</span>
<span class="gp">... </span> <span class="s1">'sender'</span><span class="p">:</span> <span class="s1">'foo@example.com'</span><span class="p">,</span>
<span class="gp">... </span> <span class="s1">'cc_myself'</span><span class="p">:</span> <span class="kc">True</span><span class="p">}</span>
<span class="gp">>>> </span><span class="n">f</span> <span class="o">=</span> <span class="n">ContactForm</span><span class="p">(</span><span class="n">data</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">f</span><span class="o">.</span><span class="n">is_valid</span><span class="p">()</span>
<span class="go">True</span>
</pre></div>
</div>
<p>Let’s try with some invalid data. In this case, <code class="docutils literal notranslate"><span class="pre">subject</span></code> is blank (an error,
because all fields are required by default) and <code class="docutils literal notranslate"><span class="pre">sender</span></code> is not a valid
email address:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">data</span> <span class="o">=</span> <span class="p">{</span><span class="s1">'subject'</span><span class="p">:</span> <span class="s1">''</span><span class="p">,</span>
<span class="gp">... </span> <span class="s1">'message'</span><span class="p">:</span> <span class="s1">'Hi there'</span><span class="p">,</span>
<span class="gp">... </span> <span class="s1">'sender'</span><span class="p">:</span> <span class="s1">'invalid email address'</span><span class="p">,</span>
<span class="gp">... </span> <span class="s1">'cc_myself'</span><span class="p">:</span> <span class="kc">True</span><span class="p">}</span>
<span class="gp">>>> </span><span class="n">f</span> <span class="o">=</span> <span class="n">ContactForm</span><span class="p">(</span><span class="n">data</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">f</span><span class="o">.</span><span class="n">is_valid</span><span class="p">()</span>
<span class="go">False</span>
</pre></div>
</div>
<dl class="attribute">
<dt id="django.forms.Form.errors">
<code class="descclassname">Form.</code><code class="descname">errors</code><a class="headerlink" href="#django.forms.Form.errors" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<p>Access the <a class="reference internal" href="#django.forms.Form.errors" title="django.forms.Form.errors"><code class="xref py py-attr docutils literal notranslate"><span class="pre">errors</span></code></a> attribute to get a dictionary of error
messages:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">f</span><span class="o">.</span><span class="n">errors</span>
<span class="go">{'sender': ['Enter a valid email address.'], 'subject': ['This field is required.']}</span>
</pre></div>
</div>
<p>In this dictionary, the keys are the field names, and the values are lists of
Unicode strings representing the error messages. The error messages are stored
in lists because a field can have multiple error messages.</p>
<p>You can access <a class="reference internal" href="#django.forms.Form.errors" title="django.forms.Form.errors"><code class="xref py py-attr docutils literal notranslate"><span class="pre">errors</span></code></a> without having to call
<a class="reference internal" href="#django.forms.Form.is_valid" title="django.forms.Form.is_valid"><code class="xref py py-meth docutils literal notranslate"><span class="pre">is_valid()</span></code></a> first. The form’s data will be validated the first time
either you call <a class="reference internal" href="#django.forms.Form.is_valid" title="django.forms.Form.is_valid"><code class="xref py py-meth docutils literal notranslate"><span class="pre">is_valid()</span></code></a> or access <a class="reference internal" href="#django.forms.Form.errors" title="django.forms.Form.errors"><code class="xref py py-attr docutils literal notranslate"><span class="pre">errors</span></code></a>.</p>
<p>The validation routines will only get called once, regardless of how many times
you access <a class="reference internal" href="#django.forms.Form.errors" title="django.forms.Form.errors"><code class="xref py py-attr docutils literal notranslate"><span class="pre">errors</span></code></a> or call <a class="reference internal" href="#django.forms.Form.is_valid" title="django.forms.Form.is_valid"><code class="xref py py-meth docutils literal notranslate"><span class="pre">is_valid()</span></code></a>. This means that
if validation has side effects, those side effects will only be triggered once.</p>
<dl class="method">
<dt id="django.forms.Form.errors.as_data">
<code class="descclassname">Form.errors.</code><code class="descname">as_data</code>()<a class="headerlink" href="#django.forms.Form.errors.as_data" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<p>Returns a <code class="docutils literal notranslate"><span class="pre">dict</span></code> that maps fields to their original <code class="docutils literal notranslate"><span class="pre">ValidationError</span></code>
instances.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">f</span><span class="o">.</span><span class="n">errors</span><span class="o">.</span><span class="n">as_data</span><span class="p">()</span>
<span class="go">{'sender': [ValidationError(['Enter a valid email address.'])],</span>
<span class="go">'subject': [ValidationError(['This field is required.'])]}</span>
</pre></div>
</div>
<p>Use this method anytime you need to identify an error by its <code class="docutils literal notranslate"><span class="pre">code</span></code>. This
enables things like rewriting the error’s message or writing custom logic in a
view when a given error is present. It can also be used to serialize the errors
in a custom format (e.g. XML); for instance, <a class="reference internal" href="#django.forms.Form.errors.as_json" title="django.forms.Form.errors.as_json"><code class="xref py py-meth docutils literal notranslate"><span class="pre">as_json()</span></code></a>
relies on <code class="docutils literal notranslate"><span class="pre">as_data()</span></code>.</p>
<p>The need for the <code class="docutils literal notranslate"><span class="pre">as_data()</span></code> method is due to backwards compatibility.
Previously <code class="docutils literal notranslate"><span class="pre">ValidationError</span></code> instances were lost as soon as their
<strong>rendered</strong> error messages were added to the <code class="docutils literal notranslate"><span class="pre">Form.errors</span></code> dictionary.
Ideally <code class="docutils literal notranslate"><span class="pre">Form.errors</span></code> would have stored <code class="docutils literal notranslate"><span class="pre">ValidationError</span></code> instances
and methods with an <code class="docutils literal notranslate"><span class="pre">as_</span></code> prefix could render them, but it had to be done
the other way around in order not to break code that expects rendered error
messages in <code class="docutils literal notranslate"><span class="pre">Form.errors</span></code>.</p>
<dl class="method">
<dt id="django.forms.Form.errors.as_json">
<code class="descclassname">Form.errors.</code><code class="descname">as_json</code>(<em>escape_html=False</em>)<a class="headerlink" href="#django.forms.Form.errors.as_json" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<p>Returns the errors serialized as JSON.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">f</span><span class="o">.</span><span class="n">errors</span><span class="o">.</span><span class="n">as_json</span><span class="p">()</span>
<span class="go">{"sender": [{"message": "Enter a valid email address.", "code": "invalid"}],</span>
<span class="go">"subject": [{"message": "This field is required.", "code": "required"}]}</span>
</pre></div>
</div>
<p>By default, <code class="docutils literal notranslate"><span class="pre">as_json()</span></code> does not escape its output. If you are using it for
something like AJAX requests to a form view where the client interprets the
response and inserts errors into the page, you’ll want to be sure to escape the
results on the client-side to avoid the possibility of a cross-site scripting
attack. It’s trivial to do so using a JavaScript library like jQuery - simply
use <code class="docutils literal notranslate"><span class="pre">$(el).text(errorText)</span></code> rather than <code class="docutils literal notranslate"><span class="pre">.html()</span></code>.</p>
<p>If for some reason you don’t want to use client-side escaping, you can also
set <code class="docutils literal notranslate"><span class="pre">escape_html=True</span></code> and error messages will be escaped so you can use them
directly in HTML.</p>
<dl class="method">
<dt id="django.forms.Form.add_error">
<code class="descclassname">Form.</code><code class="descname">add_error</code>(<em>field</em>, <em>error</em>)<a class="headerlink" href="#django.forms.Form.add_error" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<p>This method allows adding errors to specific fields from within the
<code class="docutils literal notranslate"><span class="pre">Form.clean()</span></code> method, or from outside the form altogether; for instance
from a view.</p>
<p>The <code class="docutils literal notranslate"><span class="pre">field</span></code> argument is the name of the field to which the errors
should be added. If its value is <code class="docutils literal notranslate"><span class="pre">None</span></code> the error will be treated as
a non-field error as returned by <a class="reference internal" href="#django.forms.Form.non_field_errors" title="django.forms.Form.non_field_errors"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Form.non_field_errors()</span></code></a>.</p>
<p>The <code class="docutils literal notranslate"><span class="pre">error</span></code> argument can be a simple string, or preferably an instance of
<code class="docutils literal notranslate"><span class="pre">ValidationError</span></code>. See <a class="reference internal" href="validation.html#raising-validation-error"><span class="std std-ref">Raising ValidationError</span></a> for best practices
when defining form errors.</p>
<p>Note that <code class="docutils literal notranslate"><span class="pre">Form.add_error()</span></code> automatically removes the relevant field from
<code class="docutils literal notranslate"><span class="pre">cleaned_data</span></code>.</p>
<dl class="method">
<dt id="django.forms.Form.has_error">
<code class="descclassname">Form.</code><code class="descname">has_error</code>(<em>field</em>, <em>code=None</em>)<a class="headerlink" href="#django.forms.Form.has_error" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<p>This method returns a boolean designating whether a field has an error with
a specific error <code class="docutils literal notranslate"><span class="pre">code</span></code>. If <code class="docutils literal notranslate"><span class="pre">code</span></code> is <code class="docutils literal notranslate"><span class="pre">None</span></code>, it will return <code class="docutils literal notranslate"><span class="pre">True</span></code>
if the field contains any errors at all.</p>
<p>To check for non-field errors use
<a class="reference internal" href="../exceptions.html#django.core.exceptions.NON_FIELD_ERRORS" title="django.core.exceptions.NON_FIELD_ERRORS"><code class="xref py py-data docutils literal notranslate"><span class="pre">NON_FIELD_ERRORS</span></code></a> as the <code class="docutils literal notranslate"><span class="pre">field</span></code> parameter.</p>
<dl class="method">
<dt id="django.forms.Form.non_field_errors">
<code class="descclassname">Form.</code><code class="descname">non_field_errors</code>()<a class="headerlink" href="#django.forms.Form.non_field_errors" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<p>This method returns the list of errors from <a class="reference internal" href="#django.forms.Form.errors" title="django.forms.Form.errors"><code class="xref py py-attr docutils literal notranslate"><span class="pre">Form.errors</span></code></a> that aren’t associated with a particular field.
This includes <code class="docutils literal notranslate"><span class="pre">ValidationError</span></code>s that are raised in <a class="reference internal" href="#django.forms.Form.clean" title="django.forms.Form.clean"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Form.clean()</span></code></a> and errors added using <a class="reference internal" href="#django.forms.Form.add_error" title="django.forms.Form.add_error"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Form.add_error(None,</span>
<span class="pre">"...")</span></code></a>.</p>
<div class="section" id="s-behavior-of-unbound-forms">
<span id="behavior-of-unbound-forms"></span><h3>Behavior of unbound forms<a class="headerlink" href="#behavior-of-unbound-forms" title="Permalink to this headline">¶</a></h3>
<p>It’s meaningless to validate a form with no data, but, for the record, here’s
what happens with unbound forms:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">f</span> <span class="o">=</span> <span class="n">ContactForm</span><span class="p">()</span>
<span class="gp">>>> </span><span class="n">f</span><span class="o">.</span><span class="n">is_valid</span><span class="p">()</span>
<span class="go">False</span>
<span class="gp">>>> </span><span class="n">f</span><span class="o">.</span><span class="n">errors</span>
<span class="go">{}</span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="s-dynamic-initial-values">
<span id="dynamic-initial-values"></span><h2>Dynamic initial values<a class="headerlink" href="#dynamic-initial-values" title="Permalink to this headline">¶</a></h2>
<dl class="attribute">
<dt id="django.forms.Form.initial">
<code class="descclassname">Form.</code><code class="descname">initial</code><a class="headerlink" href="#django.forms.Form.initial" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<p>Use <a class="reference internal" href="#django.forms.Form.initial" title="django.forms.Form.initial"><code class="xref py py-attr docutils literal notranslate"><span class="pre">initial</span></code></a> to declare the initial value of form fields at
runtime. For example, you might want to fill in a <code class="docutils literal notranslate"><span class="pre">username</span></code> field with the
username of the current session.</p>
<p>To accomplish this, use the <a class="reference internal" href="#django.forms.Form.initial" title="django.forms.Form.initial"><code class="xref py py-attr docutils literal notranslate"><span class="pre">initial</span></code></a> argument to a <a class="reference internal" href="#django.forms.Form" title="django.forms.Form"><code class="xref py py-class docutils literal notranslate"><span class="pre">Form</span></code></a>.
This argument, if given, should be a dictionary mapping field names to initial
values. Only include the fields for which you’re specifying an initial value;
it’s not necessary to include every field in your form. For example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">f</span> <span class="o">=</span> <span class="n">ContactForm</span><span class="p">(</span><span class="n">initial</span><span class="o">=</span><span class="p">{</span><span class="s1">'subject'</span><span class="p">:</span> <span class="s1">'Hi there!'</span><span class="p">})</span>
</pre></div>
</div>
<p>These values are only displayed for unbound forms, and they’re not used as
fallback values if a particular value isn’t provided.</p>
<p>If a <a class="reference internal" href="fields.html#django.forms.Field" title="django.forms.Field"><code class="xref py py-class docutils literal notranslate"><span class="pre">Field</span></code></a> defines <a class="reference internal" href="fields.html#django.forms.Field.initial" title="django.forms.Field.initial"><code class="xref py py-attr docutils literal notranslate"><span class="pre">initial</span></code></a> <em>and</em> you
include <a class="reference internal" href="#django.forms.Form.initial" title="django.forms.Form.initial"><code class="xref py py-attr docutils literal notranslate"><span class="pre">initial</span></code></a> when instantiating the <code class="docutils literal notranslate"><span class="pre">Form</span></code>, then the latter
<code class="docutils literal notranslate"><span class="pre">initial</span></code> will have precedence. In this example, <code class="docutils literal notranslate"><span class="pre">initial</span></code> is provided both
at the field level and at the form instance level, and the latter gets
precedence:</p>
<div class="highlight-default notranslate"><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="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="gp">... </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">initial</span><span class="o">=</span><span class="s1">'class'</span><span class="p">)</span>
<span class="gp">... </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="gp">... </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="gp">>>> </span><span class="n">f</span> <span class="o">=</span> <span class="n">CommentForm</span><span class="p">(</span><span class="n">initial</span><span class="o">=</span><span class="p">{</span><span class="s1">'name'</span><span class="p">:</span> <span class="s1">'instance'</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="nb">print</span><span class="p">(</span><span class="n">f</span><span class="p">)</span>
<span class="go"><tr><th>Name:</th><td><input type="text" name="name" value="instance" required /></td></tr></span>
<span class="go"><tr><th>Url:</th><td><input type="url" name="url" required /></td></tr></span>
<span class="go"><tr><th>Comment:</th><td><input type="text" name="comment" required /></td></tr></span>
</pre></div>
</div>
<dl class="method">
<dt id="django.forms.Form.get_initial_for_field">
<code class="descclassname">Form.</code><code class="descname">get_initial_for_field</code>(<em>field</em>, <em>field_name</em>)<a class="headerlink" href="#django.forms.Form.get_initial_for_field" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<div class="versionadded">
<span class="title">New in Django 1.11.</span> </div>
<p>Use <a class="reference internal" href="#django.forms.Form.get_initial_for_field" title="django.forms.Form.get_initial_for_field"><code class="xref py py-meth docutils literal notranslate"><span class="pre">get_initial_for_field()</span></code></a> to retrieve initial data for a form
field. It retrieves data from <a class="reference internal" href="#django.forms.Form.initial" title="django.forms.Form.initial"><code class="xref py py-attr docutils literal notranslate"><span class="pre">Form.initial</span></code></a> and <a class="reference internal" href="fields.html#django.forms.Field.initial" title="django.forms.Field.initial"><code class="xref py py-attr docutils literal notranslate"><span class="pre">Field.initial</span></code></a>,
in that order, and evaluates any callable initial values.</p>
</div>
<div class="section" id="s-checking-which-form-data-has-changed">
<span id="checking-which-form-data-has-changed"></span><h2>Checking which form data has changed<a class="headerlink" href="#checking-which-form-data-has-changed" title="Permalink to this headline">¶</a></h2>
<dl class="method">
<dt id="django.forms.Form.has_changed">
<code class="descclassname">Form.</code><code class="descname">has_changed</code>()<a class="headerlink" href="#django.forms.Form.has_changed" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<p>Use the <code class="docutils literal notranslate"><span class="pre">has_changed()</span></code> method on your <code class="docutils literal notranslate"><span class="pre">Form</span></code> when you need to check if the
form data has been changed from the initial data.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">data</span> <span class="o">=</span> <span class="p">{</span><span class="s1">'subject'</span><span class="p">:</span> <span class="s1">'hello'</span><span class="p">,</span>
<span class="gp">... </span> <span class="s1">'message'</span><span class="p">:</span> <span class="s1">'Hi there'</span><span class="p">,</span>
<span class="gp">... </span> <span class="s1">'sender'</span><span class="p">:</span> <span class="s1">'foo@example.com'</span><span class="p">,</span>
<span class="gp">... </span> <span class="s1">'cc_myself'</span><span class="p">:</span> <span class="kc">True</span><span class="p">}</span>
<span class="gp">>>> </span><span class="n">f</span> <span class="o">=</span> <span class="n">ContactForm</span><span class="p">(</span><span class="n">data</span><span class="p">,</span> <span class="n">initial</span><span class="o">=</span><span class="n">data</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">f</span><span class="o">.</span><span class="n">has_changed</span><span class="p">()</span>
<span class="go">False</span>
</pre></div>
</div>
<p>When the form is submitted, we reconstruct it and provide the original data
so that the comparison can be done:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">f</span> <span class="o">=</span> <span class="n">ContactForm</span><span class="p">(</span><span class="n">request</span><span class="o">.</span><span class="n">POST</span><span class="p">,</span> <span class="n">initial</span><span class="o">=</span><span class="n">data</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">f</span><span class="o">.</span><span class="n">has_changed</span><span class="p">()</span>
</pre></div>
</div>
<p><code class="docutils literal notranslate"><span class="pre">has_changed()</span></code> will be <code class="docutils literal notranslate"><span class="pre">True</span></code> if the data from <code class="docutils literal notranslate"><span class="pre">request.POST</span></code> differs
from what was provided in <a class="reference internal" href="#django.forms.Form.initial" title="django.forms.Form.initial"><code class="xref py py-attr docutils literal notranslate"><span class="pre">initial</span></code></a> or <code class="docutils literal notranslate"><span class="pre">False</span></code> otherwise. The
result is computed by calling <a class="reference internal" href="fields.html#django.forms.Field.has_changed" title="django.forms.Field.has_changed"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Field.has_changed()</span></code></a> for each field in the
form.</p>
<dl class="attribute">
<dt id="django.forms.Form.changed_data">
<code class="descclassname">Form.</code><code class="descname">changed_data</code><a class="headerlink" href="#django.forms.Form.changed_data" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<p>The <code class="docutils literal notranslate"><span class="pre">changed_data</span></code> attribute returns a list of the names of the fields whose
values in the form’s bound data (usually <code class="docutils literal notranslate"><span class="pre">request.POST</span></code>) differ from what was
provided in <a class="reference internal" href="#django.forms.Form.initial" title="django.forms.Form.initial"><code class="xref py py-attr docutils literal notranslate"><span class="pre">initial</span></code></a>. It returns an empty list if no data differs.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">f</span> <span class="o">=</span> <span class="n">ContactForm</span><span class="p">(</span><span class="n">request</span><span class="o">.</span><span class="n">POST</span><span class="p">,</span> <span class="n">initial</span><span class="o">=</span><span class="n">data</span><span class="p">)</span>
<span class="gp">>>> </span><span class="k">if</span> <span class="n">f</span><span class="o">.</span><span class="n">has_changed</span><span class="p">():</span>
<span class="gp">... </span> <span class="nb">print</span><span class="p">(</span><span class="s2">"The following fields changed: </span><span class="si">%s</span><span class="s2">"</span> <span class="o">%</span> <span class="s2">", "</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">f</span><span class="o">.</span><span class="n">changed_data</span><span class="p">))</span>
</pre></div>
</div>
</div>
<div class="section" id="s-accessing-the-fields-from-the-form">
<span id="accessing-the-fields-from-the-form"></span><h2>Accessing the fields from the form<a class="headerlink" href="#accessing-the-fields-from-the-form" title="Permalink to this headline">¶</a></h2>
<dl class="attribute">
<dt id="django.forms.Form.fields">
<code class="descclassname">Form.</code><code class="descname">fields</code><a class="headerlink" href="#django.forms.Form.fields" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<p>You can access the fields of <a class="reference internal" href="#django.forms.Form" title="django.forms.Form"><code class="xref py py-class docutils literal notranslate"><span class="pre">Form</span></code></a> instance from its <code class="docutils literal notranslate"><span class="pre">fields</span></code>
attribute:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="k">for</span> <span class="n">row</span> <span class="ow">in</span> <span class="n">f</span><span class="o">.</span><span class="n">fields</span><span class="o">.</span><span class="n">values</span><span class="p">():</span> <span class="nb">print</span><span class="p">(</span><span class="n">row</span><span class="p">)</span>
<span class="gp">...</span>
<span class="go"><django.forms.fields.CharField object at 0x7ffaac632510></span>
<span class="go"><django.forms.fields.URLField object at 0x7ffaac632f90></span>
<span class="go"><django.forms.fields.CharField object at 0x7ffaac3aa050></span>
<span class="gp">>>> </span><span class="n">f</span><span class="o">.</span><span class="n">fields</span><span class="p">[</span><span class="s1">'name'</span><span class="p">]</span>
<span class="go"><django.forms.fields.CharField object at 0x7ffaac6324d0></span>
</pre></div>
</div>
<p>You can alter the field of <a class="reference internal" href="#django.forms.Form" title="django.forms.Form"><code class="xref py py-class docutils literal notranslate"><span class="pre">Form</span></code></a> instance to change the way it is
presented in the form:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></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="o">.</span><span class="n">split</span><span class="p">(</span><span class="s1">'</span><span class="se">\n</span><span class="s1">'</span><span class="p">)[</span><span class="mi">0</span><span class="p">]</span>
<span class="go">'<tr><th>Name:</th><td><input name="name" type="text" value="instance" required /></td></tr>'</span>
<span class="gp">>>> </span><span class="n">f</span><span class="o">.</span><span class="n">fields</span><span class="p">[</span><span class="s1">'name'</span><span class="p">]</span><span class="o">.</span><span class="n">label</span> <span class="o">=</span> <span class="s2">"Username"</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="o">.</span><span class="n">split</span><span class="p">(</span><span class="s1">'</span><span class="se">\n</span><span class="s1">'</span><span class="p">)[</span><span class="mi">0</span><span class="p">]</span>
<span class="go">'<tr><th>Username:</th><td><input name="name" type="text" value="instance" required /></td></tr>'</span>
</pre></div>
</div>
<p>Beware not to alter the <code class="docutils literal notranslate"><span class="pre">base_fields</span></code> attribute because this modification
will influence all subsequent <code class="docutils literal notranslate"><span class="pre">ContactForm</span></code> instances within the same Python
process:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">f</span><span class="o">.</span><span class="n">base_fields</span><span class="p">[</span><span class="s1">'name'</span><span class="p">]</span><span class="o">.</span><span class="n">label</span> <span class="o">=</span> <span class="s2">"Username"</span>
<span class="gp">>>> </span><span class="n">another_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">another_f</span><span class="o">.</span><span class="n">as_table</span><span class="p">()</span><span class="o">.</span><span class="n">split</span><span class="p">(</span><span class="s1">'</span><span class="se">\n</span><span class="s1">'</span><span class="p">)[</span><span class="mi">0</span><span class="p">]</span>
<span class="go">'<tr><th>Username:</th><td><input name="name" type="text" value="class" required /></td></tr>'</span>
</pre></div>
</div>
</div>
<div class="section" id="s-accessing-clean-data">
<span id="accessing-clean-data"></span><h2>Accessing “clean” data<a class="headerlink" href="#accessing-clean-data" title="Permalink to this headline">¶</a></h2>
<dl class="attribute">
<dt id="django.forms.Form.cleaned_data">
<code class="descclassname">Form.</code><code class="descname">cleaned_data</code><a class="headerlink" href="#django.forms.Form.cleaned_data" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<p>Each field in a <a class="reference internal" href="#django.forms.Form" title="django.forms.Form"><code class="xref py py-class docutils literal notranslate"><span class="pre">Form</span></code></a> class is responsible not only for validating
data, but also for “cleaning” it – normalizing it to a consistent format. This
is a nice feature, because it allows data for a particular field to be input in
a variety of ways, always resulting in consistent output.</p>
<p>For example, <a class="reference internal" href="fields.html#django.forms.DateField" title="django.forms.DateField"><code class="xref py py-class docutils literal notranslate"><span class="pre">DateField</span></code></a> normalizes input into a
Python <code class="docutils literal notranslate"><span class="pre">datetime.date</span></code> object. Regardless of whether you pass it a string in
the format <code class="docutils literal notranslate"><span class="pre">'1994-07-15'</span></code>, a <code class="docutils literal notranslate"><span class="pre">datetime.date</span></code> object, or a number of other
formats, <code class="docutils literal notranslate"><span class="pre">DateField</span></code> will always normalize it to a <code class="docutils literal notranslate"><span class="pre">datetime.date</span></code> object
as long as it’s valid.</p>
<p>Once you’ve created a <a class="reference internal" href="#django.forms.Form" title="django.forms.Form"><code class="xref py py-class docutils literal notranslate"><span class="pre">Form</span></code></a> instance with a set of data and validated
it, you can access the clean data via its <code class="docutils literal notranslate"><span class="pre">cleaned_data</span></code> attribute:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">data</span> <span class="o">=</span> <span class="p">{</span><span class="s1">'subject'</span><span class="p">:</span> <span class="s1">'hello'</span><span class="p">,</span>
<span class="gp">... </span> <span class="s1">'message'</span><span class="p">:</span> <span class="s1">'Hi there'</span><span class="p">,</span>
<span class="gp">... </span> <span class="s1">'sender'</span><span class="p">:</span> <span class="s1">'foo@example.com'</span><span class="p">,</span>
<span class="gp">... </span> <span class="s1">'cc_myself'</span><span class="p">:</span> <span class="kc">True</span><span class="p">}</span>
<span class="gp">>>> </span><span class="n">f</span> <span class="o">=</span> <span class="n">ContactForm</span><span class="p">(</span><span class="n">data</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">f</span><span class="o">.</span><span class="n">is_valid</span><span class="p">()</span>
<span class="go">True</span>
<span class="gp">>>> </span><span class="n">f</span><span class="o">.</span><span class="n">cleaned_data</span>
<span class="go">{'cc_myself': True, 'message': 'Hi there', 'sender': 'foo@example.com', 'subject': 'hello'}</span>
</pre></div>
</div>
<p>Note that any text-based field – such as <code class="docutils literal notranslate"><span class="pre">CharField</span></code> or <code class="docutils literal notranslate"><span class="pre">EmailField</span></code> –
always cleans the input into a Unicode string. We’ll cover the encoding
implications later in this document.</p>
<p>If your data does <em>not</em> validate, the <code class="docutils literal notranslate"><span class="pre">cleaned_data</span></code> dictionary contains
only the valid fields:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">data</span> <span class="o">=</span> <span class="p">{</span><span class="s1">'subject'</span><span class="p">:</span> <span class="s1">''</span><span class="p">,</span>
<span class="gp">... </span> <span class="s1">'message'</span><span class="p">:</span> <span class="s1">'Hi there'</span><span class="p">,</span>
<span class="gp">... </span> <span class="s1">'sender'</span><span class="p">:</span> <span class="s1">'invalid email address'</span><span class="p">,</span>
<span class="gp">... </span> <span class="s1">'cc_myself'</span><span class="p">:</span> <span class="kc">True</span><span class="p">}</span>
<span class="gp">>>> </span><span class="n">f</span> <span class="o">=</span> <span class="n">ContactForm</span><span class="p">(</span><span class="n">data</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">f</span><span class="o">.</span><span class="n">is_valid</span><span class="p">()</span>
<span class="go">False</span>
<span class="gp">>>> </span><span class="n">f</span><span class="o">.</span><span class="n">cleaned_data</span>
<span class="go">{'cc_myself': True, 'message': 'Hi there'}</span>
</pre></div>
</div>
<p><code class="docutils literal notranslate"><span class="pre">cleaned_data</span></code> will always <em>only</em> contain a key for fields defined in the
<code class="docutils literal notranslate"><span class="pre">Form</span></code>, even if you pass extra data when you define the <code class="docutils literal notranslate"><span class="pre">Form</span></code>. In this
example, we pass a bunch of extra fields to the <code class="docutils literal notranslate"><span class="pre">ContactForm</span></code> constructor,
but <code class="docutils literal notranslate"><span class="pre">cleaned_data</span></code> contains only the form’s fields:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">data</span> <span class="o">=</span> <span class="p">{</span><span class="s1">'subject'</span><span class="p">:</span> <span class="s1">'hello'</span><span class="p">,</span>
<span class="gp">... </span> <span class="s1">'message'</span><span class="p">:</span> <span class="s1">'Hi there'</span><span class="p">,</span>
<span class="gp">... </span> <span class="s1">'sender'</span><span class="p">:</span> <span class="s1">'foo@example.com'</span><span class="p">,</span>
<span class="gp">... </span> <span class="s1">'cc_myself'</span><span class="p">:</span> <span class="kc">True</span><span class="p">,</span>
<span class="gp">... </span> <span class="s1">'extra_field_1'</span><span class="p">:</span> <span class="s1">'foo'</span><span class="p">,</span>
<span class="gp">... </span> <span class="s1">'extra_field_2'</span><span class="p">:</span> <span class="s1">'bar'</span><span class="p">,</span>
<span class="gp">... </span> <span class="s1">'extra_field_3'</span><span class="p">:</span> <span class="s1">'baz'</span><span class="p">}</span>
<span class="gp">>>> </span><span class="n">f</span> <span class="o">=</span> <span class="n">ContactForm</span><span class="p">(</span><span class="n">data</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">f</span><span class="o">.</span><span class="n">is_valid</span><span class="p">()</span>
<span class="go">True</span>
<span class="gp">>>> </span><span class="n">f</span><span class="o">.</span><span class="n">cleaned_data</span> <span class="c1"># Doesn't contain extra_field_1, etc.</span>
<span class="go">{'cc_myself': True, 'message': 'Hi there', 'sender': 'foo@example.com', 'subject': 'hello'}</span>
</pre></div>
</div>
<p>When the <code class="docutils literal notranslate"><span class="pre">Form</span></code> is valid, <code class="docutils literal notranslate"><span class="pre">cleaned_data</span></code> will include a key and value for
<em>all</em> its fields, even if the data didn’t include a value for some optional
fields. In this example, the data dictionary doesn’t include a value for the
<code class="docutils literal notranslate"><span class="pre">nick_name</span></code> field, but <code class="docutils literal notranslate"><span class="pre">cleaned_data</span></code> includes it, with an empty value:</p>
<div class="highlight-default notranslate"><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="k">class</span> <span class="nc">OptionalPersonForm</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="gp">... </span> <span class="n">first_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="gp">... </span> <span class="n">last_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="gp">... </span> <span class="n">nick_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">required</span><span class="o">=</span><span class="kc">False</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">data</span> <span class="o">=</span> <span class="p">{</span><span class="s1">'first_name'</span><span class="p">:</span> <span class="s1">'John'</span><span class="p">,</span> <span class="s1">'last_name'</span><span class="p">:</span> <span class="s1">'Lennon'</span><span class="p">}</span>
<span class="gp">>>> </span><span class="n">f</span> <span class="o">=</span> <span class="n">OptionalPersonForm</span><span class="p">(</span><span class="n">data</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">f</span><span class="o">.</span><span class="n">is_valid</span><span class="p">()</span>
<span class="go">True</span>
<span class="gp">>>> </span><span class="n">f</span><span class="o">.</span><span class="n">cleaned_data</span>
<span class="go">{'nick_name': '', 'first_name': 'John', 'last_name': 'Lennon'}</span>
</pre></div>
</div>
<p>In this above example, the <code class="docutils literal notranslate"><span class="pre">cleaned_data</span></code> value for <code class="docutils literal notranslate"><span class="pre">nick_name</span></code> is set to an
empty string, because <code class="docutils literal notranslate"><span class="pre">nick_name</span></code> is <code class="docutils literal notranslate"><span class="pre">CharField</span></code>, and <code class="docutils literal notranslate"><span class="pre">CharField</span></code>s treat
empty values as an empty string. Each field type knows what its “blank” value
is – e.g., for <code class="docutils literal notranslate"><span class="pre">DateField</span></code>, it’s <code class="docutils literal notranslate"><span class="pre">None</span></code> instead of the empty string. For
full details on each field’s behavior in this case, see the “Empty value” note
for each field in the “Built-in <code class="docutils literal notranslate"><span class="pre">Field</span></code> classes” section below.</p>
<p>You can write code to perform validation for particular form fields (based on
their name) or for the form as a whole (considering combinations of various
fields). More information about this is in <a class="reference internal" href="validation.html"><span class="doc">Form and field validation</span></a>.</p>
</div>
<div class="section" id="s-outputting-forms-as-html">
<span id="s-ref-forms-api-outputting-html"></span><span id="outputting-forms-as-html"></span><span id="ref-forms-api-outputting-html"></span><h2>Outputting forms as HTML<a class="headerlink" href="#outputting-forms-as-html" title="Permalink to this headline">¶</a></h2>
<p>The second task of a <code class="docutils literal notranslate"><span class="pre">Form</span></code> object is to render itself as HTML. To do so,
simply <code class="docutils literal notranslate"><span class="pre">print</span></code> it:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">f</span> <span class="o">=</span> <span class="n">ContactForm</span><span class="p">()</span>
<span class="gp">>>> </span><span class="nb">print</span><span class="p">(</span><span class="n">f</span><span class="p">)</span>
<span class="go"><tr><th><label for="id_subject">Subject:</label></th><td><input id="id_subject" type="text" name="subject" maxlength="100" required /></td></tr></span>
<span class="go"><tr><th><label for="id_message">Message:</label></th><td><input type="text" name="message" id="id_message" required /></td></tr></span>
<span class="go"><tr><th><label for="id_sender">Sender:</label></th><td><input type="email" name="sender" id="id_sender" required /></td></tr></span>
<span class="go"><tr><th><label for="id_cc_myself">Cc myself:</label></th><td><input type="checkbox" name="cc_myself" id="id_cc_myself" /></td></tr></span>
</pre></div>
</div>
<p>If the form is bound to data, the HTML output will include that data
appropriately. For example, if a field is represented by an
<code class="docutils literal notranslate"><span class="pre"><input</span> <span class="pre">type="text"></span></code>, the data will be in the <code class="docutils literal notranslate"><span class="pre">value</span></code> attribute. If a
field is represented by an <code class="docutils literal notranslate"><span class="pre"><input</span> <span class="pre">type="checkbox"></span></code>, then that HTML will
include <code class="docutils literal notranslate"><span class="pre">checked</span></code> if appropriate:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">data</span> <span class="o">=</span> <span class="p">{</span><span class="s1">'subject'</span><span class="p">:</span> <span class="s1">'hello'</span><span class="p">,</span>
<span class="gp">... </span> <span class="s1">'message'</span><span class="p">:</span> <span class="s1">'Hi there'</span><span class="p">,</span>
<span class="gp">... </span> <span class="s1">'sender'</span><span class="p">:</span> <span class="s1">'foo@example.com'</span><span class="p">,</span>
<span class="gp">... </span> <span class="s1">'cc_myself'</span><span class="p">:</span> <span class="kc">True</span><span class="p">}</span>
<span class="gp">>>> </span><span class="n">f</span> <span class="o">=</span> <span class="n">ContactForm</span><span class="p">(</span><span class="n">data</span><span class="p">)</span>
<span class="gp">>>> </span><span class="nb">print</span><span class="p">(</span><span class="n">f</span><span class="p">)</span>
<span class="go"><tr><th><label for="id_subject">Subject:</label></th><td><input id="id_subject" type="text" name="subject" maxlength="100" value="hello" required /></td></tr></span>
<span class="go"><tr><th><label for="id_message">Message:</label></th><td><input type="text" name="message" id="id_message" value="Hi there" required /></td></tr></span>
<span class="go"><tr><th><label for="id_sender">Sender:</label></th><td><input type="email" name="sender" id="id_sender" value="foo@example.com" required /></td></tr></span>
<span class="go"><tr><th><label for="id_cc_myself">Cc myself:</label></th><td><input type="checkbox" name="cc_myself" id="id_cc_myself" checked /></td></tr></span>
</pre></div>
</div>
<div class="versionchanged">
<span class="title">Changed in Django 1.11:</span> <p>The <code class="docutils literal notranslate"><span class="pre">checked</span></code> attribute was changed to use HTML5 boolean syntax rather
than <code class="docutils literal notranslate"><span class="pre">checked="checked"</span></code>.</p>
</div>
<p>This default output is a two-column HTML table, with a <code class="docutils literal notranslate"><span class="pre"><tr></span></code> for each field.
Notice the following:</p>
<ul class="simple">
<li>For flexibility, the output does <em>not</em> include the <code class="docutils literal notranslate"><span class="pre"><table></span></code> and
<code class="docutils literal notranslate"><span class="pre"></table></span></code> tags, nor does it include the <code class="docutils literal notranslate"><span class="pre"><form></span></code> and <code class="docutils literal notranslate"><span class="pre"></form></span></code>
tags or an <code class="docutils literal notranslate"><span class="pre"><input</span> <span class="pre">type="submit"></span></code> tag. It’s your job to do that.</li>
<li>Each field type has a default HTML representation. <code class="docutils literal notranslate"><span class="pre">CharField</span></code> is
represented by an <code class="docutils literal notranslate"><span class="pre"><input</span> <span class="pre">type="text"></span></code> and <code class="docutils literal notranslate"><span class="pre">EmailField</span></code> by an
<code class="docutils literal notranslate"><span class="pre"><input</span> <span class="pre">type="email"></span></code>.
<code class="docutils literal notranslate"><span class="pre">BooleanField</span></code> is represented by an <code class="docutils literal notranslate"><span class="pre"><input</span> <span class="pre">type="checkbox"></span></code>. Note
these are merely sensible defaults; you can specify which HTML to use for
a given field by using widgets, which we’ll explain shortly.</li>
<li>The HTML <code class="docutils literal notranslate"><span class="pre">name</span></code> for each tag is taken directly from its attribute name
in the <code class="docutils literal notranslate"><span class="pre">ContactForm</span></code> class.</li>
<li>The text label for each field – e.g. <code class="docutils literal notranslate"><span class="pre">'Subject:'</span></code>, <code class="docutils literal notranslate"><span class="pre">'Message:'</span></code> and
<code class="docutils literal notranslate"><span class="pre">'Cc</span> <span class="pre">myself:'</span></code> is generated from the field name by converting all
underscores to spaces and upper-casing the first letter. Again, note
these are merely sensible defaults; you can also specify labels manually.</li>
<li>Each text label is surrounded in an HTML <code class="docutils literal notranslate"><span class="pre"><label></span></code> tag, which points
to the appropriate form field via its <code class="docutils literal notranslate"><span class="pre">id</span></code>. Its <code class="docutils literal notranslate"><span class="pre">id</span></code>, in turn, is
generated by prepending <code class="docutils literal notranslate"><span class="pre">'id_'</span></code> to the field name. The <code class="docutils literal notranslate"><span class="pre">id</span></code>
attributes and <code class="docutils literal notranslate"><span class="pre"><label></span></code> tags are included in the output by default, to
follow best practices, but you can change that behavior.</li>
<li>The output uses HTML5 syntax, targeting <code class="docutils literal notranslate"><span class="pre"><!DOCTYPE</span> <span class="pre">html></span></code>. For example,
it uses boolean attributes such as <code class="docutils literal notranslate"><span class="pre">checked</span></code> rather than the XHTML style
of <code class="docutils literal notranslate"><span class="pre">checked='checked'</span></code>.</li>
</ul>
<p>Although <code class="docutils literal notranslate"><span class="pre"><table></span></code> output is the default output style when you <code class="docutils literal notranslate"><span class="pre">print</span></code> a
form, other output styles are available. Each style is available as a method on
a form object, and each rendering method returns a Unicode object.</p>
<div class="section" id="s-as-p">
<span id="as-p"></span><h3><code class="docutils literal notranslate"><span class="pre">as_p()</span></code><a class="headerlink" href="#as-p" title="Permalink to this headline">¶</a></h3>
<dl class="method">
<dt id="django.forms.Form.as_p">
<code class="descclassname">Form.</code><code class="descname">as_p</code>()<a class="headerlink" href="#django.forms.Form.as_p" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<p><code class="docutils literal notranslate"><span class="pre">as_p()</span></code> renders the form as a series of <code class="docutils literal notranslate"><span class="pre"><p></span></code> tags, with each <code class="docutils literal notranslate"><span class="pre"><p></span></code>
containing one field:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">f</span> <span class="o">=</span> <span class="n">ContactForm</span><span class="p">()</span>
<span class="gp">>>> </span><span class="n">f</span><span class="o">.</span><span class="n">as_p</span><span class="p">()</span>
<span class="go">'<p><label for="id_subject">Subject:</label> <input id="id_subject" type="text" name="subject" maxlength="100" required /></p>\n<p><label for="id_message">Message:</label> <input type="text" name="message" id="id_message" required /></p>\n<p><label for="id_sender">Sender:</label> <input type="text" name="sender" id="id_sender" required /></p>\n<p><label for="id_cc_myself">Cc myself:</label> <input type="checkbox" name="cc_myself" id="id_cc_myself" /></p>'</span>
<span class="gp">>>> </span><span class="nb">print</span><span class="p">(</span><span class="n">f</span><span class="o">.</span><span class="n">as_p</span><span class="p">())</span>
<span class="go"><p><label for="id_subject">Subject:</label> <input id="id_subject" type="text" name="subject" maxlength="100" required /></p></span>
<span class="go"><p><label for="id_message">Message:</label> <input type="text" name="message" id="id_message" required /></p></span>
<span class="go"><p><label for="id_sender">Sender:</label> <input type="email" name="sender" id="id_sender" required /></p></span>
<span class="go"><p><label for="id_cc_myself">Cc myself:</label> <input type="checkbox" name="cc_myself" id="id_cc_myself" /></p></span>
</pre></div>
</div>
</div>
<div class="section" id="s-as-ul">
<span id="as-ul"></span><h3><code class="docutils literal notranslate"><span class="pre">as_ul()</span></code><a class="headerlink" href="#as-ul" title="Permalink to this headline">¶</a></h3>
<dl class="method">
<dt id="django.forms.Form.as_ul">
<code class="descclassname">Form.</code><code class="descname">as_ul</code>()<a class="headerlink" href="#django.forms.Form.as_ul" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<p><code class="docutils literal notranslate"><span class="pre">as_ul()</span></code> renders the form as a series of <code class="docutils literal notranslate"><span class="pre"><li></span></code> tags, with each
<code class="docutils literal notranslate"><span class="pre"><li></span></code> containing one field. It does <em>not</em> include the <code class="docutils literal notranslate"><span class="pre"><ul></span></code> or
<code class="docutils literal notranslate"><span class="pre"></ul></span></code>, so that you can specify any HTML attributes on the <code class="docutils literal notranslate"><span class="pre"><ul></span></code> for
flexibility:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">f</span> <span class="o">=</span> <span class="n">ContactForm</span><span class="p">()</span>
<span class="gp">>>> </span><span class="n">f</span><span class="o">.</span><span class="n">as_ul</span><span class="p">()</span>
<span class="go">'<li><label for="id_subject">Subject:</label> <input id="id_subject" type="text" name="subject" maxlength="100" required /></li>\n<li><label for="id_message">Message:</label> <input type="text" name="message" id="id_message" required /></li>\n<li><label for="id_sender">Sender:</label> <input type="email" name="sender" id="id_sender" required /></li>\n<li><label for="id_cc_myself">Cc myself:</label> <input type="checkbox" name="cc_myself" id="id_cc_myself" /></li>'</span>
<span class="gp">>>> </span><span class="nb">print</span><span class="p">(</span><span class="n">f</span><span class="o">.</span><span class="n">as_ul</span><span class="p">())</span>
<span class="go"><li><label for="id_subject">Subject:</label> <input id="id_subject" type="text" name="subject" maxlength="100" required /></li></span>
<span class="go"><li><label for="id_message">Message:</label> <input type="text" name="message" id="id_message" required /></li></span>
<span class="go"><li><label for="id_sender">Sender:</label> <input type="email" name="sender" id="id_sender" required /></li></span>
<span class="go"><li><label for="id_cc_myself">Cc myself:</label> <input type="checkbox" name="cc_myself" id="id_cc_myself" /></li></span>
</pre></div>
</div>
</div>
<div class="section" id="s-as-table">
<span id="as-table"></span><h3><code class="docutils literal notranslate"><span class="pre">as_table()</span></code><a class="headerlink" href="#as-table" title="Permalink to this headline">¶</a></h3>
<dl class="method">
<dt id="django.forms.Form.as_table">
<code class="descclassname">Form.</code><code class="descname">as_table</code>()<a class="headerlink" href="#django.forms.Form.as_table" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<p>Finally, <code class="docutils literal notranslate"><span class="pre">as_table()</span></code> outputs the form as an HTML <code class="docutils literal notranslate"><span class="pre"><table></span></code>. This is
exactly the same as <code class="docutils literal notranslate"><span class="pre">print</span></code>. In fact, when you <code class="docutils literal notranslate"><span class="pre">print</span></code> a form object,
it calls its <code class="docutils literal notranslate"><span class="pre">as_table()</span></code> method behind the scenes:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">f</span> <span class="o">=</span> <span class="n">ContactForm</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><label for="id_subject">Subject:</label></th><td><input id="id_subject" type="text" name="subject" maxlength="100" required /></td></tr>\n<tr><th><label for="id_message">Message:</label></th><td><input type="text" name="message" id="id_message" required /></td></tr>\n<tr><th><label for="id_sender">Sender:</label></th><td><input type="email" name="sender" id="id_sender" required /></td></tr>\n<tr><th><label for="id_cc_myself">Cc myself:</label></th><td><input type="checkbox" name="cc_myself" id="id_cc_myself" /></td></tr>'</span>
<span class="gp">>>> </span><span class="nb">print</span><span class="p">(</span><span class="n">f</span><span class="p">)</span>
<span class="go"><tr><th><label for="id_subject">Subject:</label></th><td><input id="id_subject" type="text" name="subject" maxlength="100" required /></td></tr></span>
<span class="go"><tr><th><label for="id_message">Message:</label></th><td><input type="text" name="message" id="id_message" required /></td></tr></span>
<span class="go"><tr><th><label for="id_sender">Sender:</label></th><td><input type="email" name="sender" id="id_sender" required /></td></tr></span>
<span class="go"><tr><th><label for="id_cc_myself">Cc myself:</label></th><td><input type="checkbox" name="cc_myself" id="id_cc_myself" /></td></tr></span>
</pre></div>
</div>
</div>
<div class="section" id="s-styling-required-or-erroneous-form-rows">
<span id="s-ref-forms-api-styling-form-rows"></span><span id="styling-required-or-erroneous-form-rows"></span><span id="ref-forms-api-styling-form-rows"></span><h3>Styling required or erroneous form rows<a class="headerlink" href="#styling-required-or-erroneous-form-rows" title="Permalink to this headline">¶</a></h3>
<dl class="attribute">
<dt id="django.forms.Form.error_css_class">
<code class="descclassname">Form.</code><code class="descname">error_css_class</code><a class="headerlink" href="#django.forms.Form.error_css_class" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<dl class="attribute">
<dt id="django.forms.Form.required_css_class">
<code class="descclassname">Form.</code><code class="descname">required_css_class</code><a class="headerlink" href="#django.forms.Form.required_css_class" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<p>It’s pretty common to style form rows and fields that are required or have
errors. For example, you might want to present required form rows in bold and
highlight errors in red.</p>
<p>The <a class="reference internal" href="#django.forms.Form" title="django.forms.Form"><code class="xref py py-class docutils literal notranslate"><span class="pre">Form</span></code></a> class has a couple of hooks you can use to add <code class="docutils literal notranslate"><span class="pre">class</span></code>
attributes to required rows or to rows with errors: simply set the
<a class="reference internal" href="#django.forms.Form.error_css_class" title="django.forms.Form.error_css_class"><code class="xref py py-attr docutils literal notranslate"><span class="pre">Form.error_css_class</span></code></a> and/or <a class="reference internal" href="#django.forms.Form.required_css_class" title="django.forms.Form.required_css_class"><code class="xref py py-attr docutils literal notranslate"><span class="pre">Form.required_css_class</span></code></a>
attributes:</p>
<div class="highlight-default notranslate"><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">ContactForm</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">error_css_class</span> <span class="o">=</span> <span class="s1">'error'</span>
<span class="n">required_css_class</span> <span class="o">=</span> <span class="s1">'required'</span>
<span class="c1"># ... and the rest of your fields here</span>
</pre></div>
</div>
<p>Once you’ve done that, rows will be given <code class="docutils literal notranslate"><span class="pre">"error"</span></code> and/or <code class="docutils literal notranslate"><span class="pre">"required"</span></code>
classes, as needed. The HTML will look something like:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">f</span> <span class="o">=</span> <span class="n">ContactForm</span><span class="p">(</span><span class="n">data</span><span class="p">)</span>
<span class="gp">>>> </span><span class="nb">print</span><span class="p">(</span><span class="n">f</span><span class="o">.</span><span class="n">as_table</span><span class="p">())</span>
<span class="go"><tr class="required"><th><label class="required" for="id_subject">Subject:</label> ...</span>
<span class="go"><tr class="required"><th><label class="required" for="id_message">Message:</label> ...</span>
<span class="go"><tr class="required error"><th><label class="required" for="id_sender">Sender:</label> ...</span>
<span class="go"><tr><th><label for="id_cc_myself">Cc myself:<label> ...</span>
<span class="gp">>>> </span><span class="n">f</span><span class="p">[</span><span class="s1">'subject'</span><span class="p">]</span><span class="o">.</span><span class="n">label_tag</span><span class="p">()</span>
<span class="go"><label class="required" for="id_subject">Subject:</label></span>
<span class="gp">>>> </span><span class="n">f</span><span class="p">[</span><span class="s1">'subject'</span><span class="p">]</span><span class="o">.</span><span class="n">label_tag</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">'foo'</span><span class="p">})</span>
<span class="go"><label for="id_subject" class="foo required">Subject:</label></span>
</pre></div>
</div>
</div>
<div class="section" id="s-configuring-form-elements-html-id-attributes-and-label-tags">
<span id="s-ref-forms-api-configuring-label"></span><span id="configuring-form-elements-html-id-attributes-and-label-tags"></span><span id="ref-forms-api-configuring-label"></span><h3>Configuring form elements’ HTML <code class="docutils literal notranslate"><span class="pre">id</span></code> attributes and <code class="docutils literal notranslate"><span class="pre"><label></span></code> tags<a class="headerlink" href="#configuring-form-elements-html-id-attributes-and-label-tags" title="Permalink to this headline">¶</a></h3>
<dl class="attribute">
<dt id="django.forms.Form.auto_id">
<code class="descclassname">Form.</code><code class="descname">auto_id</code><a class="headerlink" href="#django.forms.Form.auto_id" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<p>By default, the form rendering methods include:</p>
<ul class="simple">
<li>HTML <code class="docutils literal notranslate"><span class="pre">id</span></code> attributes on the form elements.</li>
<li>The corresponding <code class="docutils literal notranslate"><span class="pre"><label></span></code> tags around the labels. An HTML <code class="docutils literal notranslate"><span class="pre"><label></span></code> tag
designates which label text is associated with which form element. This small
enhancement makes forms more usable and more accessible to assistive devices.
It’s always a good idea to use <code class="docutils literal notranslate"><span class="pre"><label></span></code> tags.</li>
</ul>
<p>The <code class="docutils literal notranslate"><span class="pre">id</span></code> attribute values are generated by prepending <code class="docutils literal notranslate"><span class="pre">id_</span></code> to the form
field names. This behavior is configurable, though, if you want to change the
<code class="docutils literal notranslate"><span class="pre">id</span></code> convention or remove HTML <code class="docutils literal notranslate"><span class="pre">id</span></code> attributes and <code class="docutils literal notranslate"><span class="pre"><label></span></code> tags
entirely.</p>
<p>Use the <code class="docutils literal notranslate"><span class="pre">auto_id</span></code> argument to the <code class="docutils literal notranslate"><span class="pre">Form</span></code> constructor to control the <code class="docutils literal notranslate"><span class="pre">id</span></code>
and label behavior. This argument must be <code class="docutils literal notranslate"><span class="pre">True</span></code>, <code class="docutils literal notranslate"><span class="pre">False</span></code> or a string.</p>
<p>If <code class="docutils literal notranslate"><span class="pre">auto_id</span></code> is <code class="docutils literal notranslate"><span class="pre">False</span></code>, then the form output will not include <code class="docutils literal notranslate"><span class="pre"><label></span></code>
tags nor <code class="docutils literal notranslate"><span class="pre">id</span></code> attributes:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">f</span> <span class="o">=</span> <span class="n">ContactForm</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="nb">print</span><span class="p">(</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>Subject:</th><td><input type="text" name="subject" maxlength="100" required /></td></tr></span>
<span class="go"><tr><th>Message:</th><td><input type="text" name="message" required /></td></tr></span>
<span class="go"><tr><th>Sender:</th><td><input type="email" name="sender" required /></td></tr></span>
<span class="go"><tr><th>Cc myself:</th><td><input type="checkbox" name="cc_myself" /></td></tr></span>
<span class="gp">>>> </span><span class="nb">print</span><span class="p">(</span><span class="n">f</span><span class="o">.</span><span class="n">as_ul</span><span class="p">())</span>
<span class="go"><li>Subject: <input type="text" name="subject" maxlength="100" required /></li></span>
<span class="go"><li>Message: <input type="text" name="message" required /></li></span>
<span class="go"><li>Sender: <input type="email" name="sender" required /></li></span>
<span class="go"><li>Cc myself: <input type="checkbox" name="cc_myself" /></li></span>
<span class="gp">>>> </span><span class="nb">print</span><span class="p">(</span><span class="n">f</span><span class="o">.</span><span class="n">as_p</span><span class="p">())</span>
<span class="go"><p>Subject: <input type="text" name="subject" maxlength="100" required /></p></span>
<span class="go"><p>Message: <input type="text" name="message" required /></p></span>
<span class="go"><p>Sender: <input type="email" name="sender" required /></p></span>
<span class="go"><p>Cc myself: <input type="checkbox" name="cc_myself" /></p></span>
</pre></div>
</div>
<p>If <code class="docutils literal notranslate"><span class="pre">auto_id</span></code> is set to <code class="docutils literal notranslate"><span class="pre">True</span></code>, then the form output <em>will</em> include
<code class="docutils literal notranslate"><span class="pre"><label></span></code> tags and will simply use the field name as its <code class="docutils literal notranslate"><span class="pre">id</span></code> for each form
field:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">f</span> <span class="o">=</span> <span class="n">ContactForm</span><span class="p">(</span><span class="n">auto_id</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
<span class="gp">>>> </span><span class="nb">print</span><span class="p">(</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><label for="subject">Subject:</label></th><td><input id="subject" type="text" name="subject" maxlength="100" required /></td></tr></span>
<span class="go"><tr><th><label for="message">Message:</label></th><td><input type="text" name="message" id="message" required /></td></tr></span>
<span class="go"><tr><th><label for="sender">Sender:</label></th><td><input type="email" name="sender" id="sender" required /></td></tr></span>
<span class="go"><tr><th><label for="cc_myself">Cc myself:</label></th><td><input type="checkbox" name="cc_myself" id="cc_myself" /></td></tr></span>
<span class="gp">>>> </span><span class="nb">print</span><span class="p">(</span><span class="n">f</span><span class="o">.</span><span class="n">as_ul</span><span class="p">())</span>
<span class="go"><li><label for="subject">Subject:</label> <input id="subject" type="text" name="subject" maxlength="100" required /></li></span>
<span class="go"><li><label for="message">Message:</label> <input type="text" name="message" id="message" required /></li></span>
<span class="go"><li><label for="sender">Sender:</label> <input type="email" name="sender" id="sender" required /></li></span>
<span class="go"><li><label for="cc_myself">Cc myself:</label> <input type="checkbox" name="cc_myself" id="cc_myself" /></li></span>
<span class="gp">>>> </span><span class="nb">print</span><span class="p">(</span><span class="n">f</span><span class="o">.</span><span class="n">as_p</span><span class="p">())</span>
<span class="go"><p><label for="subject">Subject:</label> <input id="subject" type="text" name="subject" maxlength="100" required /></p></span>
<span class="go"><p><label for="message">Message:</label> <input type="text" name="message" id="message" required /></p></span>
<span class="go"><p><label for="sender">Sender:</label> <input type="email" name="sender" id="sender" required /></p></span>
<span class="go"><p><label for="cc_myself">Cc myself:</label> <input type="checkbox" name="cc_myself" id="cc_myself" /></p></span>
</pre></div>
</div>
<p>If <code class="docutils literal notranslate"><span class="pre">auto_id</span></code> is set to a string containing the format character <code class="docutils literal notranslate"><span class="pre">'%s'</span></code>,
then the form output will include <code class="docutils literal notranslate"><span class="pre"><label></span></code> tags, and will generate <code class="docutils literal notranslate"><span class="pre">id</span></code>
attributes based on the format string. For example, for a format string
<code class="docutils literal notranslate"><span class="pre">'field_%s'</span></code>, a field named <code class="docutils literal notranslate"><span class="pre">subject</span></code> will get the <code class="docutils literal notranslate"><span class="pre">id</span></code> value
<code class="docutils literal notranslate"><span class="pre">'field_subject'</span></code>. Continuing our example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">f</span> <span class="o">=</span> <span class="n">ContactForm</span><span class="p">(</span><span class="n">auto_id</span><span class="o">=</span><span class="s1">'id_for_</span><span class="si">%s</span><span class="s1">'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="nb">print</span><span class="p">(</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><label for="id_for_subject">Subject:</label></th><td><input id="id_for_subject" type="text" name="subject" maxlength="100" required /></td></tr></span>
<span class="go"><tr><th><label for="id_for_message">Message:</label></th><td><input type="text" name="message" id="id_for_message" required /></td></tr></span>
<span class="go"><tr><th><label for="id_for_sender">Sender:</label></th><td><input type="email" name="sender" id="id_for_sender" required /></td></tr></span>
<span class="go"><tr><th><label for="id_for_cc_myself">Cc myself:</label></th><td><input type="checkbox" name="cc_myself" id="id_for_cc_myself" /></td></tr></span>
<span class="gp">>>> </span><span class="nb">print</span><span class="p">(</span><span class="n">f</span><span class="o">.</span><span class="n">as_ul</span><span class="p">())</span>
<span class="go"><li><label for="id_for_subject">Subject:</label> <input id="id_for_subject" type="text" name="subject" maxlength="100" required /></li></span>
<span class="go"><li><label for="id_for_message">Message:</label> <input type="text" name="message" id="id_for_message" required /></li></span>
<span class="go"><li><label for="id_for_sender">Sender:</label> <input type="email" name="sender" id="id_for_sender" required /></li></span>
<span class="go"><li><label for="id_for_cc_myself">Cc myself:</label> <input type="checkbox" name="cc_myself" id="id_for_cc_myself" /></li></span>
<span class="gp">>>> </span><span class="nb">print</span><span class="p">(</span><span class="n">f</span><span class="o">.</span><span class="n">as_p</span><span class="p">())</span>
<span class="go"><p><label for="id_for_subject">Subject:</label> <input id="id_for_subject" type="text" name="subject" maxlength="100" required /></p></span>
<span class="go"><p><label for="id_for_message">Message:</label> <input type="text" name="message" id="id_for_message" required /></p></span>
<span class="go"><p><label for="id_for_sender">Sender:</label> <input type="email" name="sender" id="id_for_sender" required /></p></span>
<span class="go"><p><label for="id_for_cc_myself">Cc myself:</label> <input type="checkbox" name="cc_myself" id="id_for_cc_myself" /></p></span>
</pre></div>
</div>
<p>If <code class="docutils literal notranslate"><span class="pre">auto_id</span></code> is set to any other true value – such as a string that doesn’t
include <code class="docutils literal notranslate"><span class="pre">%s</span></code> – then the library will act as if <code class="docutils literal notranslate"><span class="pre">auto_id</span></code> is <code class="docutils literal notranslate"><span class="pre">True</span></code>.</p>
<p>By default, <code class="docutils literal notranslate"><span class="pre">auto_id</span></code> is set to the string <code class="docutils literal notranslate"><span class="pre">'id_%s'</span></code>.</p>
<dl class="attribute">
<dt id="django.forms.Form.label_suffix">
<code class="descclassname">Form.</code><code class="descname">label_suffix</code><a class="headerlink" href="#django.forms.Form.label_suffix" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<p>A translatable string (defaults to a colon (<code class="docutils literal notranslate"><span class="pre">:</span></code>) in English) that will be
appended after any label name when a form is rendered.</p>
<p>It’s possible to customize that character, or omit it entirely, using the
<code class="docutils literal notranslate"><span class="pre">label_suffix</span></code> parameter:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">f</span> <span class="o">=</span> <span class="n">ContactForm</span><span class="p">(</span><span class="n">auto_id</span><span class="o">=</span><span class="s1">'id_for_</span><span class="si">%s</span><span class="s1">'</span><span class="p">,</span> <span class="n">label_suffix</span><span class="o">=</span><span class="s1">''</span><span class="p">)</span>
<span class="gp">>>> </span><span class="nb">print</span><span class="p">(</span><span class="n">f</span><span class="o">.</span><span class="n">as_ul</span><span class="p">())</span>
<span class="go"><li><label for="id_for_subject">Subject</label> <input id="id_for_subject" type="text" name="subject" maxlength="100" required /></li></span>
<span class="go"><li><label for="id_for_message">Message</label> <input type="text" name="message" id="id_for_message" required /></li></span>
<span class="go"><li><label for="id_for_sender">Sender</label> <input type="email" name="sender" id="id_for_sender" required /></li></span>
<span class="go"><li><label for="id_for_cc_myself">Cc myself</label> <input type="checkbox" name="cc_myself" id="id_for_cc_myself" /></li></span>
<span class="gp">>>> </span><span class="n">f</span> <span class="o">=</span> <span class="n">ContactForm</span><span class="p">(</span><span class="n">auto_id</span><span class="o">=</span><span class="s1">'id_for_</span><span class="si">%s</span><span class="s1">'</span><span class="p">,</span> <span class="n">label_suffix</span><span class="o">=</span><span class="s1">' ->'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="nb">print</span><span class="p">(</span><span class="n">f</span><span class="o">.</span><span class="n">as_ul</span><span class="p">())</span>
<span class="go"><li><label for="id_for_subject">Subject -></label> <input id="id_for_subject" type="text" name="subject" maxlength="100" required /></li></span>
<span class="go"><li><label for="id_for_message">Message -></label> <input type="text" name="message" id="id_for_message" required /></li></span>
<span class="go"><li><label for="id_for_sender">Sender -></label> <input type="email" name="sender" id="id_for_sender" required /></li></span>
<span class="go"><li><label for="id_for_cc_myself">Cc myself -></label> <input type="checkbox" name="cc_myself" id="id_for_cc_myself" /></li></span>
</pre></div>
</div>
<p>Note that the label suffix is added only if the last character of the
label isn’t a punctuation character (in English, those are <code class="docutils literal notranslate"><span class="pre">.</span></code>, <code class="docutils literal notranslate"><span class="pre">!</span></code>, <code class="docutils literal notranslate"><span class="pre">?</span></code>
or <code class="docutils literal notranslate"><span class="pre">:</span></code>).</p>
<p>Fields can also define their own <a class="reference internal" href="fields.html#django.forms.Field.label_suffix" title="django.forms.Field.label_suffix"><code class="xref py py-attr docutils literal notranslate"><span class="pre">label_suffix</span></code></a>.
This will take precedence over <a class="reference internal" href="#django.forms.Form.label_suffix" title="django.forms.Form.label_suffix"><code class="xref py py-attr docutils literal notranslate"><span class="pre">Form.label_suffix</span></code></a>. The suffix can also be overridden at runtime
using the <code class="docutils literal notranslate"><span class="pre">label_suffix</span></code> parameter to
<a class="reference internal" href="#django.forms.BoundField.label_tag" title="django.forms.BoundField.label_tag"><code class="xref py py-meth docutils literal notranslate"><span class="pre">label_tag()</span></code></a>.</p>
<dl class="attribute">
<dt id="django.forms.Form.use_required_attribute">
<code class="descclassname">Form.</code><code class="descname">use_required_attribute</code><a class="headerlink" href="#django.forms.Form.use_required_attribute" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<div class="versionadded">
<span class="title">New in Django 1.10.</span> </div>
<p>When set to <code class="docutils literal notranslate"><span class="pre">True</span></code> (the default), required form fields will have the
<code class="docutils literal notranslate"><span class="pre">required</span></code> HTML attribute.</p>
<p><a class="reference internal" href="../../topics/forms/formsets.html"><span class="doc">Formsets</span></a> instantiate forms with
<code class="docutils literal notranslate"><span class="pre">use_required_attribute=False</span></code> to avoid incorrect browser validation when
adding and deleting forms from a formset.</p>
</div>
<div class="section" id="s-configuring-the-rendering-of-a-form-s-widgets">
<span id="configuring-the-rendering-of-a-form-s-widgets"></span><h3>Configuring the rendering of a form’s widgets<a class="headerlink" href="#configuring-the-rendering-of-a-form-s-widgets" title="Permalink to this headline">¶</a></h3>
<dl class="attribute">
<dt id="django.forms.Form.default_renderer">
<code class="descclassname">Form.</code><code class="descname">default_renderer</code><a class="headerlink" href="#django.forms.Form.default_renderer" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<div class="versionadded">
<span class="title">New in Django 1.11.</span> </div>
<p>Specifies the <a class="reference internal" href="renderers.html"><span class="doc">renderer</span></a> to use for the form. Defaults to
<code class="docutils literal notranslate"><span class="pre">None</span></code> which means to use the default renderer specified by the
<a class="reference internal" href="../settings.html#std:setting-FORM_RENDERER"><code class="xref std std-setting docutils literal notranslate"><span class="pre">FORM_RENDERER</span></code></a> setting.</p>
<p>You can set this as a class attribute when declaring your form or use the
<code class="docutils literal notranslate"><span class="pre">renderer</span></code> argument to <code class="docutils literal notranslate"><span class="pre">Form.__init__()</span></code>. For example:</p>
<div class="highlight-default notranslate"><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">MyForm</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">default_renderer</span> <span class="o">=</span> <span class="n">MyRenderer</span><span class="p">()</span>
</pre></div>
</div>
<p>or:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">form</span> <span class="o">=</span> <span class="n">MyForm</span><span class="p">(</span><span class="n">renderer</span><span class="o">=</span><span class="n">MyRenderer</span><span class="p">())</span>
</pre></div>
</div>
</div>
<div class="section" id="s-notes-on-field-ordering">
<span id="notes-on-field-ordering"></span><h3>Notes on field ordering<a class="headerlink" href="#notes-on-field-ordering" title="Permalink to this headline">¶</a></h3>
<p>In the <code class="docutils literal notranslate"><span class="pre">as_p()</span></code>, <code class="docutils literal notranslate"><span class="pre">as_ul()</span></code> and <code class="docutils literal notranslate"><span class="pre">as_table()</span></code> shortcuts, the fields are
displayed in the order in which you define them in your form class. For
example, in the <code class="docutils literal notranslate"><span class="pre">ContactForm</span></code> example, the fields are defined in the order
<code class="docutils literal notranslate"><span class="pre">subject</span></code>, <code class="docutils literal notranslate"><span class="pre">message</span></code>, <code class="docutils literal notranslate"><span class="pre">sender</span></code>, <code class="docutils literal notranslate"><span class="pre">cc_myself</span></code>. To reorder the HTML
output, just change the order in which those fields are listed in the class.</p>
<p>There are several other ways to customize the order:</p>
<dl class="attribute">
<dt id="django.forms.Form.field_order">
<code class="descclassname">Form.</code><code class="descname">field_order</code><a class="headerlink" href="#django.forms.Form.field_order" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<p>By default <code class="docutils literal notranslate"><span class="pre">Form.field_order=None</span></code>, which retains the order in which you
define the fields in your form class. If <code class="docutils literal notranslate"><span class="pre">field_order</span></code> is a list of field
names, the fields are ordered as specified by the list and remaining fields are
appended according to the default order. Unknown field names in the list are
ignored. This makes it possible to disable a field in a subclass by setting it
to <code class="docutils literal notranslate"><span class="pre">None</span></code> without having to redefine ordering.</p>
<p>You can also use the <code class="docutils literal notranslate"><span class="pre">Form.field_order</span></code> argument to a <a class="reference internal" href="#django.forms.Form" title="django.forms.Form"><code class="xref py py-class docutils literal notranslate"><span class="pre">Form</span></code></a> to
override the field order. If a <a class="reference internal" href="#django.forms.Form" title="django.forms.Form"><code class="xref py py-class docutils literal notranslate"><span class="pre">Form</span></code></a> defines
<a class="reference internal" href="#django.forms.Form.field_order" title="django.forms.Form.field_order"><code class="xref py py-attr docutils literal notranslate"><span class="pre">field_order</span></code></a> <em>and</em> you include <code class="docutils literal notranslate"><span class="pre">field_order</span></code> when instantiating
the <code class="docutils literal notranslate"><span class="pre">Form</span></code>, then the latter <code class="docutils literal notranslate"><span class="pre">field_order</span></code> will have precedence.</p>
<dl class="method">
<dt id="django.forms.Form.order_fields">
<code class="descclassname">Form.</code><code class="descname">order_fields</code>(<em>field_order</em>)<a class="headerlink" href="#django.forms.Form.order_fields" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<p>You may rearrange the fields any time using <code class="docutils literal notranslate"><span class="pre">order_fields()</span></code> with a list of
field names as in <a class="reference internal" href="#django.forms.Form.field_order" title="django.forms.Form.field_order"><code class="xref py py-attr docutils literal notranslate"><span class="pre">field_order</span></code></a>.</p>
</div>
<div class="section" id="s-how-errors-are-displayed">
<span id="how-errors-are-displayed"></span><h3>How errors are displayed<a class="headerlink" href="#how-errors-are-displayed" title="Permalink to this headline">¶</a></h3>
<p>If you render a bound <code class="docutils literal notranslate"><span class="pre">Form</span></code> object, the act of rendering will automatically
run the form’s validation if it hasn’t already happened, and the HTML output
will include the validation errors as a <code class="docutils literal notranslate"><span class="pre"><ul</span> <span class="pre">class="errorlist"></span></code> near the
field. The particular positioning of the error messages depends on the output
method you’re using:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">data</span> <span class="o">=</span> <span class="p">{</span><span class="s1">'subject'</span><span class="p">:</span> <span class="s1">''</span><span class="p">,</span>
<span class="gp">... </span> <span class="s1">'message'</span><span class="p">:</span> <span class="s1">'Hi there'</span><span class="p">,</span>
<span class="gp">... </span> <span class="s1">'sender'</span><span class="p">:</span> <span class="s1">'invalid email address'</span><span class="p">,</span>
<span class="gp">... </span> <span class="s1">'cc_myself'</span><span class="p">:</span> <span class="kc">True</span><span class="p">}</span>
<span class="gp">>>> </span><span class="n">f</span> <span class="o">=</span> <span class="n">ContactForm</span><span class="p">(</span><span class="n">data</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="nb">print</span><span class="p">(</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>Subject:</th><td><ul class="errorlist"><li>This field is required.</li></ul><input type="text" name="subject" maxlength="100" required /></td></tr></span>
<span class="go"><tr><th>Message:</th><td><input type="text" name="message" value="Hi there" required /></td></tr></span>
<span class="go"><tr><th>Sender:</th><td><ul class="errorlist"><li>Enter a valid email address.</li></ul><input type="email" name="sender" value="invalid email address" required /></td></tr></span>
<span class="go"><tr><th>Cc myself:</th><td><input checked type="checkbox" name="cc_myself" /></td></tr></span>
<span class="gp">>>> </span><span class="nb">print</span><span class="p">(</span><span class="n">f</span><span class="o">.</span><span class="n">as_ul</span><span class="p">())</span>
<span class="go"><li><ul class="errorlist"><li>This field is required.</li></ul>Subject: <input type="text" name="subject" maxlength="100" required /></li></span>
<span class="go"><li>Message: <input type="text" name="message" value="Hi there" required /></li></span>
<span class="go"><li><ul class="errorlist"><li>Enter a valid email address.</li></ul>Sender: <input type="email" name="sender" value="invalid email address" required /></li></span>
<span class="go"><li>Cc myself: <input checked type="checkbox" name="cc_myself" /></li></span>
<span class="gp">>>> </span><span class="nb">print</span><span class="p">(</span><span class="n">f</span><span class="o">.</span><span class="n">as_p</span><span class="p">())</span>
<span class="go"><p><ul class="errorlist"><li>This field is required.</li></ul></p></span>
<span class="go"><p>Subject: <input type="text" name="subject" maxlength="100" required /></p></span>
<span class="go"><p>Message: <input type="text" name="message" value="Hi there" required /></p></span>
<span class="go"><p><ul class="errorlist"><li>Enter a valid email address.</li></ul></p></span>
<span class="go"><p>Sender: <input type="email" name="sender" value="invalid email address" required /></p></span>
<span class="go"><p>Cc myself: <input checked type="checkbox" name="cc_myself" /></p></span>
</pre></div>
</div>
</div>
<div class="section" id="s-customizing-the-error-list-format">
<span id="s-ref-forms-error-list-format"></span><span id="customizing-the-error-list-format"></span><span id="ref-forms-error-list-format"></span><h3>Customizing the error list format<a class="headerlink" href="#customizing-the-error-list-format" title="Permalink to this headline">¶</a></h3>
<p>By default, forms use <code class="docutils literal notranslate"><span class="pre">django.forms.utils.ErrorList</span></code> to format validation
errors. If you’d like to use an alternate class for displaying errors, you can
pass that in at construction time (replace <code class="docutils literal notranslate"><span class="pre">__str__</span></code> by <code class="docutils literal notranslate"><span class="pre">__unicode__</span></code> on
Python 2):</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">django.forms.utils</span> <span class="k">import</span> <span class="n">ErrorList</span>
<span class="gp">>>> </span><span class="k">class</span> <span class="nc">DivErrorList</span><span class="p">(</span><span class="n">ErrorList</span><span class="p">):</span>
<span class="gp">... </span> <span class="k">def</span> <span class="nf">__str__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span> <span class="c1"># __unicode__ on Python 2</span>
<span class="gp">... </span> <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">as_divs</span><span class="p">()</span>
<span class="gp">... </span> <span class="k">def</span> <span class="nf">as_divs</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="gp">... </span> <span class="k">if</span> <span class="ow">not</span> <span class="bp">self</span><span class="p">:</span> <span class="k">return</span> <span class="s1">''</span>
<span class="gp">... </span> <span class="k">return</span> <span class="s1">'<div class="errorlist"></span><span class="si">%s</span><span class="s1"></div>'</span> <span class="o">%</span> <span class="s1">''</span><span class="o">.</span><span class="n">join</span><span class="p">([</span><span class="s1">'<div class="error"></span><span class="si">%s</span><span class="s1"></div>'</span> <span class="o">%</span> <span class="n">e</span> <span class="k">for</span> <span class="n">e</span> <span class="ow">in</span> <span class="bp">self</span><span class="p">])</span>
<span class="gp">>>> </span><span class="n">f</span> <span class="o">=</span> <span class="n">ContactForm</span><span class="p">(</span><span class="n">data</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="n">error_class</span><span class="o">=</span><span class="n">DivErrorList</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">f</span><span class="o">.</span><span class="n">as_p</span><span class="p">()</span>
<span class="go"><div class="errorlist"><div class="error">This field is required.</div></div></span>
<span class="go"><p>Subject: <input type="text" name="subject" maxlength="100" required /></p></span>
<span class="go"><p>Message: <input type="text" name="message" value="Hi there" required /></p></span>
<span class="go"><div class="errorlist"><div class="error">Enter a valid email address.</div></div></span>
<span class="go"><p>Sender: <input type="email" name="sender" value="invalid email address" required /></p></span>
<span class="go"><p>Cc myself: <input checked type="checkbox" name="cc_myself" /></p></span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="s-more-granular-output">
<span id="more-granular-output"></span><h2>More granular output<a class="headerlink" href="#more-granular-output" title="Permalink to this headline">¶</a></h2>
<p>The <code class="docutils literal notranslate"><span class="pre">as_p()</span></code>, <code class="docutils literal notranslate"><span class="pre">as_ul()</span></code>, and <code class="docutils literal notranslate"><span class="pre">as_table()</span></code> methods are simply shortcuts –
they’re not the only way a form object can be displayed.</p>
<dl class="class">
<dt id="django.forms.BoundField">
<em class="property">class </em><code class="descname">BoundField</code><a class="reference internal" href="../../_modules/django/forms/boundfield.html#BoundField"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#django.forms.BoundField" title="Permalink to this definition">¶</a></dt>
<dd><p>Used to display HTML or access attributes for a single field of a
<a class="reference internal" href="#django.forms.Form" title="django.forms.Form"><code class="xref py py-class docutils literal notranslate"><span class="pre">Form</span></code></a> instance.</p>
<p>The <code class="docutils literal notranslate"><span class="pre">__str__()</span></code> (<code class="docutils literal notranslate"><span class="pre">__unicode__</span></code> on Python 2) method of this
object displays the HTML for this field.</p>
</dd></dl>
<p>To retrieve a single <code class="docutils literal notranslate"><span class="pre">BoundField</span></code>, use dictionary lookup syntax on your form
using the field’s name as the key:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">form</span> <span class="o">=</span> <span class="n">ContactForm</span><span class="p">()</span>
<span class="gp">>>> </span><span class="nb">print</span><span class="p">(</span><span class="n">form</span><span class="p">[</span><span class="s1">'subject'</span><span class="p">])</span>
<span class="go"><input id="id_subject" type="text" name="subject" maxlength="100" required /></span>
</pre></div>
</div>
<p>To retrieve all <code class="docutils literal notranslate"><span class="pre">BoundField</span></code> objects, iterate the form:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">form</span> <span class="o">=</span> <span class="n">ContactForm</span><span class="p">()</span>
<span class="gp">>>> </span><span class="k">for</span> <span class="n">boundfield</span> <span class="ow">in</span> <span class="n">form</span><span class="p">:</span> <span class="nb">print</span><span class="p">(</span><span class="n">boundfield</span><span class="p">)</span>
<span class="go"><input id="id_subject" type="text" name="subject" maxlength="100" required /></span>
<span class="go"><input type="text" name="message" id="id_message" required /></span>
<span class="go"><input type="email" name="sender" id="id_sender" required /></span>
<span class="go"><input type="checkbox" name="cc_myself" id="id_cc_myself" /></span>
</pre></div>
</div>
<p>The field-specific output honors the form object’s <code class="docutils literal notranslate"><span class="pre">auto_id</span></code> setting:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">f</span> <span class="o">=</span> <span class="n">ContactForm</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="nb">print</span><span class="p">(</span><span class="n">f</span><span class="p">[</span><span class="s1">'message'</span><span class="p">])</span>
<span class="go"><input type="text" name="message" required /></span>
<span class="gp">>>> </span><span class="n">f</span> <span class="o">=</span> <span class="n">ContactForm</span><span class="p">(</span><span class="n">auto_id</span><span class="o">=</span><span class="s1">'id_</span><span class="si">%s</span><span class="s1">'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="nb">print</span><span class="p">(</span><span class="n">f</span><span class="p">[</span><span class="s1">'message'</span><span class="p">])</span>
<span class="go"><input type="text" name="message" id="id_message" required /></span>
</pre></div>
</div>
<div class="section" id="s-attributes-of-boundfield">
<span id="attributes-of-boundfield"></span><h3>Attributes of <code class="docutils literal notranslate"><span class="pre">BoundField</span></code><a class="headerlink" href="#attributes-of-boundfield" title="Permalink to this headline">¶</a></h3>
<dl class="attribute">
<dt id="django.forms.BoundField.auto_id">
<code class="descclassname">BoundField.</code><code class="descname">auto_id</code><a class="headerlink" href="#django.forms.BoundField.auto_id" title="Permalink to this definition">¶</a></dt>
<dd><p>The HTML ID attribute for this <code class="docutils literal notranslate"><span class="pre">BoundField</span></code>. Returns an empty string
if <a class="reference internal" href="#django.forms.Form.auto_id" title="django.forms.Form.auto_id"><code class="xref py py-attr docutils literal notranslate"><span class="pre">Form.auto_id</span></code></a> is <code class="docutils literal notranslate"><span class="pre">False</span></code>.</p>
</dd></dl>
<dl class="attribute">
<dt id="django.forms.BoundField.data">
<code class="descclassname">BoundField.</code><code class="descname">data</code><a class="headerlink" href="#django.forms.BoundField.data" title="Permalink to this definition">¶</a></dt>
<dd><p>This property returns the data for this <a class="reference internal" href="#django.forms.BoundField" title="django.forms.BoundField"><code class="xref py py-class docutils literal notranslate"><span class="pre">BoundField</span></code></a>
extracted by the widget’s <a class="reference internal" href="widgets.html#django.forms.Widget.value_from_datadict" title="django.forms.Widget.value_from_datadict"><code class="xref py py-meth docutils literal notranslate"><span class="pre">value_from_datadict()</span></code></a>
method, or <code class="docutils literal notranslate"><span class="pre">None</span></code> if it wasn’t given:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">unbound_form</span> <span class="o">=</span> <span class="n">ContactForm</span><span class="p">()</span>
<span class="gp">>>> </span><span class="nb">print</span><span class="p">(</span><span class="n">unbound_form</span><span class="p">[</span><span class="s1">'subject'</span><span class="p">]</span><span class="o">.</span><span class="n">data</span><span class="p">)</span>
<span class="go">None</span>
<span class="gp">>>> </span><span class="n">bound_form</span> <span class="o">=</span> <span class="n">ContactForm</span><span class="p">(</span><span class="n">data</span><span class="o">=</span><span class="p">{</span><span class="s1">'subject'</span><span class="p">:</span> <span class="s1">'My Subject'</span><span class="p">})</span>
<span class="gp">>>> </span><span class="nb">print</span><span class="p">(</span><span class="n">bound_form</span><span class="p">[</span><span class="s1">'subject'</span><span class="p">]</span><span class="o">.</span><span class="n">data</span><span class="p">)</span>
<span class="go">My Subject</span>
</pre></div>
</div>
</dd></dl>
<dl class="attribute">
<dt id="django.forms.BoundField.errors">
<code class="descclassname">BoundField.</code><code class="descname">errors</code><a class="headerlink" href="#django.forms.BoundField.errors" title="Permalink to this definition">¶</a></dt>
<dd><p>A <a class="reference internal" href="#ref-forms-error-list-format"><span class="std std-ref">list-like object</span></a> that is displayed
as an HTML <code class="docutils literal notranslate"><span class="pre"><ul</span> <span class="pre">class="errorlist"></span></code> when printed:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">data</span> <span class="o">=</span> <span class="p">{</span><span class="s1">'subject'</span><span class="p">:</span> <span class="s1">'hi'</span><span class="p">,</span> <span class="s1">'message'</span><span class="p">:</span> <span class="s1">''</span><span class="p">,</span> <span class="s1">'sender'</span><span class="p">:</span> <span class="s1">''</span><span class="p">,</span> <span class="s1">'cc_myself'</span><span class="p">:</span> <span class="s1">''</span><span class="p">}</span>
<span class="gp">>>> </span><span class="n">f</span> <span class="o">=</span> <span class="n">ContactForm</span><span class="p">(</span><span class="n">data</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="nb">print</span><span class="p">(</span><span class="n">f</span><span class="p">[</span><span class="s1">'message'</span><span class="p">])</span>
<span class="go"><input type="text" name="message" required /></span>
<span class="gp">>>> </span><span class="n">f</span><span class="p">[</span><span class="s1">'message'</span><span class="p">]</span><span class="o">.</span><span class="n">errors</span>
<span class="go">['This field is required.']</span>
<span class="gp">>>> </span><span class="nb">print</span><span class="p">(</span><span class="n">f</span><span class="p">[</span><span class="s1">'message'</span><span class="p">]</span><span class="o">.</span><span class="n">errors</span><span class="p">)</span>
<span class="go"><ul class="errorlist"><li>This field is required.</li></ul></span>
<span class="gp">>>> </span><span class="n">f</span><span class="p">[</span><span class="s1">'subject'</span><span class="p">]</span><span class="o">.</span><span class="n">errors</span>
<span class="go">[]</span>
<span class="gp">>>> </span><span class="nb">print</span><span class="p">(</span><span class="n">f</span><span class="p">[</span><span class="s1">'subject'</span><span class="p">]</span><span class="o">.</span><span class="n">errors</span><span class="p">)</span>
<span class="gp">>>> </span><span class="nb">str</span><span class="p">(</span><span class="n">f</span><span class="p">[</span><span class="s1">'subject'</span><span class="p">]</span><span class="o">.</span><span class="n">errors</span><span class="p">)</span>
<span class="go">''</span>
</pre></div>
</div>
</dd></dl>
<dl class="attribute">
<dt id="django.forms.BoundField.field">
<code class="descclassname">BoundField.</code><code class="descname">field</code><a class="headerlink" href="#django.forms.BoundField.field" title="Permalink to this definition">¶</a></dt>
<dd><p>The form <a class="reference internal" href="fields.html#django.forms.Field" title="django.forms.Field"><code class="xref py py-class docutils literal notranslate"><span class="pre">Field</span></code></a> instance from the form class that
this <a class="reference internal" href="#django.forms.BoundField" title="django.forms.BoundField"><code class="xref py py-class docutils literal notranslate"><span class="pre">BoundField</span></code></a> wraps.</p>
</dd></dl>
<dl class="attribute">
<dt id="django.forms.BoundField.form">
<code class="descclassname">BoundField.</code><code class="descname">form</code><a class="headerlink" href="#django.forms.BoundField.form" title="Permalink to this definition">¶</a></dt>
<dd><p>The <a class="reference internal" href="#django.forms.Form" title="django.forms.Form"><code class="xref py py-class docutils literal notranslate"><span class="pre">Form</span></code></a> instance this <a class="reference internal" href="#django.forms.BoundField" title="django.forms.BoundField"><code class="xref py py-class docutils literal notranslate"><span class="pre">BoundField</span></code></a>
is bound to.</p>
</dd></dl>
<dl class="attribute">
<dt id="django.forms.BoundField.help_text">
<code class="descclassname">BoundField.</code><code class="descname">help_text</code><a class="headerlink" href="#django.forms.BoundField.help_text" title="Permalink to this definition">¶</a></dt>
<dd><p>The <a class="reference internal" href="fields.html#django.forms.Field.help_text" title="django.forms.Field.help_text"><code class="xref py py-attr docutils literal notranslate"><span class="pre">help_text</span></code></a> of the field.</p>
</dd></dl>
<dl class="attribute">
<dt id="django.forms.BoundField.html_name">
<code class="descclassname">BoundField.</code><code class="descname">html_name</code><a class="headerlink" href="#django.forms.BoundField.html_name" title="Permalink to this definition">¶</a></dt>
<dd><p>The name that will be used in the widget’s HTML <code class="docutils literal notranslate"><span class="pre">name</span></code> attribute. It takes
the form <a class="reference internal" href="#django.forms.Form.prefix" title="django.forms.Form.prefix"><code class="xref py py-attr docutils literal notranslate"><span class="pre">prefix</span></code></a> into account.</p>
</dd></dl>
<dl class="attribute">
<dt id="django.forms.BoundField.id_for_label">
<code class="descclassname">BoundField.</code><code class="descname">id_for_label</code><a class="headerlink" href="#django.forms.BoundField.id_for_label" title="Permalink to this definition">¶</a></dt>
<dd><p>Use this property to render the ID of this field. For example, if you are
manually constructing a <code class="docutils literal notranslate"><span class="pre"><label></span></code> in your template (despite the fact that
<a class="reference internal" href="#django.forms.BoundField.label_tag" title="django.forms.BoundField.label_tag"><code class="xref py py-meth docutils literal notranslate"><span class="pre">label_tag()</span></code></a> will do this for you):</p>
<div class="highlight-html+django notranslate"><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">"</span><span class="cp">{{</span> <span class="nv">form.my_field.id_for_label</span> <span class="cp">}}</span><span class="s">"</span><span class="p">></span>...<span class="p"></</span><span class="nt">label</span><span class="p">></span><span class="cp">{{</span> <span class="nv">my_field</span> <span class="cp">}}</span>
</pre></div>
</div>
<p>By default, this will be the field’s name prefixed by <code class="docutils literal notranslate"><span class="pre">id_</span></code>
(“<code class="docutils literal notranslate"><span class="pre">id_my_field</span></code>” for the example above). You may modify the ID by setting
<a class="reference internal" href="widgets.html#django.forms.Widget.attrs" title="django.forms.Widget.attrs"><code class="xref py py-attr docutils literal notranslate"><span class="pre">attrs</span></code></a> on the field’s widget. For example,
declaring a field like this:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">my_field</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">'id'</span><span class="p">:</span> <span class="s1">'myFIELD'</span><span class="p">}))</span>
</pre></div>
</div>
<p>and using the template above, would render something like:</p>
<div class="highlight-html notranslate"><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">"myFIELD"</span><span class="p">></span>...<span class="p"></</span><span class="nt">label</span><span class="p">><</span><span class="nt">input</span> <span class="na">id</span><span class="o">=</span><span class="s">"myFIELD"</span> <span class="na">type</span><span class="o">=</span><span class="s">"text"</span> <span class="na">name</span><span class="o">=</span><span class="s">"my_field"</span> <span class="na">required</span> <span class="p">/></span>
</pre></div>
</div>
</dd></dl>
<dl class="attribute">
<dt id="django.forms.BoundField.is_hidden">
<code class="descclassname">BoundField.</code><code class="descname">is_hidden</code><a class="headerlink" href="#django.forms.BoundField.is_hidden" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns <code class="docutils literal notranslate"><span class="pre">True</span></code> if this <a class="reference internal" href="#django.forms.BoundField" title="django.forms.BoundField"><code class="xref py py-class docutils literal notranslate"><span class="pre">BoundField</span></code></a>’s widget is
hidden.</p>
</dd></dl>
<dl class="attribute">
<dt id="django.forms.BoundField.label">
<code class="descclassname">BoundField.</code><code class="descname">label</code><a class="headerlink" href="#django.forms.BoundField.label" title="Permalink to this definition">¶</a></dt>
<dd><p>The <a class="reference internal" href="fields.html#django.forms.Field.label" title="django.forms.Field.label"><code class="xref py py-attr docutils literal notranslate"><span class="pre">label</span></code></a> of the field. This is used in
<a class="reference internal" href="#django.forms.BoundField.label_tag" title="django.forms.BoundField.label_tag"><code class="xref py py-meth docutils literal notranslate"><span class="pre">label_tag()</span></code></a>.</p>
</dd></dl>
<dl class="attribute">
<dt id="django.forms.BoundField.name">
<code class="descclassname">BoundField.</code><code class="descname">name</code><a class="headerlink" href="#django.forms.BoundField.name" title="Permalink to this definition">¶</a></dt>
<dd><p>The name of this field in the form:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">f</span> <span class="o">=</span> <span class="n">ContactForm</span><span class="p">()</span>
<span class="gp">>>> </span><span class="nb">print</span><span class="p">(</span><span class="n">f</span><span class="p">[</span><span class="s1">'subject'</span><span class="p">]</span><span class="o">.</span><span class="n">name</span><span class="p">)</span>
<span class="go">subject</span>
<span class="gp">>>> </span><span class="nb">print</span><span class="p">(</span><span class="n">f</span><span class="p">[</span><span class="s1">'message'</span><span class="p">]</span><span class="o">.</span><span class="n">name</span><span class="p">)</span>
<span class="go">message</span>
</pre></div>
</div>
</dd></dl>
</div>
<div class="section" id="s-methods-of-boundfield">
<span id="methods-of-boundfield"></span><h3>Methods of <code class="docutils literal notranslate"><span class="pre">BoundField</span></code><a class="headerlink" href="#methods-of-boundfield" title="Permalink to this headline">¶</a></h3>
<dl class="method">
<dt id="django.forms.BoundField.as_hidden">
<code class="descclassname">BoundField.</code><code class="descname">as_hidden</code>(<em>attrs=None</em>, <em>**kwargs</em>)<a class="reference internal" href="../../_modules/django/forms/boundfield.html#BoundField.as_hidden"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#django.forms.BoundField.as_hidden" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns a string of HTML for representing this as an <code class="docutils literal notranslate"><span class="pre"><input</span> <span class="pre">type="hidden"></span></code>.</p>
<p><code class="docutils literal notranslate"><span class="pre">**kwargs</span></code> are passed to <a class="reference internal" href="#django.forms.BoundField.as_widget" title="django.forms.BoundField.as_widget"><code class="xref py py-meth docutils literal notranslate"><span class="pre">as_widget()</span></code></a>.</p>
<p>This method is primarily used internally. You should use a widget instead.</p>
</dd></dl>
<dl class="method">
<dt id="django.forms.BoundField.as_widget">
<code class="descclassname">BoundField.</code><code class="descname">as_widget</code>(<em>widget=None</em>, <em>attrs=None</em>, <em>only_initial=False</em>)<a class="reference internal" href="../../_modules/django/forms/boundfield.html#BoundField.as_widget"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#django.forms.BoundField.as_widget" title="Permalink to this definition">¶</a></dt>
<dd><p>Renders the field by rendering the passed widget, adding any HTML
attributes passed as <code class="docutils literal notranslate"><span class="pre">attrs</span></code>. If no widget is specified, then the
field’s default widget will be used.</p>
<p><code class="docutils literal notranslate"><span class="pre">only_initial</span></code> is used by Django internals and should not be set
explicitly.</p>
</dd></dl>
<dl class="method">
<dt id="django.forms.BoundField.css_classes">
<code class="descclassname">BoundField.</code><code class="descname">css_classes</code>()<a class="reference internal" href="../../_modules/django/forms/boundfield.html#BoundField.css_classes"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#django.forms.BoundField.css_classes" title="Permalink to this definition">¶</a></dt>
<dd><p>When you use Django’s rendering shortcuts, CSS classes are used to
indicate required form fields or fields that contain errors. If you’re
manually rendering a form, you can access these CSS classes using the
<code class="docutils literal notranslate"><span class="pre">css_classes</span></code> method:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">f</span> <span class="o">=</span> <span class="n">ContactForm</span><span class="p">(</span><span class="n">data</span><span class="o">=</span><span class="p">{</span><span class="s1">'message'</span><span class="p">:</span> <span class="s1">''</span><span class="p">})</span>
<span class="gp">>>> </span><span class="n">f</span><span class="p">[</span><span class="s1">'message'</span><span class="p">]</span><span class="o">.</span><span class="n">css_classes</span><span class="p">()</span>
<span class="go">'required'</span>
</pre></div>
</div>
<p>If you want to provide some additional classes in addition to the
error and required classes that may be required, you can provide
those classes as an argument:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">f</span> <span class="o">=</span> <span class="n">ContactForm</span><span class="p">(</span><span class="n">data</span><span class="o">=</span><span class="p">{</span><span class="s1">'message'</span><span class="p">:</span> <span class="s1">''</span><span class="p">})</span>
<span class="gp">>>> </span><span class="n">f</span><span class="p">[</span><span class="s1">'message'</span><span class="p">]</span><span class="o">.</span><span class="n">css_classes</span><span class="p">(</span><span class="s1">'foo bar'</span><span class="p">)</span>
<span class="go">'foo bar required'</span>
</pre></div>
</div>
</dd></dl>
<dl class="method">
<dt id="django.forms.BoundField.label_tag">
<code class="descclassname">BoundField.</code><code class="descname">label_tag</code>(<em>contents=None</em>, <em>attrs=None</em>, <em>label_suffix=None</em>)<a class="reference internal" href="../../_modules/django/forms/boundfield.html#BoundField.label_tag"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#django.forms.BoundField.label_tag" title="Permalink to this definition">¶</a></dt>
<dd><p>To separately render the label tag of a form field, you can call its
<code class="docutils literal notranslate"><span class="pre">label_tag()</span></code> method:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">f</span> <span class="o">=</span> <span class="n">ContactForm</span><span class="p">(</span><span class="n">data</span><span class="o">=</span><span class="p">{</span><span class="s1">'message'</span><span class="p">:</span> <span class="s1">''</span><span class="p">})</span>
<span class="gp">>>> </span><span class="nb">print</span><span class="p">(</span><span class="n">f</span><span class="p">[</span><span class="s1">'message'</span><span class="p">]</span><span class="o">.</span><span class="n">label_tag</span><span class="p">())</span>
<span class="go"><label for="id_message">Message:</label></span>
</pre></div>
</div>
<p>You can provide the <code class="docutils literal notranslate"><span class="pre">contents</span></code> parameter which will replace the
auto-generated label tag. An <code class="docutils literal notranslate"><span class="pre">attrs</span></code> dictionary may contain additional
attributes for the <code class="docutils literal notranslate"><span class="pre"><label></span></code> tag.</p>
<p>The HTML that’s generated includes the form’s
<a class="reference internal" href="#django.forms.Form.label_suffix" title="django.forms.Form.label_suffix"><code class="xref py py-attr docutils literal notranslate"><span class="pre">label_suffix</span></code></a> (a colon, by default) or, if set, the
current field’s <a class="reference internal" href="fields.html#django.forms.Field.label_suffix" title="django.forms.Field.label_suffix"><code class="xref py py-attr docutils literal notranslate"><span class="pre">label_suffix</span></code></a>. The optional
<code class="docutils literal notranslate"><span class="pre">label_suffix</span></code> parameter allows you to override any previously set
suffix. For example, you can use an empty string to hide the label on selected
fields. If you need to do this in a template, you could write a custom
filter to allow passing parameters to <code class="docutils literal notranslate"><span class="pre">label_tag</span></code>.</p>
</dd></dl>
<dl class="method">
<dt id="django.forms.BoundField.value">
<code class="descclassname">BoundField.</code><code class="descname">value</code>()<a class="reference internal" href="../../_modules/django/forms/boundfield.html#BoundField.value"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#django.forms.BoundField.value" title="Permalink to this definition">¶</a></dt>
<dd><p>Use this method to render the raw value of this field as it would be rendered
by a <code class="docutils literal notranslate"><span class="pre">Widget</span></code>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">initial</span> <span class="o">=</span> <span class="p">{</span><span class="s1">'subject'</span><span class="p">:</span> <span class="s1">'welcome'</span><span class="p">}</span>
<span class="gp">>>> </span><span class="n">unbound_form</span> <span class="o">=</span> <span class="n">ContactForm</span><span class="p">(</span><span class="n">initial</span><span class="o">=</span><span class="n">initial</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">bound_form</span> <span class="o">=</span> <span class="n">ContactForm</span><span class="p">(</span><span class="n">data</span><span class="o">=</span><span class="p">{</span><span class="s1">'subject'</span><span class="p">:</span> <span class="s1">'hi'</span><span class="p">},</span> <span class="n">initial</span><span class="o">=</span><span class="n">initial</span><span class="p">)</span>
<span class="gp">>>> </span><span class="nb">print</span><span class="p">(</span><span class="n">unbound_form</span><span class="p">[</span><span class="s1">'subject'</span><span class="p">]</span><span class="o">.</span><span class="n">value</span><span class="p">())</span>
<span class="go">welcome</span>
<span class="gp">>>> </span><span class="nb">print</span><span class="p">(</span><span class="n">bound_form</span><span class="p">[</span><span class="s1">'subject'</span><span class="p">]</span><span class="o">.</span><span class="n">value</span><span class="p">())</span>
<span class="go">hi</span>
</pre></div>
</div>
</dd></dl>
</div>
</div>
<div class="section" id="s-customizing-boundfield">
<span id="customizing-boundfield"></span><h2>Customizing <code class="docutils literal notranslate"><span class="pre">BoundField</span></code><a class="headerlink" href="#customizing-boundfield" title="Permalink to this headline">¶</a></h2>
<p>If you need to access some additional information about a form field in a
template and using a subclass of <a class="reference internal" href="fields.html#django.forms.Field" title="django.forms.Field"><code class="xref py py-class docutils literal notranslate"><span class="pre">Field</span></code></a> isn’t
sufficient, consider also customizing <a class="reference internal" href="#django.forms.BoundField" title="django.forms.BoundField"><code class="xref py py-class docutils literal notranslate"><span class="pre">BoundField</span></code></a>.</p>
<p>A custom form field can override <code class="docutils literal notranslate"><span class="pre">get_bound_field()</span></code>:</p>
<dl class="method">
<dt id="django.forms.Field.get_bound_field">
<code class="descclassname">Field.</code><code class="descname">get_bound_field</code>(<em>form</em>, <em>field_name</em>)<a class="reference internal" href="../../_modules/django/forms/fields.html#Field.get_bound_field"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#django.forms.Field.get_bound_field" title="Permalink to this definition">¶</a></dt>
<dd><p>Takes an instance of <a class="reference internal" href="#django.forms.Form" title="django.forms.Form"><code class="xref py py-class docutils literal notranslate"><span class="pre">Form</span></code></a> and the name of the field.
The return value will be used when accessing the field in a template. Most
likely it will be an instance of a subclass of
<a class="reference internal" href="#django.forms.BoundField" title="django.forms.BoundField"><code class="xref py py-class docutils literal notranslate"><span class="pre">BoundField</span></code></a>.</p>
</dd></dl>
<p>If you have a <code class="docutils literal notranslate"><span class="pre">GPSCoordinatesField</span></code>, for example, and want to be able to
access additional information about the coordinates in a template, this could
be implemented as follows:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">GPSCoordinatesBoundField</span><span class="p">(</span><span class="n">BoundField</span><span class="p">):</span>
<span class="nd">@property</span>
<span class="k">def</span> <span class="nf">country</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="sd">"""</span>
<span class="sd"> Return the country the coordinates lie in or None if it can't be</span>
<span class="sd"> determined.</span>
<span class="sd"> """</span>
<span class="n">value</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</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="n">get_country_from_coordinates</span><span class="p">(</span><span class="n">value</span><span class="p">)</span>
<span class="k">else</span><span class="p">:</span>
<span class="k">return</span> <span class="kc">None</span>
<span class="k">class</span> <span class="nc">GPSCoordinatesField</span><span class="p">(</span><span class="n">Field</span><span class="p">):</span>
<span class="k">def</span> <span class="nf">get_bound_field</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">form</span><span class="p">,</span> <span class="n">field_name</span><span class="p">):</span>
<span class="k">return</span> <span class="n">GPSCoordinatesBoundField</span><span class="p">(</span><span class="n">form</span><span class="p">,</span> <span class="bp">self</span><span class="p">,</span> <span class="n">field_name</span><span class="p">)</span>
</pre></div>
</div>
<p>Now you can access the country in a template with
<code class="docutils literal notranslate"><span class="pre">{{</span> <span class="pre">form.coordinates.country</span> <span class="pre">}}</span></code>.</p>
</div>
<div class="section" id="s-binding-uploaded-files-to-a-form">
<span id="s-binding-uploaded-files"></span><span id="binding-uploaded-files-to-a-form"></span><span id="binding-uploaded-files"></span><h2>Binding uploaded files to a form<a class="headerlink" href="#binding-uploaded-files-to-a-form" title="Permalink to this headline">¶</a></h2>
<p>Dealing with forms that have <code class="docutils literal notranslate"><span class="pre">FileField</span></code> and <code class="docutils literal notranslate"><span class="pre">ImageField</span></code> fields
is a little more complicated than a normal form.</p>
<p>Firstly, in order to upload files, you’ll need to make sure that your
<code class="docutils literal notranslate"><span class="pre"><form></span></code> element correctly defines the <code class="docutils literal notranslate"><span class="pre">enctype</span></code> as
<code class="docutils literal notranslate"><span class="pre">"multipart/form-data"</span></code>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o"><</span><span class="n">form</span> <span class="n">enctype</span><span class="o">=</span><span class="s2">"multipart/form-data"</span> <span class="n">method</span><span class="o">=</span><span class="s2">"post"</span> <span class="n">action</span><span class="o">=</span><span class="s2">"/foo/"</span><span class="o">></span>
</pre></div>
</div>
<p>Secondly, when you use the form, you need to bind the file data. File
data is handled separately to normal form data, so when your form
contains a <code class="docutils literal notranslate"><span class="pre">FileField</span></code> and <code class="docutils literal notranslate"><span class="pre">ImageField</span></code>, you will need to specify
a second argument when you bind your form. So if we extend our
ContactForm to include an <code class="docutils literal notranslate"><span class="pre">ImageField</span></code> called <code class="docutils literal notranslate"><span class="pre">mugshot</span></code>, we
need to bind the file data containing the mugshot image:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># Bound form with an image field</span>
<span class="o">>>></span> <span class="kn">from</span> <span class="nn">django.core.files.uploadedfile</span> <span class="k">import</span> <span class="n">SimpleUploadedFile</span>
<span class="o">>>></span> <span class="n">data</span> <span class="o">=</span> <span class="p">{</span><span class="s1">'subject'</span><span class="p">:</span> <span class="s1">'hello'</span><span class="p">,</span>
<span class="o">...</span> <span class="s1">'message'</span><span class="p">:</span> <span class="s1">'Hi there'</span><span class="p">,</span>
<span class="o">...</span> <span class="s1">'sender'</span><span class="p">:</span> <span class="s1">'foo@example.com'</span><span class="p">,</span>
<span class="o">...</span> <span class="s1">'cc_myself'</span><span class="p">:</span> <span class="kc">True</span><span class="p">}</span>
<span class="o">>>></span> <span class="n">file_data</span> <span class="o">=</span> <span class="p">{</span><span class="s1">'mugshot'</span><span class="p">:</span> <span class="n">SimpleUploadedFile</span><span class="p">(</span><span class="s1">'face.jpg'</span><span class="p">,</span> <span class="o"><</span><span class="n">file</span> <span class="n">data</span><span class="o">></span><span class="p">)}</span>
<span class="o">>>></span> <span class="n">f</span> <span class="o">=</span> <span class="n">ContactFormWithMugshot</span><span class="p">(</span><span class="n">data</span><span class="p">,</span> <span class="n">file_data</span><span class="p">)</span>
</pre></div>
</div>
<p>In practice, you will usually specify <code class="docutils literal notranslate"><span class="pre">request.FILES</span></code> as the source
of file data (just like you use <code class="docutils literal notranslate"><span class="pre">request.POST</span></code> as the source of
form data):</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># Bound form with an image field, data from the request</span>
<span class="o">>>></span> <span class="n">f</span> <span class="o">=</span> <span class="n">ContactFormWithMugshot</span><span class="p">(</span><span class="n">request</span><span class="o">.</span><span class="n">POST</span><span class="p">,</span> <span class="n">request</span><span class="o">.</span><span class="n">FILES</span><span class="p">)</span>
</pre></div>
</div>
<p>Constructing an unbound form is the same as always – just omit both
form data <em>and</em> file data:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># Unbound form with an image field</span>
<span class="o">>>></span> <span class="n">f</span> <span class="o">=</span> <span class="n">ContactFormWithMugshot</span><span class="p">()</span>
</pre></div>
</div>
<div class="section" id="s-testing-for-multipart-forms">
<span id="testing-for-multipart-forms"></span><h3>Testing for multipart forms<a class="headerlink" href="#testing-for-multipart-forms" title="Permalink to this headline">¶</a></h3>
<dl class="method">
<dt id="django.forms.Form.is_multipart">
<code class="descclassname">Form.</code><code class="descname">is_multipart</code>()<a class="headerlink" href="#django.forms.Form.is_multipart" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<p>If you’re writing reusable views or templates, you may not know ahead of time
whether your form is a multipart form or not. The <code class="docutils literal notranslate"><span class="pre">is_multipart()</span></code> method
tells you whether the form requires multipart encoding for submission:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">f</span> <span class="o">=</span> <span class="n">ContactFormWithMugshot</span><span class="p">()</span>
<span class="gp">>>> </span><span class="n">f</span><span class="o">.</span><span class="n">is_multipart</span><span class="p">()</span>
<span class="go">True</span>
</pre></div>
</div>
<p>Here’s an example of how you might use this in a template:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">{</span><span class="o">%</span> <span class="k">if</span> <span class="n">form</span><span class="o">.</span><span class="n">is_multipart</span> <span class="o">%</span><span class="p">}</span>
<span class="o"><</span><span class="n">form</span> <span class="n">enctype</span><span class="o">=</span><span class="s2">"multipart/form-data"</span> <span class="n">method</span><span class="o">=</span><span class="s2">"post"</span> <span class="n">action</span><span class="o">=</span><span class="s2">"/foo/"</span><span class="o">></span>
<span class="p">{</span><span class="o">%</span> <span class="k">else</span> <span class="o">%</span><span class="p">}</span>
<span class="o"><</span><span class="n">form</span> <span class="n">method</span><span class="o">=</span><span class="s2">"post"</span> <span class="n">action</span><span class="o">=</span><span class="s2">"/foo/"</span><span class="o">></span>
<span class="p">{</span><span class="o">%</span> <span class="n">endif</span> <span class="o">%</span><span class="p">}</span>
<span class="p">{{</span> <span class="n">form</span> <span class="p">}}</span>
<span class="o"></</span><span class="n">form</span><span class="o">></span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="s-subclassing-forms">
<span id="subclassing-forms"></span><h2>Subclassing forms<a class="headerlink" href="#subclassing-forms" title="Permalink to this headline">¶</a></h2>
<p>If you have multiple <code class="docutils literal notranslate"><span class="pre">Form</span></code> classes that share fields, you can use
subclassing to remove redundancy.</p>
<p>When you subclass a custom <code class="docutils literal notranslate"><span class="pre">Form</span></code> class, the resulting subclass will
include all fields of the parent class(es), followed by the fields you define
in the subclass.</p>
<p>In this example, <code class="docutils literal notranslate"><span class="pre">ContactFormWithPriority</span></code> contains all the fields from
<code class="docutils literal notranslate"><span class="pre">ContactForm</span></code>, plus an additional field, <code class="docutils literal notranslate"><span class="pre">priority</span></code>. The <code class="docutils literal notranslate"><span class="pre">ContactForm</span></code>
fields are ordered first:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="k">class</span> <span class="nc">ContactFormWithPriority</span><span class="p">(</span><span class="n">ContactForm</span><span class="p">):</span>
<span class="gp">... </span> <span class="n">priority</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="gp">>>> </span><span class="n">f</span> <span class="o">=</span> <span class="n">ContactFormWithPriority</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="nb">print</span><span class="p">(</span><span class="n">f</span><span class="o">.</span><span class="n">as_ul</span><span class="p">())</span>
<span class="go"><li>Subject: <input type="text" name="subject" maxlength="100" required /></li></span>
<span class="go"><li>Message: <input type="text" name="message" required /></li></span>
<span class="go"><li>Sender: <input type="email" name="sender" required /></li></span>
<span class="go"><li>Cc myself: <input type="checkbox" name="cc_myself" /></li></span>
<span class="go"><li>Priority: <input type="text" name="priority" required /></li></span>
</pre></div>
</div>
<p>It’s possible to subclass multiple forms, treating forms as mixins. In this
example, <code class="docutils literal notranslate"><span class="pre">BeatleForm</span></code> subclasses both <code class="docutils literal notranslate"><span class="pre">PersonForm</span></code> and <code class="docutils literal notranslate"><span class="pre">InstrumentForm</span></code>
(in that order), and its field list includes the fields from the parent
classes:</p>
<div class="highlight-default notranslate"><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="k">class</span> <span class="nc">PersonForm</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="gp">... </span> <span class="n">first_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="gp">... </span> <span class="n">last_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="gp">>>> </span><span class="k">class</span> <span class="nc">InstrumentForm</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="gp">... </span> <span class="n">instrument</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="gp">>>> </span><span class="k">class</span> <span class="nc">BeatleForm</span><span class="p">(</span><span class="n">InstrumentForm</span><span class="p">,</span> <span class="n">PersonForm</span><span class="p">):</span>
<span class="gp">... </span> <span class="n">haircut_type</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="gp">>>> </span><span class="n">b</span> <span class="o">=</span> <span class="n">BeatleForm</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="nb">print</span><span class="p">(</span><span class="n">b</span><span class="o">.</span><span class="n">as_ul</span><span class="p">())</span>
<span class="go"><li>First name: <input type="text" name="first_name" required /></li></span>
<span class="go"><li>Last name: <input type="text" name="last_name" required /></li></span>
<span class="go"><li>Instrument: <input type="text" name="instrument" required /></li></span>
<span class="go"><li>Haircut type: <input type="text" name="haircut_type" required /></li></span>
</pre></div>
</div>
<p>It’s possible to declaratively remove a <code class="docutils literal notranslate"><span class="pre">Field</span></code> inherited from a parent class
by setting the name of the field to <code class="docutils literal notranslate"><span class="pre">None</span></code> on the subclass. For example:</p>
<div class="highlight-default notranslate"><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="k">class</span> <span class="nc">ParentForm</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="gp">... </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="gp">... </span> <span class="n">age</span> <span class="o">=</span> <span class="n">forms</span><span class="o">.</span><span class="n">IntegerField</span><span class="p">()</span>
<span class="gp">>>> </span><span class="k">class</span> <span class="nc">ChildForm</span><span class="p">(</span><span class="n">ParentForm</span><span class="p">):</span>
<span class="gp">... </span> <span class="n">name</span> <span class="o">=</span> <span class="kc">None</span>
<span class="gp">>>> </span><span class="nb">list</span><span class="p">(</span><span class="n">ChildForm</span><span class="p">()</span><span class="o">.</span><span class="n">fields</span><span class="p">)</span>
<span class="go">['age']</span>
</pre></div>
</div>
</div>
<div class="section" id="s-prefixes-for-forms">
<span id="s-form-prefix"></span><span id="prefixes-for-forms"></span><span id="form-prefix"></span><h2>Prefixes for forms<a class="headerlink" href="#prefixes-for-forms" title="Permalink to this headline">¶</a></h2>
<dl class="attribute">
<dt id="django.forms.Form.prefix">
<code class="descclassname">Form.</code><code class="descname">prefix</code><a class="headerlink" href="#django.forms.Form.prefix" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<p>You can put several Django forms inside one <code class="docutils literal notranslate"><span class="pre"><form></span></code> tag. To give each
<code class="docutils literal notranslate"><span class="pre">Form</span></code> its own namespace, use the <code class="docutils literal notranslate"><span class="pre">prefix</span></code> keyword argument:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">mother</span> <span class="o">=</span> <span class="n">PersonForm</span><span class="p">(</span><span class="n">prefix</span><span class="o">=</span><span class="s2">"mother"</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">father</span> <span class="o">=</span> <span class="n">PersonForm</span><span class="p">(</span><span class="n">prefix</span><span class="o">=</span><span class="s2">"father"</span><span class="p">)</span>
<span class="gp">>>> </span><span class="nb">print</span><span class="p">(</span><span class="n">mother</span><span class="o">.</span><span class="n">as_ul</span><span class="p">())</span>
<span class="go"><li><label for="id_mother-first_name">First name:</label> <input type="text" name="mother-first_name" id="id_mother-first_name" required /></li></span>
<span class="go"><li><label for="id_mother-last_name">Last name:</label> <input type="text" name="mother-last_name" id="id_mother-last_name" required /></li></span>
<span class="gp">>>> </span><span class="nb">print</span><span class="p">(</span><span class="n">father</span><span class="o">.</span><span class="n">as_ul</span><span class="p">())</span>
<span class="go"><li><label for="id_father-first_name">First name:</label> <input type="text" name="father-first_name" id="id_father-first_name" required /></li></span>
<span class="go"><li><label for="id_father-last_name">Last name:</label> <input type="text" name="father-last_name" id="id_father-last_name" required /></li></span>
</pre></div>
</div>
<p>The prefix can also be specified on the form class:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="k">class</span> <span class="nc">PersonForm</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="gp">... </span> <span class="o">...</span>
<span class="gp">... </span> <span class="n">prefix</span> <span class="o">=</span> <span class="s1">'person'</span>
</pre></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="#">The Forms API</a><ul>
<li><a class="reference internal" href="#bound-and-unbound-forms">Bound and unbound forms</a></li>
<li><a class="reference internal" href="#using-forms-to-validate-data">Using forms to validate data</a><ul>
<li><a class="reference internal" href="#behavior-of-unbound-forms">Behavior of unbound forms</a></li>
</ul>
</li>
<li><a class="reference internal" href="#dynamic-initial-values">Dynamic initial values</a></li>
<li><a class="reference internal" href="#checking-which-form-data-has-changed">Checking which form data has changed</a></li>
<li><a class="reference internal" href="#accessing-the-fields-from-the-form">Accessing the fields from the form</a></li>
<li><a class="reference internal" href="#accessing-clean-data">Accessing “clean” data</a></li>
<li><a class="reference internal" href="#outputting-forms-as-html">Outputting forms as HTML</a><ul>
<li><a class="reference internal" href="#as-p"><code class="docutils literal notranslate"><span class="pre">as_p()</span></code></a></li>
<li><a class="reference internal" href="#as-ul"><code class="docutils literal notranslate"><span class="pre">as_ul()</span></code></a></li>
<li><a class="reference internal" href="#as-table"><code class="docutils literal notranslate"><span class="pre">as_table()</span></code></a></li>
<li><a class="reference internal" href="#styling-required-or-erroneous-form-rows">Styling required or erroneous form rows</a></li>
<li><a class="reference internal" href="#configuring-form-elements-html-id-attributes-and-label-tags">Configuring form elements’ HTML <code class="docutils literal notranslate"><span class="pre">id</span></code> attributes and <code class="docutils literal notranslate"><span class="pre"><label></span></code> tags</a></li>
<li><a class="reference internal" href="#configuring-the-rendering-of-a-form-s-widgets">Configuring the rendering of a form’s widgets</a></li>
<li><a class="reference internal" href="#notes-on-field-ordering">Notes on field ordering</a></li>
<li><a class="reference internal" href="#how-errors-are-displayed">How errors are displayed</a></li>
<li><a class="reference internal" href="#customizing-the-error-list-format">Customizing the error list format</a></li>
</ul>
</li>
<li><a class="reference internal" href="#more-granular-output">More granular output</a><ul>
<li><a class="reference internal" href="#attributes-of-boundfield">Attributes of <code class="docutils literal notranslate"><span class="pre">BoundField</span></code></a></li>
<li><a class="reference internal" href="#methods-of-boundfield">Methods of <code class="docutils literal notranslate"><span class="pre">BoundField</span></code></a></li>
</ul>
</li>
<li><a class="reference internal" href="#customizing-boundfield">Customizing <code class="docutils literal notranslate"><span class="pre">BoundField</span></code></a></li>
<li><a class="reference internal" href="#binding-uploaded-files-to-a-form">Binding uploaded files to a form</a><ul>
<li><a class="reference internal" href="#testing-for-multipart-forms">Testing for multipart forms</a></li>
</ul>
</li>
<li><a class="reference internal" href="#subclassing-forms">Subclassing forms</a></li>
<li><a class="reference internal" href="#prefixes-for-forms">Prefixes for forms</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="index.html"
title="previous chapter">Forms</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="fields.html"
title="next chapter">Form fields</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../../_sources/ref/forms/api.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<h3>Last update:</h3>
<p class="topless">Feb 11, 2019</p>
</div>
</div>
<div id="ft">
<div class="nav">
« <a href="index.html" title="Forms">previous</a>
|
<a href="../index.html" title="API Reference" accesskey="U">up</a>
|
<a href="fields.html" title="Form fields">next</a> »</div>
</div>
</div>
<div class="clearer"></div>
</div>
</body>
</html>
