PageRenderTime 43ms CodeModel.GetById 20ms RepoModel.GetById 0ms app.codeStats 0ms

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