<!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">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>The Forms API — Django v1.2 documentation</title>
<link rel="stylesheet" href="../../_static/default.css" type="text/css" />
<link rel="stylesheet" href="../../_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../../',
VERSION: '1.2',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="../../_static/jquery.js"></script>
<script type="text/javascript" src="../../_static/underscore.js"></script>
<script type="text/javascript" src="../../_static/doctools.js"></script>
<link rel="top" title="Django v1.2 documentation" href="../../index.html" />
<link rel="up" title="Forms" href="index.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 v1.2 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.forms">
<span id="s-the-forms-api"></span><span id="module-django.forms.forms"></span><span id="the-forms-api"></span><h1>The Forms API<a class="headerlink" href="#module-django.forms.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"><em>introduction to working with forms</em></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"><tt class="xref py py-class docutils literal"><span class="pre">Form</span></tt></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><tt class="descname">Form</tt><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"><tt class="xref py py-class docutils literal"><span class="pre">Form</span></tt></a> instance, simply instantiate the class:</p>
<div class="highlight-python"><div class="highlight"><pre><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"><tt class="xref py py-class docutils literal"><span class="pre">Form</span></tt></a> class constructor:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">data</span> <span class="o">=</span> <span class="p">{</span><span class="s">'subject'</span><span class="p">:</span> <span class="s">'hello'</span><span class="p">,</span>
<span class="gp">... </span> <span class="s">'message'</span><span class="p">:</span> <span class="s">'Hi there'</span><span class="p">,</span>
<span class="gp">... </span> <span class="s">'sender'</span><span class="p">:</span> <span class="s">'foo@example.com'</span><span class="p">,</span>
<span class="gp">... </span> <span class="s">'cc_myself'</span><span class="p">:</span> <span class="bp">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"><tt class="xref py py-class docutils literal"><span class="pre">Form</span></tt></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"><tt class="xref py py-class docutils literal"><span class="pre">Field</span></tt></a>, as we'll see
in a moment.</p>
<dl class="attribute">
<dt id="django.forms.Form.is_bound">
<tt class="descclassname">Form.</tt><tt class="descname">is_bound</tt><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"><tt class="xref py py-attr docutils literal"><span class="pre">is_bound</span></tt></a> attribute:</p>
<div class="highlight-python"><div class="highlight"><pre><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="s">'subject'</span><span class="p">:</span> <span class="s">'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-python"><div class="highlight"><pre><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"><tt class="xref py py-class docutils literal"><span class="pre">Form</span></tt></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"><tt class="xref py py-class docutils literal"><span class="pre">Form</span></tt></a> instance to some data, create
another <a class="reference internal" href="#django.forms.Form" title="django.forms.Form"><tt class="xref py py-class docutils literal"><span class="pre">Form</span></tt></a> instance. There is no way to change data in a
<a class="reference internal" href="#django.forms.Form" title="django.forms.Form"><tt class="xref py py-class docutils literal"><span class="pre">Form</span></tt></a> instance. Once a <a class="reference internal" href="#django.forms.Form" title="django.forms.Form"><tt class="xref py py-class docutils literal"><span class="pre">Form</span></tt></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.is_valid">
<tt class="descclassname">Form.</tt><tt class="descname">is_valid</tt>()<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"><tt class="xref py py-class docutils literal"><span class="pre">Form</span></tt></a> object is to validate data. With a bound
<a class="reference internal" href="#django.forms.Form" title="django.forms.Form"><tt class="xref py py-class docutils literal"><span class="pre">Form</span></tt></a> instance, call the <a class="reference internal" href="#django.forms.Form.is_valid" title="django.forms.Form.is_valid"><tt class="xref py py-meth docutils literal"><span class="pre">is_valid()</span></tt></a> method to run validation
and return a boolean designating whether the data was valid:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">data</span> <span class="o">=</span> <span class="p">{</span><span class="s">'subject'</span><span class="p">:</span> <span class="s">'hello'</span><span class="p">,</span>
<span class="gp">... </span> <span class="s">'message'</span><span class="p">:</span> <span class="s">'Hi there'</span><span class="p">,</span>
<span class="gp">... </span> <span class="s">'sender'</span><span class="p">:</span> <span class="s">'foo@example.com'</span><span class="p">,</span>
<span class="gp">... </span> <span class="s">'cc_myself'</span><span class="p">:</span> <span class="bp">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, <tt class="docutils literal"><span class="pre">subject</span></tt> is blank (an error,
because all fields are required by default) and <tt class="docutils literal"><span class="pre">sender</span></tt> is not a valid
e-mail address:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">data</span> <span class="o">=</span> <span class="p">{</span><span class="s">'subject'</span><span class="p">:</span> <span class="s">''</span><span class="p">,</span>
<span class="gp">... </span> <span class="s">'message'</span><span class="p">:</span> <span class="s">'Hi there'</span><span class="p">,</span>
<span class="gp">... </span> <span class="s">'sender'</span><span class="p">:</span> <span class="s">'invalid e-mail address'</span><span class="p">,</span>
<span class="gp">... </span> <span class="s">'cc_myself'</span><span class="p">:</span> <span class="bp">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">
<tt class="descclassname">Form.</tt><tt class="descname">errors</tt><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"><tt class="xref py py-attr docutils literal"><span class="pre">errors</span></tt></a> attribute to get a dictionary of error
messages:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">f</span><span class="o">.</span><span class="n">errors</span>
<span class="go">{'sender': [u'Enter a valid e-mail address.'], 'subject': [u'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"><tt class="xref py py-attr docutils literal"><span class="pre">errors</span></tt></a> without having to call
<a class="reference internal" href="#django.forms.Form.is_valid" title="django.forms.Form.is_valid"><tt class="xref py py-meth docutils literal"><span class="pre">is_valid()</span></tt></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"><tt class="xref py py-meth docutils literal"><span class="pre">is_valid()</span></tt></a> or access <a class="reference internal" href="#django.forms.Form.errors" title="django.forms.Form.errors"><tt class="xref py py-attr docutils literal"><span class="pre">errors</span></tt></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"><tt class="xref py py-attr docutils literal"><span class="pre">errors</span></tt></a> or call <a class="reference internal" href="#django.forms.Form.is_valid" title="django.forms.Form.is_valid"><tt class="xref py py-meth docutils literal"><span class="pre">is_valid()</span></tt></a>. This means that
if validation has side effects, those side effects will only be triggered once.</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-python"><div class="highlight"><pre><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">
<tt class="descclassname">Form.</tt><tt class="descname">initial</tt><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"><tt class="xref py py-attr docutils literal"><span class="pre">initial</span></tt></a> to declare the initial value of form fields at
runtime. For example, you might want to fill in a <tt class="docutils literal"><span class="pre">username</span></tt> 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"><tt class="xref py py-attr docutils literal"><span class="pre">initial</span></tt></a> argument to a <a class="reference internal" href="#django.forms.Form" title="django.forms.Form"><tt class="xref py py-class docutils literal"><span class="pre">Form</span></tt></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-python"><div class="highlight"><pre><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="s">'subject'</span><span class="p">:</span> <span class="s">'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>Note that if a <tt class="xref py py-class docutils literal"><span class="pre">Field</span></tt> defines
<a class="reference internal" href="#django.forms.Form.initial" title="django.forms.Form.initial"><tt class="xref py py-attr docutils literal"><span class="pre">initial</span></tt></a> <em>and</em> you include <tt class="docutils literal"><span class="pre">initial</span></tt> when instantiating the
<tt class="docutils literal"><span class="pre">Form</span></tt>, then the latter <tt class="docutils literal"><span class="pre">initial</span></tt> will have precedence. In this example,
<tt class="docutils literal"><span class="pre">initial</span></tt> is provided both at the field level and at the form instance level,
and the latter gets precedence:</p>
<div class="highlight-python"><div class="highlight"><pre><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="s">'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="s">'name'</span><span class="p">:</span> <span class="s">'instance'</span><span class="p">},</span> <span class="n">auto_id</span><span class="o">=</span><span class="bp">False</span><span class="p">)</span>
<span class="gp">>>> </span><span class="k">print</span> <span class="n">f</span>
<span class="go"><tr><th>Name:</th><td><input type="text" name="name" value="instance" /></td></tr></span>
<span class="go"><tr><th>Url:</th><td><input type="text" name="url" /></td></tr></span>
<span class="go"><tr><th>Comment:</th><td><input type="text" name="comment" /></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">
<tt class="descclassname">Form.</tt><tt class="descname">cleaned_data</tt><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"><tt class="xref py py-class docutils literal"><span class="pre">Form</span></tt></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"><tt class="xref py py-class docutils literal"><span class="pre">DateField</span></tt></a> normalizes input into a
Python <tt class="docutils literal"><span class="pre">datetime.date</span></tt> object. Regardless of whether you pass it a string in
the format <tt class="docutils literal"><span class="pre">'1994-07-15'</span></tt>, a <tt class="docutils literal"><span class="pre">datetime.date</span></tt> object, or a number of other
formats, <tt class="docutils literal"><span class="pre">DateField</span></tt> will always normalize it to a <tt class="docutils literal"><span class="pre">datetime.date</span></tt> 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"><tt class="xref py py-class docutils literal"><span class="pre">Form</span></tt></a> instance with a set of data and validated
it, you can access the clean data via its <tt class="docutils literal"><span class="pre">cleaned_data</span></tt> attribute:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">data</span> <span class="o">=</span> <span class="p">{</span><span class="s">'subject'</span><span class="p">:</span> <span class="s">'hello'</span><span class="p">,</span>
<span class="gp">... </span> <span class="s">'message'</span><span class="p">:</span> <span class="s">'Hi there'</span><span class="p">,</span>
<span class="gp">... </span> <span class="s">'sender'</span><span class="p">:</span> <span class="s">'foo@example.com'</span><span class="p">,</span>
<span class="gp">... </span> <span class="s">'cc_myself'</span><span class="p">:</span> <span class="bp">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': u'Hi there', 'sender': u'foo@example.com', 'subject': u'hello'}</span>
</pre></div>
</div>
<div class="versionchanged">
<span class="title">Changed in Django 1.0:</span> The <tt class="docutils literal"><span class="pre">cleaned_data</span></tt> attribute was called <tt class="docutils literal"><span class="pre">clean_data</span></tt> in earlier releases.</div>
<p>Note that any text-based field -- such as <tt class="docutils literal"><span class="pre">CharField</span></tt> or <tt class="docutils literal"><span class="pre">EmailField</span></tt> --
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, your <tt class="docutils literal"><span class="pre">Form</span></tt> instance will not have a
<tt class="docutils literal"><span class="pre">cleaned_data</span></tt> attribute:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">data</span> <span class="o">=</span> <span class="p">{</span><span class="s">'subject'</span><span class="p">:</span> <span class="s">''</span><span class="p">,</span>
<span class="gp">... </span> <span class="s">'message'</span><span class="p">:</span> <span class="s">'Hi there'</span><span class="p">,</span>
<span class="gp">... </span> <span class="s">'sender'</span><span class="p">:</span> <span class="s">'invalid e-mail address'</span><span class="p">,</span>
<span class="gp">... </span> <span class="s">'cc_myself'</span><span class="p">:</span> <span class="bp">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="gt">Traceback (most recent call last):</span>
<span class="c">...</span>
<span class="nc">AttributeError</span>: <span class="n-Identifier">'ContactForm' object has no attribute 'cleaned_data'</span>
</pre></div>
</div>
<p><tt class="docutils literal"><span class="pre">cleaned_data</span></tt> will always <em>only</em> contain a key for fields defined in the
<tt class="docutils literal"><span class="pre">Form</span></tt>, even if you pass extra data when you define the <tt class="docutils literal"><span class="pre">Form</span></tt>. In this
example, we pass a bunch of extra fields to the <tt class="docutils literal"><span class="pre">ContactForm</span></tt> constructor,
but <tt class="docutils literal"><span class="pre">cleaned_data</span></tt> contains only the form's fields:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">data</span> <span class="o">=</span> <span class="p">{</span><span class="s">'subject'</span><span class="p">:</span> <span class="s">'hello'</span><span class="p">,</span>
<span class="gp">... </span> <span class="s">'message'</span><span class="p">:</span> <span class="s">'Hi there'</span><span class="p">,</span>
<span class="gp">... </span> <span class="s">'sender'</span><span class="p">:</span> <span class="s">'foo@example.com'</span><span class="p">,</span>
<span class="gp">... </span> <span class="s">'cc_myself'</span><span class="p">:</span> <span class="bp">True</span><span class="p">,</span>
<span class="gp">... </span> <span class="s">'extra_field_1'</span><span class="p">:</span> <span class="s">'foo'</span><span class="p">,</span>
<span class="gp">... </span> <span class="s">'extra_field_2'</span><span class="p">:</span> <span class="s">'bar'</span><span class="p">,</span>
<span class="gp">... </span> <span class="s">'extra_field_3'</span><span class="p">:</span> <span class="s">'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="c"># Doesn't contain extra_field_1, etc.</span>
<span class="go">{'cc_myself': True, 'message': u'Hi there', 'sender': u'foo@example.com', 'subject': u'hello'}</span>
</pre></div>
</div>
<p><tt class="docutils literal"><span class="pre">cleaned_data</span></tt> will include a key and value for <em>all</em> fields defined in the
<tt class="docutils literal"><span class="pre">Form</span></tt>, even if the data didn't include a value for fields that are not
required. In this example, the data dictionary doesn't include a value for the
<tt class="docutils literal"><span class="pre">nick_name</span></tt> field, but <tt class="docutils literal"><span class="pre">cleaned_data</span></tt> includes it, with an empty value:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="k">class</span> <span class="nc">OptionalPersonForm</span><span class="p">(</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">CharField</span><span class="p">()</span>
<span class="gp">... </span> <span class="n">last_name</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">CharField</span><span class="p">(</span><span class="n">required</span><span class="o">=</span><span class="bp">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="s">'first_name'</span><span class="p">:</span> <span class="s">u'John'</span><span class="p">,</span> <span class="s">'last_name'</span><span class="p">:</span> <span class="s">u'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': u'', 'first_name': u'John', 'last_name': u'Lennon'}</span>
</pre></div>
</div>
<p>In this above example, the <tt class="docutils literal"><span class="pre">cleaned_data</span></tt> value for <tt class="docutils literal"><span class="pre">nick_name</span></tt> is set to an
empty string, because <tt class="docutils literal"><span class="pre">nick_name</span></tt> is <tt class="docutils literal"><span class="pre">CharField</span></tt>, and <tt class="docutils literal"><span class="pre">CharField</span></tt>s treat
empty values as an empty string. Each field type knows what its "blank" value
is -- e.g., for <tt class="docutils literal"><span class="pre">DateField</span></tt>, it's <tt class="xref docutils literal"><span class="pre">None</span></tt> 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 <tt class="docutils literal"><span class="pre">Field</span></tt> 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"><em>Form and field validation</em></a>.</p>
</div>
<div class="section" id="s-outputting-forms-as-html">
<span id="outputting-forms-as-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 <tt class="docutils literal"><span class="pre">Form</span></tt> object is to render itself as HTML. To do so,
simply <tt class="docutils literal"><span class="pre">print</span></tt> it:</p>
<div class="highlight-python"><div class="highlight"><pre><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="k">print</span> <span class="n">f</span>
<span class="go"><tr><th><label for="id_subject">Subject:</label></th><td><input id="id_subject" type="text" name="subject" maxlength="100" /></td></tr></span>
<span class="go"><tr><th><label for="id_message">Message:</label></th><td><input type="text" name="message" id="id_message" /></td></tr></span>
<span class="go"><tr><th><label for="id_sender">Sender:</label></th><td><input type="text" name="sender" id="id_sender" /></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
<tt class="docutils literal"><span class="pre"><input</span> <span class="pre">type="text"></span></tt>, the data will be in the <tt class="docutils literal"><span class="pre">value</span></tt> attribute. If a
field is represented by an <tt class="docutils literal"><span class="pre"><input</span> <span class="pre">type="checkbox"></span></tt>, then that HTML will
include <tt class="docutils literal"><span class="pre">checked="checked"</span></tt> if appropriate:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">data</span> <span class="o">=</span> <span class="p">{</span><span class="s">'subject'</span><span class="p">:</span> <span class="s">'hello'</span><span class="p">,</span>
<span class="gp">... </span> <span class="s">'message'</span><span class="p">:</span> <span class="s">'Hi there'</span><span class="p">,</span>
<span class="gp">... </span> <span class="s">'sender'</span><span class="p">:</span> <span class="s">'foo@example.com'</span><span class="p">,</span>
<span class="gp">... </span> <span class="s">'cc_myself'</span><span class="p">:</span> <span class="bp">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="k">print</span> <span class="n">f</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" /></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" /></td></tr></span>
<span class="go"><tr><th><label for="id_sender">Sender:</label></th><td><input type="text" name="sender" id="id_sender" value="foo@example.com" /></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="checked" /></td></tr></span>
</pre></div>
</div>
<p>This default output is a two-column HTML table, with a <tt class="docutils literal"><span class="pre"><tr></span></tt> for each field.
Notice the following:</p>
<ul class="simple">
<li>For flexibility, the output does <em>not</em> include the <tt class="docutils literal"><span class="pre"><table></span></tt> and
<tt class="docutils literal"><span class="pre"></table></span></tt> tags, nor does it include the <tt class="docutils literal"><span class="pre"><form></span></tt> and <tt class="docutils literal"><span class="pre"></form></span></tt>
tags or an <tt class="docutils literal"><span class="pre"><input</span> <span class="pre">type="submit"></span></tt> tag. It's your job to do that.</li>
<li>Each field type has a default HTML representation. <tt class="docutils literal"><span class="pre">CharField</span></tt> and
<tt class="docutils literal"><span class="pre">EmailField</span></tt> are represented by an <tt class="docutils literal"><span class="pre"><input</span> <span class="pre">type="text"></span></tt>.
<tt class="docutils literal"><span class="pre">BooleanField</span></tt> is represented by an <tt class="docutils literal"><span class="pre"><input</span> <span class="pre">type="checkbox"></span></tt>. 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 <tt class="docutils literal"><span class="pre">name</span></tt> for each tag is taken directly from its attribute name
in the <tt class="docutils literal"><span class="pre">ContactForm</span></tt> class.</li>
<li>The text label for each field -- e.g. <tt class="docutils literal"><span class="pre">'Subject:'</span></tt>, <tt class="docutils literal"><span class="pre">'Message:'</span></tt> and
<tt class="docutils literal"><span class="pre">'Cc</span> <span class="pre">myself:'</span></tt> 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 <tt class="docutils literal"><span class="pre"><label></span></tt> tag, which points
to the appropriate form field via its <tt class="docutils literal"><span class="pre">id</span></tt>. Its <tt class="docutils literal"><span class="pre">id</span></tt>, in turn, is
generated by prepending <tt class="docutils literal"><span class="pre">'id_'</span></tt> to the field name. The <tt class="docutils literal"><span class="pre">id</span></tt>
attributes and <tt class="docutils literal"><span class="pre"><label></span></tt> tags are included in the output by default, to
follow best practices, but you can change that behavior.</li>
</ul>
<p>Although <tt class="docutils literal"><span class="pre"><table></span></tt> output is the default output style when you <tt class="docutils literal"><span class="pre">print</span></tt> 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><tt class="docutils literal"><span class="pre">as_p()</span></tt><a class="headerlink" href="#as-p" title="Permalink to this headline">¶</a></h3>
<dl class="method">
<dt id="django.forms.Form.as_p">
<tt class="descclassname">Form.</tt><tt class="descname">as_p</tt>()<a class="headerlink" href="#django.forms.Form.as_p" title="Permalink to this definition">¶</a></dt>
<dd><p><tt class="docutils literal"><span class="pre">as_p()</span></tt> renders the form as a series of <tt class="docutils literal"><span class="pre"><p></span></tt> tags, with each <tt class="docutils literal"><span class="pre"><p></span></tt>
containing one field:</p>
<div class="highlight-python"><div class="highlight"><pre><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">u'<p><label for="id_subject">Subject:</label> <input id="id_subject" type="text" name="subject" maxlength="100" /></p>\n<p><label for="id_message">Message:</label> <input type="text" name="message" id="id_message" /></p>\n<p><label for="id_sender">Sender:</label> <input type="text" name="sender" id="id_sender" /></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="k">print</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" /></p></span>
<span class="go"><p><label for="id_message">Message:</label> <input type="text" name="message" id="id_message" /></p></span>
<span class="go"><p><label for="id_sender">Sender:</label> <input type="text" name="sender" id="id_sender" /></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>
</dd></dl>
</div>
<div class="section" id="s-as-ul">
<span id="as-ul"></span><h3><tt class="docutils literal"><span class="pre">as_ul()</span></tt><a class="headerlink" href="#as-ul" title="Permalink to this headline">¶</a></h3>
<dl class="method">
<dt id="django.forms.Form.as_ul">
<tt class="descclassname">Form.</tt><tt class="descname">as_ul</tt>()<a class="headerlink" href="#django.forms.Form.as_ul" title="Permalink to this definition">¶</a></dt>
<dd><p><tt class="docutils literal"><span class="pre">as_ul()</span></tt> renders the form as a series of <tt class="docutils literal"><span class="pre"><li></span></tt> tags, with each
<tt class="docutils literal"><span class="pre"><li></span></tt> containing one field. It does <em>not</em> include the <tt class="docutils literal"><span class="pre"><ul></span></tt> or
<tt class="docutils literal"><span class="pre"></ul></span></tt>, so that you can specify any HTML attributes on the <tt class="docutils literal"><span class="pre"><ul></span></tt> for
flexibility:</p>
<div class="highlight-python"><div class="highlight"><pre><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">u'<li><label for="id_subject">Subject:</label> <input id="id_subject" type="text" name="subject" maxlength="100" /></li>\n<li><label for="id_message">Message:</label> <input type="text" name="message" id="id_message" /></li>\n<li><label for="id_sender">Sender:</label> <input type="text" name="sender" id="id_sender" /></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="k">print</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" /></li></span>
<span class="go"><li><label for="id_message">Message:</label> <input type="text" name="message" id="id_message" /></li></span>
<span class="go"><li><label for="id_sender">Sender:</label> <input type="text" name="sender" id="id_sender" /></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>
</dd></dl>
</div>
<div class="section" id="s-as-table">
<span id="as-table"></span><h3><tt class="docutils literal"><span class="pre">as_table()</span></tt><a class="headerlink" href="#as-table" title="Permalink to this headline">¶</a></h3>
<dl class="method">
<dt id="django.forms.Form.as_table">
<tt class="descclassname">Form.</tt><tt class="descname">as_table</tt>()<a class="headerlink" href="#django.forms.Form.as_table" title="Permalink to this definition">¶</a></dt>
<dd><p>Finally, <tt class="docutils literal"><span class="pre">as_table()</span></tt> outputs the form as an HTML <tt class="docutils literal"><span class="pre"><table></span></tt>. This is
exactly the same as <tt class="docutils literal"><span class="pre">print</span></tt>. In fact, when you <tt class="docutils literal"><span class="pre">print</span></tt> a form object,
it calls its <tt class="docutils literal"><span class="pre">as_table()</span></tt> method behind the scenes:</p>
<div class="highlight-python"><div class="highlight"><pre><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">u'<tr><th><label for="id_subject">Subject:</label></th><td><input id="id_subject" type="text" name="subject" maxlength="100" /></td></tr>\n<tr><th><label for="id_message">Message:</label></th><td><input type="text" name="message" id="id_message" /></td></tr>\n<tr><th><label for="id_sender">Sender:</label></th><td><input type="text" name="sender" id="id_sender" /></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="k">print</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" /></td></tr></span>
<span class="go"><tr><th><label for="id_message">Message:</label></th><td><input type="text" name="message" id="id_message" /></td></tr></span>
<span class="go"><tr><th><label for="id_sender">Sender:</label></th><td><input type="text" name="sender" id="id_sender" /></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>
</dd></dl>
</div>
<div class="section" id="s-styling-required-or-erroneous-form-rows">
<span id="styling-required-or-erroneous-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>
<div class="versionadded">
<span class="title">New in Django 1.2:</span> <a class="reference internal" href="../../releases/1.2.html"><em>Please, see the release notes</em></a></div>
<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"><tt class="xref py py-class docutils literal"><span class="pre">Form</span></tt></a> class has a couple of hooks you can use to add <tt class="docutils literal"><span class="pre">class</span></tt>
attributes to required rows or to rows with errors: simple set the
<tt class="xref py py-attr docutils literal"><span class="pre">Form.error_css_class</span></tt> and/or <tt class="xref py py-attr docutils literal"><span class="pre">Form.required_css_class</span></tt>
attributes:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">class</span> <span class="nc">ContactForm</span><span class="p">(</span><span class="n">Form</span><span class="p">):</span>
<span class="n">error_css_class</span> <span class="o">=</span> <span class="s">'error'</span>
<span class="n">required_css_class</span> <span class="o">=</span> <span class="s">'required'</span>
<span class="c"># ... and the rest of your fields here</span>
</pre></div>
</div>
<p>Once you've done that, rows will be given <tt class="docutils literal"><span class="pre">"error"</span></tt> and/or <tt class="docutils literal"><span class="pre">"required"</span></tt>
classes, as needed. The HTML will look something like:</p>
<div class="highlight-python"><div class="highlight"><pre><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="k">print</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 for="id_subject">Subject:</label> ...</span>
<span class="go"><tr class="required"><th><label for="id_message">Message:</label> ...</span>
<span class="go"><tr class="required error"><th><label for="id_sender">Sender:</label> ...</span>
<span class="go"><tr><th><label for="id_cc_myself">Cc myself:<label> ...</span>
</pre></div>
</div>
</div>
<div class="section" id="s-configuring-html-label-tags">
<span id="s-ref-forms-api-configuring-label"></span><span id="configuring-html-label-tags"></span><span id="ref-forms-api-configuring-label"></span><h3>Configuring HTML <tt class="docutils literal"><span class="pre"><label></span></tt> tags<a class="headerlink" href="#configuring-html-label-tags" title="Permalink to this headline">¶</a></h3>
<p>An HTML <tt class="docutils literal"><span class="pre"><label></span></tt> 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 <tt class="docutils literal"><span class="pre"><label></span></tt> tags.</p>
<p>By default, the form rendering methods include HTML <tt class="docutils literal"><span class="pre">id</span></tt> attributes on the
form elements and corresponding <tt class="docutils literal"><span class="pre"><label></span></tt> tags around the labels. The <tt class="docutils literal"><span class="pre">id</span></tt>
attribute values are generated by prepending <tt class="docutils literal"><span class="pre">id_</span></tt> to the form field names.
This behavior is configurable, though, if you want to change the <tt class="docutils literal"><span class="pre">id</span></tt>
convention or remove HTML <tt class="docutils literal"><span class="pre">id</span></tt> attributes and <tt class="docutils literal"><span class="pre"><label></span></tt> tags entirely.</p>
<p>Use the <tt class="docutils literal"><span class="pre">auto_id</span></tt> argument to the <tt class="docutils literal"><span class="pre">Form</span></tt> constructor to control the label
and <tt class="docutils literal"><span class="pre">id</span></tt> behavior. This argument must be <tt class="xref docutils literal"><span class="pre">True</span></tt>, <tt class="xref docutils literal"><span class="pre">False</span></tt> or a string.</p>
<p>If <tt class="docutils literal"><span class="pre">auto_id</span></tt> is <tt class="xref docutils literal"><span class="pre">False</span></tt>, then the form output will not include <tt class="docutils literal"><span class="pre"><label></span></tt>
tags nor <tt class="docutils literal"><span class="pre">id</span></tt> attributes:</p>
<div class="highlight-python"><div class="highlight"><pre><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="bp">False</span><span class="p">)</span>
<span class="gp">>>> </span><span class="k">print</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" /></td></tr></span>
<span class="go"><tr><th>Message:</th><td><input type="text" name="message" /></td></tr></span>
<span class="go"><tr><th>Sender:</th><td><input type="text" name="sender" /></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="k">print</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" /></li></span>
<span class="go"><li>Message: <input type="text" name="message" /></li></span>
<span class="go"><li>Sender: <input type="text" name="sender" /></li></span>
<span class="go"><li>Cc myself: <input type="checkbox" name="cc_myself" /></li></span>
<span class="gp">>>> </span><span class="k">print</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" /></p></span>
<span class="go"><p>Message: <input type="text" name="message" /></p></span>
<span class="go"><p>Sender: <input type="text" name="sender" /></p></span>
<span class="go"><p>Cc myself: <input type="checkbox" name="cc_myself" /></p></span>
</pre></div>
</div>
<p>If <tt class="docutils literal"><span class="pre">auto_id</span></tt> is set to <tt class="xref docutils literal"><span class="pre">True</span></tt>, then the form output <em>will</em> include
<tt class="docutils literal"><span class="pre"><label></span></tt> tags and will simply use the field name as its <tt class="docutils literal"><span class="pre">id</span></tt> for each form
field:</p>
<div class="highlight-python"><div class="highlight"><pre><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="bp">True</span><span class="p">)</span>
<span class="gp">>>> </span><span class="k">print</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" /></td></tr></span>
<span class="go"><tr><th><label for="message">Message:</label></th><td><input type="text" name="message" id="message" /></td></tr></span>
<span class="go"><tr><th><label for="sender">Sender:</label></th><td><input type="text" name="sender" id="sender" /></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="k">print</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" /></li></span>
<span class="go"><li><label for="message">Message:</label> <input type="text" name="message" id="message" /></li></span>
<span class="go"><li><label for="sender">Sender:</label> <input type="text" name="sender" id="sender" /></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="k">print</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" /></p></span>
<span class="go"><p><label for="message">Message:</label> <input type="text" name="message" id="message" /></p></span>
<span class="go"><p><label for="sender">Sender:</label> <input type="text" name="sender" id="sender" /></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 <tt class="docutils literal"><span class="pre">auto_id</span></tt> is set to a string containing the format character <tt class="docutils literal"><span class="pre">'%s'</span></tt>,
then the form output will include <tt class="docutils literal"><span class="pre"><label></span></tt> tags, and will generate <tt class="docutils literal"><span class="pre">id</span></tt>
attributes based on the format string. For example, for a format string
<tt class="docutils literal"><span class="pre">'field_%s'</span></tt>, a field named <tt class="docutils literal"><span class="pre">subject</span></tt> will get the <tt class="docutils literal"><span class="pre">id</span></tt> value
<tt class="docutils literal"><span class="pre">'field_subject'</span></tt>. Continuing our example:</p>
<div class="highlight-python"><div class="highlight"><pre><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="s">'id_for_</span><span class="si">%s</span><span class="s">'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="k">print</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" /></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" /></td></tr></span>
<span class="go"><tr><th><label for="id_for_sender">Sender:</label></th><td><input type="text" name="sender" id="id_for_sender" /></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="k">print</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" /></li></span>
<span class="go"><li><label for="id_for_message">Message:</label> <input type="text" name="message" id="id_for_message" /></li></span>
<span class="go"><li><label for="id_for_sender">Sender:</label> <input type="text" name="sender" id="id_for_sender" /></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="k">print</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" /></p></span>
<span class="go"><p><label for="id_for_message">Message:</label> <input type="text" name="message" id="id_for_message" /></p></span>
<span class="go"><p><label for="id_for_sender">Sender:</label> <input type="text" name="sender" id="id_for_sender" /></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 <tt class="docutils literal"><span class="pre">auto_id</span></tt> is set to any other true value -- such as a string that doesn't
include <tt class="docutils literal"><span class="pre">%s</span></tt> -- then the library will act as if <tt class="docutils literal"><span class="pre">auto_id</span></tt> is <tt class="xref docutils literal"><span class="pre">True</span></tt>.</p>
<p>By default, <tt class="docutils literal"><span class="pre">auto_id</span></tt> is set to the string <tt class="docutils literal"><span class="pre">'id_%s'</span></tt>.</p>
<p>Normally, a colon (<tt class="docutils literal"><span class="pre">:</span></tt>) will be appended after any label name when a form is
rendered. It's possible to change the colon to another character, or omit it
entirely, using the <tt class="docutils literal"><span class="pre">label_suffix</span></tt> parameter:</p>
<div class="highlight-python"><div class="highlight"><pre><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="s">'id_for_</span><span class="si">%s</span><span class="s">'</span><span class="p">,</span> <span class="n">label_suffix</span><span class="o">=</span><span class="s">''</span><span class="p">)</span>
<span class="gp">>>> </span><span class="k">print</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" /></li></span>
<span class="go"><li><label for="id_for_message">Message</label> <input type="text" name="message" id="id_for_message" /></li></span>
<span class="go"><li><label for="id_for_sender">Sender</label> <input type="text" name="sender" id="id_for_sender" /></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="s">'id_for_</span><span class="si">%s</span><span class="s">'</span><span class="p">,</span> <span class="n">label_suffix</span><span class="o">=</span><span class="s">' ->'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="k">print</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" /></li></span>
<span class="go"><li><label for="id_for_message">Message -></label> <input type="text" name="message" id="id_for_message" /></li></span>
<span class="go"><li><label for="id_for_sender">Sender -></label> <input type="text" name="sender" id="id_for_sender" /></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 (<tt class="docutils literal"><span class="pre">.</span></tt>, <tt class="docutils literal"><span class="pre">!</span></tt>, <tt class="docutils literal"><span class="pre">?</span></tt> or <tt class="docutils literal"><span class="pre">:</span></tt>)</p>
</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 <tt class="docutils literal"><span class="pre">as_p()</span></tt>, <tt class="docutils literal"><span class="pre">as_ul()</span></tt> and <tt class="docutils literal"><span class="pre">as_table()</span></tt> shortcuts, the fields are
displayed in the order in which you define them in your form class. For
example, in the <tt class="docutils literal"><span class="pre">ContactForm</span></tt> example, the fields are defined in the order
<tt class="docutils literal"><span class="pre">subject</span></tt>, <tt class="docutils literal"><span class="pre">message</span></tt>, <tt class="docutils literal"><span class="pre">sender</span></tt>, <tt class="docutils literal"><span class="pre">cc_myself</span></tt>. To reorder the HTML
output, just change the order in which those fields are listed in the class.</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 <tt class="docutils literal"><span class="pre">Form</span></tt> 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 <tt class="docutils literal"><span class="pre"><ul</span> <span class="pre">class="errorlist"></span></tt> near the
field. The particular positioning of the error messages depends on the output
method you're using:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">data</span> <span class="o">=</span> <span class="p">{</span><span class="s">'subject'</span><span class="p">:</span> <span class="s">''</span><span class="p">,</span>
<span class="gp">... </span> <span class="s">'message'</span><span class="p">:</span> <span class="s">'Hi there'</span><span class="p">,</span>
<span class="gp">... </span> <span class="s">'sender'</span><span class="p">:</span> <span class="s">'invalid e-mail address'</span><span class="p">,</span>
<span class="gp">... </span> <span class="s">'cc_myself'</span><span class="p">:</span> <span class="bp">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="bp">False</span><span class="p">)</span>
<span class="gp">>>> </span><span class="k">print</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" /></td></tr></span>
<span class="go"><tr><th>Message:</th><td><input type="text" name="message" value="Hi there" /></td></tr></span>
<span class="go"><tr><th>Sender:</th><td><ul class="errorlist"><li>Enter a valid e-mail address.</li></ul><input type="text" name="sender" value="invalid e-mail address" /></td></tr></span>
<span class="go"><tr><th>Cc myself:</th><td><input checked="checked" type="checkbox" name="cc_myself" /></td></tr></span>
<span class="gp">>>> </span><span class="k">print</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" /></li></span>
<span class="go"><li>Message: <input type="text" name="message" value="Hi there" /></li></span>
<span class="go"><li><ul class="errorlist"><li>Enter a valid e-mail address.</li></ul>Sender: <input type="text" name="sender" value="invalid e-mail address" /></li></span>
<span class="go"><li>Cc myself: <input checked="checked" type="checkbox" name="cc_myself" /></li></span>
<span class="gp">>>> </span><span class="k">print</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" /></p></span>
<span class="go"><p>Message: <input type="text" name="message" value="Hi there" /></p></span>
<span class="go"><p><ul class="errorlist"><li>Enter a valid e-mail address.</li></ul></p></span>
<span class="go"><p>Sender: <input type="text" name="sender" value="invalid e-mail address" /></p></span>
<span class="go"><p>Cc myself: <input checked="checked" type="checkbox" name="cc_myself" /></p></span>
</pre></div>
</div>
</div>
<div class="section" id="s-customizing-the-error-list-format">
<span id="customizing-the-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 <tt class="docutils literal"><span class="pre">django.forms.util.ErrorList</span></tt> to format validation
errors. If you'd like to use an alternate class for displaying errors, you can
pass that in at construction time:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">django.forms.util</span> <span class="kn">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">__unicode__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</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="s">u''</span>
<span class="gp">... </span> <span class="k">return</span> <span class="s">u'<div class="errorlist"></span><span class="si">%s</span><span class="s"></div>'</span> <span class="o">%</span> <span class="s">''</span><span class="o">.</span><span class="n">join</span><span class="p">([</span><span class="s">u'<div class="error"></span><span class="si">%s</span><span class="s"></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="bp">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" /></p></span>
<span class="go"><p>Message: <input type="text" name="message" value="Hi there" /></p></span>
<span class="go"><div class="errorlist"><div class="error">Enter a valid e-mail address.</div></div></span>
<span class="go"><p>Sender: <input type="text" name="sender" value="invalid e-mail address" /></p></span>
<span class="go"><p>Cc myself: <input checked="checked" type="checkbox" name="cc_myself" /></p></span>
</pre></div>
</div>
</div>
<div class="section" id="s-more-granular-output">
<span id="more-granular-output"></span><h3>More granular output<a class="headerlink" href="#more-granular-output" title="Permalink to this headline">¶</a></h3>
<p>The <tt class="docutils literal"><span class="pre">as_p()</span></tt>, <tt class="docutils literal"><span class="pre">as_ul()</span></tt> and <tt class="docutils literal"><span class="pre">as_table()</span></tt> methods are simply shortcuts for
lazy developers -- they're not the only way a form object can be displayed.</p>
<p>To display the HTML for a single field in your form, use dictionary lookup
syntax using the field's name as the key, and print the resulting object:</p>
<div class="highlight-python"><div class="highlight"><pre><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="k">print</span> <span class="n">f</span><span class="p">[</span><span class="s">'subject'</span><span class="p">]</span>
<span class="go"><input id="id_subject" type="text" name="subject" maxlength="100" /></span>
<span class="gp">>>> </span><span class="k">print</span> <span class="n">f</span><span class="p">[</span><span class="s">'message'</span><span class="p">]</span>
<span class="go"><input type="text" name="message" id="id_message" /></span>
<span class="gp">>>> </span><span class="k">print</span> <span class="n">f</span><span class="p">[</span><span class="s">'sender'</span><span class="p">]</span>
<span class="go"><input type="text" name="sender" id="id_sender" /></span>
<span class="gp">>>> </span><span class="k">print</span> <span class="n">f</span><span class="p">[</span><span class="s">'cc_myself'</span><span class="p">]</span>
<span class="go"><input type="checkbox" name="cc_myself" id="id_cc_myself" /></span>
</pre></div>
</div>
<p>Call <tt class="docutils literal"><span class="pre">str()</span></tt> or <tt class="docutils literal"><span class="pre">unicode()</span></tt> on the field to get its rendered HTML as a
string or Unicode object, respectively:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="nb">str</span><span class="p">(</span><span class="n">f</span><span class="p">[</span><span class="s">'subject'</span><span class="p">])</span>
<span class="go">'<input id="id_subject" type="text" name="subject" maxlength="100" />'</span>
<span class="gp">>>> </span><span class="nb">unicode</span><span class="p">(</span><span class="n">f</span><span class="p">[</span><span class="s">'subject'</span><span class="p">])</span>
<span class="go">u'<input id="id_subject" type="text" name="subject" maxlength="100" />'</span>
</pre></div>
</div>
<p>Form objects define a custom <tt class="docutils literal"><span class="pre">__iter__()</span></tt> method, which allows you to loop
through their fields:</p>
<div class="highlight-python"><div class="highlight"><pre><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="k">for</span> <span class="n">field</span> <span class="ow">in</span> <span class="n">f</span><span class="p">:</span> <span class="k">print</span> <span class="n">field</span>
<span class="go"><input id="id_subject" type="text" name="subject" maxlength="100" /></span>
<span class="go"><input type="text" name="message" id="id_message" /></span>
<span class="go"><input type="text" name="sender" id="id_sender" /></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 <tt class="docutils literal"><span class="pre">auto_id</span></tt> setting:</p>
<div class="highlight-python"><div class="highlight"><pre><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="bp">False</span><span class="p">)</span>
<span class="gp">>>> </span><span class="k">print</span> <span class="n">f</span><span class="p">[</span><span class="s">'message'</span><span class="p">]</span>
<span class="go"><input type="text" name="message" /></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="s">'id_</span><span class="si">%s</span><span class="s">'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="k">print</span> <span class="n">f</span><span class="p">[</span><span class="s">'message'</span><span class="p">]</span>
<span class="go"><input type="text" name="message" id="id_message" /></span>
</pre></div>
</div>
<p>For a field's list of errors, access the field's <tt class="docutils literal"><span class="pre">errors</span></tt> attribute. This
is a list-like object that is displayed as an HTML <tt class="docutils literal"><span class="pre"><ul</span> <span class="pre">class="errorlist"></span></tt>
when printed:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">data</span> <span class="o">=</span> <span class="p">{</span><span class="s">'subject'</span><span class="p">:</span> <span class="s">'hi'</span><span class="p">,</span> <span class="s">'message'</span><span class="p">:</span> <span class="s">''</span><span class="p">,</span> <span class="s">'sender'</span><span class="p">:</span> <span class="s">''</span><span class="p">,</span> <span class="s">'cc_myself'</span><span class="p">:</span> <span class="s">''</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="bp">False</span><span class="p">)</span>
<span class="gp">>>> </span><span class="k">print</span> <span class="n">f</span><span class="p">[</span><span class="s">'message'</span><span class="p">]</span>
<span class="go"><input type="text" name="message" /></span>
<span class="gp">>>> </span><span class="n">f</span><span class="p">[</span><span class="s">'message'</span><span class="p">]</span><span class="o">.</span><span class="n">errors</span>
<span class="go">[u'This field is required.']</span>
<span class="gp">>>> </span><span class="k">print</span> <span class="n">f</span><span class="p">[</span><span class="s">'message'</span><span class="p">]</span><span class="o">.</span><span class="n">errors</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="s">'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="k">print</span> <span class="n">f</span><span class="p">[</span><span class="s">'subject'</span><span class="p">]</span><span class="o">.</span><span class="n">errors</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="s">'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>
<div class="versionadded">
<span class="title">New in Django 1.2:</span> <a class="reference internal" href="../../releases/1.2.html"><em>Please, see the release notes</em></a></div>
<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
<tt class="docutils literal"><span class="pre">css_classes</span></tt> method:</p>
<div class="highlight-python"><div class="highlight"><pre><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="p">[</span><span class="s">'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-python"><div class="highlight"><pre><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="p">[</span><span class="s">'message'</span><span class="p">]</span><span class="o">.</span><span class="n">css_classes</span><span class="p">(</span><span class="s">'foo bar'</span><span class="p">)</span>
<span class="go">'foo bar required'</span>
</pre></div>
</div>
</div>
</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>
<div class="versionadded">
<span class="title">New in Django 1.0:</span> <a class="reference internal" href="../../releases/1.0.html"><em>Please, see the release notes</em></a></div>
<p>Dealing with forms that have <tt class="docutils literal"><span class="pre">FileField</span></tt> and <tt class="docutils literal"><span class="pre">ImageField</span></tt> 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
<tt class="docutils literal"><span class="pre"><form></span></tt> element correctly defines the <tt class="docutils literal"><span class="pre">enctype</span></tt> as
<tt class="docutils literal"><span class="pre">"multipart/form-data"</span></tt>:</p>
<div class="highlight-python"><pre><form enctype="multipart/form-data" method="post" action="/foo/"></pre>
</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 <tt class="docutils literal"><span class="pre">FileField</span></tt> and <tt class="docutils literal"><span class="pre">ImageField</span></tt>, you will need to specify
a second argument when you bind your form. So if we extend our
ContactForm to include an <tt class="docutils literal"><span class="pre">ImageField</span></tt> called <tt class="docutils literal"><span class="pre">mugshot</span></tt>, we
need to bind the file data containing the mugshot image:</p>
<div class="highlight-python"><pre># Bound form with an image field
>>> from django.core.files.uploadedfile import SimpleUploadedFile
>>> data = {'subject': 'hello',
... 'message': 'Hi there',
... 'sender': 'foo@example.com',
... 'cc_myself': True}
>>> file_data = {'mugshot': SimpleUploadedFile('face.jpg', <file data>)}
>>> f = ContactFormWithMugshot(data, file_data)</pre>
</div>
<p>In practice, you will usually specify <tt class="docutils literal"><span class="pre">request.FILES</span></tt> as the source
of file data (just like you use <tt class="docutils literal"><span class="pre">request.POST</span></tt> as the source of
form data):</p>
<div class="highlight-python"><pre># Bound form with an image field, data from the request
>>> f = ContactFormWithMugshot(request.POST, request.FILES)</pre>
</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-python"><pre># Unbound form with a image field
>>> f = ContactFormWithMugshot()</pre>
</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>
<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 <tt class="docutils literal"><span class="pre">is_multipart()</span></tt> method
tells you whether the form requires multipart encoding for submission:</p>
<div class="highlight-python"><div class="highlight"><pre><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-python"><pre>{% if form.is_multipart %}
<form enctype="multipart/form-data" method="post" action="/foo/">
{% else %}
<form method="post" action="/foo/">
{% endif %}
{{ form }}
</form></pre>
</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 <tt class="docutils literal"><span class="pre">Form</span></tt> classes that share fields, you can use
subclassing to remove redundancy.</p>
<p>When you subclass a custom <tt class="docutils literal"><span class="pre">Form</span></tt> 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, <tt class="docutils literal"><span class="pre">ContactFormWithPriority</span></tt> contains all the fields from
<tt class="docutils literal"><span class="pre">ContactForm</span></tt>, plus an additional field, <tt class="docutils literal"><span class="pre">priority</span></tt>. The <tt class="docutils literal"><span class="pre">ContactForm</span></tt>
fields are ordered first:</p>
<div class="highlight-python"><div class="highlight"><pre><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="bp">False</span><span class="p">)</span>
<span class="gp">>>> </span><span class="k">print</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" /></li></span>
<span class="go"><li>Message: <input type="text" name="message" /></li></span>
<span class="go"><li>Sender: <input type="text" name="sender" /></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" /></li></span>
</pre></div>
</div>
<p>It's possible to subclass multiple forms, treating forms as "mix-ins." In this
example, <tt class="docutils literal"><span class="pre">BeatleForm</span></tt> subclasses both <tt class="docutils literal"><span class="pre">PersonForm</span></tt> and <tt class="docutils literal"><span class="pre">InstrumentForm</span></tt>
(in that order), and its field list includes the fields from the parent
classes:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="k">class</span> <span class="nc">PersonForm</span><span class="p">(</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">CharField</span><span class="p">()</span>
<span class="gp">... </span> <span class="n">last_name</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">Form</span><span class="p">):</span>
<span class="gp">... </span> <span class="n">instrument</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">PersonForm</span><span class="p">,</span> <span class="n">InstrumentForm</span><span class="p">):</span>
<span class="gp">... </span> <span class="n">haircut_type</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="bp">False</span><span class="p">)</span>
<span class="gp">>>> </span><span class="k">print</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" /></li></span>
<span class="go"><li>Last name: <input type="text" name="last_name" /></li></span>
<span class="go"><li>Instrument: <input type="text" name="instrument" /></li></span>
<span class="go"><li>Haircut type: <input type="text" name="haircut_type" /></li></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">
<tt class="descclassname">Form.</tt><tt class="descname">prefix</tt><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 <tt class="docutils literal"><span class="pre"><form></span></tt> tag. To give each
<tt class="docutils literal"><span class="pre">Form</span></tt> its own namespace, use the <tt class="docutils literal"><span class="pre">prefix</span></tt> keyword argument:</p>
<div class="highlight-python"><div class="highlight"><pre><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="s">"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="s">"father"</span><span class="p">)</span>
<span class="gp">>>> </span><span class="k">print</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" /></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" /></li></span>
<span class="gp">>>> </span><span class="k">print</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" /></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" /></li></span>
</pre></div>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="yui-b" id="sidebar">
<div class="sphinxsidebar">
<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="#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"><tt class="docutils literal"><span class="pre">as_p()</span></tt></a></li>
<li><a class="reference internal" href="#as-ul"><tt class="docutils literal"><span class="pre">as_ul()</span></tt></a></li>
<li><a class="reference internal" href="#as-table"><tt class="docutils literal"><span class="pre">as_table()</span></tt></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-html-label-tags">Configuring HTML <tt class="docutils literal"><span class="pre"><label></span></tt> tags</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>
<li><a class="reference internal" href="#more-granular-output">More granular output</a></li>
</ul>
</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>
<h3>Browse</h3>
<ul>
<li>Prev: <a href="index.html">Forms</a></li>
<li>Next: <a href="fields.html">Form fields</a></li>
</ul>
<h3>You are here:</h3>
<ul>
<li>
<a href="../../index.html">Django v1.2 documentation</a>
<ul><li><a href="../index.html">API Reference</a>
<ul><li><a href="index.html">Forms</a>
<ul><li>The Forms API</li></ul>
</li></ul></li></ul>
</li>
</ul>
<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 id="searchbox" style="display: none">
<h3>Quick search</h3>
<form class="search" action="../../search.html" method="get">
<input type="text" name="q" size="18" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
<p class="searchtip" style="font-size: 90%">
Enter search terms or a module, class or function name.
</p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<h3>Last update:</h3>
<p class="topless">Oct 20, 2010</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>
distrib
>
Arklinux
>
devel
>
i586
>
media
>
main
>
by-pkgid
>
5fcb1fedf34660bc240dc59b7bfcebc4
>
files
>
381
