Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Fixed #5432 -- Added docs/form_preview.txt. Thanks, ryankanno

git-svn-id: http://code.djangoproject.com/svn/django/trunk@6247 bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
commit 92e55fe8b1ff5ed8867d9fe09b789cf493050623 1 parent 6c16d84
Adrian Holovaty authored September 14, 2007
1  AUTHORS
@@ -252,6 +252,7 @@ answer newbie questions, and generally made Django that much better:
252 252
     Armin Ronacher
253 253
     Brian Rosner <brosner@gmail.com>
254 254
     Oliver Rutherfurd <http://rutherfurd.net/>
  255
+    ryankanno
255 256
     Ivan Sagalaev (Maniac) <http://www.softwaremaniacs.org/>
256 257
     Vinay Sajip <vinay_sajip@yahoo.co.uk>
257 258
     David Schein
42  django/contrib/formtools/preview.py
... ...
@@ -1,47 +1,5 @@
1 1
 """
2 2
 Formtools Preview application.
3  
-
4  
-This is an abstraction of the following workflow:
5  
-
6  
-    "Display an HTML form, force a preview, then do something with the submission."
7  
-
8  
-Given a django.newforms.Form object that you define, this takes care of the
9  
-following:
10  
-
11  
-    * Displays the form as HTML on a Web page.
12  
-    * Validates the form data once it's submitted via POST.
13  
-        * If it's valid, displays a preview page.
14  
-        * If it's not valid, redisplays the form with error messages.
15  
-    * At the preview page, if the preview confirmation button is pressed, calls
16  
-      a hook that you define -- a done() method.
17  
-
18  
-The framework enforces the required preview by passing a shared-secret hash to
19  
-the preview page. If somebody tweaks the form parameters on the preview page,
20  
-the form submission will fail the hash comparison test.
21  
-
22  
-Usage
23  
-=====
24  
-
25  
-Subclass FormPreview and define a done() method:
26  
-
27  
-    def done(self, request, cleaned_data):
28  
-        # ...
29  
-
30  
-This method takes an HttpRequest object and a dictionary of the form data after
31  
-it has been validated and cleaned. It should return an HttpResponseRedirect.
32  
-
33  
-Then, just instantiate your FormPreview subclass by passing it a Form class,
34  
-and pass that to your URLconf, like so:
35  
-
36  
-    (r'^post/$', MyFormPreview(MyForm)),
37  
-
38  
-The FormPreview class has a few other hooks. See the docstrings in the source
39  
-code below.
40  
-
41  
-The framework also uses two templates: 'formtools/preview.html' and
42  
-'formtools/form.html'. You can override these by setting 'preview_template' and
43  
-'form_template' attributes on your FormPreview subclass. See
44  
-django/contrib/formtools/templates for the default templates.
45 3
 """
46 4
 
47 5
 from django.conf import settings
5  docs/add_ons.txt
@@ -70,8 +70,9 @@ An abstraction of the following workflow:
70 70
 
71 71
 "Display an HTML form, force a preview, then do something with the submission."
72 72
 
73  
-Full documentation for this feature does not yet exist, but you can read the
74  
-code and docstrings in ``django/contrib/formtools/preview.py`` for a start.
  73
+See the `form preview documentation`_.
  74
+
  75
+.. _form preview documentation: ../form_preview/
75 76
 
76 77
 humanize
77 78
 ========
97  docs/form_preview.txt
... ...
@@ -0,0 +1,97 @@
  1
+============
  2
+Form preview
  3
+============
  4
+
  5
+Django comes with an optional "form preview" application that helps automate
  6
+the following workflow:
  7
+
  8
+"Display an HTML form, force a preview, then do something with the submission."
  9
+
  10
+To force a preview of a form submission, all you have to do is write a short
  11
+Python class.
  12
+
  13
+Overview
  14
+=========
  15
+
  16
