|
|
|
|
@ -1,762 +0,0 @@
|
|
|
|
|
===========
|
|
|
|
|
Form wizard
|
|
|
|
|
===========
|
|
|
|
|
|
|
|
|
|
.. module:: django.contrib.formtools.wizard.views
|
|
|
|
|
:synopsis: Splits forms across multiple Web pages.
|
|
|
|
|
|
|
|
|
|
Django comes with an optional "form wizard" application that splits
|
|
|
|
|
:doc:`forms </topics/forms/index>` 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.
|
|
|
|
|
|
|
|
|
|
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`_.
|
|
|
|
|
|
|
|
|
|
.. _explained on Wikipedia: http://en.wikipedia.org/wiki/Wizard_%28software%29
|
|
|
|
|
|
|
|
|
|
How it works
|
|
|
|
|
============
|
|
|
|
|
|
|
|
|
|
Here's the basic workflow for how a user would use a wizard:
|
|
|
|
|
|
|
|
|
|
1. The user visits the first page of the wizard, fills in the form and
|
|
|
|
|
submits it.
|
|
|
|
|
2. 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.
|
|
|
|
|
3. Step 1 and 2 repeat, for every subsequent form in the wizard.
|
|
|
|
|
4. 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.
|
|
|
|
|
|
|
|
|
|
Usage
|
|
|
|
|
=====
|
|
|
|
|
|
|
|
|
|
This application handles as much machinery for you as possible. Generally,
|
|
|
|
|
you just have to do these things:
|
|
|
|
|
|
|
|
|
|
1. Define a number of :class:`~django.forms.Form` classes -- one per
|
|
|
|
|
wizard page.
|
|
|
|
|
|
|
|
|
|
2. Create a :class:`WizardView` 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.
|
|
|
|
|
|
|
|
|
|
3. 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.
|
|
|
|
|
|
|
|
|
|
4. Add ``django.contrib.formtools`` to your
|
|
|
|
|
:setting:`INSTALLED_APPS` list in your settings file.
|
|
|
|
|
|
|
|
|
|
5. Point your URLconf at your :class:`WizardView` :meth:`~WizardView.as_view`
|
|
|
|
|
method.
|
|
|
|
|
|
|
|
|
|
Defining ``Form`` classes
|
|
|
|
|
-------------------------
|
|
|
|
|
|
|
|
|
|
The first step in creating a form wizard is to create the
|
|
|
|
|
:class:`~django.forms.Form` classes. These should be standard
|
|
|
|
|
:class:`django.forms.Form` classes, covered in the :doc:`forms documentation
|
|
|
|
|
</topics/forms/index>`. These classes can live anywhere in your codebase,
|
|
|
|
|
but convention is to put them in a file called :file:`forms.py` in your
|
|
|
|
|
application.
|
|
|
|
|
|
|
|
|
|
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 :file:`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)
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
.. note::
|
|
|
|
|
|
|
|
|
|
In order to use :class:`~django.forms.FileField` in any form, see the
|
|
|
|
|
section :ref:`Handling files <wizard-files>` below to learn more about
|
|
|
|
|
what to do.
|
|
|
|
|
|
|
|
|
|
Creating a ``WizardView`` subclass
|
|
|
|
|
----------------------------------
|
|
|
|
|
|
|
|
|
|
.. class:: SessionWizardView
|
|
|
|
|
.. class:: CookieWizardView
|
|
|
|
|
|
|
|
|
|
The next step is to create a
|
|
|
|
|
:class:`django.contrib.formtools.wizard.views.WizardView` subclass. You can
|
|
|
|
|
also use the :class:`SessionWizardView` or :class:`CookieWizardView` 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).
|
|
|
|
|
|
|
|
|
|
.. note::
|
|
|
|
|
|
|
|
|
|
To use the :class:`SessionWizardView` follow the instructions
|
|
|
|
|
in the :doc:`sessions documentation </topics/http/sessions>` on
|
|
|
|
|
how to enable sessions.
|
|
|
|
|
|
|
|
|
|
We will use the :class:`SessionWizardView` in all examples but is completely
|
|
|
|
|
fine to use the :class:`CookieWizardView` instead. As with your
|
|
|
|
|
:class:`~django.forms.Form` classes, this :class:`WizardView` class can live
|
|
|
|
|
anywhere in your codebase, but convention is to put it in :file:`views.py`.
|
|
|
|
|
|
|
|
|
|
The only requirement on this subclass is that it implement a
|
|
|
|
|
:meth:`~WizardView.done()` method.
|
|
|
|
|
|
|
|
|
|
.. method:: WizardView.done(form_list, form_dict, **kwargs)
|
|
|
|
|
|
|
|
|
|
This method specifies what should happen when the data for *every* form is
|
|
|
|
|
submitted and validated. This method is passed a list and dictionary of
|
|
|
|
|
validated :class:`~django.forms.Form` instances.
|
|
|
|
|
|
|
|
|
|
In this simplistic example, rather than performing 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.views import SessionWizardView
|
|
|
|
|
|
|
|
|
|
class ContactWizard(SessionWizardView):
|
|
|
|
|
def done(self, form_list, **kwargs):
|
|
|
|
|
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.views import SessionWizardView
|
|
|
|
|
|
|
|
|
|
class ContactWizard(SessionWizardView):
|
|
|
|
|
def done(self, form_list, **kwargs):
|
|
|
|
|
do_something_with_the_form_data(form_list)
|
|
|
|
|
return HttpResponseRedirect('/page-to-redirect-to-when-done/')
|
|
|
|
|
|
|
|
|
|
In addition to ``form_list``, the :meth:`~WizardView.done` method
|
|
|
|
|
is passed a ``form_dict``, which allows you to access the wizard's
|
|
|
|
|
forms based on their step names. This is especially useful when using
|
|
|
|
|
:class:`NamedUrlWizardView`, for example::
|
|
|
|
|
|
|
|
|
|
def done(self, form_list, form_dict, **kwargs):
|
|
|
|
|
user = form_dict['user'].save()
|
|
|
|
|
credit_card = form_dict['credit_card'].save()
|
|
|
|
|
# ...
|
|
|
|
|
|
|
|
|
|
.. versionchanged:: 1.7
|
|
|
|
|
|
|
|
|
|
Previously, the ``form_dict`` argument wasn't passed to the
|
|
|
|
|
``done`` method.
|
|
|
|
|
|
|
|
|
|
See the section :ref:`Advanced WizardView methods <wizardview-advanced-methods>`
|
|
|
|
|
below to learn about more :class:`WizardView` hooks.
|
|
|
|
|
|
|
|
|
|
Creating templates for the forms
|
|
|
|
|
--------------------------------
|
|
|
|
|
|
|
|
|
|
Next, you'll need to create a template that renders the wizard's forms. By
|
|
|
|
|
default, every form uses a template called
|
|
|
|
|
:file:`formtools/wizard/wizard_form.html`. You can change this template name
|
|
|
|
|
by overriding either the
|
|
|
|
|
:attr:`~django.views.generic.base.TemplateResponseMixin.template_name` attribute
|
|
|
|
|
or the
|
|
|
|
|
:meth:`~django.views.generic.base.TemplateResponseMixin.get_template_names()`
|
|
|
|
|
method, which are documented in the
|
|
|
|
|
:class:`~django.views.generic.base.TemplateResponseMixin` documentation. The
|
|
|
|
|
latter one allows you to use a different template for each form (:ref:`see the
|
|
|
|
|
example below <wizard-template-for-each-form>`).
|
|
|
|
|
|
|
|
|
|
This template expects a ``wizard`` object that has various items attached to
|
|
|
|
|
it:
|
|
|
|
|
|
|
|
|
|
* ``form`` -- The :class:`~django.forms.Form` or
|
|
|
|
|
:class:`~django.forms.formsets.BaseFormSet` instance for the current step
|
|
|
|
|
(either empty or with errors).
|
|
|
|
|
|
|
|
|
|
* ``steps`` -- A helper object to access the various steps related data:
|
|
|
|
|
|
|
|
|
|
* ``step0`` -- The current step (zero-based).
|
|
|
|
|
* ``step1`` -- The current step (one-based).
|
|
|
|
|
* ``count`` -- The total number of steps.
|
|
|
|
|
* ``first`` -- The first step.
|
|
|
|
|
* ``last`` -- The last step.
|
|
|
|
|
* ``current`` -- The current (or first) step.
|
|
|
|
|
* ``next`` -- The next step.
|
|
|
|
|
* ``prev`` -- The previous step.
|
|
|
|
|
* ``index`` -- The index of the current step.
|
|
|
|
|
* ``all`` -- A list of all steps of the wizard.
|
|
|
|
|
|
|
|
|
|
You can supply additional context variables by using the
|
|
|
|
|
:meth:`~WizardView.get_context_data` method of your :class:`WizardView`
|
|
|
|
|
subclass.
|
|
|
|
|
|
|
|
|
|
Here's a full example template:
|
|
|
|
|
|
|
|
|
|
.. code-block:: html+django
|
|
|
|
|
|
|
|
|
|
{% extends "base.html" %}
|
|
|
|
|
{% load i18n %}
|
|
|
|
|
|
|
|
|
|
{% block head %}
|
|
|
|
|
{{ wizard.form.media }}
|
|
|
|
|
{% endblock %}
|
|
|
|
|
|
|
|
|
|
{% block content %}
|
|
|
|
|
<p>Step {{ wizard.steps.step1 }} of {{ wizard.steps.count }}</p>
|
|
|
|
|
<form action="" method="post">{% csrf_token %}
|
|
|
|
|
<table>
|
|
|
|
|
{{ wizard.management_form }}
|
|
|
|
|
{% if wizard.form.forms %}
|
|
|
|
|
{{ wizard.form.management_form }}
|
|
|
|
|
{% for form in wizard.form.forms %}
|
|
|
|
|
{{ form }}
|
|
|
|
|
{% endfor %}
|
|
|
|
|
{% else %}
|
|
|
|
|
{{ wizard.form }}
|
|
|
|
|
{% endif %}
|
|
|
|
|
</table>
|
|
|
|
|
{% if wizard.steps.prev %}
|
|
|
|
|
<button name="wizard_goto_step" type="submit" value="{{ wizard.steps.first }}">{% trans "first step" %}</button>
|
|
|
|
|
<button name="wizard_goto_step" type="submit" value="{{ wizard.steps.prev }}">{% trans "prev step" %}</button>
|
|
|
|
|
{% endif %}
|
|
|
|
|
<input type="submit" value="{% trans "submit" %}"/>
|
|
|
|
|
</form>
|
|
|
|
|
{% endblock %}
|
|
|
|
|
|
|
|
|
|
.. note::
|
|
|
|
|
|
|
|
|
|
Note that ``{{ wizard.management_form }}`` **must be used** for
|
|
|
|
|
the wizard to work properly.
|
|
|
|
|
|
|
|
|
|
.. _wizard-urlconf:
|
|
|
|
|
|
|
|
|
|
Hooking the wizard into a URLconf
|
|
|
|
|
---------------------------------
|
|
|
|
|
|
|
|
|
|
.. method:: WizardView.as_view()
|
|
|
|
|
|
|
|
|
|
Finally, we need to specify which forms to use in the wizard, and then
|
|
|
|
|
deploy the new :class:`WizardView` object at a URL in the ``urls.py``. The
|
|
|
|
|
wizard's ``as_view()`` method takes a list of your
|
|
|
|
|
:class:`~django.forms.Form` classes as an argument during instantiation::
|
|
|
|
|
|
|
|
|
|
from django.conf.urls import url
|
|
|
|
|
|
|
|
|
|
from myapp.forms import ContactForm1, ContactForm2
|
|
|
|
|
from myapp.views import ContactWizard
|
|
|
|
|
|
|
|
|
|
urlpatterns = [
|
|
|
|
|
url(r'^contact/$', ContactWizard.as_view([ContactForm1, ContactForm2])),
|
|
|
|
|
]
|
|
|
|
|
|
|
|
|
|
You can also pass the form list as a class attribute named ``form_list``::
|
|
|
|
|
|
|
|
|
|
class ContactWizard(WizardView):
|
|
|
|
|
form_list = [ContactForm1, ContactForm2]
|
|
|
|
|
|
|
|
|
|
.. _wizard-template-for-each-form:
|
|
|
|
|
|
|
|
|
|
Using a different template for each form
|
|
|
|
|
----------------------------------------
|
|
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
Here's what the view code might look like::
|
|
|
|
|
|
|
|
|
|
from django.http import HttpResponseRedirect
|
|
|
|
|
from django.contrib.formtools.wizard.views import SessionWizardView
|
|
|
|
|
|
|
|
|
|
FORMS = [("address", myapp.forms.AddressForm),
|
|
|
|
|
("paytype", myapp.forms.PaymentChoiceForm),
|
|
|
|
|
("cc", myapp.forms.CreditCardForm),
|
|
|
|
|
("confirmation", myapp.forms.OrderForm)]
|
|
|
|
|
|
|
|
|
|
TEMPLATES = {"address": "checkout/billingaddress.html",
|
|
|
|
|
"paytype": "checkout/paymentmethod.html",
|
|
|
|
|
"cc": "checkout/creditcard.html",
|
|
|
|
|
"confirmation": "checkout/confirmation.html"}
|
|
|
|
|
|
|
|
|
|
def pay_by_credit_card(wizard):
|
|
|
|
|
"""Return true if user opts to pay by credit card"""
|
|
|
|
|
# Get cleaned data from payment step
|
|
|
|
|
cleaned_data = wizard.get_cleaned_data_for_step('paytype') or {'method': 'none'}
|
|
|
|
|
# Return true if the user selected credit card
|
|
|
|
|
return cleaned_data['method'] == 'cc'
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
class OrderWizard(SessionWizardView):
|
|
|
|
|
def get_template_names(self):
|
|
|
|
|
return [TEMPLATES[self.steps.current]]
|
|
|
|
|
|
|
|
|
|
def done(self, form_list, **kwargs):
|
|
|
|
|
do_something_with_the_form_data(form_list)
|
|
|
|
|
return HttpResponseRedirect('/page-to-redirect-to-when-done/')
|
|
|
|
|
...
|
|
|
|
|
|
|
|
|
|
The ``urls.py`` file would contain something like::
|
|
|
|
|
|
|
|
|
|
urlpatterns = [
|
|
|
|
|
url(r'^checkout/$', OrderWizard.as_view(FORMS, condition_dict={'cc': pay_by_credit_card})),
|
|
|
|
|
]
|
|
|
|
|
|
|
|
|
|
The ``condition_dict`` can be passed as attribute for the ``as_view()`
|
|
|
|
|
method or as a class attribute named ``condition_dict``::
|
|
|
|
|
|
|
|
|
|
class OrderWizard(WizardView):
|
|
|
|
|
condition_dict = {'cc': pay_by_credit_card}
|
|
|
|
|
|
|
|
|
|
Note that the ``OrderWizard`` 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.
|
|
|
|
|
|
|
|
|
|
In this example, the
|
|
|
|
|
:meth:`~django.views.generic.base.TemplateResponseMixin.get_template_names()`
|
|
|
|
|
method returns a list containing a single template, which is selected based on
|
|
|
|
|
the name of the current step.
|
|
|
|
|
|
|
|
|
|
.. _wizardview-advanced-methods:
|
|
|
|
|
|
|
|
|
|
Advanced ``WizardView`` methods
|
|
|
|
|
===============================
|
|
|
|
|
|
|
|
|
|
.. class:: WizardView
|
|
|
|
|
|
|
|
|
|
Aside from the :meth:`~done()` method, :class:`WizardView` 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 as string representing the current step of the wizard. (E.g., the
|
|
|
|
|
first form is ``'0'`` and the second form is ``'1'``)
|
|
|
|
|
|
|
|
|
|
.. method:: WizardView.get_form_prefix(step=None, form=None)
|
|
|
|
|
|
|
|
|
|
Returns the prefix which will be used when calling the form for the given
|
|
|
|
|
step. ``step`` contains the step name, ``form`` the form class which will
|
|
|
|
|
be called with the returned prefix.
|
|
|
|
|
|
|
|
|
|
If no ``step`` is given, it will be determined automatically. By default,
|
|
|
|
|
this simply uses the step itself and the ``form`` parameter is not used.
|
|
|
|
|
|
|
|
|
|
For more, see the :ref:`form prefix documentation <form-prefix>`.
|
|
|
|
|
|
|
|
|
|
.. method:: WizardView.get_form_initial(step)
|
|
|
|
|
|
|
|
|
|
Returns a dictionary which will be passed as the
|
|
|
|
|
:attr:`~django.forms.Form.initial` argument when instantiating the Form
|
|
|
|
|
instance for step ``step``. If no initial data was provided while
|
|
|
|
|
initializing the form wizard, an empty dictionary should be returned.
|
|
|
|
|
|
|
|
|
|
The default implementation::
|
|
|
|
|
|
|
|
|
|
def get_form_initial(self, step):
|
|
|
|
|
return self.initial_dict.get(step, {})
|
|
|
|
|
|
|
|
|
|
.. method:: WizardView.get_form_kwargs(step)
|
|
|
|
|
|
|
|
|
|
Returns a dictionary which will be used as the keyword arguments when
|
|
|
|
|
instantiating the form instance on given ``step``.
|
|
|
|
|
|
|
|
|
|
The default implementation::
|
|
|
|
|
|
|
|
|
|
def get_form_kwargs(self, step):
|
|
|
|
|
return {}
|
|
|
|
|
|
|
|
|
|
.. method:: WizardView.get_form_instance(step)
|
|
|
|
|
|
|
|
|
|
This method will be called only if a :class:`~django.forms.ModelForm` is
|
|
|
|
|
used as the form for step ``step``.
|
|
|
|
|
|
|
|
|
|
Returns an :class:`~django.db.models.Model` object which will be passed as
|
|
|
|
|
the ``instance`` argument when instantiating the ``ModelForm`` for step
|
|
|
|
|
``step``. If no instance object was provided while initializing the form
|
|
|
|
|
wizard, ``None`` will be returned.
|
|
|
|
|
|
|
|
|
|
The default implementation::
|
|
|
|
|
|
|
|
|
|
def get_form_instance(self, step):
|
|
|
|
|
return self.instance_dict.get(step, None)
|
|
|
|
|
|
|
|
|
|
.. method:: WizardView.get_context_data(form, **kwargs)
|
|
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
The default template context variables are:
|
|
|
|
|
|
|
|
|
|
* Any extra data the storage backend has stored
|
|
|
|
|
* ``wizard`` -- a dictionary representation of the wizard instance with the
|
|
|
|
|
following key/values:
|
|
|
|
|
|
|
|
|
|
* ``form`` -- :class:`~django.forms.Form` or
|
|
|
|
|
:class:`~django.forms.formsets.BaseFormSet` instance for the current step
|
|
|
|
|
* ``steps`` -- A helper object to access the various steps related data
|
|
|
|
|
* ``management_form`` -- all the management data for the current step
|
|
|
|
|
|
|
|
|
|
Example to add extra variables for a specific step::
|
|
|
|
|
|
|
|
|
|
def get_context_data(self, form, **kwargs):
|
|
|
|
|
context = super(MyWizard, self).get_context_data(form=form, **kwargs)
|
|
|
|
|
if self.steps.current == 'my_step_name':
|
|
|
|
|
context.update({'another_var': True})
|
|
|
|
|
return context
|
|
|
|
|
|
|
|
|
|
.. method:: WizardView.get_prefix(*args, **kwargs)
|
|
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
Default implementation::
|
|
|
|
|
|
|
|
|
|
def get_prefix(self, *args, **kwargs):
|
|
|
|
|
# use the lowercase underscore version of the class name
|
|
|
|
|
return normalize_name(self.__class__.__name__)
|
|
|
|
|
|
|
|
|
|
.. method:: WizardView.get_form(step=None, data=None, files=None)
|
|
|
|
|
|
|
|
|
|
This method constructs the form for a given ``step``. If no ``step`` is
|
|
|
|
|
defined, the current step will be determined automatically. If you override
|
|
|
|
|
``get_form``, however, you will need to set ``step`` yourself using
|
|
|
|
|
``self.steps.current`` as in the example below. The method gets three
|
|
|
|
|
arguments:
|
|
|
|
|
|
|
|
|
|
* ``step`` -- The step for which the form instance should be generated.
|
|
|
|
|
* ``data`` -- Gets passed to the form's data argument
|
|
|
|
|
* ``files`` -- Gets passed to the form's files argument
|
|
|
|
|
|
|
|
|
|
You can override this method to add extra arguments to the form instance.
|
|
|
|
|
|
|
|
|
|
Example code to add a user attribute to the form on step 2::
|
|
|
|
|
|
|
|
|
|
def get_form(self, step=None, data=None, files=None):
|
|
|
|
|
form = super(MyWizard, self).get_form(step, data, files)
|
|
|
|
|
|
|
|
|
|
# determine the step if not given
|
|
|
|
|
if step is None:
|
|
|
|
|
step = self.steps.current
|
|
|
|
|
|
|
|
|
|
if step == '1':
|
|
|
|
|
form.user = self.request.user
|
|
|
|
|
return form
|
|
|
|
|
|
|
|
|
|
.. method:: WizardView.process_step(form)
|
|
|
|
|
|
|
|
|
|
Hook for modifying the wizard's internal state, given a fully validated
|
|
|
|
|
:class:`~django.forms.Form` object. The Form is guaranteed to have clean,
|
|
|
|
|
valid data.
|
|
|
|
|
|
|
|
|
|
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
|
|
|
|
|
``form.data`` 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).
|
|
|
|
|
|
|
|
|
|
Note that this method is called every time a page is rendered for *all*
|
|
|
|
|
submitted steps.
|
|
|
|
|
|
|
|
|
|
The default implementation::
|
|
|
|
|
|
|
|
|
|
def process_step(self, form):
|
|
|
|
|
return self.get_form_step_data(form)
|
|
|
|
|
|
|
|
|
|
.. method:: WizardView.process_step_files(form)
|
|
|
|
|
|
|
|
|
|
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 ``form.files`` 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).
|
|
|
|
|
|
|
|
|
|
Default implementation::
|
|
|
|
|
|
|
|
|
|
def process_step_files(self, form):
|
|
|
|
|
return self.get_form_step_files(form)
|
|
|
|
|
|
|
|
|
|
.. method:: WizardView.render_goto_step(step, goto_step, **kwargs)
|
|
|
|
|
|
|
|
|
|
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 ``goto_step`` in the storage and then renders the new step.
|
|
|
|
|
|
|
|
|
|
If you want to store the entered data of the current step before rendering
|
|
|
|
|
the next step, you can overwrite this method.
|
|
|
|
|
|
|
|
|
|
.. method:: WizardView.render_revalidation_failure(step, form, **kwargs)
|
|
|
|
|
|
|
|
|
|
When the wizard thinks all steps have passed it revalidates all forms with
|
|
|
|
|
the data from the backend storage.
|
|
|
|
|
|
|
|
|
|
If any of the forms don't validate correctly, this method gets called.
|
|
|
|
|
This method expects two arguments, ``step`` and ``form``.
|
|
|
|
|
|
|
|
|
|
The default implementation resets the current step to the first failing
|
|
|
|
|
form and redirects the user to the invalid form.
|
|
|
|
|
|
|
|
|
|
Default implementation::
|
|
|
|
|
|
|
|
|
|
def render_revalidation_failure(self, step, form, **kwargs):
|
|
|
|
|
self.storage.current_step = step
|
|
|
|
|
return self.render(form, **kwargs)
|
|
|
|
|
|
|
|
|
|
.. method:: WizardView.get_form_step_data(form)
|
|
|
|
|
|
|
|
|
|
This method fetches the data from the ``form`` Form instance and returns the
|
|
|
|
|
dictionary. You can use this method to manipulate the values before the data
|
|
|
|
|
gets stored in the storage backend.
|
|
|
|
|
|
|
|
|
|
Default implementation::
|
|
|
|
|
|
|
|
|
|
def get_form_step_data(self, form):
|
|
|
|
|
return form.data
|
|
|
|
|
|
|
|
|
|
.. method:: WizardView.get_form_step_files(form)
|
|
|
|
|
|
|
|
|
|
This method returns the form files. You can use this method to manipulate
|
|
|
|
|
the files before the data gets stored in the storage backend.
|
|
|
|
|
|
|
|
|
|
Default implementation::
|
|
|
|
|
|
|
|
|
|
def get_form_step_files(self, form):
|
|
|
|
|
return form.files
|
|
|
|
|
|
|
|
|
|
.. method:: WizardView.render(form, **kwargs)
|
|
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
Default implementation::
|
|
|
|
|
|
|
|
|
|
def render(self, form=None, **kwargs):
|
|
|
|
|
form = form or self.get_form()
|
|
|
|
|
context = self.get_context_data(form=form, **kwargs)
|
|
|
|
|
return self.render_to_response(context)
|
|
|
|
|
|
|
|
|
|
.. method:: WizardView.get_cleaned_data_for_step(step)
|
|
|
|
|
|
|
|
|
|
This method returns the cleaned data for a given ``step``. Before returning
|
|
|
|
|
the cleaned data, the stored values are revalidated through the form. If
|
|
|
|
|
the data doesn't validate, ``None`` will be returned.
|
|
|
|
|
|
|
|
|
|
.. method:: WizardView.get_all_cleaned_data()
|
|
|
|
|
|
|
|
|
|
This method returns a merged dictionary of all form steps' ``cleaned_data``
|
|
|
|
|
dictionaries. If a step contains a ``FormSet``, the key will be prefixed
|
|
|
|
|
with ``formset-`` and contain a list of the formset's ``cleaned_data``
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
Providing initial data for the forms
|
|
|
|
|
====================================
|
|
|
|
|
|
|
|
|
|
.. attribute:: WizardView.initial_dict
|
|
|
|
|
|
|
|
|
|
Initial data for a wizard's :class:`~django.forms.Form` objects can be
|
|
|
|
|
provided using the optional :attr:`~WizardView.initial_dict` 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
|
|
|
|
|
:class:`~django.forms.Form`::
|
|
|
|
|
|
|
|
|
|
>>> from myapp.forms import ContactForm1, ContactForm2
|
|
|
|
|
>>> from myapp.views import ContactWizard
|
|
|
|
|
>>> initial = {
|
|
|
|
|
... '0': {'subject': 'Hello', 'sender': 'user@example.com'},
|
|
|
|
|
... '1': {'message': 'Hi there!'}
|
|
|
|
|
... }
|
|
|
|
|
>>> # This example is illustrative only and isn't meant to be run in
|
|
|
|
|
>>> # the shell since it requires an HttpRequest to pass to the view.
|
|
|
|
|
>>> wiz = ContactWizard.as_view([ContactForm1, ContactForm2], initial_dict=initial)(request)
|
|
|
|
|
>>> form1 = wiz.get_form('0')
|
|
|
|
|
>>> form2 = wiz.get_form('1')
|
|
|
|
|
>>> form1.initial
|
|
|
|
|
{'sender': 'user@example.com', 'subject': 'Hello'}
|
|
|
|
|
>>> form2.initial
|
|
|
|
|
{'message': 'Hi there!'}
|
|
|
|
|
|
|
|
|
|
The ``initial_dict`` can also take a list of dictionaries for a specific
|
|
|
|
|
step if the step is a ``FormSet``.
|
|
|
|
|
|
|
|
|
|
The ``initial_dict`` can also be added as a class attribute named
|
|
|
|
|
``initial_dict`` to avoid having the initial data in the ``urls.py``.
|
|
|
|
|
|
|
|
|
|
.. _wizard-files:
|
|
|
|
|
|
|
|
|
|
Handling files
|
|
|
|
|
==============
|
|
|
|
|
|
|
|
|
|
.. attribute:: WizardView.file_storage
|
|
|
|
|
|
|
|
|
|
To handle :class:`~django.forms.FileField` within any step form of the wizard,
|
|
|
|
|
you have to add a ``file_storage`` to your :class:`WizardView` subclass.
|
|
|
|
|
|
|
|
|
|
This storage will temporarily store the uploaded files for the wizard. The
|
|
|
|
|
``file_storage`` attribute should be a
|
|
|
|
|
:class:`~django.core.files.storage.Storage` subclass.
|
|
|
|
|
|
|
|
|
|
Django provides a built-in storage class (see :ref:`the built-in filesystem
|
|
|
|
|
storage class <builtin-fs-storage>`)::
|
|
|
|
|
|
|
|
|
|
from django.conf import settings
|
|
|
|
|
from django.core.files.storage import FileSystemStorage
|
|
|
|
|
|
|
|
|
|
class CustomWizardView(WizardView):
|
|
|
|
|
...
|
|
|
|
|
file_storage = FileSystemStorage(location=os.path.join(settings.MEDIA_ROOT, 'photos'))
|
|
|
|
|
|
|
|
|
|
.. warning::
|
|
|
|
|
|
|
|
|
|
Please remember to take care of removing old temporary files, as the
|
|
|
|
|
:class:`WizardView` will only remove these files if the wizard finishes
|
|
|
|
|
correctly.
|
|
|
|
|
|
|
|
|
|
Conditionally view/skip specific steps
|
|
|
|
|
======================================
|
|
|
|
|
|
|
|
|
|
.. attribute:: WizardView.condition_dict
|
|
|
|
|
|
|
|
|
|
The :meth:`~WizardView.as_view` method accepts a ``condition_dict`` argument.
|
|
|
|
|
You can pass a dictionary of boolean values or callables. The key should match
|
|
|
|
|
the steps names (e.g. '0', '1').
|
|
|
|
|
|
|
|
|
|
If the value of a specific step is callable it will be called with the
|
|
|
|
|
:class:`WizardView` instance as the only argument. If the return value is true,
|
|
|
|
|
the step's form will be used.
|
|
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
The steps are defined in a ``forms.py`` file::
|
|
|
|
|
|
|
|
|
|
from django import forms
|
|
|
|
|
|
|
|
|
|
class ContactForm1(forms.Form):
|
|
|
|
|
subject = forms.CharField(max_length=100)
|
|
|
|
|
sender = forms.EmailField()
|
|
|
|
|
leave_message = forms.BooleanField(required=False)
|
|
|
|
|
|
|
|
|
|
class ContactForm2(forms.Form):
|
|
|
|
|
message = forms.CharField(widget=forms.Textarea)
|
|
|
|
|
|
|
|
|
|
We define our wizard in a ``views.py``::
|
|
|
|
|
|
|
|
|
|
from django.shortcuts import render_to_response
|
|
|
|
|
from django.contrib.formtools.wizard.views import SessionWizardView
|
|
|
|
|
|
|
|
|
|
def show_message_form_condition(wizard):
|
|
|
|
|
# try to get the cleaned data of step 1
|
|
|
|
|
cleaned_data = wizard.get_cleaned_data_for_step('0') or {}
|
|
|
|
|
# check if the field ``leave_message`` was checked.
|
|
|
|
|
return cleaned_data.get('leave_message', True)
|
|
|
|
|
|
|
|
|
|
class ContactWizard(SessionWizardView):
|
|
|
|
|
|
|
|
|
|
def done(self, form_list, **kwargs):
|
|
|
|
|
return render_to_response('done.html', {
|
|
|
|
|
'form_data': [form.cleaned_data for form in form_list],
|
|
|
|
|
})
|
|
|
|
|
|
|
|
|
|
We need to add the ``ContactWizard`` to our ``urls.py`` file::
|
|
|
|
|
|
|
|
|
|
from django.conf.urls import url
|
|
|
|
|
|
|
|
|
|
from myapp.forms import ContactForm1, ContactForm2
|
|
|
|
|
from myapp.views import ContactWizard, show_message_form_condition
|
|
|
|
|
|
|
|
|
|
contact_forms = [ContactForm1, ContactForm2]
|
|
|
|
|
|
|
|
|
|
urlpatterns = [
|
|
|
|
|
url(r'^contact/$', ContactWizard.as_view(contact_forms,
|
|
|
|
|
condition_dict={'1': show_message_form_condition}
|
|
|
|
|
)),
|
|
|
|
|
]
|
|
|
|
|
|
|
|
|
|
As you can see, we defined a ``show_message_form_condition`` next to our
|
|
|
|
|
:class:`WizardView` subclass and added a ``condition_dict`` argument to the
|
|
|
|
|
:meth:`~WizardView.as_view` method. The key refers to the second wizard step
|
|
|
|
|
(because of the zero based step index).
|
|
|
|
|
|
|
|
|
|
How to work with ModelForm and ModelFormSet
|
|
|
|
|
===========================================
|
|
|
|
|
|
|
|
|
|
.. attribute:: WizardView.instance_dict
|
|
|
|
|
|
|
|
|
|
WizardView supports :doc:`ModelForms </topics/forms/modelforms>` and
|
|
|
|
|
:ref:`ModelFormSets <model-formsets>`. Additionally to
|
|
|
|
|
:attr:`~WizardView.initial_dict`, the :meth:`~WizardView.as_view` method takes
|
|
|
|
|
an ``instance_dict`` argument that should contain model instances for steps
|
|
|
|
|
based on ``ModelForm`` and querysets for steps based on ``ModelFormSet``.
|
|
|
|
|
|
|
|
|
|
Usage of ``NamedUrlWizardView``
|
|
|
|
|
===============================
|
|
|
|
|
|
|
|
|
|
.. class:: NamedUrlWizardView
|
|
|
|
|
.. class:: NamedUrlSessionWizardView
|
|
|
|
|
.. class:: NamedUrlCookieWizardView
|
|
|
|
|
|
|
|
|
|
``NamedUrlWizardView`` is a :class:`WizardView` subclass which adds named-urls
|
|
|
|
|
support to the wizard. This allows you to have separate URLs for every step.
|
|
|
|
|
You can also use the :class:`NamedUrlSessionWizardView` or :class:`NamedUrlCookieWizardView`
|
|
|
|
|
classes which preselect the backend used for storing information (Django sessions and
|
|
|
|
|
browser cookies respectively).
|
|
|
|
|
|
|
|
|
|
To use the named URLs, you should not only use the :class:`NamedUrlWizardView` instead of
|
|
|
|
|
:class:`WizardView`, but you will also have to change your ``urls.py``.
|
|
|
|
|
|
|
|
|
|
The :meth:`~WizardView.as_view` method takes two additional arguments:
|
|
|
|
|
|
|
|
|
|
* a required ``url_name`` -- the name of the url (as provided in the ``urls.py``)
|
|
|
|
|
* an optional ``done_step_name`` -- the name of the done step, to be used in the URL
|
|
|
|
|
|
|
|
|
|
This is an example of a ``urls.py`` for a contact wizard with two steps, step 1 named
|
|
|
|
|
``contactdata`` and step 2 named ``leavemessage``::
|
|
|
|
|
|
|
|
|
|
from django.conf.urls import url
|
|
|
|
|
|
|
|
|
|
from myapp.forms import ContactForm1, ContactForm2
|
|
|
|
|
from myapp.views import ContactWizard
|
|
|
|
|
|
|
|
|
|
named_contact_forms = (
|
|
|
|
|
('contactdata', ContactForm1),
|
|
|
|
|
('leavemessage', ContactForm2),
|
|
|
|
|
)
|
|
|
|
|
|
|
|
|
|
contact_wizard = ContactWizard.as_view(named_contact_forms,
|
|
|
|
|
url_name='contact_step', done_step_name='finished')
|
|
|
|
|
|
|
|
|
|
urlpatterns = [
|
|
|
|
|
url(r'^contact/(?P<step>.+)/$', contact_wizard, name='contact_step'),
|
|
|
|
|
url(r'^contact/$', contact_wizard, name='contact'),
|
|
|
|
|
]
|
|
|
|
|
|
|
|
|
|
Advanced ``NamedUrlWizardView`` methods
|
|
|
|
|
=======================================
|
|
|
|
|
|
|
|
|
|
.. method:: NamedUrlWizardView.get_step_url(step)
|
|
|
|
|
|
|
|
|
|
This method returns the URL for a specific step.
|
|
|
|
|
|
|
|
|
|
Default implementation::
|
|
|
|
|
|
|
|
|
|
def get_step_url(self, step):
|
|
|
|
|
return reverse(self.url_name, kwargs={'step': step})
|
Jannis Leidel
Tim Graham