============ Form preview ============ Django comes with an optional "form preview" application that helps automate the following workflow: "Display an HTML form, force a preview, then do something with the submission." To force a preview of a form submission, all you have to do is write a short Python class. Overview ========= Given a ``django.forms.Form`` subclass that you define, this application takes care of the following workflow: 1. Displays the form as HTML on a Web page. 2. Validates the form data when it's submitted via POST. a. If it's valid, displays a preview page. b. If it's not valid, redisplays the form with error messages. 3. When the "confirmation" form is submitted from the preview page, calls a hook that you define -- a ``done()`` method that gets passed the valid data. The framework enforces the required preview by passing a shared-secret hash to the preview page via hidden form fields. If somebody tweaks the form parameters on the preview page, the form submission will fail the hash-comparison test. How to use ``FormPreview`` ========================== 1. Point Django at the default FormPreview templates. There are two ways to do this: * Add ``'django.contrib.formtools'`` to your ``INSTALLED_APPS`` setting. This will work if your ``TEMPLATE_LOADERS`` setting includes the ``app_directories`` template loader (which is the case by default). See the `template loader docs`_ for more. * Otherwise, determine the full filesystem path to the ``django/contrib/formtools/templates`` directory, and add that directory to your ``TEMPLATE_DIRS`` setting. 2. Create a ``FormPreview`` subclass that overrides the ``done()`` method:: from django.contrib.formtools.preview import FormPreview from myapp.models import SomeModel class SomeModelFormPreview(FormPreview): def done(self, request, cleaned_data): # Do something with the cleaned_data, then redirect # to a "success" page. return HttpResponseRedirect('/form/success') This method takes an ``HttpRequest`` object and a dictionary of the form data after it has been validated and cleaned. It should return an ``HttpResponseRedirect`` that is the end result of the form being submitted. 3. Change your URLconf to point to an instance of your ``FormPreview`` subclass:: from myapp.preview import SomeModelFormPreview from myapp.models import SomeModel from django import forms ...and add the following line to the appropriate model in your URLconf:: (r'^post/$', SomeModelFormPreview(SomeModelForm)), where ``SomeModelForm`` is a Form or ModelForm class for the model. 4. Run the Django server and visit ``/post/`` in your browser. .. _template loader docs: ../templates_python/#loader-types ``FormPreview`` classes ======================= A ``FormPreview`` class is a simple Python class that represents the preview workflow. ``FormPreview`` classes must subclass ``django.contrib.formtools.preview.FormPreview`` and override the ``done()`` method. They can live anywhere in your codebase. ``FormPreview`` templates ========================= By default, the form is rendered via the template ``formtools/form.html``, and the preview page is rendered via the template ``formtools.preview.html``. These values can be overridden for a particular form preview by setting ``preview_template`` and ``form_template`` attributes on the FormPreview subclass. See ``django/contrib/formtools/templates`` for the default templates.