Django comes with an optional “form wizard” application that splits forms across multiple Web pages. It maintains state in hashed HTML <input type="hidden"> fields, and the data isn’t processed server-side until the final form is submitted.
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.
The term “wizard,” in this context, is explained on Wikipedia.
Here’s the basic workflow for how a user would use a wizard:
This application handles as much machinery for you as possible. Generally, you just have to do these things:
The first step in creating a form wizard is to create the Form classes. These should be standard django.forms.Form classes, covered in the forms documentation. These classes can live anywhere in your codebase, but convention is to put them in a file called forms.py in your application.
For example, let’s write a “contact form” wizard, where the first page’s form collects the sender’s e-mail address and subject, and the second page collects the message itself. Here’s what the forms.py might look like:
from django import forms
class ContactForm1(forms.Form):
subject = forms.CharField(max_length=100)
sender = forms.EmailField()
class ContactForm2(forms.Form):
message = forms.CharField(widget=forms.Textarea)
Important limitation: Because the wizard uses HTML hidden fields to store data between pages, you may not include a FileField in any form except the last one.
The next step is to create a django.contrib.formtools.wizard.FormWizard subclass. As with your Form classes, this FormWizard class can live anywhere in your codebase, but convention is to put it in forms.py.
The only requirement on this subclass is that it implement a done() method.
This method specifies what should happen when the data for every form is submitted and validated. This method is passed two arguments:
In this simplistic example, rather than perform any database operation, the method simply renders a template of the validated data:
from django.shortcuts import render_to_response
from django.contrib.formtools.wizard import FormWizard
class ContactWizard(FormWizard):
def done(self, request, form_list):
return render_to_response('done.html', {
'form_data': [form.cleaned_data for form in form_list],
})
Note that this method will be called via POST, so it really ought to be a good Web citizen and redirect after processing the data. Here's another example:
from django.http import HttpResponseRedirect
from django.contrib.formtools.wizard import FormWizard
class ContactWizard(FormWizard):
def done(self, request, form_list):
do_something_with_the_form_data(form_list)
return HttpResponseRedirect('/page-to-redirect-to-when-done/')
See the section Advanced FormWizard methods below to learn about more FormWizard hooks.
Next, you'll need to create a template that renders the wizard's forms. By default, every form uses a template called forms/wizard.html. (You can change this template name by overriding get_template(), which is documented below. This hook also allows you to use a different template for each form.)
This template expects the following context:
You can supply extra context to this template in two ways:
Here's a full example template:
{% extends "base.html" %}
{% block content %}
<p>Step {{ step }} of {{ step_count }}</p>
<form action="." method="post">{% csrf_token %}
<table>
{{ form }}
</table>
<input type="hidden" name="{{ step_field }}" value="{{ step0 }}" />
{{ previous_fields|safe }}
<input type="submit">
</form>
{% endblock %}
Note that previous_fields, step_field and step0 are all required for the wizard to work properly.
Finally, give your new FormWizard object a URL in urls.py. The wizard takes a list of your Form objects as arguments:
from django.conf.urls.defaults import *
from mysite.testapp.forms import ContactForm1, ContactForm2, ContactWizard
urlpatterns = patterns('',
(r'^contact/$', ContactWizard([ContactForm1, ContactForm2])),
)
Aside from the done() method, FormWizard offers a few advanced method hooks that let you customize how your wizard works.
Some of these methods take an argument step, which is a zero-based counter representing the current step of the wizard. (E.g., the first form is 0 and the second form is 1.)
Given the step, returns a form prefix to use. By default, this simply uses the step itself. For more, see the form prefix documentation.
Default implementation:
def prefix_for_step(self, step):
return str(step)
Renders a template if the hash check fails. It's rare that you'd need to override this.
Default implementation:
def render_hash_failure(self, request, step):
return self.render(self.get_form(step), request, step,
context={'wizard_error':
'We apologize, but your form has expired. Please'
' continue filling out the form from this page.'})
Calculates the security hash for the given request object and Form instance.
By default, this uses an MD5 hash of the form data and your SECRET_KEY setting. It's rare that somebody would need to override this.
Example:
def security_hash(self, request, form):
return my_hash_function(request, form)
A hook for saving state from the request object and args / kwargs that were captured from the URL by your URLconf.
By default, this does nothing.
Example:
def parse_params(self, request, *args, **kwargs):
self.my_state = args[0]
Returns the name of the template that should be used for the given step.
By default, this returns 'forms/wizard.html', regardless of step.
Example:
def get_template(self, step):
return 'myapp/wizard_%s.html' % step
If get_template() returns a list of strings, then the wizard will use the template system's select_template() function. This means the system will use the first template that exists on the filesystem. For example:
def get_template(self, step):
return ['myapp/wizard_%s.html' % step, 'myapp/wizard.html']
Renders the template for the given step, returning an HttpResponse object.
Override this method if you want to add a custom context, return a different MIME type, etc. If you only need to override the template name, use get_template() instead.
The template will be rendered with the context documented in the "Creating templates for the forms" section above.
Hook for modifying the wizard's internal state, given a fully validated Form object. The Form is guaranteed to have clean, valid data.
This method should not modify any of that data. Rather, it might want to set self.extra_context or dynamically alter self.form_list, based on previously submitted forms.
Note that this method is called every time a page is rendered for all submitted steps.
The function signature:
def process_step(self, request, form, step):
# ...
Jul 05, 2010