PageRenderTime 82ms CodeModel.GetById 40ms app.highlight 1ms RepoModel.GetById 39ms app.codeStats 0ms

/docs/ref/contrib/formtools/form-preview.txt

https://code.google.com/p/mango-py/
Plain Text | 121 lines | 88 code | 33 blank | 0 comment | 0 complexity | e76ba5ea36ad05040cfaa4ec8a851cf9 MD5 | raw file
  1============
  2Form 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
  9Django comes with an optional "form preview" application that helps automate
 10the following workflow:
 11
 12"Display an HTML form, force a preview, then do something with the submission."
 13
 14To force a preview of a form submission, all you have to do is write a short
 15Python class.
 16
 17Overview
 18=========
 19
 20Given a :class:`django.forms.Form` subclass that you define, this
 21application 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
 32The framework enforces the required preview by passing a shared-secret hash to
 33the preview page via hidden form fields. If somebody tweaks the form parameters
 34on the preview page, the form submission will fail the hash-comparison test.
 35
 36How 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
 92A :class:`~django.contrib.formtools.preview.FormPreview` class is a simple Python class
 93that 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
 97anywhere in your codebase.
 98
 99``FormPreview`` templates
100=========================
101
102By default, the form is rendered via the template :file:`formtools/form.html`,
103and the preview page is rendered via the template :file:`formtools/preview.html`.
104These 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
107FormPreview subclass. See :file:`django/contrib/formtools/templates` for the
108default templates.
109
110Advanced ``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.