django/docs/form_preview.txt

98 lines
3.8 KiB
Plaintext

============
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.newforms.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 newforms as forms
...and add the following line to the appropriate model in your URLconf::
(r'^post/$', SomeModelFormPreview(forms.models.form_for_model(SomeModel))),
Or, if you already have a Form class defined for the model::
(r'^post/$', SomeModelFormPreview(SomeModelForm)),
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.