<!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>Form wizard — 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="django.contrib.formtools" href="index.html" />
<link rel="next" title="GeoDjango" href="../gis/index.html" />
<link rel="prev" title="Form preview" href="form-preview.html" />
<script type="text/javascript" src="../../../templatebuiltins.js"></script>
<script type="text/javascript">
(function($) {
if (!django_template_builtins) {
// templatebuiltins.js missing, do nothing.
return;
}
$(document).ready(function() {
// Hyperlink Django template tags and filters
var base = "../../templates/builtins.html";
if (base == "#") {
// Special case for builtins.html itself
base = "";
}
// Tags are keywords, class '.k'
$("div.highlight\\-html\\+django span.k").each(function(i, elem) {
var tagname = $(elem).text();
if ($.inArray(tagname, django_template_builtins.ttags) != -1) {
var fragment = tagname.replace(/_/, '-');
$(elem).html("<a href='" + base + "#" + fragment + "'>" + tagname + "</a>");
}
});
// Filters are functions, class '.nf'
$("div.highlight\\-html\\+django span.nf").each(function(i, elem) {
var filtername = $(elem).text();
if ($.inArray(filtername, django_template_builtins.tfilters) != -1) {
var fragment = filtername.replace(/_/, '-');
$(elem).html("<a href='" + base + "#" + fragment + "'>" + filtername + "</a>");
}
});
});
})(jQuery);
</script>
</head>
<body>
<div class="document">
<div id="custom-doc" class="yui-t6">
<div id="hd">
<h1><a href="../../../index.html">Django 1.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="form-preview.html" title="Form preview">previous</a>
|
<a href="../../index.html" title="API Reference" accesskey="U">up</a>
|
<a href="../gis/index.html" title="GeoDjango">next</a> »</div>
</div>
<div id="bd">
<div id="yui-main">
<div class="yui-b">
<div class="yui-g" id="ref-contrib-formtools-form-wizard">
<div class="section" id="s-module-django.contrib.formtools.wizard.views">
<span id="s-form-wizard"></span><span id="module-django.contrib.formtools.wizard.views"></span><span id="form-wizard"></span><h1>Form wizard<a class="headerlink" href="#module-django.contrib.formtools.wizard.views" title="Permalink to this headline">¶</a></h1>
<p>Django comes with an optional “form wizard” application that splits
<a class="reference internal" href="../../../topics/forms/index.html"><em>forms</em></a> across multiple Web pages. It maintains
state in one of the backends so that the full server-side processing can be
delayed until the submission of the final form.</p>
<p>You might want to use this if you have a lengthy form that would be too
unwieldy for display on a single page. The first page might ask the user for
core information, the second page might ask for less important information,
etc.</p>
<p>The term “wizard”, in this context, is <a class="reference external" href="http://en.wikipedia.org/wiki/Wizard_%28software%29">explained on Wikipedia</a>.</p>
<div class="section" id="s-how-it-works">
<span id="how-it-works"></span><h2>How it works<a class="headerlink" href="#how-it-works" title="Permalink to this headline">¶</a></h2>
<p>Here’s the basic workflow for how a user would use a wizard:</p>
<ol class="arabic simple">
<li>The user visits the first page of the wizard, fills in the form and
submits it.</li>
<li>The server validates the data. If it’s invalid, the form is displayed
again, with error messages. If it’s valid, the server saves the current
state of the wizard in the backend and redirects to the next step.</li>
<li>Step 1 and 2 repeat, for every subsequent form in the wizard.</li>
<li>Once the user has submitted all the forms and all the data has been
validated, the wizard processes the data – saving it to the database,
sending an email, or whatever the application needs to do.</li>
</ol>
</div>
<div class="section" id="s-usage">
<span id="usage"></span><h2>Usage<a class="headerlink" href="#usage" title="Permalink to this headline">¶</a></h2>
<p>This application handles as much machinery for you as possible. Generally,
you just have to do these things:</p>
<ol class="arabic simple">
<li>Define a number of <a class="reference internal" href="../../forms/api.html#django.forms.Form" title="django.forms.Form"><tt class="xref py py-class docutils literal"><span class="pre">Form</span></tt></a> classes – one per
wizard page.</li>
<li>Create a <a class="reference internal" href="#django.contrib.formtools.wizard.views.WizardView" title="django.contrib.formtools.wizard.views.WizardView"><tt class="xref py py-class docutils literal"><span class="pre">WizardView</span></tt></a> subclass that specifies what to do once
all of your forms have been submitted and validated. This also lets
you override some of the wizard’s behavior.</li>
<li>Create some templates that render the forms. You can define a single,
generic template to handle every one of the forms, or you can define a
specific template for each form.</li>
<li>Add <tt class="docutils literal"><span class="pre">django.contrib.formtools</span></tt> to your
<a class="reference internal" href="../../settings.html#std:setting-INSTALLED_APPS"><tt class="xref std std-setting docutils literal"><span class="pre">INSTALLED_APPS</span></tt></a> list in your settings file.</li>
<li>Point your URLconf at your <a class="reference internal" href="#django.contrib.formtools.wizard.views.WizardView" title="django.contrib.formtools.wizard.views.WizardView"><tt class="xref py py-class docutils literal"><span class="pre">WizardView</span></tt></a> <a class="reference internal" href="#django.contrib.formtools.wizard.views.WizardView.as_view" title="django.contrib.formtools.wizard.views.WizardView.as_view"><tt class="xref py py-meth docutils literal"><span class="pre">as_view()</span></tt></a>
method.</li>
</ol>
<div class="section" id="s-defining-form-classes">
<span id="defining-form-classes"></span><h3>Defining <tt class="docutils literal"><span class="pre">Form</span></tt> classes<a class="headerlink" href="#defining-form-classes" title="Permalink to this headline">¶</a></h3>
<p>The first step in creating a form wizard is to create the
<a class="reference internal" href="../../forms/api.html#django.forms.Form" title="django.forms.Form"><tt class="xref py py-class docutils literal"><span class="pre">Form</span></tt></a> classes. These should be standard
<a class="reference internal" href="../../forms/api.html#django.forms.Form" title="django.forms.Form"><tt class="xref py py-class docutils literal"><span class="pre">django.forms.Form</span></tt></a> classes, covered in the <a class="reference internal" href="../../../topics/forms/index.html"><em>forms documentation</em></a>. These classes can live anywhere in your codebase,
but convention is to put them in a file called <tt class="file docutils literal"><span class="pre">forms.py</span></tt> in your
application.</p>
<p>For example, let’s write a “contact form” wizard, where the first page’s form
collects the sender’s email address and subject, and the second page collects
the message itself. Here’s what the <tt class="file docutils literal"><span class="pre">forms.py</span></tt> might look like:</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">ContactForm1</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">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="k">class</span> <span class="nc">ContactForm2</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">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">widget</span><span class="o">=</span><span class="n">forms</span><span class="o">.</span><span class="n">Textarea</span><span class="p">)</span>
</pre></div>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">In order to use <a class="reference internal" href="../../forms/fields.html#django.forms.FileField" title="django.forms.FileField"><tt class="xref py py-class docutils literal"><span class="pre">FileField</span></tt></a> in any form, see the
section <a class="reference internal" href="#wizard-files"><em>Handling files</em></a> below to learn more about
what to do.</p>
</div>
</div>
<div class="section" id="s-creating-a-wizardview-subclass">
<span id="creating-a-wizardview-subclass"></span><h3>Creating a <tt class="docutils literal"><span class="pre">WizardView</span></tt> subclass<a class="headerlink" href="#creating-a-wizardview-subclass" title="Permalink to this headline">¶</a></h3>
<dl class="class">
<dt id="django.contrib.formtools.wizard.views.SessionWizardView">
<em class="property">class </em><tt class="descname">SessionWizardView</tt><a class="headerlink" href="#django.contrib.formtools.wizard.views.SessionWizardView" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<dl class="class">
<dt id="django.contrib.formtools.wizard.views.CookieWizardView">
<em class="property">class </em><tt class="descname">CookieWizardView</tt><a class="headerlink" href="#django.contrib.formtools.wizard.views.CookieWizardView" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<p>The next step is to create a
<a class="reference internal" href="#django.contrib.formtools.wizard.views.WizardView" title="django.contrib.formtools.wizard.views.WizardView"><tt class="xref py py-class docutils literal"><span class="pre">django.contrib.formtools.wizard.views.WizardView</span></tt></a> subclass. You can
also use the <a class="reference internal" href="#django.contrib.formtools.wizard.views.SessionWizardView" title="django.contrib.formtools.wizard.views.SessionWizardView"><tt class="xref py py-class docutils literal"><span class="pre">SessionWizardView</span></tt></a> or <a class="reference internal" href="#django.contrib.formtools.wizard.views.CookieWizardView" title="django.contrib.formtools.wizard.views.CookieWizardView"><tt class="xref py py-class docutils literal"><span class="pre">CookieWizardView</span></tt></a> classes
which preselect the backend used for storing information during execution of the
wizard (as their names indicate, server-side sessions and browser cookies
respectively).</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">To use the <a class="reference internal" href="#django.contrib.formtools.wizard.views.SessionWizardView" title="django.contrib.formtools.wizard.views.SessionWizardView"><tt class="xref py py-class docutils literal"><span class="pre">SessionWizardView</span></tt></a> follow the instructions
in the <a class="reference internal" href="../../../topics/http/sessions.html"><em>sessions documentation</em></a> on
how to enable sessions.</p>
</div>
<p>We will use the <a class="reference internal" href="#django.contrib.formtools.wizard.views.SessionWizardView" title="django.contrib.formtools.wizard.views.SessionWizardView"><tt class="xref py py-class docutils literal"><span class="pre">SessionWizardView</span></tt></a> in all examples but is completely
fine to use the <a class="reference internal" href="#django.contrib.formtools.wizard.views.CookieWizardView" title="django.contrib.formtools.wizard.views.CookieWizardView"><tt class="xref py py-class docutils literal"><span class="pre">CookieWizardView</span></tt></a> instead. As with your
<a class="reference internal" href="../../forms/api.html#django.forms.Form" title="django.forms.Form"><tt class="xref py py-class docutils literal"><span class="pre">Form</span></tt></a> classes, this <a class="reference internal" href="#django.contrib.formtools.wizard.views.WizardView" title="django.contrib.formtools.wizard.views.WizardView"><tt class="xref py py-class docutils literal"><span class="pre">WizardView</span></tt></a> class can live
anywhere in your codebase, but convention is to put it in <tt class="file docutils literal"><span class="pre">views.py</span></tt>.</p>
<p>The only requirement on this subclass is that it implement a
<a class="reference internal" href="#django.contrib.formtools.wizard.views.WizardView.done" title="django.contrib.formtools.wizard.views.WizardView.done"><tt class="xref py py-meth docutils literal"><span class="pre">done()</span></tt></a> method.</p>
<dl class="method">
<dt id="django.contrib.formtools.wizard.views.WizardView.done">
<tt class="descclassname">WizardView.</tt><tt class="descname">done</tt>(<em>form_list</em>)<a class="headerlink" href="#django.contrib.formtools.wizard.views.WizardView.done" title="Permalink to this definition">¶</a></dt>
<dd><p>This method specifies what should happen when the data for <em>every</em> form is
submitted and validated. This method is passed a list of validated
<a class="reference internal" href="../../forms/api.html#django.forms.Form" title="django.forms.Form"><tt class="xref py py-class docutils literal"><span class="pre">Form</span></tt></a> instances.</p>
<p>In this simplistic example, rather than performing any database operation,
the method simply renders a template of the validated data:</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_to_response</span>
<span class="kn">from</span> <span class="nn">django.contrib.formtools.wizard.views</span> <span class="kn">import</span> <span class="n">SessionWizardView</span>
<span class="k">class</span> <span class="nc">ContactWizard</span><span class="p">(</span><span class="n">SessionWizardView</span><span class="p">):</span>
<span class="k">def</span> <span class="nf">done</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">form_list</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">):</span>
<span class="k">return</span> <span class="n">render_to_response</span><span class="p">(</span><span class="s">'done.html'</span><span class="p">,</span> <span class="p">{</span>
<span class="s">'form_data'</span><span class="p">:</span> <span class="p">[</span><span class="n">form</span><span class="o">.</span><span class="n">cleaned_data</span> <span class="k">for</span> <span class="n">form</span> <span class="ow">in</span> <span class="n">form_list</span><span class="p">],</span>
<span class="p">})</span>
</pre></div>
</div>
<p>Note that this method will be called via <tt class="docutils literal"><span class="pre">POST</span></tt>, so it really ought to be a
good Web citizen and redirect after processing the data. Here’s another
example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">django.http</span> <span class="kn">import</span> <span class="n">HttpResponseRedirect</span>
<span class="kn">from</span> <span class="nn">django.contrib.formtools.wizard.views</span> <span class="kn">import</span> <span class="n">SessionWizardView</span>
<span class="k">class</span> <span class="nc">ContactWizard</span><span class="p">(</span><span class="n">SessionWizardView</span><span class="p">):</span>
<span class="k">def</span> <span class="nf">done</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">form_list</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">):</span>
<span class="n">do_something_with_the_form_data</span><span class="p">(</span><span class="n">form_list</span><span class="p">)</span>
<span class="k">return</span> <span class="n">HttpResponseRedirect</span><span class="p">(</span><span class="s">'/page-to-redirect-to-when-done/'</span><span class="p">)</span>
</pre></div>
</div>
</dd></dl>
<p>See the section <a class="reference internal" href="#wizardview-advanced-methods"><em>Advanced WizardView methods</em></a>
below to learn about more <a class="reference internal" href="#django.contrib.formtools.wizard.views.WizardView" title="django.contrib.formtools.wizard.views.WizardView"><tt class="xref py py-class docutils literal"><span class="pre">WizardView</span></tt></a> hooks.</p>
</div>
<div class="section" id="s-creating-templates-for-the-forms">
<span id="creating-templates-for-the-forms"></span><h3>Creating templates for the forms<a class="headerlink" href="#creating-templates-for-the-forms" title="Permalink to this headline">¶</a></h3>
<p>Next, you’ll need to create a template that renders the wizard’s forms. By
default, every form uses a template called
<tt class="file docutils literal"><span class="pre">formtools/wizard/wizard_form.html</span></tt>. You can change this template name
by overriding either the
<a class="reference internal" href="../../class-based-views/mixins-simple.html#django.views.generic.base.TemplateResponseMixin.template_name" title="django.views.generic.base.TemplateResponseMixin.template_name"><tt class="xref py py-attr docutils literal"><span class="pre">template_name</span></tt></a> attribute
or the
<a class="reference internal" href="../../class-based-views/mixins-simple.html#django.views.generic.base.TemplateResponseMixin.get_template_names" title="django.views.generic.base.TemplateResponseMixin.get_template_names"><tt class="xref py py-meth docutils literal"><span class="pre">get_template_names()</span></tt></a>
method, which are documented in the
<a class="reference internal" href="../../class-based-views/mixins-simple.html#django.views.generic.base.TemplateResponseMixin" title="django.views.generic.base.TemplateResponseMixin"><tt class="xref py py-class docutils literal"><span class="pre">TemplateResponseMixin</span></tt></a> documentation. The
latter one allows you to use a different template for each form (<a class="reference internal" href="#wizard-template-for-each-form"><em>see the
example below</em></a>).</p>
<p>This template expects a <tt class="docutils literal"><span class="pre">wizard</span></tt> object that has various items attached to
it:</p>
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">form</span></tt> – The <a class="reference internal" href="../../forms/api.html#django.forms.Form" title="django.forms.Form"><tt class="xref py py-class docutils literal"><span class="pre">Form</span></tt></a> or
<a class="reference internal" href="../../../topics/forms/formsets.html#django.forms.formsets.BaseFormSet" title="django.forms.formsets.BaseFormSet"><tt class="xref py py-class docutils literal"><span class="pre">BaseFormSet</span></tt></a> instance for the current step
(either empty or with errors).</li>
<li><tt class="docutils literal"><span class="pre">steps</span></tt> – A helper object to access the various steps related data:<ul>
<li><tt class="docutils literal"><span class="pre">step0</span></tt> – The current step (zero-based).</li>
<li><tt class="docutils literal"><span class="pre">step1</span></tt> – The current step (one-based).</li>
<li><tt class="docutils literal"><span class="pre">count</span></tt> – The total number of steps.</li>
<li><tt class="docutils literal"><span class="pre">first</span></tt> – The first step.</li>
<li><tt class="docutils literal"><span class="pre">last</span></tt> – The last step.</li>
<li><tt class="docutils literal"><span class="pre">current</span></tt> – The current (or first) step.</li>
<li><tt class="docutils literal"><span class="pre">next</span></tt> – The next step.</li>
<li><tt class="docutils literal"><span class="pre">prev</span></tt> – The previous step.</li>
<li><tt class="docutils literal"><span class="pre">index</span></tt> – The index of the current step.</li>
<li><tt class="docutils literal"><span class="pre">all</span></tt> – A list of all steps of the wizard.</li>
</ul>
</li>
</ul>
<p>You can supply additional context variables by using the
<a class="reference internal" href="#django.contrib.formtools.wizard.views.WizardView.get_context_data" title="django.contrib.formtools.wizard.views.WizardView.get_context_data"><tt class="xref py py-meth docutils literal"><span class="pre">get_context_data()</span></tt></a> method of your <a class="reference internal" href="#django.contrib.formtools.wizard.views.WizardView" title="django.contrib.formtools.wizard.views.WizardView"><tt class="xref py py-class docutils literal"><span class="pre">WizardView</span></tt></a>
subclass.</p>
<p>Here’s a full example template:</p>
<div class="highlight-html+django"><div class="highlight"><pre><span class="cp">{%</span> <span class="k">extends</span> <span class="s2">"base.html"</span> <span class="cp">%}</span>
<span class="cp">{%</span> <span class="k">load</span> <span class="nv">i18n</span> <span class="cp">%}</span>
<span class="cp">{%</span> <span class="k">block</span> <span class="nv">head</span> <span class="cp">%}</span>
<span class="cp">{{</span> <span class="nv">wizard.form.media</span> <span class="cp">}}</span>
<span class="cp">{%</span> <span class="k">endblock</span> <span class="cp">%}</span>
<span class="cp">{%</span> <span class="k">block</span> <span class="nv">content</span> <span class="cp">%}</span>
<span class="nt"><p></span>Step <span class="cp">{{</span> <span class="nv">wizard.steps.step1</span> <span class="cp">}}</span> of <span class="cp">{{</span> <span class="nv">wizard.steps.count</span> <span class="cp">}}</span><span class="nt"></p></span>
<span class="nt"><form</span> <span class="na">action=</span><span class="s">""</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="nt"><table></span>
<span class="cp">{{</span> <span class="nv">wizard.management_form</span> <span class="cp">}}</span>
<span class="cp">{%</span> <span class="k">if</span> <span class="nv">wizard.form.forms</span> <span class="cp">%}</span>
<span class="cp">{{</span> <span class="nv">wizard.form.management_form</span> <span class="cp">}}</span>
<span class="cp">{%</span> <span class="k">for</span> <span class="nv">form</span> <span class="k">in</span> <span class="nv">wizard.form.forms</span> <span class="cp">%}</span>
<span class="cp">{{</span> <span class="nv">form</span> <span class="cp">}}</span>
<span class="cp">{%</span> <span class="k">endfor</span> <span class="cp">%}</span>
<span class="cp">{%</span> <span class="k">else</span> <span class="cp">%}</span>
<span class="cp">{{</span> <span class="nv">wizard.form</span> <span class="cp">}}</span>
<span class="cp">{%</span> <span class="k">endif</span> <span class="cp">%}</span>
<span class="nt"></table></span>
<span class="cp">{%</span> <span class="k">if</span> <span class="nv">wizard.steps.prev</span> <span class="cp">%}</span>
<span class="nt"><button</span> <span class="na">name=</span><span class="s">"wizard_goto_step"</span> <span class="na">type=</span><span class="s">"submit"</span> <span class="na">value=</span><span class="s">"</span><span class="cp">{{</span> <span class="nv">wizard.steps.first</span> <span class="cp">}}</span><span class="s">"</span><span class="nt">></span><span class="cp">{%</span> <span class="k">trans</span> <span class="s2">"first step"</span> <span class="cp">%}</span><span class="nt"></button></span>
<span class="nt"><button</span> <span class="na">name=</span><span class="s">"wizard_goto_step"</span> <span class="na">type=</span><span class="s">"submit"</span> <span class="na">value=</span><span class="s">"</span><span class="cp">{{</span> <span class="nv">wizard.steps.prev</span> <span class="cp">}}</span><span class="s">"</span><span class="nt">></span><span class="cp">{%</span> <span class="k">trans</span> <span class="s2">"prev step"</span> <span class="cp">%}</span><span class="nt"></button></span>
<span class="cp">{%</span> <span class="k">endif</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">"</span><span class="cp">{%</span> <span class="k">trans</span> <span class="s2">"submit"</span> <span class="cp">%}</span><span class="s">"</span><span class="nt">/></span>
<span class="nt"></form></span>
<span class="cp">{%</span> <span class="k">endblock</span> <span class="cp">%}</span>
</pre></div>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Note that <tt class="docutils literal"><span class="pre">{{</span> <span class="pre">wizard.management_form</span> <span class="pre">}}</span></tt> <strong>must be used</strong> for
the wizard to work properly.</p>
</div>
</div>
<div class="section" id="s-hooking-the-wizard-into-a-urlconf">
<span id="s-wizard-urlconf"></span><span id="hooking-the-wizard-into-a-urlconf"></span><span id="wizard-urlconf"></span><h3>Hooking the wizard into a URLconf<a class="headerlink" href="#hooking-the-wizard-into-a-urlconf" title="Permalink to this headline">¶</a></h3>
<dl class="method">
<dt id="django.contrib.formtools.wizard.views.WizardView.as_view">
<tt class="descclassname">WizardView.</tt><tt class="descname">as_view</tt>()<a class="headerlink" href="#django.contrib.formtools.wizard.views.WizardView.as_view" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<p>Finally, we need to specify which forms to use in the wizard, and then
deploy the new <a class="reference internal" href="#django.contrib.formtools.wizard.views.WizardView" title="django.contrib.formtools.wizard.views.WizardView"><tt class="xref py py-class docutils literal"><span class="pre">WizardView</span></tt></a> object at a URL in the <tt class="docutils literal"><span class="pre">urls.py</span></tt>. The
wizard’s <tt class="docutils literal"><span class="pre">as_view()</span></tt> method takes a list of your
<a class="reference internal" href="../../forms/api.html#django.forms.Form" title="django.forms.Form"><tt class="xref py py-class docutils literal"><span class="pre">Form</span></tt></a> classes as an argument during instantiation:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">django.conf.urls</span> <span class="kn">import</span> <span class="n">patterns</span>
<span class="kn">from</span> <span class="nn">myapp.forms</span> <span class="kn">import</span> <span class="n">ContactForm1</span><span class="p">,</span> <span class="n">ContactForm2</span>
<span class="kn">from</span> <span class="nn">myapp.views</span> <span class="kn">import</span> <span class="n">ContactWizard</span>
<span class="n">urlpatterns</span> <span class="o">=</span> <span class="n">patterns</span><span class="p">(</span><span class="s">''</span><span class="p">,</span>
<span class="p">(</span><span class="s">r'^contact/$'</span><span class="p">,</span> <span class="n">ContactWizard</span><span class="o">.</span><span class="n">as_view</span><span class="p">([</span><span class="n">ContactForm1</span><span class="p">,</span> <span class="n">ContactForm2</span><span class="p">])),</span>
<span class="p">)</span>
</pre></div>
</div>
<div class="versionchanged">
<span class="title">Changed in Django 1.6.</span> </div>
<p>You can also pass the form list as a class attribute named <tt class="docutils literal"><span class="pre">form_list</span></tt>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">class</span> <span class="nc">ContactWizard</span><span class="p">(</span><span class="n">WizardView</span><span class="p">):</span>
<span class="n">form_list</span> <span class="o">=</span> <span class="p">[</span><span class="n">ContactForm1</span><span class="p">,</span> <span class="n">ContactForm2</span><span class="p">]</span>
</pre></div>
</div>
</div>
<div class="section" id="s-using-a-different-template-for-each-form">
<span id="s-wizard-template-for-each-form"></span><span id="using-a-different-template-for-each-form"></span><span id="wizard-template-for-each-form"></span><h3>Using a different template for each form<a class="headerlink" href="#using-a-different-template-for-each-form" title="Permalink to this headline">¶</a></h3>
<p>As mentioned above, you may specify a different template for each form.
Consider an example using a form wizard to implement a multi-step checkout
process for an online store. In the first step, the user specifies a billing
and shipping address. In the second step, the user chooses payment type. If
they chose to pay by credit card, they will enter credit card information in
the next step. In the final step, they will confirm the purchase.</p>
<p>Here’s what the view code might look like:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">django.http</span> <span class="kn">import</span> <span class="n">HttpResponseRedirect</span>
<span class="kn">from</span> <span class="nn">django.contrib.formtools.wizard.views</span> <span class="kn">import</span> <span class="n">SessionWizardView</span>
<span class="n">FORMS</span> <span class="o">=</span> <span class="p">[(</span><span class="s">"address"</span><span class="p">,</span> <span class="n">myapp</span><span class="o">.</span><span class="n">forms</span><span class="o">.</span><span class="n">AddressForm</span><span class="p">),</span>
<span class="p">(</span><span class="s">"paytype"</span><span class="p">,</span> <span class="n">myapp</span><span class="o">.</span><span class="n">forms</span><span class="o">.</span><span class="n">PaymentChoiceForm</span><span class="p">),</span>
<span class="p">(</span><span class="s">"cc"</span><span class="p">,</span> <span class="n">myapp</span><span class="o">.</span><span class="n">forms</span><span class="o">.</span><span class="n">CreditCardForm</span><span class="p">),</span>
<span class="p">(</span><span class="s">"confirmation"</span><span class="p">,</span> <span class="n">myapp</span><span class="o">.</span><span class="n">forms</span><span class="o">.</span><span class="n">OrderForm</span><span class="p">)]</span>
<span class="n">TEMPLATES</span> <span class="o">=</span> <span class="p">{</span><span class="s">"address"</span><span class="p">:</span> <span class="s">"checkout/billingaddress.html"</span><span class="p">,</span>
<span class="s">"paytype"</span><span class="p">:</span> <span class="s">"checkout/paymentmethod.html"</span><span class="p">,</span>
<span class="s">"cc"</span><span class="p">:</span> <span class="s">"checkout/creditcard.html"</span><span class="p">,</span>
<span class="s">"confirmation"</span><span class="p">:</span> <span class="s">"checkout/confirmation.html"</span><span class="p">}</span>
<span class="k">def</span> <span class="nf">pay_by_credit_card</span><span class="p">(</span><span class="n">wizard</span><span class="p">):</span>
<span class="sd">"""Return true if user opts to pay by credit card"""</span>
<span class="c"># Get cleaned data from payment step</span>
<span class="n">cleaned_data</span> <span class="o">=</span> <span class="n">wizard</span><span class="o">.</span><span class="n">get_cleaned_data_for_step</span><span class="p">(</span><span class="s">'paytype'</span><span class="p">)</span> <span class="ow">or</span> <span class="p">{</span><span class="s">'method'</span><span class="p">:</span> <span class="s">'none'</span><span class="p">}</span>
<span class="c"># Return true if the user selected credit card</span>
<span class="k">return</span> <span class="n">cleaned_data</span><span class="p">[</span><span class="s">'method'</span><span class="p">]</span> <span class="o">==</span> <span class="s">'cc'</span>
<span class="k">class</span> <span class="nc">OrderWizard</span><span class="p">(</span><span class="n">SessionWizardView</span><span class="p">):</span>
<span class="k">def</span> <span class="nf">get_template_names</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="k">return</span> <span class="p">[</span><span class="n">TEMPLATES</span><span class="p">[</span><span class="bp">self</span><span class="o">.</span><span class="n">steps</span><span class="o">.</span><span class="n">current</span><span class="p">]]</span>
<span class="k">def</span> <span class="nf">done</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">form_list</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">):</span>
<span class="n">do_something_with_the_form_data</span><span class="p">(</span><span class="n">form_list</span><span class="p">)</span>
<span class="k">return</span> <span class="n">HttpResponseRedirect</span><span class="p">(</span><span class="s">'/page-to-redirect-to-when-done/'</span><span class="p">)</span>
<span class="o">...</span>
</pre></div>
</div>
<p>The <tt class="docutils literal"><span class="pre">urls.py</span></tt> file would contain something like:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">urlpatterns</span> <span class="o">=</span> <span class="n">patterns</span><span class="p">(</span><span class="s">''</span><span class="p">,</span>
<span class="p">(</span><span class="s">r'^checkout/$'</span><span class="p">,</span> <span class="n">OrderWizard</span><span class="o">.</span><span class="n">as_view</span><span class="p">(</span><span class="n">FORMS</span><span class="p">,</span> <span class="n">condition_dict</span><span class="o">=</span><span class="p">{</span><span class="s">'cc'</span><span class="p">:</span> <span class="n">pay_by_credit_card</span><span class="p">})),</span>
<span class="p">)</span>
</pre></div>
</div>
<div class="versionchanged">
<span class="title">Changed in Django 1.6.</span> </div>
<p>The <tt class="docutils literal"><span class="pre">condition_dict</span></tt> can be passed as attribute for the <tt class="docutils literal"><span class="pre">as_view()`</span>
<span class="pre">method</span> <span class="pre">or</span> <span class="pre">as</span> <span class="pre">a</span> <span class="pre">class</span> <span class="pre">attribute</span> <span class="pre">named</span> <span class="pre">``condition_dict</span></tt>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">class</span> <span class="nc">OrderWizard</span><span class="p">(</span><span class="n">WizardView</span><span class="p">):</span>
<span class="n">condition_dict</span> <span class="o">=</span> <span class="p">{</span><span class="s">'cc'</span><span class="p">:</span> <span class="n">pay_by_credit_card</span><span class="p">}</span>
</pre></div>
</div>
<p>Note that the <tt class="docutils literal"><span class="pre">OrderWizard</span></tt> object is initialized with a list of pairs.
The first element in the pair is a string that corresponds to the name of the
step and the second is the form class.</p>
<p>In this example, the
<a class="reference internal" href="../../class-based-views/mixins-simple.html#django.views.generic.base.TemplateResponseMixin.get_template_names" title="django.views.generic.base.TemplateResponseMixin.get_template_names"><tt class="xref py py-meth docutils literal"><span class="pre">get_template_names()</span></tt></a>
method returns a list containing a single template, which is selected based on
the name of the current step.</p>
</div>
</div>
<div class="section" id="s-advanced-wizardview-methods">
<span id="s-wizardview-advanced-methods"></span><span id="advanced-wizardview-methods"></span><span id="wizardview-advanced-methods"></span><h2>Advanced <tt class="docutils literal"><span class="pre">WizardView</span></tt> methods<a class="headerlink" href="#advanced-wizardview-methods" title="Permalink to this headline">¶</a></h2>
<dl class="class">
<dt id="django.contrib.formtools.wizard.views.WizardView">
<em class="property">class </em><tt class="descname">WizardView</tt><a class="headerlink" href="#django.contrib.formtools.wizard.views.WizardView" title="Permalink to this definition">¶</a></dt>
<dd><p>Aside from the <a class="reference internal" href="#django.contrib.formtools.wizard.views.WizardView.done" title="django.contrib.formtools.wizard.views.WizardView.done"><tt class="xref py py-meth docutils literal"><span class="pre">done()</span></tt></a> method, <a class="reference internal" href="#django.contrib.formtools.wizard.views.WizardView" title="django.contrib.formtools.wizard.views.WizardView"><tt class="xref py py-class docutils literal"><span class="pre">WizardView</span></tt></a> offers a few
advanced method hooks that let you customize how your wizard works.</p>
<p>Some of these methods take an argument <tt class="docutils literal"><span class="pre">step</span></tt>, which is a zero-based
counter as string representing the current step of the wizard. (E.g., the
first form is <tt class="docutils literal"><span class="pre">'0'</span></tt> and the second form is <tt class="docutils literal"><span class="pre">'1'</span></tt>)</p>
</dd></dl>
<dl class="method">
<dt id="django.contrib.formtools.wizard.views.WizardView.get_form_prefix">
<tt class="descclassname">WizardView.</tt><tt class="descname">get_form_prefix</tt>(<em>step=None</em>, <em>form=None</em>)<a class="headerlink" href="#django.contrib.formtools.wizard.views.WizardView.get_form_prefix" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns the prefix which will be used when calling the form for the given
step. <tt class="docutils literal"><span class="pre">step</span></tt> contains the step name, <tt class="docutils literal"><span class="pre">form</span></tt> the form class which will
be called with the returned prefix.</p>
<p>If no <tt class="docutils literal"><span class="pre">step</span></tt> is given, it will be determined automatically. By default,
this simply uses the step itself and the <tt class="docutils literal"><span class="pre">form</span></tt> parameter is not used.</p>
<p>For more, see the <a class="reference internal" href="../../forms/api.html#form-prefix"><em>form prefix documentation</em></a>.</p>
</dd></dl>
<dl class="method">
<dt id="django.contrib.formtools.wizard.views.WizardView.get_form_initial">
<tt class="descclassname">WizardView.</tt><tt class="descname">get_form_initial</tt>(<em>step</em>)<a class="headerlink" href="#django.contrib.formtools.wizard.views.WizardView.get_form_initial" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns a dictionary which will be passed as the
<a class="reference internal" href="../../forms/api.html#django.forms.Form.initial" title="django.forms.Form.initial"><tt class="xref py py-attr docutils literal"><span class="pre">initial</span></tt></a> argument when instantiating the Form
instance for step <tt class="docutils literal"><span class="pre">step</span></tt>. If no initial data was provided while
initializing the form wizard, an empty dictionary should be returned.</p>
<p>The default implementation:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">def</span> <span class="nf">get_form_initial</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">step</span><span class="p">):</span>
<span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">initial_dict</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="n">step</span><span class="p">,</span> <span class="p">{})</span>
</pre></div>
</div>
</dd></dl>
<dl class="method">
<dt id="django.contrib.formtools.wizard.views.WizardView.get_form_kwargs">
<tt class="descclassname">WizardView.</tt><tt class="descname">get_form_kwargs</tt>(<em>step</em>)<a class="headerlink" href="#django.contrib.formtools.wizard.views.WizardView.get_form_kwargs" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns a dictionary which will be used as the keyword arguments when
instantiating the form instance on given <tt class="docutils literal"><span class="pre">step</span></tt>.</p>
<p>The default implementation:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">def</span> <span class="nf">get_form_kwargs</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">step</span><span class="p">):</span>
<span class="k">return</span> <span class="p">{}</span>
</pre></div>
</div>
</dd></dl>
<dl class="method">
<dt id="django.contrib.formtools.wizard.views.WizardView.get_form_instance">
<tt class="descclassname">WizardView.</tt><tt class="descname">get_form_instance</tt>(<em>step</em>)<a class="headerlink" href="#django.contrib.formtools.wizard.views.WizardView.get_form_instance" title="Permalink to this definition">¶</a></dt>
<dd><p>This method will be called only if a <a class="reference internal" href="../../../topics/forms/modelforms.html#django.forms.ModelForm" title="django.forms.ModelForm"><tt class="xref py py-class docutils literal"><span class="pre">ModelForm</span></tt></a> is
used as the form for step <tt class="docutils literal"><span class="pre">step</span></tt>.</p>
<p>Returns an <a class="reference internal" href="../../models/instances.html#django.db.models.Model" title="django.db.models.Model"><tt class="xref py py-class docutils literal"><span class="pre">Model</span></tt></a> object which will be passed as
the <tt class="docutils literal"><span class="pre">instance</span></tt> argument when instantiating the <tt class="docutils literal"><span class="pre">ModelForm</span></tt> for step
<tt class="docutils literal"><span class="pre">step</span></tt>. If no instance object was provided while initializing the form
wizard, <tt class="docutils literal"><span class="pre">None</span></tt> will be returned.</p>
<p>The default implementation:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">def</span> <span class="nf">get_form_instance</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">step</span><span class="p">):</span>
<span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">instance_dict</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="n">step</span><span class="p">,</span> <span class="bp">None</span><span class="p">)</span>
</pre></div>
</div>
</dd></dl>
<dl class="method">
<dt id="django.contrib.formtools.wizard.views.WizardView.get_context_data">
<tt class="descclassname">WizardView.</tt><tt class="descname">get_context_data</tt>(<em>form</em>, <em>**kwargs</em>)<a class="headerlink" href="#django.contrib.formtools.wizard.views.WizardView.get_context_data" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns the template context for a step. You can overwrite this method
to add more data for all or some steps. This method returns a dictionary
containing the rendered form step.</p>
<p>The default template context variables are:</p>
<ul class="simple">
<li>Any extra data the storage backend has stored</li>
<li><tt class="docutils literal"><span class="pre">wizard</span></tt> – a dictionary representation of the wizard instance with the
following key/values:<ul>
<li><tt class="docutils literal"><span class="pre">form</span></tt> – <a class="reference internal" href="../../forms/api.html#django.forms.Form" title="django.forms.Form"><tt class="xref py py-class docutils literal"><span class="pre">Form</span></tt></a> or
<a class="reference internal" href="../../../topics/forms/formsets.html#django.forms.formsets.BaseFormSet" title="django.forms.formsets.BaseFormSet"><tt class="xref py py-class docutils literal"><span class="pre">BaseFormSet</span></tt></a> instance for the current step</li>
<li><tt class="docutils literal"><span class="pre">steps</span></tt> – A helper object to access the various steps related data</li>
<li><tt class="docutils literal"><span class="pre">management_form</span></tt> – all the management data for the current step</li>
</ul>
</li>
</ul>
<p>Example to add extra variables for a specific step:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">def</span> <span class="nf">get_context_data</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">form</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">):</span>
<span class="n">context</span> <span class="o">=</span> <span class="nb">super</span><span class="p">(</span><span class="n">MyWizard</span><span class="p">,</span> <span class="bp">self</span><span class="p">)</span><span class="o">.</span><span class="n">get_context_data</span><span class="p">(</span><span class="n">form</span><span class="o">=</span><span class="n">form</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">)</span>
<span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">steps</span><span class="o">.</span><span class="n">current</span> <span class="o">==</span> <span class="s">'my_step_name'</span><span class="p">:</span>
<span class="n">context</span><span class="o">.</span><span class="n">update</span><span class="p">({</span><span class="s">'another_var'</span><span class="p">:</span> <span class="bp">True</span><span class="p">})</span>
<span class="k">return</span> <span class="n">context</span>
</pre></div>
</div>
</dd></dl>
<dl class="method">
<dt id="django.contrib.formtools.wizard.views.WizardView.get_prefix">
<tt class="descclassname">WizardView.</tt><tt class="descname">get_prefix</tt>(<em>*args</em>, <em>**kwargs</em>)<a class="headerlink" href="#django.contrib.formtools.wizard.views.WizardView.get_prefix" title="Permalink to this definition">¶</a></dt>
<dd><p>This method returns a prefix for use by the storage backends. Backends use
the prefix as a mechanism to allow data to be stored separately for each
wizard. This allows wizards to store their data in a single backend
without overwriting each other.</p>
<p>You can change this method to make the wizard data prefix more unique to,
e.g. have multiple instances of one wizard in one session.</p>
<p>Default implementation:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">def</span> <span class="nf">get_prefix</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">):</span>
<span class="c"># use the lowercase underscore version of the class name</span>
<span class="k">return</span> <span class="n">normalize_name</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">__class__</span><span class="o">.</span><span class="n">__name__</span><span class="p">)</span>
</pre></div>
</div>
</dd></dl>
<dl class="method">
<dt id="django.contrib.formtools.wizard.views.WizardView.get_form">
<tt class="descclassname">WizardView.</tt><tt class="descname">get_form</tt>(<em>step=None</em>, <em>data=None</em>, <em>files=None</em>)<a class="headerlink" href="#django.contrib.formtools.wizard.views.WizardView.get_form" title="Permalink to this definition">¶</a></dt>
<dd><p>This method constructs the form for a given <tt class="docutils literal"><span class="pre">step</span></tt>. If no <tt class="docutils literal"><span class="pre">step</span></tt> is
defined, the current step will be determined automatically. If you override
<tt class="docutils literal"><span class="pre">get_form</span></tt>, however, you will need to set <tt class="docutils literal"><span class="pre">step</span></tt> yourself using
<tt class="docutils literal"><span class="pre">self.steps.current</span></tt> as in the example below. The method gets three
arguments:</p>
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">step</span></tt> – The step for which the form instance should be generated.</li>
<li><tt class="docutils literal"><span class="pre">data</span></tt> – Gets passed to the form’s data argument</li>
<li><tt class="docutils literal"><span class="pre">files</span></tt> – Gets passed to the form’s files argument</li>
</ul>
<p>You can override this method to add extra arguments to the form instance.</p>
<p>Example code to add a user attribute to the form on step 2:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">def</span> <span class="nf">get_form</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">step</span><span class="o">=</span><span class="bp">None</span><span class="p">,</span> <span class="n">data</span><span class="o">=</span><span class="bp">None</span><span class="p">,</span> <span class="n">files</span><span class="o">=</span><span class="bp">None</span><span class="p">):</span>
<span class="n">form</span> <span class="o">=</span> <span class="nb">super</span><span class="p">(</span><span class="n">MyWizard</span><span class="p">,</span> <span class="bp">self</span><span class="p">)</span><span class="o">.</span><span class="n">get_form</span><span class="p">(</span><span class="n">step</span><span class="p">,</span> <span class="n">data</span><span class="p">,</span> <span class="n">files</span><span class="p">)</span>
<span class="c"># determine the step if not given</span>
<span class="k">if</span> <span class="n">step</span> <span class="ow">is</span> <span class="bp">None</span><span class="p">:</span>
<span class="n">step</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">steps</span><span class="o">.</span><span class="n">current</span>
<span class="k">if</span> <span class="n">step</span> <span class="o">==</span> <span class="s">'1'</span><span class="p">:</span>
<span class="n">form</span><span class="o">.</span><span class="n">user</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">request</span><span class="o">.</span><span class="n">user</span>
<span class="k">return</span> <span class="n">form</span>
</pre></div>
</div>
</dd></dl>
<dl class="method">
<dt id="django.contrib.formtools.wizard.views.WizardView.process_step">
<tt class="descclassname">WizardView.</tt><tt class="descname">process_step</tt>(<em>form</em>)<a class="headerlink" href="#django.contrib.formtools.wizard.views.WizardView.process_step" title="Permalink to this definition">¶</a></dt>
<dd><p>Hook for modifying the wizard’s internal state, given a fully validated
<a class="reference internal" href="../../forms/api.html#django.forms.Form" title="django.forms.Form"><tt class="xref py py-class docutils literal"><span class="pre">Form</span></tt></a> object. The Form is guaranteed to have clean,
valid data.</p>
<p>This method gives you a way to post-process the form data before the data
gets stored within the storage backend. By default it just returns the
<tt class="docutils literal"><span class="pre">form.data</span></tt> dictionary. You should not manipulate the data here but you
can use it to do some extra work if needed (e.g. set storage extra data).</p>
<p>Note that this method is called every time a page is rendered for <em>all</em>
submitted steps.</p>
<p>The default implementation:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">def</span> <span class="nf">process_step</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">form</span><span class="p">):</span>
<span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">get_form_step_data</span><span class="p">(</span><span class="n">form</span><span class="p">)</span>
</pre></div>
</div>
</dd></dl>
<dl class="method">
<dt id="django.contrib.formtools.wizard.views.WizardView.process_step_files">
<tt class="descclassname">WizardView.</tt><tt class="descname">process_step_files</tt>(<em>form</em>)<a class="headerlink" href="#django.contrib.formtools.wizard.views.WizardView.process_step_files" title="Permalink to this definition">¶</a></dt>
<dd><p>This method gives you a way to post-process the form files before the
files gets stored within the storage backend. By default it just returns
the <tt class="docutils literal"><span class="pre">form.files</span></tt> dictionary. You should not manipulate the data here
but you can use it to do some extra work if needed (e.g. set storage
extra data).</p>
<p>Default implementation:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">def</span> <span class="nf">process_step_files</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">form</span><span class="p">):</span>
<span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">get_form_step_files</span><span class="p">(</span><span class="n">form</span><span class="p">)</span>
</pre></div>
</div>
</dd></dl>
<dl class="method">
<dt id="django.contrib.formtools.wizard.views.WizardView.render_goto_step">
<tt class="descclassname">WizardView.</tt><tt class="descname">render_goto_step</tt>(<em>step</em>, <em>goto_step</em>, <em>**kwargs</em>)<a class="headerlink" href="#django.contrib.formtools.wizard.views.WizardView.render_goto_step" title="Permalink to this definition">¶</a></dt>
<dd><div class="versionadded">
<span class="title">New in Django 1.6.</span> </div>
<p>This method is called when the step should be changed to something else
than the next step. By default, this method just stores the requested
step <tt class="docutils literal"><span class="pre">goto_step</span></tt> in the storage and then renders the new step.</p>
<p>If you want to store the entered data of the current step before rendering
the next step, you can overwrite this method.</p>
</dd></dl>
<dl class="method">
<dt id="django.contrib.formtools.wizard.views.WizardView.render_revalidation_failure">
<tt class="descclassname">WizardView.</tt><tt class="descname">render_revalidation_failure</tt>(<em>step</em>, <em>form</em>, <em>**kwargs</em>)<a class="headerlink" href="#django.contrib.formtools.wizard.views.WizardView.render_revalidation_failure" title="Permalink to this definition">¶</a></dt>
<dd><p>When the wizard thinks all steps have passed it revalidates all forms with
the data from the backend storage.</p>
<p>If any of the forms don’t validate correctly, this method gets called.
This method expects two arguments, <tt class="docutils literal"><span class="pre">step</span></tt> and <tt class="docutils literal"><span class="pre">form</span></tt>.</p>
<p>The default implementation resets the current step to the first failing
form and redirects the user to the invalid form.</p>
<p>Default implementation:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">def</span> <span class="nf">render_revalidation_failure</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">step</span><span class="p">,</span> <span class="n">form</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">):</span>
<span class="bp">self</span><span class="o">.</span><span class="n">storage</span><span class="o">.</span><span class="n">current_step</span> <span class="o">=</span> <span class="n">step</span>
<span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">render</span><span class="p">(</span><span class="n">form</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">)</span>
</pre></div>
</div>
</dd></dl>
<dl class="method">
<dt id="django.contrib.formtools.wizard.views.WizardView.get_form_step_data">
<tt class="descclassname">WizardView.</tt><tt class="descname">get_form_step_data</tt>(<em>form</em>)<a class="headerlink" href="#django.contrib.formtools.wizard.views.WizardView.get_form_step_data" title="Permalink to this definition">¶</a></dt>
<dd><p>This method fetches the data from the <tt class="docutils literal"><span class="pre">form</span></tt> Form instance and returns the
dictionary. You can use this method to manipulate the values before the data
gets stored in the storage backend.</p>
<p>Default implementation:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">def</span> <span class="nf">get_form_step_data</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">form</span><span class="p">):</span>
<span class="k">return</span> <span class="n">form</span><span class="o">.</span><span class="n">data</span>
</pre></div>
</div>
</dd></dl>
<dl class="method">
<dt id="django.contrib.formtools.wizard.views.WizardView.get_form_step_files">
<tt class="descclassname">WizardView.</tt><tt class="descname">get_form_step_files</tt>(<em>form</em>)<a class="headerlink" href="#django.contrib.formtools.wizard.views.WizardView.get_form_step_files" title="Permalink to this definition">¶</a></dt>
<dd><p>This method returns the form files. You can use this method to manipulate
the files before the data gets stored in the storage backend.</p>
<p>Default implementation:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">def</span> <span class="nf">get_form_step_files</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">form</span><span class="p">):</span>
<span class="k">return</span> <span class="n">form</span><span class="o">.</span><span class="n">files</span>
</pre></div>
</div>
</dd></dl>
<dl class="method">
<dt id="django.contrib.formtools.wizard.views.WizardView.render">
<tt class="descclassname">WizardView.</tt><tt class="descname">render</tt>(<em>form</em>, <em>**kwargs</em>)<a class="headerlink" href="#django.contrib.formtools.wizard.views.WizardView.render" title="Permalink to this definition">¶</a></dt>
<dd><p>This method gets called after the GET or POST request has been handled. You
can hook in this method to, e.g. change the type of HTTP response.</p>
<p>Default implementation:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">def</span> <span class="nf">render</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">form</span><span class="o">=</span><span class="bp">None</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">):</span>
<span class="n">form</span> <span class="o">=</span> <span class="n">form</span> <span class="ow">or</span> <span class="bp">self</span><span class="o">.</span><span class="n">get_form</span><span class="p">()</span>
<span class="n">context</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">get_context_data</span><span class="p">(</span><span class="n">form</span><span class="o">=</span><span class="n">form</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">)</span>
<span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">render_to_response</span><span class="p">(</span><span class="n">context</span><span class="p">)</span>
</pre></div>
</div>
</dd></dl>
<dl class="method">
<dt id="django.contrib.formtools.wizard.views.WizardView.get_cleaned_data_for_step">
<tt class="descclassname">WizardView.</tt><tt class="descname">get_cleaned_data_for_step</tt>(<em>step</em>)<a class="headerlink" href="#django.contrib.formtools.wizard.views.WizardView.get_cleaned_data_for_step" title="Permalink to this definition">¶</a></dt>
<dd><p>This method returns the cleaned data for a given <tt class="docutils literal"><span class="pre">step</span></tt>. Before returning
the cleaned data, the stored values are revalidated through the form. If
the data doesn’t validate, <tt class="docutils literal"><span class="pre">None</span></tt> will be returned.</p>
</dd></dl>
<dl class="method">
<dt id="django.contrib.formtools.wizard.views.WizardView.get_all_cleaned_data">
<tt class="descclassname">WizardView.</tt><tt class="descname">get_all_cleaned_data</tt>()<a class="headerlink" href="#django.contrib.formtools.wizard.views.WizardView.get_all_cleaned_data" title="Permalink to this definition">¶</a></dt>
<dd><p>This method returns a merged dictionary of all form steps’ <tt class="docutils literal"><span class="pre">cleaned_data</span></tt>
dictionaries. If a step contains a <tt class="docutils literal"><span class="pre">FormSet</span></tt>, the key will be prefixed
with <tt class="docutils literal"><span class="pre">formset-</span></tt> and contain a list of the formset’s <tt class="docutils literal"><span class="pre">cleaned_data</span></tt>
dictionaries. Note that if two or more steps have a field with the same
name, the value for that field from the latest step will overwrite the
value from any earlier steps.</p>
</dd></dl>
</div>
<div class="section" id="s-providing-initial-data-for-the-forms">
<span id="providing-initial-data-for-the-forms"></span><h2>Providing initial data for the forms<a class="headerlink" href="#providing-initial-data-for-the-forms" title="Permalink to this headline">¶</a></h2>
<dl class="attribute">
<dt id="django.contrib.formtools.wizard.views.WizardView.initial_dict">
<tt class="descclassname">WizardView.</tt><tt class="descname">initial_dict</tt><a class="headerlink" href="#django.contrib.formtools.wizard.views.WizardView.initial_dict" title="Permalink to this definition">¶</a></dt>
<dd><p>Initial data for a wizard’s <a class="reference internal" href="../../forms/api.html#django.forms.Form" title="django.forms.Form"><tt class="xref py py-class docutils literal"><span class="pre">Form</span></tt></a> objects can be
provided using the optional <a class="reference internal" href="#django.contrib.formtools.wizard.views.WizardView.initial_dict" title="django.contrib.formtools.wizard.views.WizardView.initial_dict"><tt class="xref py py-attr docutils literal"><span class="pre">initial_dict</span></tt></a> keyword
argument. This argument should be a dictionary mapping the steps to
dictionaries containing the initial data for each step. The dictionary of
initial data will be passed along to the constructor of the step’s
<a class="reference internal" href="../../forms/api.html#django.forms.Form" title="django.forms.Form"><tt class="xref py py-class docutils literal"><span class="pre">Form</span></tt></a>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">myapp.forms</span> <span class="kn">import</span> <span class="n">ContactForm1</span><span class="p">,</span> <span class="n">ContactForm2</span>
<span class="gp">>>> </span><span class="kn">from</span> <span class="nn">myapp.views</span> <span class="kn">import</span> <span class="n">ContactWizard</span>
<span class="gp">>>> </span><span class="n">initial</span> <span class="o">=</span> <span class="p">{</span>
<span class="gp">... </span> <span class="s">'0'</span><span class="p">:</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="s">'sender'</span><span class="p">:</span> <span class="s">'user@example.com'</span><span class="p">},</span>
<span class="gp">... </span> <span class="s">'1'</span><span class="p">:</span> <span class="p">{</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="p">}</span>
<span class="gp">>>> </span><span class="c"># This example is illustrative only and isn't meant to be run in</span>
<span class="gp">>>> </span><span class="c"># the shell since it requires an HttpRequest to pass to the view.</span>
<span class="gp">>>> </span><span class="n">wiz</span> <span class="o">=</span> <span class="n">ContactWizard</span><span class="o">.</span><span class="n">as_view</span><span class="p">([</span><span class="n">ContactForm1</span><span class="p">,</span> <span class="n">ContactForm2</span><span class="p">],</span> <span class="n">initial_dict</span><span class="o">=</span><span class="n">initial</span><span class="p">)(</span><span class="n">request</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">form1</span> <span class="o">=</span> <span class="n">wiz</span><span class="o">.</span><span class="n">get_form</span><span class="p">(</span><span class="s">'0'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">form2</span> <span class="o">=</span> <span class="n">wiz</span><span class="o">.</span><span class="n">get_form</span><span class="p">(</span><span class="s">'1'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">form1</span><span class="o">.</span><span class="n">initial</span>
<span class="go">{'sender': 'user@example.com', 'subject': 'Hello'}</span>
<span class="gp">>>> </span><span class="n">form2</span><span class="o">.</span><span class="n">initial</span>
<span class="go">{'message': 'Hi there!'}</span>
</pre></div>
</div>
<p>The <tt class="docutils literal"><span class="pre">initial_dict</span></tt> can also take a list of dictionaries for a specific
step if the step is a <tt class="docutils literal"><span class="pre">FormSet</span></tt>.</p>
<div class="versionchanged">
<span class="title">Changed in Django 1.6.</span> </div>
<p>The <tt class="docutils literal"><span class="pre">initial_dict</span></tt> can also be added as a class attribute named
<tt class="docutils literal"><span class="pre">initial_dict</span></tt> to avoid having the initial data in the <tt class="docutils literal"><span class="pre">urls.py</span></tt>.</p>
</dd></dl>
</div>
<div class="section" id="s-handling-files">
<span id="s-wizard-files"></span><span id="handling-files"></span><span id="wizard-files"></span><h2>Handling files<a class="headerlink" href="#handling-files" title="Permalink to this headline">¶</a></h2>
<dl class="attribute">
<dt id="django.contrib.formtools.wizard.views.WizardView.file_storage">
<tt class="descclassname">WizardView.</tt><tt class="descname">file_storage</tt><a class="headerlink" href="#django.contrib.formtools.wizard.views.WizardView.file_storage" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<p>To handle <a class="reference internal" href="../../forms/fields.html#django.forms.FileField" title="django.forms.FileField"><tt class="xref py py-class docutils literal"><span class="pre">FileField</span></tt></a> within any step form of the wizard,
you have to add a <tt class="docutils literal"><span class="pre">file_storage</span></tt> to your <a class="reference internal" href="#django.contrib.formtools.wizard.views.WizardView" title="django.contrib.formtools.wizard.views.WizardView"><tt class="xref py py-class docutils literal"><span class="pre">WizardView</span></tt></a> subclass.</p>
<p>This storage will temporarily store the uploaded files for the wizard. The
<tt class="docutils literal"><span class="pre">file_storage</span></tt> attribute should be a
<a class="reference internal" href="../../files/storage.html#django.core.files.storage.Storage" title="django.core.files.storage.Storage"><tt class="xref py py-class docutils literal"><span class="pre">Storage</span></tt></a> subclass.</p>
<p>Django provides a built-in storage class (see <a class="reference internal" href="../../../topics/files.html#builtin-fs-storage"><em>the built-in filesystem
storage class</em></a>):</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">django.conf</span> <span class="kn">import</span> <span class="n">settings</span>
<span class="kn">from</span> <span class="nn">django.core.files.storage</span> <span class="kn">import</span> <span class="n">FileSystemStorage</span>
<span class="k">class</span> <span class="nc">CustomWizardView</span><span class="p">(</span><span class="n">WizardView</span><span class="p">):</span>
<span class="o">...</span>
<span class="n">file_storage</span> <span class="o">=</span> <span class="n">FileSystemStorage</span><span class="p">(</span><span class="n">location</span><span class="o">=</span><span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">settings</span><span class="o">.</span><span class="n">MEDIA_ROOT</span><span class="p">,</span> <span class="s">'photos'</span><span class="p">))</span>
</pre></div>
</div>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">Please remember to take care of removing old files as the
<a class="reference internal" href="#django.contrib.formtools.wizard.views.WizardView" title="django.contrib.formtools.wizard.views.WizardView"><tt class="xref py py-class docutils literal"><span class="pre">WizardView</span></tt></a> won’t remove any files, whether the wizard gets
finished correctly or not.</p>
</div>
</div>
<div class="section" id="s-conditionally-view-skip-specific-steps">
<span id="conditionally-view-skip-specific-steps"></span><h2>Conditionally view/skip specific steps<a class="headerlink" href="#conditionally-view-skip-specific-steps" title="Permalink to this headline">¶</a></h2>
<dl class="attribute">
<dt id="django.contrib.formtools.wizard.views.WizardView.condition_dict">
<tt class="descclassname">WizardView.</tt><tt class="descname">condition_dict</tt><a class="headerlink" href="#django.contrib.formtools.wizard.views.WizardView.condition_dict" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<p>The <a class="reference internal" href="#django.contrib.formtools.wizard.views.WizardView.as_view" title="django.contrib.formtools.wizard.views.WizardView.as_view"><tt class="xref py py-meth docutils literal"><span class="pre">as_view()</span></tt></a> method accepts a <tt class="docutils literal"><span class="pre">condition_dict</span></tt> argument.
You can pass a dictionary of boolean values or callables. The key should match
the steps names (e.g. ‘0’, ‘1’).</p>
<p>If the value of a specific step is callable it will be called with the
<a class="reference internal" href="#django.contrib.formtools.wizard.views.WizardView" title="django.contrib.formtools.wizard.views.WizardView"><tt class="xref py py-class docutils literal"><span class="pre">WizardView</span></tt></a> instance as the only argument. If the return value is true,
the step’s form will be used.</p>
<p>This example provides a contact form including a condition. The condition is
used to show a message form only if a checkbox in the first step was checked.</p>
<p>The steps are defined in a <tt class="docutils literal"><span class="pre">forms.py</span></tt> file:</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">ContactForm1</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">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">leave_message</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>
<span class="k">class</span> <span class="nc">ContactForm2</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">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">widget</span><span class="o">=</span><span class="n">forms</span><span class="o">.</span><span class="n">Textarea</span><span class="p">)</span>
</pre></div>
</div>
<p>We define our wizard in a <tt class="docutils literal"><span class="pre">views.py</span></tt>:</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_to_response</span>
<span class="kn">from</span> <span class="nn">django.contrib.formtools.wizard.views</span> <span class="kn">import</span> <span class="n">SessionWizardView</span>
<span class="k">def</span> <span class="nf">show_message_form_condition</span><span class="p">(</span><span class="n">wizard</span><span class="p">):</span>
<span class="c"># try to get the cleaned data of step 1</span>
<span class="n">cleaned_data</span> <span class="o">=</span> <span class="n">wizard</span><span class="o">.</span><span class="n">get_cleaned_data_for_step</span><span class="p">(</span><span class="s">'0'</span><span class="p">)</span> <span class="ow">or</span> <span class="p">{}</span>
<span class="c"># check if the field ``leave_message`` was checked.</span>
<span class="k">return</span> <span class="n">cleaned_data</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s">'leave_message'</span><span class="p">,</span> <span class="bp">True</span><span class="p">)</span>
<span class="k">class</span> <span class="nc">ContactWizard</span><span class="p">(</span><span class="n">SessionWizardView</span><span class="p">):</span>
<span class="k">def</span> <span class="nf">done</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">form_list</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">):</span>
<span class="k">return</span> <span class="n">render_to_response</span><span class="p">(</span><span class="s">'done.html'</span><span class="p">,</span> <span class="p">{</span>
<span class="s">'form_data'</span><span class="p">:</span> <span class="p">[</span><span class="n">form</span><span class="o">.</span><span class="n">cleaned_data</span> <span class="k">for</span> <span class="n">form</span> <span class="ow">in</span> <span class="n">form_list</span><span class="p">],</span>
<span class="p">})</span>
</pre></div>
</div>
<p>We need to add the <tt class="docutils literal"><span class="pre">ContactWizard</span></tt> to our <tt class="docutils literal"><span class="pre">urls.py</span></tt> file:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">django.conf.urls</span> <span class="kn">import</span> <span class="n">patterns</span>
<span class="kn">from</span> <span class="nn">myapp.forms</span> <span class="kn">import</span> <span class="n">ContactForm1</span><span class="p">,</span> <span class="n">ContactForm2</span>
<span class="kn">from</span> <span class="nn">myapp.views</span> <span class="kn">import</span> <span class="n">ContactWizard</span><span class="p">,</span> <span class="n">show_message_form_condition</span>
<span class="n">contact_forms</span> <span class="o">=</span> <span class="p">[</span><span class="n">ContactForm1</span><span class="p">,</span> <span class="n">ContactForm2</span><span class="p">]</span>
<span class="n">urlpatterns</span> <span class="o">=</span> <span class="n">patterns</span><span class="p">(</span><span class="s">''</span><span class="p">,</span>
<span class="p">(</span><span class="s">r'^contact/$'</span><span class="p">,</span> <span class="n">ContactWizard</span><span class="o">.</span><span class="n">as_view</span><span class="p">(</span><span class="n">contact_forms</span><span class="p">,</span>
<span class="n">condition_dict</span><span class="o">=</span><span class="p">{</span><span class="s">'1'</span><span class="p">:</span> <span class="n">show_message_form_condition</span><span class="p">}</span>
<span class="p">)),</span>
<span class="p">)</span>
</pre></div>
</div>
<p>As you can see, we defined a <tt class="docutils literal"><span class="pre">show_message_form_condition</span></tt> next to our
<a class="reference internal" href="#django.contrib.formtools.wizard.views.WizardView" title="django.contrib.formtools.wizard.views.WizardView"><tt class="xref py py-class docutils literal"><span class="pre">WizardView</span></tt></a> subclass and added a <tt class="docutils literal"><span class="pre">condition_dict</span></tt> argument to the
<a class="reference internal" href="#django.contrib.formtools.wizard.views.WizardView.as_view" title="django.contrib.formtools.wizard.views.WizardView.as_view"><tt class="xref py py-meth docutils literal"><span class="pre">as_view()</span></tt></a> method. The key refers to the second wizard step
(because of the zero based step index).</p>
</div>
<div class="section" id="s-how-to-work-with-modelform-and-modelformset">
<span id="how-to-work-with-modelform-and-modelformset"></span><h2>How to work with ModelForm and ModelFormSet<a class="headerlink" href="#how-to-work-with-modelform-and-modelformset" title="Permalink to this headline">¶</a></h2>
<dl class="attribute">
<dt id="django.contrib.formtools.wizard.views.WizardView.instance_dict">
<tt class="descclassname">WizardView.</tt><tt class="descname">instance_dict</tt><a class="headerlink" href="#django.contrib.formtools.wizard.views.WizardView.instance_dict" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<p>WizardView supports <a class="reference internal" href="../../../topics/forms/modelforms.html"><em>ModelForms</em></a> and
<a class="reference internal" href="../../../topics/forms/modelforms.html#model-formsets"><em>ModelFormSets</em></a>. Additionally to
<a class="reference internal" href="#django.contrib.formtools.wizard.views.WizardView.initial_dict" title="django.contrib.formtools.wizard.views.WizardView.initial_dict"><tt class="xref py py-attr docutils literal"><span class="pre">initial_dict</span></tt></a>, the <a class="reference internal" href="#django.contrib.formtools.wizard.views.WizardView.as_view" title="django.contrib.formtools.wizard.views.WizardView.as_view"><tt class="xref py py-meth docutils literal"><span class="pre">as_view()</span></tt></a> method takes
an <tt class="docutils literal"><span class="pre">instance_dict</span></tt> argument that should contain model instances for steps
based on <tt class="docutils literal"><span class="pre">ModelForm</span></tt> and querysets for steps based on <tt class="docutils literal"><span class="pre">ModelFormSet</span></tt>.</p>
</div>
<div class="section" id="s-usage-of-namedurlwizardview">
<span id="usage-of-namedurlwizardview"></span><h2>Usage of <tt class="docutils literal"><span class="pre">NamedUrlWizardView</span></tt><a class="headerlink" href="#usage-of-namedurlwizardview" title="Permalink to this headline">¶</a></h2>
<dl class="class">
<dt id="django.contrib.formtools.wizard.views.NamedUrlWizardView">
<em class="property">class </em><tt class="descname">NamedUrlWizardView</tt><a class="headerlink" href="#django.contrib.formtools.wizard.views.NamedUrlWizardView" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<dl class="class">
<dt id="django.contrib.formtools.wizard.views.NamedUrlSessionWizardView">
<em class="property">class </em><tt class="descname">NamedUrlSessionWizardView</tt><a class="headerlink" href="#django.contrib.formtools.wizard.views.NamedUrlSessionWizardView" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<dl class="class">
<dt id="django.contrib.formtools.wizard.views.NamedUrlCookieWizardView">
<em class="property">class </em><tt class="descname">NamedUrlCookieWizardView</tt><a class="headerlink" href="#django.contrib.formtools.wizard.views.NamedUrlCookieWizardView" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<p><tt class="docutils literal"><span class="pre">NamedUrlWizardView</span></tt> is a <a class="reference internal" href="#django.contrib.formtools.wizard.views.WizardView" title="django.contrib.formtools.wizard.views.WizardView"><tt class="xref py py-class docutils literal"><span class="pre">WizardView</span></tt></a> subclass which adds named-urls
support to the wizard. This allows you to have separate URLs for every step.
You can also use the <a class="reference internal" href="#django.contrib.formtools.wizard.views.NamedUrlSessionWizardView" title="django.contrib.formtools.wizard.views.NamedUrlSessionWizardView"><tt class="xref py py-class docutils literal"><span class="pre">NamedUrlSessionWizardView</span></tt></a> or <a class="reference internal" href="#django.contrib.formtools.wizard.views.NamedUrlCookieWizardView" title="django.contrib.formtools.wizard.views.NamedUrlCookieWizardView"><tt class="xref py py-class docutils literal"><span class="pre">NamedUrlCookieWizardView</span></tt></a>
classes which preselect the backend used for storing information (Django sessions and
browser cookies respectively).</p>
<p>To use the named URLs, you should not only use the <a class="reference internal" href="#django.contrib.formtools.wizard.views.NamedUrlWizardView" title="django.contrib.formtools.wizard.views.NamedUrlWizardView"><tt class="xref py py-class docutils literal"><span class="pre">NamedUrlWizardView</span></tt></a> instead of
<a class="reference internal" href="#django.contrib.formtools.wizard.views.WizardView" title="django.contrib.formtools.wizard.views.WizardView"><tt class="xref py py-class docutils literal"><span class="pre">WizardView</span></tt></a>, but you will also have to change your <tt class="docutils literal"><span class="pre">urls.py</span></tt>.</p>
<p>The <a class="reference internal" href="#django.contrib.formtools.wizard.views.WizardView.as_view" title="django.contrib.formtools.wizard.views.WizardView.as_view"><tt class="xref py py-meth docutils literal"><span class="pre">as_view()</span></tt></a> method takes two additional arguments:</p>
<ul class="simple">
<li>a required <tt class="docutils literal"><span class="pre">url_name</span></tt> – the name of the url (as provided in the <tt class="docutils literal"><span class="pre">urls.py</span></tt>)</li>
<li>an optional <tt class="docutils literal"><span class="pre">done_step_name</span></tt> – the name of the done step, to be used in the URL</li>
</ul>
<p>This is an example of a <tt class="docutils literal"><span class="pre">urls.py</span></tt> for a contact wizard with two steps, step 1 named
<tt class="docutils literal"><span class="pre">contactdata</span></tt> and step 2 named <tt class="docutils literal"><span class="pre">leavemessage</span></tt>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">django.conf.urls</span> <span class="kn">import</span> <span class="n">url</span><span class="p">,</span> <span class="n">patterns</span>
<span class="kn">from</span> <span class="nn">myapp.forms</span> <span class="kn">import</span> <span class="n">ContactForm1</span><span class="p">,</span> <span class="n">ContactForm2</span>
<span class="kn">from</span> <span class="nn">myapp.views</span> <span class="kn">import</span> <span class="n">ContactWizard</span>
<span class="n">named_contact_forms</span> <span class="o">=</span> <span class="p">(</span>
<span class="p">(</span><span class="s">'contactdata'</span><span class="p">,</span> <span class="n">ContactForm1</span><span class="p">),</span>
<span class="p">(</span><span class="s">'leavemessage'</span><span class="p">,</span> <span class="n">ContactForm2</span><span class="p">),</span>
<span class="p">)</span>
<span class="n">contact_wizard</span> <span class="o">=</span> <span class="n">ContactWizard</span><span class="o">.</span><span class="n">as_view</span><span class="p">(</span><span class="n">named_contact_forms</span><span class="p">,</span>
<span class="n">url_name</span><span class="o">=</span><span class="s">'contact_step'</span><span class="p">,</span> <span class="n">done_step_name</span><span class="o">=</span><span class="s">'finished'</span><span class="p">)</span>
<span class="n">urlpatterns</span> <span class="o">=</span> <span class="n">patterns</span><span class="p">(</span><span class="s">''</span><span class="p">,</span>
<span class="n">url</span><span class="p">(</span><span class="s">r'^contact/(?P<step>.+)/$'</span><span class="p">,</span> <span class="n">contact_wizard</span><span class="p">,</span> <span class="n">name</span><span class="o">=</span><span class="s">'contact_step'</span><span class="p">),</span>
<span class="n">url</span><span class="p">(</span><span class="s">r'^contact/$'</span><span class="p">,</span> <span class="n">contact_wizard</span><span class="p">,</span> <span class="n">name</span><span class="o">=</span><span class="s">'contact'</span><span class="p">),</span>
<span class="p">)</span>
</pre></div>
</div>
</div>
<div class="section" id="s-advanced-namedurlwizardview-methods">
<span id="advanced-namedurlwizardview-methods"></span><h2>Advanced <tt class="docutils literal"><span class="pre">NamedUrlWizardView</span></tt> methods<a class="headerlink" href="#advanced-namedurlwizardview-methods" title="Permalink to this headline">¶</a></h2>
<dl class="method">
<dt id="django.contrib.formtools.wizard.views.NamedUrlWizardView.get_step_url">
<tt class="descclassname">NamedUrlWizardView.</tt><tt class="descname">get_step_url</tt>(<em>step</em>)<a class="headerlink" href="#django.contrib.formtools.wizard.views.NamedUrlWizardView.get_step_url" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<p>This method returns the URL for a specific step.</p>
<p>Default implementation:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">def</span> <span class="nf">get_step_url</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">step</span><span class="p">):</span>
<span class="k">return</span> <span class="n">reverse</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">url_name</span><span class="p">,</span> <span class="n">kwargs</span><span class="o">=</span><span class="p">{</span><span class="s">'step'</span><span class="p">:</span> <span class="n">step</span><span class="p">})</span>
</pre></div>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="yui-b" id="sidebar">
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<h3><a href="../../../contents.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Form wizard</a><ul>
<li><a class="reference internal" href="#how-it-works">How it works</a></li>
<li><a class="reference internal" href="#usage">Usage</a><ul>
<li><a class="reference internal" href="#defining-form-classes">Defining <tt class="docutils literal"><span class="pre">Form</span></tt> classes</a></li>
<li><a class="reference internal" href="#creating-a-wizardview-subclass">Creating a <tt class="docutils literal"><span class="pre">WizardView</span></tt> subclass</a></li>
<li><a class="reference internal" href="#creating-templates-for-the-forms">Creating templates for the forms</a></li>
<li><a class="reference internal" href="#hooking-the-wizard-into-a-urlconf">Hooking the wizard into a URLconf</a></li>
<li><a class="reference internal" href="#using-a-different-template-for-each-form">Using a different template for each form</a></li>
</ul>
</li>
<li><a class="reference internal" href="#advanced-wizardview-methods">Advanced <tt class="docutils literal"><span class="pre">WizardView</span></tt> methods</a></li>
<li><a class="reference internal" href="#providing-initial-data-for-the-forms">Providing initial data for the forms</a></li>
<li><a class="reference internal" href="#handling-files">Handling files</a></li>
<li><a class="reference internal" href="#conditionally-view-skip-specific-steps">Conditionally view/skip specific steps</a></li>
<li><a class="reference internal" href="#how-to-work-with-modelform-and-modelformset">How to work with ModelForm and ModelFormSet</a></li>
<li><a class="reference internal" href="#usage-of-namedurlwizardview">Usage of <tt class="docutils literal"><span class="pre">NamedUrlWizardView</span></tt></a></li>
<li><a class="reference internal" href="#advanced-namedurlwizardview-methods">Advanced <tt class="docutils literal"><span class="pre">NamedUrlWizardView</span></tt> methods</a></li>
</ul>
</li>
</ul>
<h3>Browse</h3>
<ul>
<li>Prev: <a href="form-preview.html">Form preview</a></li>
<li>Next: <a href="../gis/index.html">GeoDjango</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">API Reference</a>
<ul><li><a href="../index.html"><tt class="docutils literal"><span class="pre">contrib</span></tt> packages</a>
<ul><li><a href="index.html">django.contrib.formtools</a>
<ul><li>Form wizard</li></ul>
</li></ul></li></ul></li></ul>
</li>
</ul>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../../../_sources/ref/contrib/formtools/form-wizard.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="form-preview.html" title="Form preview">previous</a>
|
<a href="../../index.html" title="API Reference" accesskey="U">up</a>
|
<a href="../gis/index.html" title="GeoDjango">next</a> »</div>
</div>
</div>
<div class="clearer"></div>
</div>
</body>
</html>
