<!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.1 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.1',
COLLAPSE_MODINDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="../../_static/jquery.js"></script>
<script type="text/javascript" src="../../_static/doctools.js"></script>
<link rel="top" title="Django v1.1 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.1 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="../../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-ref-forms-api"></span><span id="module-django.forms.forms"></span><span id="ref-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 external" href="../../topics/forms/index.html#topics-forms-index"><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 title="django.forms.Form" class="reference internal" href="#django.forms.Form"><tt class="xref 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 title="django.forms.Form" class="reference internal" href="#django.forms.Form"><tt class="xref 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 title="django.forms.Form" class="reference internal" href="#django.forms.Form"><tt class="xref 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 title="django.forms.Form" class="reference internal" href="#django.forms.Form"><tt class="xref 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 title="django.forms.Field" class="reference external" href="fields.html#django.forms.Field"><tt class="xref 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 title="django.forms.Form.is_bound" class="reference internal" href="#django.forms.Form.is_bound"><tt class="xref 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 title="django.forms.Form" class="reference internal" href="#django.forms.Form"><tt class="xref 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 title="django.forms.Form" class="reference internal" href="#django.forms.Form"><tt class="xref docutils literal"><span class="pre">Form</span></tt></a> instance to some data, create
another <a title="django.forms.Form" class="reference internal" href="#django.forms.Form"><tt class="xref docutils literal"><span class="pre">Form</span></tt></a> instance. There is no way to change data in a
<a title="django.forms.Form" class="reference internal" href="#django.forms.Form"><tt class="xref docutils literal"><span class="pre">Form</span></tt></a> instance. Once a <a title="django.forms.Form" class="reference internal" href="#django.forms.Form"><tt class="xref 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 title="django.forms.Form" class="reference internal" href="#django.forms.Form"><tt class="xref docutils literal"><span class="pre">Form</span></tt></a> object is to validate data. With a bound
<a title="django.forms.Form" class="reference internal" href="#django.forms.Form"><tt class="xref docutils literal"><span class="pre">Form</span></tt></a> instance, call the <a title="django.forms.Form.is_valid" class="reference internal" href="#django.forms.Form.is_valid"><tt class="xref 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 title="django.forms.Form.errors" class="reference internal" href="#django.forms.Form.errors"><tt class="xref 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 title="django.forms.Form.errors" class="reference internal" href="#django.forms.Form.errors"><tt class="xref docutils literal"><span class="pre">errors</span></tt></a> without having to call
<a title="django.forms.Form.is_valid" class="reference internal" href="#django.forms.Form.is_valid"><tt class="xref 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 title="django.forms.Form.is_valid" class="reference internal" href="#django.forms.Form.is_valid"><tt class="xref docutils literal"><span class="pre">is_valid()</span></tt></a> or access <a title="django.forms.Form.errors" class="reference internal" href="#django.forms.Form.errors"><tt class="xref 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 title="django.forms.Form.errors" class="reference internal" href="#django.forms.Form.errors"><tt class="xref docutils literal"><span class="pre">errors</span></tt></a> or call <a title="django.forms.Form.is_valid" class="reference internal" href="#django.forms.Form.is_valid"><tt class="xref 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 title="django.forms.Form.initial" class="reference internal" href="#django.forms.Form.initial"><tt class="xref 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 title="django.forms.Form.initial" class="reference internal" href="#django.forms.Form.initial"><tt class="xref docutils literal"><span class="pre">initial</span></tt></a> argument to a <a title="django.forms.Form" class="reference internal" href="#django.forms.Form"><tt class="xref 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 docutils literal"><span class="pre">Field</span></tt> defines
<a title="django.forms.Form.initial" class="reference internal" href="#django.forms.Form.initial"><tt class="xref 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 title="django.forms.Form" class="reference internal" href="#django.forms.Form"><tt class="xref 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 title="django.forms.DateField" class="reference external" href="fields.html#django.forms.DateField"><tt class="xref 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 title="django.forms.Form" class="reference internal" href="#django.forms.Form"><tt class="xref 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 external" href="validation.html#ref-forms-validation"><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-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>
</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 external" href="../../releases/1.0.html#releases-1-0"><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 external" href="#">The Forms API</a><ul>
<li><a class="reference external" href="#bound-and-unbound-forms">Bound and unbound forms</a></li>
<li><a class="reference external" href="#using-forms-to-validate-data">Using forms to validate data</a><ul>
<li><a class="reference external" href="#behavior-of-unbound-forms">Behavior of unbound forms</a></li>
</ul>
</li>
<li><a class="reference external" href="#dynamic-initial-values">Dynamic initial values</a></li>
<li><a class="reference external" href="#accessing-clean-data">Accessing “clean” data</a></li>
<li><a class="reference external" href="#outputting-forms-as-html">Outputting forms as HTML</a><ul>
<li><a class="reference external" href="#as-p"><tt class="docutils literal"><span class="pre">as_p()</span></tt></a></li>
<li><a class="reference external" href="#as-ul"><tt class="docutils literal"><span class="pre">as_ul()</span></tt></a></li>
<li><a class="reference external" href="#as-table"><tt class="docutils literal"><span class="pre">as_table()</span></tt></a></li>
<li><a class="reference external" href="#configuring-html-label-tags">Configuring HTML <tt class="docutils literal"><span class="pre"><label></span></tt> tags</a></li>
<li><a class="reference external" href="#notes-on-field-ordering">Notes on field ordering</a></li>
<li><a class="reference external" href="#how-errors-are-displayed">How errors are displayed</a></li>
<li><a class="reference external" href="#customizing-the-error-list-format">Customizing the error list format</a></li>
<li><a class="reference external" href="#more-granular-output">More granular output</a></li>
</ul>
</li>
<li><a class="reference external" href="#binding-uploaded-files-to-a-form">Binding uploaded files to a form</a><ul>
<li><a class="reference external" href="#testing-for-multipart-forms">Testing for multipart forms</a></li>
</ul>
</li>
<li><a class="reference external" href="#subclassing-forms">Subclassing forms</a></li>
<li><a class="reference external" 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.1 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">Feb 18, 2011</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
>
Mandriva
>
current
>
i586
>
media
>
main-updates
>
by-pkgid
>
57efe471f3561e70a829edf1b0e9f507
>
files
>
2319
