Zend_Form によるフォームの作成Zend_Form クラスは、フォームの要素や 表示グループ、そしてサブフォームの集約を行います。 そして、その要素に対して次のような操作を行います。
Zend_Form で作成したフォームが複雑なものになることもありますが、 シンプルなフォームで使用するのがもっともよくある使用例でしょう。 手早いアプリケーション開発 (RAD) やプロトタイピングでの使用に最適です。 もっとも基本的な使用法は、単にフォームオブジェクトを作成するものです。
Zend_Config のインスタンスあるいは配列で設定を渡すことができます。 これを使用すると、オブジェクトの状態を設定したり新しい要素を作成したりできます。
Zend_Form は順次処理が可能です。 各要素や表示グループ、サブフォームごとに処理できます。 処理順は、登録した順番および各項目に設定されている順番となります。 これは、各要素のレンダリングを適切な順で行いたいときに便利です。 Zend_Form は、要素や表示グループのファクトリとして使用できると同時に デコレータで自分自身をレンダリングすることもできます。 プラグインローダーZend_Form では、 Zend_Loader_PluginLoader を使用することで 別の要素やデコレータの位置を指定できます。 それぞれにプラグインローダーを関連づけることができ、 汎用的なアクセサを使用してそれを取得したり変更したりします。 使用できるローダーの型は 'element' と 'decorator' です。さまざまなプラグインローダーメソッドが用意されています。 型の名前は大文字小文字を区別しません。 プラグインローダーで使用できるメソッドは、次のとおりです。
さらに、Zend_Form のインスタンスで作成したすべての要素や表示グループ用のプレフィックスパスを設定するには 次のメソッドを使用します。
独自の要素やデコレータを使用すると、 複数フォーム間で機能を共有したり 独自の機能をカプセル化したりできるようになります。 独自の要素を既存の標準クラスに置き換えて使用する例については、 要素のドキュメントの中の 独自のラベルを作る例 を参照ください。 要素Zend_Form では、フォームに要素を追加したり フォームから要素を削除したりするためのアクセサを提供しています。 これらは要素オブジェクトのインスタンスを受け取ることもできますし、 ファクトリとして要素オブジェクトのインスタンスを作成させることもできます。 要素を追加するもっとも基本的なメソッドが addElement() です。 このメソッドは、 Zend_Form_Element 型 (あるいは Zend_Form_Element を継承したクラス) のオブジェクト あるいは新しい要素を作成するための引数 (要素の型や名前、設定オプション) を受け取ります。 例を示します。
要素をフォームに追加したら、名前を指定してそれを取得できます。 取得するには、 getElement() メソッドを使用するか オブジェクトのプロパティとして要素にアクセスします。 property:
時には、フォームにアタッチせずに要素を作成したいこともあるでしょう (フォームに登録されているさまざまなプラグインパスを使いたいけれど、 そのオブジェクトは後でサブフォームにアタッチしたい場合など)。 そんな場合は createElement() メソッドを使用します。
値の設定と取得フォームの検証をすませたら、通常は値を取得することになるでしょう。 その値を用いてデータベースの更新なりウェブサービスの操作なりといった作業を行います。 すべての要素の値を取得するには getValues() を使用します。 getValue($name) を使用すると、 要素名を指定して特定の要素の値を取得できます。
レンダリング前に、フォームに特定の値を設定したいこともあるでしょう。 これを行うには setDefaults() メソッドあるいは populate() メソッドを使用します。
逆に、値を設定したり検証したりした後でフォームをクリアしたいこともあるでしょう。 これを行うには reset() メソッドを使用します。
グローバルな操作時には、すべての要素に対して何らかの操作を行いたくなることもあります。 ありがちな例としては、すべての要素に対してプラグインのプレフィックスを設定したり デコレータを設定したり、フィルタを設定したりといったものがあります。 以下に例を示します。 Example #1 すべての要素に対するプレフィックスパスの設定 型を指定してすべての要素に対するプレフィックスパスを設定したり、 グローバルプレフィックスを使用したりする例です。
Example #2 すべての要素に対するデコレータの設定 すべての要素に対するデコレータを設定できます。 setElementDecorators() に setDecorators() と同じようなデコレータの配列を渡すと、 各要素にそれまで設定されていたすべてのデコレータを上書きします。 この例では、単純に ViewHelper デコレータと Label デコレータを設定します。
Example #3 いくつかの要素に対するデコレータの設定 設定したい要素、あるいは設定したくない要素を指定することで、 一部の要素にだけデコレータを設定することもできます。 setElementDecorators() の 2 番目の引数に要素名の配列を指定します。 デフォルトでは、ここで指定した要素にのみデコレータが設定されます。 3 番目の引数を渡すこともできます。 これは、設定「したい」要素なのか設定「したくない」 要素なのかを表すフラグとなります。 FALSE を渡すと、指定した 以外の すべての要素にデコレータを設定します。 このメソッドの標準的な使用法と同様、 各要素にそれまで設定されていたすべてのデコレータを上書きします。 次の例は、 ViewHelper デコレータと Label デコレータを 要素 'foo' および 'bar' に対してのみ使用するものです。 一方、この例では、ViewHelper デコレータと Label デコレータを 'foo' と 'bar' 以外の すべての要素に対して使用します。
Example #4 すべての要素に対するフィルタの設定 すべての要素に対して同じフィルタを適用したくなることもよくあります。 たとえば、すべての値を trim() するなどです。 要素を操作するためのメソッド次のメソッドを使用して、要素を操作します。
表示グループ表示グループを使用すると、複数の要素を仮想的にグループ化して 表示させることができます。 フォーム内の各要素に対しては名前を指定してアクセスできますが、 フォームの要素を順次処理したりレンダリングしたりするときは 表示グループは一括して扱われます。 表示グループのもっとも一般的な使用例は、 フィールドセット内の要素をグループ化することです。 表示グループの基底クラスは Zend_Form_DisplayGroup です。 このクラスのインスタンスを直接作成することもできますが、 一般的には Zend_Form の addDisplayGroup() メソッドでインスタンスを作成することになります。 このメソッドの最初の引数には要素名の配列を渡し、 表示グループの名前を 2 番目の引数で指定します。 オプションの 3 番目の引数で、設定の配列や Zend_Config オブジェクトを渡すこともできます。 'username' と 'password' という要素がすでにフォームに登録済みである場合に、 次のコードを使用するとそれらを表示グループ 'login' にまとめることができます。 表示グループにアクセスするには、 getDisplayGroup() メソッドを使用するか あるいは表示グループ名を指定します。
グローバルな操作要素と同様、表示グループに対しても全体に共通の操作があるでしょう。 デコレータを設定したり、デコレータを探すプラグインパスを設定したりといったものです。 Example #5 すべての表示グループに対するデコレータプレフィックスパスの設定 デフォルトでは、表示グループはフォームが使用しているデコレータパスを継承します。 別の場所を探すようにしたい場合は addDisplayGroupPrefixPath() メソッドを使用します。
Example #6 すべての表示グループに対するデコレータの設定 すべての表示グループに対するデコレータを設定できます。 setDisplayGroupDecorators() に setDecorators() と同じようなデコレータの配列を渡すと、 各表示グループにそれまで設定されていたすべてのデコレータを上書きします。 この例では、単純に fieldset デコレータ (FormElements デコレータは、要素を順次処理するために必須です) を設定します。
独自の表示グループクラスの使用デフォルトでは、Zend_Form は 表示グループ用に Zend_Form_DisplayGroup クラスを使用します。 このクラスを継承すれば、独自の機能を持つクラスを作成できます。 addDisplayGroup() には具象インスタンスを渡すことはできませんが、 どのクラスを使用するのかをオプションで指定できます。 このときに使用するキーは 'displayGroupClass' です。 そのクラスがまだ読み込まれていない場合は、Zend_Form は Zend_Loader を使ってクラスを読み込みます。 デフォルトの表示グループクラスを指定し、 そのフォームオブジェクトで作成するすべての表示グループで 同じクラスを使わせることもできます。
これは、設定項目 'defaultDisplayGroupClass' で指定することもできます。 そうすれば、事前にこのクラスが読み込まれて すべての表示グループでこのクラスを使うようになります。 表示グループを操作するためのメソッド次のメソッドを使用して、表示グループを操作します。
Zend_Form_DisplayGroup のメソッドZend_Form_DisplayGroup には次のようなメソッドがあります。 タイプ別にまとめます。
サブフォームサブフォームの役割は、次のようなものです。
サブフォームは Zend_Form のオブジェクトです。一般的には Zend_Form_SubForm のオブジェクトとなります。 後者のクラスには、大きなフォームに含めるのに適したデコレータが含まれています (HTML の form タグをレンダリングせず、要素をグループ化するものです)。 サブフォームをアタッチするには、単にそれを要素に追加して名前を指定するだけです。
サブフォームを取得するには、 getSubForm($name) を使用するかあるいはサブフォームの名前を使用します。
サブフォームは、親フォームの要素のひとつとして順次処理できます。 サブフォーム内の要素は処理できません。 グローバルな操作要素や表示グループと同様、サブフォームに対しても全体に共通の操作があるでしょう。 しかし、表示グループや要素とは異なり、 サブフォームは親フォームのほとんどの機能を継承しています。 グローバルな操作として本当に必要なのは、サブフォーム用のデコレータの設定くらいです。 そんな場合には setSubFormDecorators() メソッドを使用します。次の例では、すべてのサブフォームに対して 単純に fieldset デコレータを設定します (FormElements デコレータは、要素を順次処理するために必須です)。
サブフォームを操作するためのメソッド次のメソッドを使用して、サブフォームを操作します。
メタデータおよび属性フォームで一番大切なのはフォームが含む要素ですが、 フォームにはそれ以外のメタデータも含まれます。たとえばフォームの名前 (この名前は、HTML のマークアップ時に ID として用いられます) やアクション、そしてメソッドなどです。 要素や表示グループ、サブフォームの数も含まれます。 それ以外にも任意のメタデータを含めることができます (通常は、form タグで指定する HTML 属性などをここに含めます)。 フォームの名前を設定したり取得したりするには name アクセサを使用します。
アクション (フォームを送信したときに進む URL) やメソッド (送信する方法。たとえば 'POST' あるいは 'GET') を設定するには、それぞれ action アクセサおよび method アクセサを使用します。
フォームのエンコード形式を設定するには enctype アクセサを使用します。 Zend_Form では 2 つの定数 Zend_Form::ENCTYPE_URLENCODED と Zend_Form::ENCTYPE_MULTIPART を定義しており、 これらはそれぞれ 'application/x-www-form-urlencoded' と 'multipart/form-data' に対応します。 しかし、これ以外にも任意のエンコード形式を指定できます。
Zend_Form は Countable インターフェイスを実装しており、count 関数の引数として使用できます。 任意のメタデータを設定するには attribs アクセサを使用します。 Zend_Form ではオーバーロードを使用して 要素や表示グループそしてサブフォームにアクセスしているので、 これがメタデータにアクセスするための唯一の方法となります。
デコレータフォームのマークアップを作成するのは手間のかかる作業です。 特に、検証エラーの表示や値の送信などの決まりきった処理を何度も行うのは大変なことです。 この問題に対する Zend_Form からの回答が デコレータ です。 Zend_Form オブジェクトのデコレータを使用して、 フォームをレンダリングします。 FormElements デコレータは、フォームのすべての項目 (要素、表示グループ、サブフォーム) を順次処理し、それらをレンダリングした結果を返します。 それ以外のデコレータを使用して、コンテンツをラップしたり 前後に何かを追加したりできます。 Zend_Form のデフォルトのデコレータは、FormElements と HtmlTag (定義リストによるラッピングをします)、そして Form です。 以下のコードと同様です。 これは、次のような出力をします。
フォームオブジェクトに設定した任意の属性は、 HTML の <form> タグの属性となります。
独自のデコレータを使用してフォームを作成することもできます。 一般的な使用例としては、作成したい HTML が厳密に決まっている場合などがあります。 デコレータでそれとまったく同じ HTML を作成し、単純にそれを返せばいいのです。 個々の要素や表示グループに対してもそれぞれデコレータを使用できます。 デコレータ関連のメソッドを以下にまとめます。
Zend_Form は、 オーバーロードを使用して特定のデコレータをレンダリングすることもできます。 'render' で始まる名前のメソッドを __call() で捕捉し、メソッド名の残りの部分にもとづいてデコレータを探します。 見つかった場合は、そのデコレータ だけ をレンダリングします。 引数を渡すと、それがデコレータの render() メソッドにコンテンツとして渡されます。次の例を参照ください。 デコレータが存在しない場合は、例外が発生します。 バリデーションフォームの主な使用法は、送信されたデータを検証することです。 Zend_Form は、フォーム全体あるいはその一部を一度に検証したり、 XmlHttpRequests (AJAX) のレスポンスを自動的に検証したりできます。 送信されたデータが無効な場合は、 要素やサブフォームについて 検証エラーのコードやメッセージを取得するメソッドが用意されています。 フォーム全体のバリデーションを行うには isValid() メソッドを使用します。
isValid() はすべての必須要素の検証を行います。 また非必須要素の中で値が送信された要素についても検証します。 時には一部のデータだけを検証したいこともあるでしょう。そんな場合には isValidPartial($data) を使用します。
isValidPartial() は、 data の項目にマッチする要素についてのみ検証を行います。 マッチする要素がなかった場合は処理をスキップします。 AJAX リクエストの要素や要素グループを検証する際は、 通常はフォームの一部を検証してその結果を JSON で返すことになります。 processAjax() が、まさにその作業を行うメソッドです。
こうすれば、単純に JSON レスポンスをクライアントに返すことができます。 フォームの検証に成功した場合は、この結果は TRUE となります。 失敗した場合は、キーとメッセージのペアを含む javascript オブジェクトを返します。個々の 'message' が検証エラーメッセージの配列となります。 フォームの検証に失敗した場合は、エラーコードとエラーメッセージをそれぞれ getErrors() と getMessages() で取得できます。
個々の要素のコードとエラーメッセージを取得するには、 それぞれのメソッドに要素名を渡します。
独自のエラーメッセージ時には、要素にアタッチされたバリデータが生成するエラーメッセージではなく 独自のエラーメッセージを指定したくなることもあるでしょう。 さらに、時には自分自身でフォームを無効だとマークしたいこともあるでしょう。 次のメソッドでこの機能を使用できます。
この方式で設定したすべてのエラーは翻訳されることになります。 正しい値だけを取得There are scenarios when you want to allow your user to work on a valid form in several steps. Meanwhile you allow the user to save the form with any set of values inbetween. Then if all the data is specified you can transfer the model from the building or prototying stage to a valid stage. You can retrieve all the valid values that match the submitted data by calling:
メソッド以下の一覧は、Zend_Form のメソッドをタイプ別にまとめたものです。
設定Zend_Form は、 setOptions() や setConfig() を用いて (あるいはコンストラクタでオプションや Zend_Config オブジェクトを渡して) さまざまに設定できます。 これらのメソッドを使用して、フォームの要素や表示グループ、デコレータ、 そしてメタデータを設定できます。 全般的なルールとして、もし 'set' + オプションのキー という名前のメソッドが Zend_Form にあった場合は、そのメソッドを使用するとオプションを設定できます。 アクセサが存在しない場合は キーが属性への参照とみなされ、 setAttrib() に渡されます。 このルールには、次のような例外があります。
例として、すべての型の設定データを渡すファイルを見てみましょう。
これは、XML や PHP の配列形式の設定ファイルにも簡単に置き換えることができます。 カスタムフォーム独自の設定のフォームを使用するもうひとつの方法は、 Zend_Form のサブクラスを作成することです。 これには次のような利点があります。
一般的な使用法としては、 init() メソッドでフォーム要素などの設定を行います。
このフォームのインスタンスを作成するのは、次のように簡単です。
そして、すべての機能はすでに準備済みの状態で、 設定ファイルは不要です (この例はかなり単純化していることに注意しましょう。 バリデーションや要素のフィルタなどは省略しています)。 独自のフォームを作成する理由としてもうひとつよくあるのが、 デフォルトのデコレータを定義したいというものです。 この場合は loadDefaultDecorators() メソッドを上書きします。
|
|