<commit_before>.. _ref-contrib-formtools-form-wizard:

===========
Form wizard
===========

.. module:: django.contrib.formtools.wizard
    :synopsis: Splits forms across multiple Web pages.

.. versionadded:: 1.0

Django comes with an optional "form wizard" application that splits
:ref:`forms <topics-forms-index>` across multiple Web pages. It maintains
state in hashed HTML :samp:`<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`_.

.. _explained on Wikipedia: http://en.wikipedia.org/wiki/Wizard_%28software%29
.. _forms: ../forms/

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 calculates a
       secure hash of the data and presents the user with the next form,
       saving the validated data and hash in :samp:`<input type="hidden">`
       fields.
    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 e-mail, 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 :mod:`django.forms`
       :class:`~django.forms.forms.Form` classes -- one per wizard page.
       
    2. Create a :class:`~django.contrib.formtools.wizard.FormWizard` class
       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. Point your URLconf at your
       :class:`~django.contrib.formtools.wizard.FormWizard` class.

Defining ``Form`` classes
=========================

The first step in creating a form wizard is to create the :class:`~django.forms.forms.Form` classes.
These should be standard :mod:`django.forms`
:class:`~django.forms.forms.Form` classes, covered in the
:ref:`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 e-mail 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)

**Important limitation:** Because the wizard uses HTML hidden fields to store
data between pages, you may not include a :class:`~django.forms.fields.FileField`
in any form except the last one.

Creating a ``FormWizard`` class
===============================

The next step is to create a :class:`~django.contrib.formtools.wizard.FormWizard`
class, which should be a subclass of ``django.contrib.formtools.wizard.FormWizard``.

As your :class:`~django.forms.forms.Form` classes, this
:class:`~django.contrib.formtools.wizard.FormWizard` class can live anywhere
in your codebase, but convention is to put it in :file:`forms.py`.

The only requirement on this subclass is that it implement a
:meth:`~django.contrib.formtools.wizard.FormWizard.done()` method,
which specifies what should happen when the data for *every* form is submitted
and validated. This method is passed two arguments:

    * ``request`` -- an :class:`~django.http.HttpRequest` object
    * ``form_list`` -- a list of :mod:`django.forms`
      :class:`~django.forms.forms.Form` classes

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<commit_msg>Fixed #11508: Adding missing word to form wizard doc.  Thanks thepointer and timo.<commit_after>.. _ref-contrib-formtools-form-wizard:

===========
Form wizard
===========

.. module:: django.contrib.formtools.wizard
    :synopsis: Splits forms across multiple Web pages.

.. versionadded:: 1.0

Django comes with an optional "form wizard" application that splits
:ref:`forms <topics-forms-index>` across multiple Web pages. It maintains
state in hashed HTML :samp:`<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`_.

.. _explained on Wikipedia: http://en.wikipedia.org/wiki/Wizard_%28software%29
.. _forms: ../forms/

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 calculates a
       secure hash of the data and presents the user with the next form,
       saving the validated data and hash in :samp:`<input type="hidden">`
       fields.
    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 e-mail, 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 :mod:`django.forms`
       :class:`~django.forms.forms.Form` classes -- one per wizard page.
       
    2. Create a :class:`~django.contrib.formtools.wizard.FormWizard` class
       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. Point your URLconf at your
       :class:`~django.contrib.formtools.wizard.FormWizard` class.

Defining ``Form`` classes
=========================

The first step in creating a form wizard is to create the :class:`~django.forms.forms.Form` classes.
These should be standard :mod:`django.forms`
:class:`~django.forms.forms.Form` classes, covered in the
:ref:`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 e-mail 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)

**Important limitation:** Because the wizard uses HTML hidden fields to store
data between pages, you may not include a :class:`~django.forms.fields.FileField`
in any form except the last one.

Creating a ``FormWizard`` class
===============================

The next step is to create a :class:`~django.contrib.formtools.wizard.FormWizard`
class, which should be a subclass of ``django.contrib.formtools.wizard.FormWizard``.

As with your :class:`~django.forms.forms.Form` classes, this
:class:`~django.contrib.formtools.wizard.FormWizard` class can live anywhere
in your codebase, but convention is to put it in :file:`forms.py`.

The only requirement on this subclass is that it implement a
:meth:`~django.contrib.formtools.wizard.FormWizard.done()` method,
which specifies what should happen when the data for *every* form is submitted
and validated. This method is passed two arguments:

    * ``request`` -- an :class:`~django.http.HttpRequest` object
    * ``form_list`` -- a list of :mod:`django.forms`
      :class:`~django.forms.forms.Form` classes

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
{'fraction_non_alphanumeric': 0.09831223628691983, 'fraction_numerical': 0.004957805907172996, 'mean_word_length': 3.8200305033045248, 'pattern_counts': {'":': 0, '<': 11, '<?xml version=': 0, '>': 11, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7577783', 'n_tokens_mistral': 2632, 'n_tokens_neox': 2496, 'n_words': 1176}