Ticket #3218: form_wizard.txt

===========
Form Wizard
===========

**New in Django devleopment version.**

The form wizard allows you to divide your forms into multiple pages, 
maintaining form data in hidden fields until submission in the final step.

Usage
=====

Define the forms you will use in you wizard in a ``forms.py`` file for your 
application::

    from django import newforms as forms

    class ContactForm(forms.Form):
        subject = forms.CharField(max_length=100)
        message = forms.CharField()
        sender = forms.EmailField()
        cc_myself = forms.BooleanField()

    class ContactFormPage2(forms.Form):
        code = forms.CharField()

.. warning:: Do not include ``FileField`` or ``ImageField`` in any form that 
    will not be displayed on the last page of your form wizard.

In your application's ``views.py``, subclass a form wizard object.  You'll 
need to override the ``done`` method with your own form processing code.  
In the example below, rather than perform any database operation, the method 
simply returns a list of the (validated) data the user entered into the form 
to be displayed by a template ``done.html``::

    from django.shortcuts import render_to_response
    from django.contrib.formtools.wizard import Wizard

    class ContactWizard(Wizard):
        def done(self, request, form_list):
            return render_to_response('done.html', 
                {'form_data' : [ form.cleaned_data for form in form_list ] })

Next, connect your new form wizard object to the path of your choosing 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 ContactForm, ContactFormPage2
    from mysite.testapp.views import ContactWizard

    urlpatterns = patterns('',
        (r'^contact/$', ContactWizard([ContactForm, ContactFormPage2])),
    )

Finally, you'll need to create a template named ``wizard.html`` in your 
``templates`` directory.  That template will contain template code that will 
display your form fields so that they can be processed properly by the form 
wizard.  For example::

    {% extends "base.html" %}
    {% block content %}
    <p>Step {{ current_step }} of {{ step_count }}</p>
    <form action="." method="POST">
    <table>
    {{ form }}
    </table>
    <input type="hidden" name="{{ step_field }}" value="{{ step }}" />
    <!-- include previous fields -->
    {{ previous_fields }}
    <input type="submit">
    </form>
    {% endblock %}

The ``current_step`` and ``step_count`` variables can be displayed to notify
your users where they are in the process.  Note also the presence of the 
template variables ``step_fields``, ``step``, ``previous_fields``, which are 
used for hidden form fields.

Advanced Usage
==============

You may override the ``process_step`` method in your wizard class to, for 
example, dynamically generate a ``form_list`` and/or add items to 
``self.extra_context`` based on the contents of previously submitted forms::

    def process_step(self, request, form, step):
        if step == 0:
            # do something for the second step in your form wizard
            # based on data submitted from step 1

The method is called every time a page is rendered, for all submitted steps.