.. _ref-contrib-formtools-form-preview:

==================
フォームプレビュー
==================

:revision-up-to: 11321 (1.1)

.. module:: django.contrib.formtools
    :synopsis: HTML フォームを表示し、必ずプレビューを行ってから入力内容を
               提出させるためのモジュールです。

Django には、フォームプレビュー (form preview) アプリケーションが付属してい
ます。フォームプレビューは「HTMLフォームを表示し、プレビューを行わせ、フォー
ム提出時に何らかの処理を行う」というワークフローを自動化する上で役立ちます:

ちょっとした Python クラスを書くだけで、プレビューつきのフォームアプリケー
ションを作成できます。

概要
=====

フォームプレビューフレームワークは、 :class:`django.forms.Form` のサブクラ
スを定義するだけで、以下のワークフローを管理できるようにします:

    1. フォームを HTML 形式で Web ページ上に表示します。
    2. フォームデータが POST で提出されると、データを検証します。
       a. データの検証に成功したら、プレビューページを表示します。
       b. 検証に失敗したら、エラーメッセージつきでフォームを再表示します。
    3. プレビューページで「承認 (confirm)」フォームを提出すると、予め定義
       しておいたフックメソッド、
       :meth:`~django.contrib.formtools.FormPreview.done()` を呼出します。
       このフックメソッドには検証済みのデータが渡されます。

フォームプレビューフレームワークは、隠しフィールドを使って、プレビューペー
ジに共有鍵のハッシュ値を渡します。プレビューページのフォームパラメタを変更
してフォームを提出しようとすると、ハッシュ比較テストに失敗します。

``FormPreview`` の使い方
==========================

    1. Django にデフォルトのフォームプレビューテンプレートの場所を設定します:

       * :setting:`INSTALLED_APPS` 設定に ``'django.contrib.formtools'`` を
         追加します。 :setting:`TEMPLATE_LOADERS` 設定に
         ``app_directories`` テンプレートローダを指定 (デフォルトで指定され
         ています) しておく必要もあります。 
	 :ref:`テンプレートローダのドキュメント <template-loaders>` も参照
         してください。

       * ``app_directories`` を使わない場合、 :setting:`TEMPLATE_DIRS` 設定
         に :file:`django/contrib/formtools/templates` の絶対パスを追加して
         ください。

    2. :class:`~django.contrib.formtools.FormPreview` のサブクラスを作成し、
       :meth:`~django.contrib.formtools.FormPreview.done` メソッドをオーバ
       ライドします::

           from django.contrib.formtools.preview import FormPreview
           from myapp.models import SomeModel

           class SomeModelFormPreview(FormPreview):

               def done(self, request, cleaned_data):
                   # cleaned_data を使って何らかの処理を行い、
                   # "success" ページにリダイレクトする
                   return HttpResponseRedirect('/form/success')

       このメソッドは :class:`~django.http.HttpRequest` オブジェクトと、バ
       リデーション・クリーニング済みのフォームデータの入った辞書を引数にと
       ります。メソッドはプレビュー内容を承認した後に遷移する先のページにリ
       ダイレクトする :class:`~django.http.HttpResponseRedirect` を返さねば
       なりません。

    3. URLconf を変更して、 :class:`~django.contrib.formtools.FormPreview`
       サブクラスを import します::

           from myapp.preview import SomeModelFormPreview
           from myapp.forms import SomeModelForm
           from django import forms

       そして、 URLconf に以下の行を追加します。モデルからフォームを生成す
       るなら、以下のようにするとよいでしょう::

           (r'^post/$', SomeModelFormPreview(SomeModelForm)),

       ``SomeModelForm`` はモデルのフォームまたはモデルフォームクラスです。

    4. Django のサーバを実行して、ブラウザで :file:`/post/` にアクセスします。
    
``FormPreview`` クラス
==========================

.. class:: FormPreview

:class:`~django.contrib.formtools.FormPreview` クラスは、プレビューのワーク
フローを表現する単純な Pythonのクラスです。 フォームプレビュークラスを作成
するときには、:class:`django.contrib.formtools.preview.FormPreview` のサブ
クラスを作成して、 :meth:`~django.contrib.formtools.FormPreview.done` メソッ
ドをオーバライドします。フォームプレビュークラスは、コードベースのどこに置
いても構いません。

.. _`FormPreview templates`:

:class:`~django.contrib.formtools.FormPreview` のテンプレート
==============================================================

デフォルトでは、フォームは :file:`formtools/form.html` を使ってレンダされま
す。また、プレビューページのレンダには :file:`formtools/preview.html` を使
います。これらのテンプレートは、
:class:`~django.contrib.formtools.FormPreview` のサブクラスで、それぞれ
:attr:`~django.contrib.formtools.FormPreview.preview_template` および 
:attr:`~django.contrib.formtools.FormPreview.form_template` 属性を設定すれ
ばオーバライドできます。デフォルトのテンプレートの内容は 
"file"`django/contrib/formtools/templates` を参照してください。