Zend Framework に同梱されている標準のフォーム要素Zend Framework には標準でいくつかの具象要素クラスが組み込まれており、 HTML フォーム要素の大半を網羅しています。 そのほとんどは特定のビューヘルパーを指定して要素をデコレートするだけのものですが、 追加機能を提供しているものもあります。 ここでは、標準の要素クラスとその機能についての説明をまとめます。 Zend_Form_Element_ButtonHTML の button 要素を作成する際に使用します。 Zend_Form_Element_Button は Zend_Form_Element_Submit を継承して独自の機能を追加したものです。 'formButton' ビューヘルパーでデコレートを行います。 submit 要素と同様、要素のラベルを表示時の値として使用します。 つまり、ボタンのテキストを設定するにはその要素の value を設定します。 翻訳アダプタが存在するときは、ラベルも翻訳されます。 ラベルも要素の一部なので、button 要素は ViewHelper デコレータと DtDdWrapper デコレータのみを使用します。 Zend_Form_Element_CaptchaCAPTCHAs は、ボットやその他の自動処理プロセスからの自動送信を防ぐための仕組みです。 Captcha フォーム要素は、フォームの captcha でどの Zend_Captcha アダプタ を使用するかを選択できます。 それからこのアダプタをオブジェクトのバリデータとして設定し、 CAPTCHA デコレータを使用してレンダリングを行います (CAPTCHA アダプタへのプロキシとなります)。 アダプタとしては Zend_Captcha の任意のアダプタを使用でき、また別途定義したその他のアダプタも使用できます。 そのためには、プラグインローダのプレフィックスパスを指定する際に 追加のキー 'CAPTCHA' あるいは 'captcha' を指定します。
CAPTCHA を登録するには setCaptcha() メソッドを使用します。ここには、具象インスタンスあるいは CAPTCHA アダプタの短い名前を指定します。
設定経由で要素を読み込みたい場合は、キー 'captcha' の値に配列 (キー 'captcha' を含むもの) を指定するか、 キー 'captcha' と 'captchaOptions' の両方を指定します。
使用するデコレータは、captcha アダプタの設定によって決まります。 デフォルトでは Captcha デコレータ を使用しますが、 getDecorator() メソッドで別のアダプタを指定することもできます。 captcha アダプタそれ自体は、要素のバリデータとして動作することに注意しましょう。 さらに、NotEmpty バリデータは用いず、 その要素は必須指定となります。 ほとんどの場合は、フォームに captcha を表示させるために特に何もする必要はないでしょう。 Zend_Form_Element_CheckboxHTML のチェックボックスは指定した値を返すことができます。 しかし、基本的には boolean として扱います。 チェックされている場合はその値が送信され、 チェックされていない場合はなにも送信されません。 内部的に、Zend_Form_Element_Checkbox はこの状態を強制します。 デフォルトでは、チェックされているときの値は '1' でチェックされていないときの値は '0' です。 使用する値を指定するには、アクセサ setCheckedValue() および setUncheckedValue() をそれぞれ使用します。内部的には、この値を設定すると、 渡された値が checked 値と一致する場合はその値を設定しますが、 それ以外の値が渡された場合は unchecked 値を設定します。 さらに、値を設定するとチェックボックスの checked プロパティも設定されます。 この内容を確認するには、 isChecked() を使用するか、単純にそのプロパティにアクセスします。 setChecked($flag) メソッドを使用すると、 フラグの状態を設定すると同時に checked 値あるいは unchecked 値のいずれか適切なほうを要素の値として設定します。 チェックボックス要素のチェック状態を設定するときには、 このメソッドを使用してプロパティが適切に設定されるようにしましょう。 Zend_Form_Element_Checkbox は 'formCheckbox' ビューヘルパーを使用します。 値としては常に checked 値を使用します。 Zend_Form_Element_FileFile フォーム要素は、ファイルアップロード用のフィールドをフォームに用意します。 Zend_File_Transfer を内部で使用してこの機能を実現しており、 FormFile ビューヘルパーと File デコレータでフォーム要素を表示しています。
デフォルトでは、Http 転送アダプタを使用します。
これは Example #1 File フォーム要素の使用法 上の説明だけでは File フォーム要素を使うのが難しく感じられるかもしれません。 でも、実際に使ってみると比較的簡単なものです。
また、正しいエンコード形式をフォームに指定する必要があります。 'multipart/form-data' を使用しなければなりません。 これは、フォームの 'enctype' 属性で指定します。
フォームの検証が成功したら、 receive() でファイルを受信して最終的な場所に保存しなければなりません。 さらに、最終的な場所を取得するには getFileName() を使用します。
デフォルトでは、フォーム上で getValues() をコールしたときにファイルが自動的に受信されます。 このような挙動となる理由は、ファイルそのものが file 要素の値となるからです。
しかし、ファイルを受信せずに getValues() をコールしたい場合もあるかもしれません。 そのような場合は setValueDisabled(true) をコールします。 このフラグの値を取得するには isValueDisabled() をコールします。 Example #2 明示的なファイルの取得 まずは setValueDisabled(true) をコールします。
これで、 getValues() をコールしてもファイルは取得されなくなります。 したがって、file 要素上で receive() をコールするか、 あるいは Zend_File_Transfer のインスタンスを自分で作成しなければなりません。
アップロードされたファイルの状態については、次のメソッドで調べることができます。
Example #3 オプションのファイルがアップロードされたかどうかの確認
Zend_Form_Element_File は複数のファイルもサポートしています。 setMultiFile($count) メソッドをコールすると、 作成したい file 要素の数を設定できます。 これを使えば、同じ設定を何度も行う手間が省けます。 Example #4 複数のファイルの設定 複数の要素を作成する方法は、単一の要素を作成する場合と同じで、 作成した後にさらに setMultiFile() をコールするだけです。
ビューにおいて、同じ設定のファイルアップロード要素が 3 つ取得できます。 現在設定されている値を取得するには getMultiFile() をコールします。
アップロードされるファイルのサイズを制限するには、 フォームで受け付けるファイルサイズの最大値も設定しなければなりません。 受け付けるサイズをクライアント側で制限するには、form のオプション MAX_FILE_SIZE を設定します。この値を setMaxFileSize($size) メソッドで設定すると、 それが file 要素のレンダリング時に用いられます。
Zend_Form_Element_Hashこの要素は CSRF 攻撃からフォームを保護するものです。 送信されたデータがもとのフォームのユーザセッションからのものである (悪意のあるスクリプトからのものではない) ことを保証できるようにします。 これを実現するために、フォームにハッシュ要素を追加して あとでそのハッシュを検証するようにしています。 ハッシュ要素の名前は一意なものでなければなりません。 この要素ではオプション salt を使うことを推奨します。 名前が同じでも salt が異なればハッシュは衝突しません。
salt は、後から setSalt($salt) メソッドを使って設定することもできます。 内部的には、この要素は一意な ID を Zend_Session_Namespace を用いて保存しており、 送信されたときにその内容 (TTL が期限切れになっていないかどうか) をチェックしています そして、'Identical' バリデータを使用して、 送信されたハッシュと保存されているハッシュを比較します。 'formHidden' ビューヘルパーを使用して要素をフォームにレンダリングします。
|
|