+Given a ``django.newforms.Form`` subclass that you define, this application
  17
+takes care of the following workflow:
  18
+
  19
+    1. Displays the form as HTML on a Web page.
  20
+    2. Validates the form data when it's submitted via POST.
  21
+       a. If it's valid, displays a preview page.
  22
+       b. If it's not valid, redisplays the form with error messages.
  23
+    3. When the "confirmation" form is submitted from the preview page, calls
  24
+       a hook that you define -- a ``done()`` method that gets passed the valid
  25
+       data.
  26
+
  27
+The framework enforces the required preview by passing a shared-secret hash to
  28
+the preview page via hidden form fields. If somebody tweaks the form parameters
  29
+on the preview page, the form submission will fail the hash-comparison test.
  30
+
  31
+How to use ``FormPreview``
  32
+==========================
  33
+
  34
+    1. Point Django at the default FormPreview templates. There are two ways to
  35
+       do this:
  36
+
  37
+       * Add ``'django.contrib.formtools'`` to your ``INSTALLED_APPS``
  38
+         setting. This will work if your ``TEMPLATE_LOADERS`` setting includes
  39
+         the ``app_directories`` template loader (which is the case by
  40
+         default). See the `template loader docs`_ for more.
  41
+
  42
+       * Otherwise, determine the full filesystem path to the
  43
+         ``django/contrib/formtools/templates`` directory, and add that
  44
+         directory to your ``TEMPLATE_DIRS`` setting.
  45
+
  46
+    2. Create a ``FormPreview`` subclass that overrides the ``done()`` method::
  47
+
  48
+           from django.contrib.formtools import FormPreview
  49
+           from myapp.models import SomeModel
  50
+
  51
+           class SomeModelFormPreview(FormPreview):
  52
+
  53
+               def done(self, request, cleaned_data):
  54
+                   # Do something with the cleaned_data, then redirect
  55
+                   # to a "success" page.
  56
+                   return HttpResponseRedirect('/form/success')
  57
+
  58
+       This method takes an ``HttpRequest`` object and a dictionary of the form
  59
+       data after it has been validated and cleaned. It should return an
  60
+       ``HttpResponseRedirect`` that is the end result of the form being
  61
+       submitted.
  62
+
  63
+    3. Change your URLconf to point to an instance of your ``FormPreview``
  64
+       subclass::
  65
+
  66
+           from myapp.preview import SomeModelFormPreview
  67
+           from myapp.models import SomeModel
  68
+           from django import newforms as forms
  69
+
  70
+       ...and add the following line to the appropriate model in your URLconf::
  71
+
  72
+           (r'^post/$', SomeModelFormPreview(forms.models.form_for_model(SomeModel))),
  73
+
  74
+       Or, if you already have a Form class defined for the model::
  75
+
  76
+           (r'^post/$', SomeModelFormPreview(SomeModelForm)),
  77
+
  78
+    4. Run the Django server and visit ``/post/`` in your browser.
  79
+
  80
+.. _template loader docs: ../templates_python/#loader-types
  81
+
  82
+``FormPreview`` classes
  83
+=======================
  84
+
  85
+A ``FormPreview`` class is a simple Python class that represents the preview
  86
+workflow.  ``FormPreview`` classes must subclass
  87
+``django.contrib.formtools.preview.FormPreview`` and override the ``done()``
  88
+method. They can live anywhere in your codebase.
  89
+
  90
+``FormPreview`` templates
  91
+=========================
  92
+
  93
+By default, the form is rendered via the template ``formtools/form.html``, and
  94
+the preview page is rendered via the template ``formtools.preview.html``.
  95
+These values can be overridden for a particular form preview by setting
  96
+``preview_template`` and ``form_template`` attributes on the FormPreview
  97
+subclass. See ``django/contrib/formtools/templates`` for the default templates.

0 notes on commit 92e55fe

Please sign in to comment.
Something went wrong with that request. Please try again.