<!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>Working with forms — Django 1.6.7 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.6.7',
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 1.6.7 documentation" href="../../index.html" />
<link rel="up" title="Using Django" href="../index.html" />
<link rel="next" title="Formsets" href="formsets.html" />
<link rel="prev" title="How to use sessions" href="../http/sessions.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 = "../../ref/templates/builtins.html";
if (base == "#") {
// Special case for builtins.html itself
base = "";
}
// Tags are keywords, class '.k'
$("div.highlight\\-html\\+django span.k").each(function(i, elem) {
var tagname = $(elem).text();
if ($.inArray(tagname, django_template_builtins.ttags) != -1) {
var fragment = tagname.replace(/_/, '-');
$(elem).html("<a href='" + base + "#" + fragment + "'>" + tagname + "</a>");
}
});
// Filters are functions, class '.nf'
$("div.highlight\\-html\\+django span.nf").each(function(i, elem) {
var filtername = $(elem).text();
if ($.inArray(filtername, django_template_builtins.tfilters) != -1) {
var fragment = filtername.replace(/_/, '-');
$(elem).html("<a href='" + base + "#" + fragment + "'>" + filtername + "</a>");
}
});
});
})(jQuery);
</script>
</head>
<body>
<div class="document">
<div id="custom-doc" class="yui-t6">
<div id="hd">
<h1><a href="../../index.html">Django 1.6.7 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="../http/sessions.html" title="How to use sessions">previous</a>
|
<a href="../index.html" title="Using Django" accesskey="U">up</a>
|
<a href="formsets.html" title="Formsets">next</a> »</div>
</div>
<div id="bd">
<div id="yui-main">
<div class="yui-b">
<div class="yui-g" id="topics-forms-index">
<div class="section" id="s-working-with-forms">
<span id="working-with-forms"></span><h1>Working with forms<a class="headerlink" href="#working-with-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 provides an introduction to Django’s form handling features.
For a more detailed look at specific areas of the forms API, see
<a class="reference internal" href="../../ref/forms/api.html"><em>The Forms API</em></a>, <a class="reference internal" href="../../ref/forms/fields.html"><em>Form fields</em></a>, and
<a class="reference internal" href="../../ref/forms/validation.html"><em>Form and field validation</em></a>.</p>
</div>
<p><tt class="docutils literal"><span class="pre">django.forms</span></tt> is Django’s form-handling library.</p>
<p>While it is possible to process form submissions just using Django’s
<a class="reference internal" href="../../ref/request-response.html#django.http.HttpRequest" title="django.http.HttpRequest"><tt class="xref py py-class docutils literal"><span class="pre">HttpRequest</span></tt></a> class, using the form library takes care of a
number of common form-related tasks. Using it, you can:</p>
<ol class="arabic simple">
<li>Display an HTML form with automatically generated form widgets.</li>
<li>Check submitted data against a set of validation rules.</li>
<li>Redisplay a form in the case of validation errors.</li>
<li>Convert submitted form data to the relevant Python data types.</li>
</ol>
<div class="section" id="s-overview">
<span id="overview"></span><h2>Overview<a class="headerlink" href="#overview" title="Permalink to this headline">¶</a></h2>
<p>The library deals with these concepts:</p>
<dl class="glossary docutils">
<dt id="term-widget">Widget</dt>
<dd>A class that corresponds to an HTML form widget, e.g.
<tt class="docutils literal"><span class="pre"><input</span> <span class="pre">type="text"></span></tt> or <tt class="docutils literal"><span class="pre"><textarea></span></tt>. This handles rendering of the
widget as HTML.</dd>
<dt id="term-field">Field</dt>
<dd>A class that is responsible for doing validation, e.g.
an <tt class="docutils literal"><span class="pre">EmailField</span></tt> that makes sure its data is a valid email address.</dd>
<dt id="term-form">Form</dt>
<dd>A collection of fields that knows how to validate itself and
display itself as HTML.</dd>
<dt id="term-form-assets-the-media-class">Form Assets (the <tt class="docutils literal"><span class="pre">Media</span></tt> class)</dt>
<dd>The CSS and JavaScript resources that are required to render a form.</dd>
</dl>
<p>The library is decoupled from the other Django components, such as the database
layer, views and templates. It relies only on Django settings, a couple of
<tt class="docutils literal"><span class="pre">django.utils</span></tt> helper functions and Django’s internationalization hooks (but
you’re not required to be using internationalization features to use this
library).</p>
</div>
<div class="section" id="s-form-objects">
<span id="form-objects"></span><h2>Form objects<a class="headerlink" href="#form-objects" title="Permalink to this headline">¶</a></h2>
<p>A Form object encapsulates a sequence of form fields and a collection of
validation rules that must be fulfilled in order for the form to be accepted.
Form classes are created as subclasses of <tt class="docutils literal"><span class="pre">django.forms.Form</span></tt> and
make use of a declarative style that you’ll be familiar with if you’ve used
Django’s database models.</p>
<p>For example, consider a form used to implement “contact me” functionality on a
personal Web site:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">django</span> <span class="kn">import</span> <span class="n">forms</span>
<span class="k">class</span> <span class="nc">ContactForm</span><span class="p">(</span><span class="n">forms</span><span class="o">.</span><span class="n">Form</span><span class="p">):</span>
<span class="n">subject</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">max_length</span><span class="o">=</span><span class="mi">100</span><span class="p">)</span>
<span class="n">message</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">sender</span> <span class="o">=</span> <span class="n">forms</span><span class="o">.</span><span class="n">EmailField</span><span class="p">()</span>
<span class="n">cc_myself</span> <span class="o">=</span> <span class="n">forms</span><span class="o">.</span><span class="n">BooleanField</span><span class="p">(</span><span class="n">required</span><span class="o">=</span><span class="bp">False</span><span class="p">)</span>
</pre></div>
</div>
<p>A form is composed of <tt class="docutils literal"><span class="pre">Field</span></tt> objects. In this case, our form has four
fields: <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> and <tt class="docutils literal"><span class="pre">cc_myself</span></tt>. <tt class="docutils literal"><span class="pre">CharField</span></tt>,
<tt class="docutils literal"><span class="pre">EmailField</span></tt> and <tt class="docutils literal"><span class="pre">BooleanField</span></tt> are just three of the available field types;
a full list can be found in <a class="reference internal" href="../../ref/forms/fields.html"><em>Form fields</em></a>.</p>
<p>If your form is going to be used to directly add or edit a Django model, you can
use a <a class="reference internal" href="modelforms.html"><em>ModelForm</em></a> to avoid duplicating your model
description.</p>
<div class="section" id="s-using-a-form-in-a-view">
<span id="s-id1"></span><span id="using-a-form-in-a-view"></span><span id="id1"></span><h3>Using a form in a view<a class="headerlink" href="#using-a-form-in-a-view" title="Permalink to this headline">¶</a></h3>
<p>The standard pattern for processing a form in a view looks like this:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">django.shortcuts</span> <span class="kn">import</span> <span class="n">render</span>
<span class="kn">from</span> <span class="nn">django.http</span> <span class="kn">import</span> <span class="n">HttpResponseRedirect</span>
<span class="k">def</span> <span class="nf">contact</span><span class="p">(</span><span class="n">request</span><span class="p">):</span>
<span class="k">if</span> <span class="n">request</span><span class="o">.</span><span class="n">method</span> <span class="o">==</span> <span class="s">'POST'</span><span class="p">:</span> <span class="c"># If the form has been submitted...</span>
<span class="c"># ContactForm was defined in the previous section</span>
<span class="n">form</span> <span class="o">=</span> <span class="n">ContactForm</span><span class="p">(</span><span class="n">request</span><span class="o">.</span><span class="n">POST</span><span class="p">)</span> <span class="c"># A form bound to the POST data</span>
<span class="k">if</span> <span class="n">form</span><span class="o">.</span><span class="n">is_valid</span><span class="p">():</span> <span class="c"># All validation rules pass</span>
<span class="c"># Process the data in form.cleaned_data</span>
<span class="c"># ...</span>
<span class="k">return</span> <span class="n">HttpResponseRedirect</span><span class="p">(</span><span class="s">'/thanks/'</span><span class="p">)</span> <span class="c"># Redirect after POST</span>
<span class="k">else</span><span class="p">:</span>
<span class="n">form</span> <span class="o">=</span> <span class="n">ContactForm</span><span class="p">()</span> <span class="c"># An unbound form</span>
<span class="k">return</span> <span class="n">render</span><span class="p">(</span><span class="n">request</span><span class="p">,</span> <span class="s">'contact.html'</span><span class="p">,</span> <span class="p">{</span>
<span class="s">'form'</span><span class="p">:</span> <span class="n">form</span><span class="p">,</span>
<span class="p">})</span>
</pre></div>
</div>
<p>There are three possible code paths here:</p>
<table class="docutils">
<colgroup>
<col width="24%" />
<col width="20%" />
<col width="55%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Form submitted?</th>
<th class="head">Data?</th>
<th class="head">What occurs</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td>Unsubmitted</td>
<td>None yet</td>
<td>Template gets passed unbound instance
of ContactForm.</td>
</tr>
<tr class="row-odd"><td>Submitted</td>
<td>Invalid data</td>
<td>Template gets passed bound instance
of ContactForm.</td>
</tr>
<tr class="row-even"><td>Submitted</td>
<td>Valid data</td>
<td>Valid data is processed. Redirect to a
“thanks” page.</td>
</tr>
</tbody>
</table>
<p>The distinction between <a class="reference internal" href="../../ref/forms/api.html#ref-forms-api-bound-unbound"><em>Bound and unbound forms</em></a> is important:</p>
<ul class="simple">
<li>An unbound form has no data associated with it. When rendered to the user,
it will be empty or will contain default values.</li>
<li>A bound form has submitted data, and hence can be used to tell if that data
is valid. If an invalid bound form is rendered, it can include inline error
messages telling the user what data to correct.</li>
</ul>
</div>
<div class="section" id="s-handling-file-uploads-with-a-form">
<span id="handling-file-uploads-with-a-form"></span><h3>Handling file uploads with a form<a class="headerlink" href="#handling-file-uploads-with-a-form" title="Permalink to this headline">¶</a></h3>
<p>To see how to handle file uploads with your form, see
<a class="reference internal" href="../../ref/forms/api.html#binding-uploaded-files"><em>Binding uploaded files to a form</em></a>.</p>
</div>
<div class="section" id="s-processing-the-data-from-a-form">
<span id="processing-the-data-from-a-form"></span><h3>Processing the data from a form<a class="headerlink" href="#processing-the-data-from-a-form" title="Permalink to this headline">¶</a></h3>
<p>Once <tt class="docutils literal"><span class="pre">is_valid()</span></tt> returns <tt class="docutils literal"><span class="pre">True</span></tt>, the successfully validated form data
will be in the <tt class="docutils literal"><span class="pre">form.cleaned_data</span></tt> dictionary. This data will have been
converted nicely into Python types for you.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">You can still access the unvalidated data directly from <tt class="docutils literal"><span class="pre">request.POST</span></tt> at
this point, but the validated data is better.</p>
</div>
<p>In the above example, <tt class="docutils literal"><span class="pre">cc_myself</span></tt> will be a boolean value. Likewise, fields
such as <tt class="docutils literal"><span class="pre">IntegerField</span></tt> and <tt class="docutils literal"><span class="pre">FloatField</span></tt> convert values to a Python int and
float respectively.</p>
<p>Read-only fields are not available in <tt class="docutils literal"><span class="pre">form.cleaned_data</span></tt> (and setting
a value in a custom <tt class="docutils literal"><span class="pre">clean()</span></tt> method won’t have any effect). These
fields are displayed as text rather than as input elements, and thus are not
posted back to the server.</p>
<p>Extending the earlier example, here’s how the form data could be processed:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">if</span> <span class="n">form</span><span class="o">.</span><span class="n">is_valid</span><span class="p">():</span>
<span class="n">subject</span> <span class="o">=</span> <span class="n">form</span><span class="o">.</span><span class="n">cleaned_data</span><span class="p">[</span><span class="s">'subject'</span><span class="p">]</span>
<span class="n">message</span> <span class="o">=</span> <span class="n">form</span><span class="o">.</span><span class="n">cleaned_data</span><span class="p">[</span><span class="s">'message'</span><span class="p">]</span>
<span class="n">sender</span> <span class="o">=</span> <span class="n">form</span><span class="o">.</span><span class="n">cleaned_data</span><span class="p">[</span><span class="s">'sender'</span><span class="p">]</span>
<span class="n">cc_myself</span> <span class="o">=</span> <span class="n">form</span><span class="o">.</span><span class="n">cleaned_data</span><span class="p">[</span><span class="s">'cc_myself'</span><span class="p">]</span>
<span class="n">recipients</span> <span class="o">=</span> <span class="p">[</span><span class="s">'info@example.com'</span><span class="p">]</span>
<span class="k">if</span> <span class="n">cc_myself</span><span class="p">:</span>
<span class="n">recipients</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">sender</span><span class="p">)</span>
<span class="kn">from</span> <span class="nn">django.core.mail</span> <span class="kn">import</span> <span class="n">send_mail</span>
<span class="n">send_mail</span><span class="p">(</span><span class="n">subject</span><span class="p">,</span> <span class="n">message</span><span class="p">,</span> <span class="n">sender</span><span class="p">,</span> <span class="n">recipients</span><span class="p">)</span>
<span class="k">return</span> <span class="n">HttpResponseRedirect</span><span class="p">(</span><span class="s">'/thanks/'</span><span class="p">)</span> <span class="c"># Redirect after POST</span>
</pre></div>
</div>
<div class="admonition tip">
<p class="first admonition-title">Tip</p>
<p class="last">For more on sending email from Django, see <a class="reference internal" href="../email.html"><em>Sending email</em></a>.</p>
</div>
</div>
<div class="section" id="s-displaying-a-form-using-a-template">
<span id="displaying-a-form-using-a-template"></span><h3>Displaying a form using a template<a class="headerlink" href="#displaying-a-form-using-a-template" title="Permalink to this headline">¶</a></h3>
<p>Forms are designed to work with the Django template language. In the above
example, we passed our <tt class="docutils literal"><span class="pre">ContactForm</span></tt> instance to the template using the
context variable <tt class="docutils literal"><span class="pre">form</span></tt>. Here’s a simple example template:</p>
<div class="highlight-html+django"><div class="highlight"><pre><span class="nt"><form</span> <span class="na">action=</span><span class="s">"/contact/"</span> <span class="na">method=</span><span class="s">"post"</span><span class="nt">></span><span class="cp">{%</span> <span class="k">csrf_token</span> <span class="cp">%}</span>
<span class="cp">{{</span> <span class="nv">form.as_p</span> <span class="cp">}}</span>
<span class="nt"><input</span> <span class="na">type=</span><span class="s">"submit"</span> <span class="na">value=</span><span class="s">"Submit"</span> <span class="nt">/></span>
<span class="nt"></form></span>
</pre></div>
</div>
<p>The form only outputs its own fields; it is up to you to provide the surrounding
<tt class="docutils literal"><span class="pre"><form></span></tt> tags and the submit button.</p>
<p>If your form includes uploaded files, be sure to include
<tt class="docutils literal"><span class="pre">enctype="multipart/form-data"</span></tt> in the <tt class="docutils literal"><span class="pre">form</span></tt> element. If you wish to write
a generic template that will work whether or not the form has files, you can
use the <a class="reference internal" href="../../ref/forms/api.html#django.forms.Form.is_multipart" title="django.forms.Form.is_multipart"><tt class="xref py py-meth docutils literal"><span class="pre">is_multipart()</span></tt></a> attribute on the form:</p>
<div class="highlight-html+django"><div class="highlight"><pre><span class="nt"><form</span> <span class="na">action=</span><span class="s">"/contact/"</span> <span class="na">method=</span><span class="s">"post"</span>
<span class="cp">{%</span> <span class="k">if</span> <span class="nv">form.is_multipart</span> <span class="cp">%}</span><span class="na">enctype=</span><span class="s">"multipart/form-data"</span><span class="cp">{%</span> <span class="k">endif</span> <span class="cp">%}</span><span class="nt">></span>
</pre></div>
</div>
<div class="admonition-forms-and-cross-site-request-forgery-protection admonition">
<p class="first admonition-title">Forms and Cross Site Request Forgery protection</p>
<p class="last">Django ships with an easy-to-use <a class="reference internal" href="../../ref/contrib/csrf.html"><em>protection against Cross Site Request
Forgeries</em></a>. When submitting a form via POST with
CSRF protection enabled you must use the <a class="reference internal" href="../../ref/templates/builtins.html#std:templatetag-csrf_token"><tt class="xref std std-ttag docutils literal"><span class="pre">csrf_token</span></tt></a> template tag
as in the preceding example. However, since CSRF protection is not
directly tied to forms in templates, this tag is omitted from the
following examples in this document.</p>
</div>
<p><tt class="docutils literal"><span class="pre">form.as_p</span></tt> will output the form with each form field and accompanying label
wrapped in a paragraph. Here’s the output for our example template:</p>
<div class="highlight-html+django"><div class="highlight"><pre><span class="nt"><form</span> <span class="na">action=</span><span class="s">"/contact/"</span> <span class="na">method=</span><span class="s">"post"</span><span class="nt">></span>
<span class="nt"><p><label</span> <span class="na">for=</span><span class="s">"id_subject"</span><span class="nt">></span>Subject:<span class="nt"></label></span>
<span class="nt"><input</span> <span class="na">id=</span><span class="s">"id_subject"</span> <span class="na">type=</span><span class="s">"text"</span> <span class="na">name=</span><span class="s">"subject"</span> <span class="na">maxlength=</span><span class="s">"100"</span> <span class="nt">/></p></span>
<span class="nt"><p><label</span> <span class="na">for=</span><span class="s">"id_message"</span><span class="nt">></span>Message:<span class="nt"></label></span>
<span class="nt"><input</span> <span class="na">type=</span><span class="s">"text"</span> <span class="na">name=</span><span class="s">"message"</span> <span class="na">id=</span><span class="s">"id_message"</span> <span class="nt">/></p></span>
<span class="nt"><p><label</span> <span class="na">for=</span><span class="s">"id_sender"</span><span class="nt">></span>Sender:<span class="nt"></label></span>
<span class="nt"><input</span> <span class="na">type=</span><span class="s">"email"</span> <span class="na">name=</span><span class="s">"sender"</span> <span class="na">id=</span><span class="s">"id_sender"</span> <span class="nt">/></p></span>
<span class="nt"><p><label</span> <span class="na">for=</span><span class="s">"id_cc_myself"</span><span class="nt">></span>Cc myself:<span class="nt"></label></span>
<span class="nt"><input</span> <span class="na">type=</span><span class="s">"checkbox"</span> <span class="na">name=</span><span class="s">"cc_myself"</span> <span class="na">id=</span><span class="s">"id_cc_myself"</span> <span class="nt">/></p></span>
<span class="nt"><input</span> <span class="na">type=</span><span class="s">"submit"</span> <span class="na">value=</span><span class="s">"Submit"</span> <span class="nt">/></span>
<span class="nt"></form></span>
</pre></div>
</div>
<p>Note that each form field has an ID attribute set to <tt class="docutils literal"><span class="pre">id_<field-name></span></tt>, which
is referenced by the accompanying label tag. This is important for ensuring
forms are accessible to assistive technology such as screen reader software. You
can also <a class="reference internal" href="../../ref/forms/api.html#ref-forms-api-configuring-label"><em>customize the way in which labels and ids are generated</em></a>.</p>
<p>You can also use <tt class="docutils literal"><span class="pre">form.as_table</span></tt> to output table rows (you’ll need to provide
your own <tt class="docutils literal"><span class="pre"><table></span></tt> tags) and <tt class="docutils literal"><span class="pre">form.as_ul</span></tt> to output list items.</p>
</div>
<div class="section" id="s-customizing-the-form-template">
<span id="customizing-the-form-template"></span><h3>Customizing the form template<a class="headerlink" href="#customizing-the-form-template" title="Permalink to this headline">¶</a></h3>
<p>If the default generated HTML is not to your taste, you can completely customize
the way a form is presented using the Django template language. Extending the
above example:</p>
<div class="highlight-html+django"><div class="highlight"><pre><span class="nt"><form</span> <span class="na">action=</span><span class="s">"/contact/"</span> <span class="na">method=</span><span class="s">"post"</span><span class="nt">></span>
<span class="cp">{{</span> <span class="nv">form.non_field_errors</span> <span class="cp">}}</span>
<span class="nt"><div</span> <span class="na">class=</span><span class="s">"fieldWrapper"</span><span class="nt">></span>
<span class="cp">{{</span> <span class="nv">form.subject.errors</span> <span class="cp">}}</span>
<span class="nt"><label</span> <span class="na">for=</span><span class="s">"id_subject"</span><span class="nt">></span>Email subject:<span class="nt"></label></span>
<span class="cp">{{</span> <span class="nv">form.subject</span> <span class="cp">}}</span>
<span class="nt"></div></span>
<span class="nt"><div</span> <span class="na">class=</span><span class="s">"fieldWrapper"</span><span class="nt">></span>
<span class="cp">{{</span> <span class="nv">form.message.errors</span> <span class="cp">}}</span>
<span class="nt"><label</span> <span class="na">for=</span><span class="s">"id_message"</span><span class="nt">></span>Your message:<span class="nt"></label></span>
<span class="cp">{{</span> <span class="nv">form.message</span> <span class="cp">}}</span>
<span class="nt"></div></span>
<span class="nt"><div</span> <span class="na">class=</span><span class="s">"fieldWrapper"</span><span class="nt">></span>
<span class="cp">{{</span> <span class="nv">form.sender.errors</span> <span class="cp">}}</span>
<span class="nt"><label</span> <span class="na">for=</span><span class="s">"id_sender"</span><span class="nt">></span>Your email address:<span class="nt"></label></span>
<span class="cp">{{</span> <span class="nv">form.sender</span> <span class="cp">}}</span>
<span class="nt"></div></span>
<span class="nt"><div</span> <span class="na">class=</span><span class="s">"fieldWrapper"</span><span class="nt">></span>
<span class="cp">{{</span> <span class="nv">form.cc_myself.errors</span> <span class="cp">}}</span>
<span class="nt"><label</span> <span class="na">for=</span><span class="s">"id_cc_myself"</span><span class="nt">></span>CC yourself?<span class="nt"></label></span>
<span class="cp">{{</span> <span class="nv">form.cc_myself</span> <span class="cp">}}</span>
<span class="nt"></div></span>
<span class="nt"><p><input</span> <span class="na">type=</span><span class="s">"submit"</span> <span class="na">value=</span><span class="s">"Send message"</span> <span class="nt">/></p></span>
<span class="nt"></form></span>
</pre></div>
</div>
<p>Each named form-field can be output to the template using
<tt class="docutils literal"><span class="pre">{{</span> <span class="pre">form.name_of_field</span> <span class="pre">}}</span></tt>, which will produce the HTML needed to display the
form widget. Using <tt class="docutils literal"><span class="pre">{{</span> <span class="pre">form.name_of_field.errors</span> <span class="pre">}}</span></tt> displays a list of form
errors, rendered as an unordered list. This might look like:</p>
<div class="highlight-html+django"><div class="highlight"><pre><span class="nt"><ul</span> <span class="na">class=</span><span class="s">"errorlist"</span><span class="nt">></span>
<span class="nt"><li></span>Sender is required.<span class="nt"></li></span>
<span class="nt"></ul></span>
</pre></div>
</div>
<p>The list has a CSS class of <tt class="docutils literal"><span class="pre">errorlist</span></tt> to allow you to style its appearance.
If you wish to further customize the display of errors you can do so by looping
over them:</p>
<div class="highlight-html+django"><div class="highlight"><pre><span class="cp">{%</span> <span class="k">if</span> <span class="nv">form.subject.errors</span> <span class="cp">%}</span>
<span class="nt"><ol></span>
<span class="cp">{%</span> <span class="k">for</span> <span class="nv">error</span> <span class="k">in</span> <span class="nv">form.subject.errors</span> <span class="cp">%}</span>
<span class="nt"><li><strong></span><span class="cp">{{</span> <span class="nv">error</span><span class="o">|</span><span class="nf">escape</span> <span class="cp">}}</span><span class="nt"></strong></li></span>
<span class="cp">{%</span> <span class="k">endfor</span> <span class="cp">%}</span>
<span class="nt"></ol></span>
<span class="cp">{%</span> <span class="k">endif</span> <span class="cp">%}</span>
</pre></div>
</div>
</div>
<div class="section" id="s-looping-over-the-form-s-fields">
<span id="looping-over-the-form-s-fields"></span><h3>Looping over the form’s fields<a class="headerlink" href="#looping-over-the-form-s-fields" title="Permalink to this headline">¶</a></h3>
<p>If you’re using the same HTML for each of your form fields, you can reduce
duplicate code by looping through each field in turn using a <tt class="docutils literal"><span class="pre">{%</span> <span class="pre">for</span> <span class="pre">%}</span></tt>
loop:</p>
<div class="highlight-html+django"><div class="highlight"><pre><span class="nt"><form</span> <span class="na">action=</span><span class="s">"/contact/"</span> <span class="na">method=</span><span class="s">"post"</span><span class="nt">></span>
<span class="cp">{%</span> <span class="k">for</span> <span class="nv">field</span> <span class="k">in</span> <span class="nv">form</span> <span class="cp">%}</span>
<span class="nt"><div</span> <span class="na">class=</span><span class="s">"fieldWrapper"</span><span class="nt">></span>
<span class="cp">{{</span> <span class="nv">field.errors</span> <span class="cp">}}</span>
<span class="cp">{{</span> <span class="nv">field.label_tag</span> <span class="cp">}}</span> <span class="cp">{{</span> <span class="nv">field</span> <span class="cp">}}</span>
<span class="nt"></div></span>
<span class="cp">{%</span> <span class="k">endfor</span> <span class="cp">%}</span>
<span class="nt"><p><input</span> <span class="na">type=</span><span class="s">"submit"</span> <span class="na">value=</span><span class="s">"Send message"</span> <span class="nt">/></p></span>
<span class="nt"></form></span>
</pre></div>
</div>
<p>Within this loop, <tt class="docutils literal"><span class="pre">{{</span> <span class="pre">field</span> <span class="pre">}}</span></tt> is an instance of
<a class="reference internal" href="../../ref/forms/api.html#django.forms.BoundField" title="django.forms.BoundField"><tt class="xref py py-class docutils literal"><span class="pre">BoundField</span></tt></a>. <tt class="docutils literal"><span class="pre">BoundField</span></tt> also has the following
attributes, which can be useful in your templates:</p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">{{</span> <span class="pre">field.label</span> <span class="pre">}}</span></tt></dt>
<dd>The label of the field, e.g. <tt class="docutils literal"><span class="pre">Email</span> <span class="pre">address</span></tt>.</dd>
<dt><tt class="docutils literal"><span class="pre">{{</span> <span class="pre">field.label_tag</span> <span class="pre">}}</span></tt></dt>
<dd><p class="first">The field’s label wrapped in the appropriate HTML <tt class="docutils literal"><span class="pre"><label></span></tt> tag.</p>
<div class="last versionchanged">
<span class="title">Changed in Django 1.6:</span> <p>This includes the form’s <a class="reference internal" href="../../ref/forms/api.html#django.forms.Form.label_suffix" title="django.forms.Form.label_suffix"><tt class="xref py py-attr docutils literal"><span class="pre">label_suffix</span></tt></a>. For
example, the default <tt class="docutils literal"><span class="pre">label_suffix</span></tt> is a colon:</p>
<div class="highlight-html+django"><div class="highlight"><pre><span class="nt"><label</span> <span class="na">for=</span><span class="s">"id_email"</span><span class="nt">></span>Email address:<span class="nt"></label></span>
</pre></div>
</div>
</div>
</dd>
<dt><tt class="docutils literal"><span class="pre">{{</span> <span class="pre">field.id_for_label</span> <span class="pre">}}</span></tt></dt>
<dd>The ID that will be used for this field (<tt class="docutils literal"><span class="pre">id_email</span></tt> in the example
above). You may want to use this in lieu of <tt class="docutils literal"><span class="pre">label_tag</span></tt> if you are
constructing the label manually. It’s also useful, for example, if you have
some inline JavaScript and want to avoid hardcoding the field’s ID.</dd>
<dt><tt class="docutils literal"><span class="pre">{{</span> <span class="pre">field.value</span> <span class="pre">}}</span></tt></dt>
<dd>The value of the field. e.g <tt class="docutils literal"><span class="pre">someone@example.com</span></tt></dd>
<dt><tt class="docutils literal"><span class="pre">{{</span> <span class="pre">field.html_name</span> <span class="pre">}}</span></tt></dt>
<dd>The name of the field that will be used in the input element’s name
field. This takes the form prefix into account, if it has been set.</dd>
<dt><tt class="docutils literal"><span class="pre">{{</span> <span class="pre">field.help_text</span> <span class="pre">}}</span></tt></dt>
<dd>Any help text that has been associated with the field.</dd>
<dt><tt class="docutils literal"><span class="pre">{{</span> <span class="pre">field.errors</span> <span class="pre">}}</span></tt></dt>
<dd>Outputs a <tt class="docutils literal"><span class="pre"><ul</span> <span class="pre">class="errorlist"></span></tt> containing any validation errors
corresponding to this field. You can customize the presentation of
the errors with a <tt class="docutils literal"><span class="pre">{%</span> <span class="pre">for</span> <span class="pre">error</span> <span class="pre">in</span> <span class="pre">field.errors</span> <span class="pre">%}</span></tt> loop. In this
case, each object in the loop is a simple string containing the error
message.</dd>
<dt><tt class="docutils literal"><span class="pre">{{</span> <span class="pre">field.is_hidden</span> <span class="pre">}}</span></tt></dt>
<dd><p class="first">This attribute is <tt class="docutils literal"><span class="pre">True</span></tt> if the form field is a hidden field and
<tt class="docutils literal"><span class="pre">False</span></tt> otherwise. It’s not particularly useful as a template
variable, but could be useful in conditional tests such as:</p>
<div class="last highlight-html+django"><div class="highlight"><pre><span class="cp">{%</span> <span class="k">if</span> <span class="nv">field.is_hidden</span> <span class="cp">%}</span>
<span class="c">{# Do something special #}</span>
<span class="cp">{%</span> <span class="k">endif</span> <span class="cp">%}</span>
</pre></div>
</div>
</dd>
<dt><tt class="docutils literal"><span class="pre">{{</span> <span class="pre">field.field</span> <span class="pre">}}</span></tt></dt>
<dd>The <a class="reference internal" href="../../ref/forms/fields.html#django.forms.Field" title="django.forms.Field"><tt class="xref py py-class docutils literal"><span class="pre">Field</span></tt></a> instance from the form class that
this <a class="reference internal" href="../../ref/forms/api.html#django.forms.BoundField" title="django.forms.BoundField"><tt class="xref py py-class docutils literal"><span class="pre">BoundField</span></tt></a> wraps. You can use it to access
<a class="reference internal" href="../../ref/forms/fields.html#django.forms.Field" title="django.forms.Field"><tt class="xref py py-class docutils literal"><span class="pre">Field</span></tt></a> attributes , e.g.
<tt class="docutils literal"><span class="pre">{{</span> <span class="pre">char_field.field.max_length</span> <span class="pre">}}</span></tt>.</dd>
</dl>
<div class="section" id="s-looping-over-hidden-and-visible-fields">
<span id="looping-over-hidden-and-visible-fields"></span><h4>Looping over hidden and visible fields<a class="headerlink" href="#looping-over-hidden-and-visible-fields" title="Permalink to this headline">¶</a></h4>
<p>If you’re manually laying out a form in a template, as opposed to relying on
Django’s default form layout, you might want to treat <tt class="docutils literal"><span class="pre"><input</span> <span class="pre">type="hidden"></span></tt>
fields differently than non-hidden fields. For example, because hidden fields
don’t display anything, putting error messages “next to” the field could cause
confusion for your users – so errors for those fields should be handled
differently.</p>
<p>Django provides two methods on a form that allow you to loop over the hidden
and visible fields independently: <tt class="docutils literal"><span class="pre">hidden_fields()</span></tt> and
<tt class="docutils literal"><span class="pre">visible_fields()</span></tt>. Here’s a modification of an earlier example that uses
these two methods:</p>
<div class="highlight-html+django"><div class="highlight"><pre><span class="nt"><form</span> <span class="na">action=</span><span class="s">"/contact/"</span> <span class="na">method=</span><span class="s">"post"</span><span class="nt">></span>
<span class="c">{# Include the hidden fields #}</span>
<span class="cp">{%</span> <span class="k">for</span> <span class="nv">hidden</span> <span class="k">in</span> <span class="nv">form.hidden_fields</span> <span class="cp">%}</span>
<span class="cp">{{</span> <span class="nv">hidden</span> <span class="cp">}}</span>
<span class="cp">{%</span> <span class="k">endfor</span> <span class="cp">%}</span>
<span class="c">{# Include the visible fields #}</span>
<span class="cp">{%</span> <span class="k">for</span> <span class="nv">field</span> <span class="k">in</span> <span class="nv">form.visible_fields</span> <span class="cp">%}</span>
<span class="nt"><div</span> <span class="na">class=</span><span class="s">"fieldWrapper"</span><span class="nt">></span>
<span class="cp">{{</span> <span class="nv">field.errors</span> <span class="cp">}}</span>
<span class="cp">{{</span> <span class="nv">field.label_tag</span> <span class="cp">}}</span> <span class="cp">{{</span> <span class="nv">field</span> <span class="cp">}}</span>
<span class="nt"></div></span>
<span class="cp">{%</span> <span class="k">endfor</span> <span class="cp">%}</span>
<span class="nt"><p><input</span> <span class="na">type=</span><span class="s">"submit"</span> <span class="na">value=</span><span class="s">"Send message"</span> <span class="nt">/></p></span>
<span class="nt"></form></span>
</pre></div>
</div>
<p>This example does not handle any errors in the hidden fields. Usually, an
error in a hidden field is a sign of form tampering, since normal form
interaction won’t alter them. However, you could easily insert some error
displays for those form errors, as well.</p>
</div>
</div>
<div class="section" id="s-reusable-form-templates">
<span id="reusable-form-templates"></span><h3>Reusable form templates<a class="headerlink" href="#reusable-form-templates" title="Permalink to this headline">¶</a></h3>
<p>If your site uses the same rendering logic for forms in multiple places, you
can reduce duplication by saving the form’s loop in a standalone template and
using the <a class="reference internal" href="../../ref/templates/builtins.html#std:templatetag-include"><tt class="xref std std-ttag docutils literal"><span class="pre">include</span></tt></a> tag to reuse it in other templates:</p>
<div class="highlight-html+django"><div class="highlight"><pre><span class="nt"><form</span> <span class="na">action=</span><span class="s">"/contact/"</span> <span class="na">method=</span><span class="s">"post"</span><span class="nt">></span>
<span class="cp">{%</span> <span class="k">include</span> <span class="s2">"form_snippet.html"</span> <span class="cp">%}</span>
<span class="nt"><p><input</span> <span class="na">type=</span><span class="s">"submit"</span> <span class="na">value=</span><span class="s">"Send message"</span> <span class="nt">/></p></span>
<span class="nt"></form></span>
# In form_snippet.html:
<span class="cp">{%</span> <span class="k">for</span> <span class="nv">field</span> <span class="k">in</span> <span class="nv">form</span> <span class="cp">%}</span>
<span class="nt"><div</span> <span class="na">class=</span><span class="s">"fieldWrapper"</span><span class="nt">></span>
<span class="cp">{{</span> <span class="nv">field.errors</span> <span class="cp">}}</span>
<span class="cp">{{</span> <span class="nv">field.label_tag</span> <span class="cp">}}</span> <span class="cp">{{</span> <span class="nv">field</span> <span class="cp">}}</span>
<span class="nt"></div></span>
<span class="cp">{%</span> <span class="k">endfor</span> <span class="cp">%}</span>
</pre></div>
</div>
<p>If the form object passed to a template has a different name within the
context, you can alias it using the <tt class="docutils literal"><span class="pre">with</span></tt> argument of the <a class="reference internal" href="../../ref/templates/builtins.html#std:templatetag-include"><tt class="xref std std-ttag docutils literal"><span class="pre">include</span></tt></a>
tag:</p>
<div class="highlight-html+django"><div class="highlight"><pre><span class="nt"><form</span> <span class="na">action=</span><span class="s">"/comments/add/"</span> <span class="na">method=</span><span class="s">"post"</span><span class="nt">></span>
<span class="cp">{%</span> <span class="k">include</span> <span class="s2">"form_snippet.html"</span> <span class="k">with</span> <span class="nv">form</span><span class="o">=</span><span class="nv">comment_form</span> <span class="cp">%}</span>
<span class="nt"><p><input</span> <span class="na">type=</span><span class="s">"submit"</span> <span class="na">value=</span><span class="s">"Submit comment"</span> <span class="nt">/></p></span>
<span class="nt"></form></span>
</pre></div>
</div>
<p>If you find yourself doing this often, you might consider creating a custom
<a class="reference internal" href="../../howto/custom-template-tags.html#howto-custom-template-tags-inclusion-tags"><em>inclusion tag</em></a>.</p>
</div>
</div>
<div class="section" id="s-further-topics">
<span id="further-topics"></span><h2>Further topics<a class="headerlink" href="#further-topics" title="Permalink to this headline">¶</a></h2>
<p>This covers the basics, but forms can do a whole lot more:</p>
<div class="toctree-wrapper compound">
<ul>
<li class="toctree-l1"><a class="reference internal" href="formsets.html">Formsets</a><ul>
<li class="toctree-l2"><a class="reference internal" href="formsets.html#using-initial-data-with-a-formset">Using initial data with a formset</a></li>
<li class="toctree-l2"><a class="reference internal" href="formsets.html#limiting-the-maximum-number-of-forms">Limiting the maximum number of forms</a></li>
<li class="toctree-l2"><a class="reference internal" href="formsets.html#formset-validation">Formset validation</a></li>
<li class="toctree-l2"><a class="reference internal" href="formsets.html#validating-the-number-of-forms-in-a-formset">Validating the number of forms in a formset</a></li>
<li class="toctree-l2"><a class="reference internal" href="formsets.html#dealing-with-ordering-and-deletion-of-forms">Dealing with ordering and deletion of forms</a></li>
<li class="toctree-l2"><a class="reference internal" href="formsets.html#adding-additional-fields-to-a-formset">Adding additional fields to a formset</a></li>
<li class="toctree-l2"><a class="reference internal" href="formsets.html#using-a-formset-in-views-and-templates">Using a formset in views and templates</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="modelforms.html">Creating forms from models</a><ul>
<li class="toctree-l2"><a class="reference internal" href="modelforms.html#modelform"><tt class="docutils literal"><span class="pre">ModelForm</span></tt></a></li>
<li class="toctree-l2"><a class="reference internal" href="modelforms.html#model-formsets">Model formsets</a></li>
<li class="toctree-l2"><a class="reference internal" href="modelforms.html#inline-formsets">Inline formsets</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="media.html">Form Assets (the <tt class="docutils literal"><span class="pre">Media</span></tt> class)</a><ul>
<li class="toctree-l2"><a class="reference internal" href="media.html#assets-as-a-static-definition">Assets as a static definition</a></li>
<li class="toctree-l2"><a class="reference internal" href="media.html#media-as-a-dynamic-property"><tt class="docutils literal"><span class="pre">Media</span></tt> as a dynamic property</a></li>
<li class="toctree-l2"><a class="reference internal" href="media.html#paths-in-asset-definitions">Paths in asset definitions</a></li>
<li class="toctree-l2"><a class="reference internal" href="media.html#media-objects"><tt class="docutils literal"><span class="pre">Media</span></tt> objects</a></li>
<li class="toctree-l2"><a class="reference internal" href="media.html#media-on-forms"><tt class="docutils literal"><span class="pre">Media</span></tt> on Forms</a></li>
</ul>
</li>
</ul>
</div>
<div class="admonition-see-also admonition seealso">
<p class="first admonition-title">See also</p>
<dl class="last docutils">
<dt><a class="reference internal" href="../../ref/forms/index.html"><em>The Forms Reference</em></a></dt>
<dd>Covers the full API reference, including form fields, form widgets,
and form and field validation.</dd>
</dl>
</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="#">Working with forms</a><ul>
<li><a class="reference internal" href="#overview">Overview</a></li>
<li><a class="reference internal" href="#form-objects">Form objects</a><ul>
<li><a class="reference internal" href="#using-a-form-in-a-view">Using a form in a view</a></li>
<li><a class="reference internal" href="#handling-file-uploads-with-a-form">Handling file uploads with a form</a></li>
<li><a class="reference internal" href="#processing-the-data-from-a-form">Processing the data from a form</a></li>
<li><a class="reference internal" href="#displaying-a-form-using-a-template">Displaying a form using a template</a></li>
<li><a class="reference internal" href="#customizing-the-form-template">Customizing the form template</a></li>
<li><a class="reference internal" href="#looping-over-the-form-s-fields">Looping over the form’s fields</a><ul>
<li><a class="reference internal" href="#looping-over-hidden-and-visible-fields">Looping over hidden and visible fields</a></li>
</ul>
</li>
<li><a class="reference internal" href="#reusable-form-templates">Reusable form templates</a></li>
</ul>
</li>
<li><a class="reference internal" href="#further-topics">Further topics</a><ul>
</ul>
</li>
</ul>
</li>
</ul>
<h3>Browse</h3>
<ul>
<li>Prev: <a href="../http/sessions.html">How to use sessions</a></li>
<li>Next: <a href="formsets.html">Formsets</a></li>
</ul>
<h3>You are here:</h3>
<ul>
<li>
<a href="../../index.html">Django 1.6.7 documentation</a>
<ul><li><a href="../index.html">Using Django</a>
<ul><li>Working with forms</li></ul>
</li></ul>
</li>
</ul>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../../_sources/topics/forms/index.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" />
<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">Sep 26, 2014</p>
</div>
</div>
<div id="ft">
<div class="nav">
« <a href="../http/sessions.html" title="How to use sessions">previous</a>
|
<a href="../index.html" title="Using Django" accesskey="U">up</a>
|
<a href="formsets.html" title="Formsets">next</a> »</div>
</div>
</div>
<div class="clearer"></div>
</div>
</body>
</html>
