Ticket #5432: django_form_preview.diff

docs/add_ons.txt

@@ -70 +70 @@
 
 "Display an HTML form, force a preview, then do something with the submission."
 
-Full documentation for this feature does not yet exist, but you can read the
-code and docstrings in ``django/contrib/formtools/preview.py`` for a start.
+See the `form preview documentation`_.
 
+.. _form preview documentation: ../form_preview/
+
 humanize
 ========
 

docs/form_preview.txt

@@ +1 @@
+============
+Form preview
+============
+
+Django comes with an optional form preview application that helps with 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`` object 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 once 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. At the preview page, if the preview confirmation button is pressed, calls
+       a hook that you define -- a done() method.
+       
+The framework enforces the required preview by passing a shared-secret hash to
+the preview page. 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 of the
+       FormPreview class::
+
+           from django.contrib.formtools import FormPreview
+           from myapp.models import SomeModel
+
+           class SomeModelFormPreview(FormPreview):
+               
+               def done(self, request, cleaned_data):
+                   ''' Submit form, then redirect to success '''
+                   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.
+       The FormPreview subclass can live anywhere in your codebase.
+       
+    3. Change your URLconf to point to the ``FormPreview`` workflow::
+
+           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 the appropriate model ``/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.
+ No newline at end of file