1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
|
============
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
|
