Zend_Form_Element を用いたフォーム要素の作成フォームは、いくつかの要素から構成されています。 これらの要素は、HTML フォームの入力項目に対応します。 Zend_Form_Element は個々のフォーム要素をカプセル化し、 以下の機能を提供します。
基底クラスである Zend_Form_Element は、 ほとんどの場合にうまく利用できるデフォルトを定義しています。 しかし、よく使われる特別な要素については それを継承したクラスを作成するほうがいいでしょう。 さらに、Zend Framework には数多くの標準 XHTML 要素が同梱されています。 標準の要素についての章 を参照ください。 プラグインローダーZend_Form_Element は、Zend_Loader_PluginLoader を使用しており、バリデータやフィルタ、デコレータの場所を指定できます。 それぞれに独自のプラグインローダーが関連付けられており、 アクセサを使用して個別に取得したり変更したりできます。 プラグインローダーのメソッドで使用できるローダーの型は 'validate'、'filter' と 'decorator' です。 この型名は大文字小文字を区別しません。 プラグインローダーを使用するためのメソッドを以下にまとめます。
独自のバリデータやフィルタ、デコレータを作成すると、 複数のフォームで機能を共有したり独自の機能をカプセル化したりすることが簡単になります。 Example #1 独自のラベル プラグインの使用例としてよくあるのは、 既存の標準クラス群のかわりとして使用することです。 たとえば、'Label' デコレータの実装を変更し、 最後に常にコロンを追加するようにしたくなったとしましょう。 そんな場合は、独自の 'Label' デコレータを クラスプレフィックスつきで作成し、 それをプレフィックスパスに追加します。 では、独自の Label デコレータを作ってみましょう。 ここではクラスプレフィックスを "My_Decorator" とします。 このクラスは、"My/Decorator/Label.php" というファイルで定義されることになります。
では、デコレータを探す際にこのプラグインパスを考慮するように 要素に指定してみましょう。
あるいは、フォームレベルでこれを設定してしまうべ、 すべてのデコレータがこのパスを考慮するようになります。
このパスにデコレータを追加すれば 'My/Decorator/' にあるデコレータがまず最初に見つけられることになります。 つまり、'Label' デコレータが必要となる場面ではそのかわりに 'My_Decorator_Label' が使われることになるわけです。 フィルタ
バリデーションの前に、入力の正規化を行えると便利です。
あるいはそれが必要となることもあるでしょう。
たとえば、HTML タグを除去した後の内容を検証したりといった場合です。
あるいは、入力の前後に含まれるスペースを取り除いてから検証を行わないと
StringLength バリデータが正しい判断をできないなどという場合もあります。
これらの操作は
Zend_Filter が行います。
Zend_Form_Element はフィルタチェインをサポートしているので、
複数のフィルタを順に適用できます。
フィルタリングは、バリデーションの際や要素の値を
フィルタをチェインに追加する方法は、次のふたつです。
では、例を見てみましょう。
短い形式の名前とは、通常はフィルタ名からプレフィックスを除いた部分のことです。 デフォルトでは、'Zend_Filter_' を除いた部分を表します。 また、最初の文字は大文字でも小文字でもかまいません。
フィルタリング前の値がほしい場合は
フィルタについての詳細な情報は Zend_Filter のドキュメント を参照ください。 フィルタ関係のメソッドを以下にまとめます。
バリデータセキュリティ界で有名なお言葉 "入力はフィルタリングせよ。 出力はエスケープせよ。" に賛同する人なら、フォームの入力を検証 ("入力のフィルタリング") したくなるでしょう。 Zend_Form では、各要素が個別にバリデータチェインを保持しています。 これは Zend_Validate_* のバリデータでできています。 バリデータをチェインに追加する方法は、次のふたつです。
では、例を見てみましょう。
短い形式の名前とは、通常はバリデータ名からプレフィックスを除いた部分のことです。 デフォルトでは、バリデータ名から 'Zend_Validate_' を除いた部分を表します。 また、最初の文字は大文字でも小文字でもかまいません。
どれかひとつのバリデーションに失敗したときに それ以降のバリデータを実行しないようにさせるには、2 番目のパラメータに TRUE を渡します。
バリデータの名前を指定して追加する場合で
そのバリデータクラスのコンストラクタが引数を受け付ける場合は、
この方式で引数を渡す場合は、コンストラクタで定義されているとおりの順で指定する必要があります。
上の例では、Zend_Validate_StringLenth
クラスのインスタンスを作成する際にパラメータ
複数のバリデータを一度に設定するには
もうすこし詳しくはっきりと書きたい場合は、キー 'validator'、'breakChainOnFailure' そして 'options' を持つ配列を使用することもできます。 この使用法は、設定ファイルを用いてバリデータを設定する場合に便利です。
それが必要か否かにかかわらず、すべての項目がキーを持つことに注意しましょう。 これは、設定ファイルを使用する場合の制限事項となります。 しかし、これにより、その引数がどういう意味なのかをきちんと明示できるようになります。 バリデータのオプションは、正しい順で指定しなければならないことに注意しましょう。
要素を検証するには、その値を
バリデータは、順番どおりに処理されます。 すべてのバリデータが実行されますが、 $breakChainOnFailure が true の場合はどれかひとつのバリデータが検証に失敗した時点で処理を終了します。 バリデータは、適切な順で指定するようにしましょう。 検証に失敗したときは、バリデータチェインから エラーコードとメッセージを取得できます。
(注意: 返されるエラーメッセージは連想配列形式で、 エラーコードとエラーメッセージのペアとなります) バリデータに加えて、ある要素が必須である場合は setRequired($flag) を使用できます。 デフォルトではこのフラグは FALSE です。 In combination with setAllowEmpty($flag) (TRUE by default) and setAutoInsertNotEmptyValidator($flag) (TRUE by default), the behavior of your validator chain can be modified in a number of ways:
バリデータについての詳細な情報は Zend_Validate のドキュメント を参照ください。
検証関係のメソッドを以下にまとめます。
独自のエラーメッセージ時には、要素にアタッチされたバリデータが生成するエラーメッセージではなく 独自のエラーメッセージを指定したくなることもあるでしょう。 さらに、時には自分自身でフォームを無効だとマークしたいこともあるでしょう。 1.6.0 以降、次のメソッドでこの機能を使用できるようになりました。
この方式で設定したすべてのエラーは翻訳されることになります。 さらに、プレースホルダ "%value%" を使用して要素の値を表すこともできます。 エラーメッセージを取得する際に、この部分が現在の要素の値に置き換えられます。 デコレータ多くのウェブ開発者にとって、XHTML のフォームを作成することは悩みの種です。 フォームの要素ひとつひとつに対して ラベルなどのマークアップが必要ですし、 ユーザの使いやすさを考慮して検証エラーメッセージも表示させなければなりません。 要素の数が増えれば増えるほど、この作業量は無視できなくなります。 Zend_Form_Element は、この問題を解決するために "デコレータ" を使用します。デコレータは、 要素にアクセスしてその中身をレンダリングするためのメソッドを持つクラスです。 デコレータの動作原理については、Zend_Form_Decorator のセクションを参照ください。 Zend_Form_Element がデフォルトで使用するデコレータは次のとおりです。
デコレータの実行順序は登録された順によって決まります。 つまり、最初に登録したデコレータから順に実行することになります。 したがって、デコレータを登録するときにはその順番に気をつけなければなりません。 あるいは、placement オプションを明示的に指定して順序を決めることもできます。 例として、デフォルトのデコレータを登録するコードを示します。 最初のコンテンツを作成するのは 'ViewHelper' デコレータで、これはフォーム要素そのものを作成します。 次に 'Errors' デコレータがその要素のエラーメッセージを取得し、 もしエラーが発生していた場合はそれをビューヘルパー 'FormErrors' に渡してレンダリングさせます。 説明が存在する場合は、'Description' デコレータがクラス 'description' の段落を追加します。ここには、そのコンテンツの内容を説明するテキストが書き込まれます。 その次のデコレータである 'HtmlTag' は、要素とエラーと説明文を HTML の <dd> タグで囲みます。最後に、'label' が要素のラベルを取得します。それをビューヘルパー 'FormLabel' に渡し、HTML の <dt> で囲みます。 ラベルの内容は、デフォルトでコンテンツの前に付加されます。 出力結果は、基本的にはこのようになります。
デコレータについての詳細な情報は Zend_Form_Decorator のセクション を参照ください。
デコレータ関連のメソッドを以下にまとめます。
Zend_Form_Element は、
オーバーロードを使用して特定のデコレータをレンダリングすることもできます。
'render' で始まる名前のメソッドを デコレータが存在しない場合は、例外が発生します。 メタデータおよび属性Zend_Form_Element は、 要素の属性やメタデータを処理できます。 基本的な属性には次のようなものがあります。
フォームの要素の中にはメタデータを要するものもあります。たとえば XHTML のフォーム要素では、class や id といった属性を指定することになるでしょう。 これは、次のメソッドで行います。
しかし、たいていの場合はもっとシンプルにオブジェクトのプロパティとしてアクセスすることになるでしょう。 Zend_Form_Element はオーバーロードを使用してこの機能を実現しています。
デフォルトでは、すべての属性がビューヘルパーに渡され、 要素の描画時に使用します。これらの属性は、要素タグの HTML 属性として設定されます。 標準の要素Zend_Form には、標準的な要素が同梱されています。詳細は 標準要素 の章を参照ください。 Zend_Form_Element のメソッドZend_Form_Element には非常にたくさんのメソッドがあります。 以下に、それらのシグネチャを種類別に分けて簡単にまとめました。
設定Zend_Form_Element のコンストラクタには、配列あるいは Zend_Config オブジェクトでオプションを指定できます。 また、 setOptions() や setConfig() で設定を変更することもできます。 一般に、キーの名前は次のようになります。
このルールには、次のような例外があります。
例として、すべての型の設定データを渡すファイルを見てみましょう。
カスタム要素独自の要素を作成するには Zend_Form_Element クラスを継承したクラスを作成します。 独自の要素を作成することになるのは、たとえば次のような場合です。
要素を継承する際に主に使用するメソッドは次の 2 つです。 init() で独自の初期化ロジックをあなたの要素に追加し、 loadDefaultDecorators() でデフォルトのデコレータのリストをあなたの要素に設定します。, たとえば、あなたが作成するフォーム上のテキストボックスでは、すべて StringTrim フィルタが必要で、 かつ正規表現による入力検証を行うことになるとしましょう。 ついでに、表示用に独自のデコレータ 'My_Decorator_TextItem' も使用するものとします。さらに、標準の属性 'size' や 'maxLength'、そして 'class' なども設定します。 このような要素は、次のように定義します。
それから、フォームオブジェクトに対して この要素のプレフィックスパスを登録した上で要素を作成します。
'foo' 要素はこれで My_Element_Text 型となりました。先ほど説明したような機能を持つテキストボックスです。 Zend_Form_Element を継承したクラスでオーバーライドしたくなる その他のメソッドとして、 loadDefaultDecorators() があります。このメソッドは、条件付きで 要素にデフォルトのデコレータセットを読み込みます。 継承したクラスで、このデコレータ群を置き換えることができます。
要素のカスタマイズにはさまざまな方法があります。 Zend_Form_Element の API ドキュメントを熟読し、 どんな機能が使用できるのかを覚えていきましょう。
|
|