139 lines
4.3 KiB
ReStructuredText
139 lines
4.3 KiB
ReStructuredText
============
|
|
Form preview
|
|
============
|
|
|
|
.. module:: formtools.preview
|
|
:synopsis: Displays an HTML form, forces a preview, then does something
|
|
with the submission.
|
|
|
|
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 :class:`~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 :meth:`~FormPreview.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 ``'formtools'`` to your
|
|
:setting:`INSTALLED_APPS` setting.
|
|
|
|
This will work if your :setting:`TEMPLATES` setting includes the
|
|
``app_directories`` template loader (which is the case by default).
|
|
|
|
See the :ref:`template loader docs <template-loaders>` for more.
|
|
|
|
* Otherwise, determine the full filesystem path to the
|
|
:file:`formtools/templates` directory and add that directory to your
|
|
:setting:`DIRS <TEMPLATES-DIRS>` option in the :setting:`TEMPLATES`
|
|
setting.
|
|
|
|
2. Create a :class:`~FormPreview` subclass that
|
|
overrides the ``done()`` method::
|
|
|
|
from django.http import HttpResponseRedirect
|
|
|
|
from 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 :class:`~django.http.HttpRequest` object and a
|
|
dictionary of the form data after it has been validated and cleaned.
|
|
It should return an :class:`~django.http.HttpResponseRedirect` that
|
|
is the end result of the form being submitted.
|
|
|
|
3. Change your URLconf to point to an instance of your
|
|
:class:`~FormPreview` subclass::
|
|
|
|
from django import forms
|
|
|
|
from myapp.forms import SomeModelForm
|
|
from myapp.preview import SomeModelFormPreview
|
|
|
|
...and add the following line to the appropriate model in your URLconf::
|
|
|
|
url(r'^post/$', SomeModelFormPreview(SomeModelForm)),
|
|
|
|
where ``SomeModelForm`` is a Form or ModelForm class for the model.
|
|
|
|
4. Run the Django server and visit :file:`/post/` in your browser.
|
|
|
|
``FormPreview`` classes
|
|
=======================
|
|
|
|
.. class:: FormPreview
|
|
|
|
A :class:`~FormPreview` class is a simple Python class
|
|
that represents the preview workflow.
|
|
:class:`~FormPreview` classes must subclass
|
|
``FormPreview`` and override the ``done()``
|
|
method. They can live anywhere in your codebase.
|
|
|
|
``FormPreview`` templates
|
|
=========================
|
|
|
|
.. attribute:: FormPreview.form_template
|
|
.. attribute:: FormPreview.preview_template
|
|
|
|
By default, the form is rendered via the template :file:`formtools/form.html`,
|
|
and the preview page is rendered via the template :file:`formtools/preview.html`.
|
|
|
|
These values can be overridden for a particular form preview by setting
|
|
:attr:`~FormPreview.preview_template` and
|
|
:attr:`~FormPreview.form_template` attributes on the
|
|
FormPreview subclass. See :file:`formtools/templates` for the default templates.
|
|
|
|
Required methods
|
|
================
|
|
|
|
.. automethod:: FormPreview.done
|
|
|
|
Optional methods
|
|
================
|
|
|
|
.. automethod:: FormPreview.get_auto_id
|
|
|
|
.. automethod:: FormPreview.get_initial
|
|
|
|
.. automethod:: FormPreview.get_context
|
|
|
|
.. automethod:: FormPreview.parse_params
|
|
|
|
.. automethod:: FormPreview.process_preview
|
|
|
|
.. automethod:: FormPreview.security_hash
|
|
|
|
.. automethod:: FormPreview.failed_hash
|