python/lib/django_1_4/docs/ref/contrib/formtools/form-preview.txt

   1 ============
   2 Form preview
   3 ============
   4
   5 .. module:: django.contrib.formtools.preview
   6     :synopsis: Displays an HTML form, forces a preview, then does something
   7                with the submission.
   8
   9 Django comes with an optional "form preview" application that helps automate
  10 the following workflow:
  11
  12 "Display an HTML form, force a preview, then do something with the submission."
  13
  14 To force a preview of a form submission, all you have to do is write a short
  15 Python class.
  16
  17 Overview
  18 =========
  19
  20 Given a :class:`django.forms.Form` subclass that you define, this
  21 application takes care of the following workflow:
  22
  23 1. Displays the form as HTML on a Web page.
  24 2. Validates the form data when it's submitted via POST.
  25    a. If it's valid, displays a preview page.
  26    b. If it's not valid, redisplays the form with error messages.
  27 3. When the "confirmation" form is submitted from the preview page, calls
  28    a hook that you define -- a
  29    :meth:`~django.contrib.formtools.preview.FormPreview.done()` method that gets
  30    passed the valid data.
  31
  32 The framework enforces the required preview by passing a shared-secret hash to
  33 the preview page via hidden form fields. If somebody tweaks the form parameters
  34 on the preview page, the form submission will fail the hash-comparison test.
  35
  36 How to use ``FormPreview``
  37 ==========================
  38
  39 1. Point Django at the default FormPreview templates. There are two ways to
  40    do this:
  41
  42    * Add ``'django.contrib.formtools'`` to your
  43      :setting:`INSTALLED_APPS` setting. This will work if your
  44      :setting:`TEMPLATE_LOADERS` setting includes the
  45      ``app_directories`` template loader (which is the case by
  46      default). See the :ref:`template loader docs <template-loaders>`
  47      for more.
  48
  49    * Otherwise, determine the full filesystem path to the
  50      :file:`django/contrib/formtools/templates` directory, and add that
  51      directory to your :setting:`TEMPLATE_DIRS` setting.
  52
  53 2. Create a :class:`~django.contrib.formtools.preview.FormPreview` subclass that
  54    overrides the :meth:`~django.contrib.formtools.preview.FormPreview.done()`
  55    method::
  56
  57        from django.contrib.formtools.preview import FormPreview
  58        from myapp.models import SomeModel
  59
  60        class SomeModelFormPreview(FormPreview):
  61
  62            def done(self, request, cleaned_data):
  63                # Do something with the cleaned_data, then redirect
  64                # to a "success" page.
  65                return HttpResponseRedirect('/form/success')
  66
  67    This method takes an :class:`~django.http.HttpRequest` object and a
  68    dictionary of the form data after it has been validated and cleaned.
  69    It should return an :class:`~django.http.HttpResponseRedirect` that
  70    is the end result of the form being submitted.
  71
  72 3. Change your URLconf to point to an instance of your
  73    :class:`~django.contrib.formtools.preview.FormPreview` subclass::
  74
  75        from myapp.preview import SomeModelFormPreview
  76        from myapp.forms import SomeModelForm
  77        from django import forms
  78
  79    ...and add the following line to the appropriate model in your URLconf::
  80
  81        (r'^post/$', SomeModelFormPreview(SomeModelForm)),
  82
  83    where ``SomeModelForm`` is a Form or ModelForm class for the model.
  84
  85 4. Run the Django server and visit :file:`/post/` in your browser.
  86
  87 ``FormPreview`` classes
  88 =======================
  89
  90 .. class:: FormPreview
  91
  92 A :class:`~django.contrib.formtools.preview.FormPreview` class is a simple Python class
  93 that represents the preview workflow.
  94 :class:`~django.contrib.formtools.preview.FormPreview` classes must subclass
  95 ``django.contrib.formtools.preview.FormPreview`` and override the
  96 :meth:`~django.contrib.formtools.preview.FormPreview.done()` method. They can live
  97 anywhere in your codebase.
  98
  99 ``FormPreview`` templates
 100 =========================
 101
 102 By default, the form is rendered via the template :file:`formtools/form.html`,
 103 and the preview page is rendered via the template :file:`formtools/preview.html`.
 104 These values can be overridden for a particular form preview by setting
 105 :attr:`~django.contrib.formtools.preview.FormPreview.preview_template` and
 106 :attr:`~django.contrib.formtools.preview.FormPreview.form_template` attributes on the
 107 FormPreview subclass. See :file:`django/contrib/formtools/templates` for the
 108 default templates.
 109
 110 Advanced ``FormPreview`` methods
 111 ================================
 112
 113 .. versionadded:: 1.2
 114
 115 .. method:: FormPreview.process_preview
 116
 117     Given a validated form, performs any extra processing before displaying the
 118     preview page, and saves any extra data in context.
 119
 120     By default, this method is empty.  It is called after the form is validated,
 121     but before the context is modified with hash information and rendered.