p15693087
/
django
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

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
This commit is contained in:
Adrian Holovaty 2007-09-14 23:15:40 +00:00
parent 6c16d84a0b
commit 92e55fe8b1
4 changed files with 101 additions and 44 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
AUTHORS
View File

@ -252,6 +252,7 @@ answer newbie questions, and generally made Django that much better:
Armin Ronacher
Brian Rosner <brosner@gmail.com>
Oliver Rutherfurd <http://rutherfurd.net/>
ryankanno
Ivan Sagalaev (Maniac) <http://www.softwaremaniacs.org/>
Vinay Sajip <vinay_sajip@yahoo.co.uk>
David Schein

42
django/contrib/formtools/preview.py
View File

@ -1,47 +1,5 @@
"""
Formtools Preview application.
This is an abstraction of the following workflow:
"Display an HTML form, force a preview, then do something with the submission."
Given a django.newforms.Form object that you define, this takes care of the
following:
* Displays the form as HTML on a Web page.
* Validates the form data once it's submitted via POST.
* If it's valid, displays a preview page.
* If it's not valid, redisplays the form with error messages.
* 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.
Usage
=====
Subclass FormPreview and define a done() method:
def done(self, request, cleaned_data):
# ...
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.
Then, just instantiate your FormPreview subclass by passing it a Form class,
and pass that to your URLconf, like so:
(r'^post/$', MyFormPreview(MyForm)),
The FormPreview class has a few other hooks. See the docstrings in the source
code below.
The framework also uses two templates: 'formtools/preview.html' and
'formtools/form.html'. You can override these by setting 'preview_template' and
'form_template' attributes on your FormPreview subclass. See
django/contrib/formtools/templates for the default templates.
"""
from django.conf import settings

5
docs/add_ons.txt
View File

@ -70,8 +70,9 @@ An abstraction of the following workflow:
"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
========

97
docs/form_preview.txt Normal file
View File

@ -0,0 +1,97 @@
============
Form preview
============
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 ``django.newforms.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 ``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 ``'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::
from django.contrib.formtools 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 ``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.
3. Change your URLconf to point to an instance of your ``FormPreview``
subclass::
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 ``/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.