mirror of
https://github.com/django/django.git
synced 2024-12-22 09:05:43 +00:00
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:
parent
6c16d84a0b
commit
92e55fe8b1
1
AUTHORS
1
AUTHORS
@ -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
|
||||
|
@ -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
|
||||
|
@ -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
97
docs/form_preview.txt
Normal 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.
|
Loading…
Reference in New Issue
Block a user