documentation/manual/ja/module_specs/Zend_Form-Elements.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <!-- EN-Revision: 21606 -->
   4 <sect1 id="zend.form.elements">
   5     <title>Zend_Form_Element を用いたフォーム要素の作成</title>
   6
   7     <para>
   8         フォームは、いくつかの要素から構成されています。
   9         これらの要素は、HTML フォームの入力項目に対応します。
  10         <classname>Zend_Form_Element</classname> は個々のフォーム要素をカプセル化し、
  11         以下の機能を提供します。
  12     </para>
  13
  14     <itemizedlist>
  15         <listitem>
  16             <para>
  17                 バリデーション (入力されたデータが妥当か?)
  18             </para>
  19
  20             <itemizedlist>
  21                 <listitem><para>検証エラーのコードやメッセージの取得</para></listitem>
  22             </itemizedlist>
  23         </listitem>
  24
  25         <listitem><para>
  26             フィルタリング (出力用のエスケープや検証前後の正規化をどうするか?)
  27         </para></listitem>
  28
  29         <listitem><para>
  30             レンダリング (要素をどのように表示するか?)
  31         </para></listitem>
  32
  33         <listitem><para>
  34             メタデータおよび属性 (その要素についての詳細な情報は?)
  35         </para></listitem>
  36     </itemizedlist>
  37
  38     <para>
  39         基底クラスである <classname>Zend_Form_Element</classname> は、
  40         ほとんどの場合にうまく利用できるデフォルトを定義しています。
  41         しかし、よく使われる特別な要素については
  42         それを継承したクラスを作成するほうがいいでしょう。
  43         さらに、Zend Framework には数多くの標準 <acronym>XHTML</acronym> 要素が同梱されています。
  44         <link linkend="zend.form.standardElements">標準の要素についての章</link>
  45         を参照ください。
  46     </para>
  47
  48     <sect2 id="zend.form.elements.loaders">
  49         <title>プラグインローダー</title>
  50
  51         <para>
  52             <classname>Zend_Form_Element</classname> は、<link
  53                 linkend="zend.loader.pluginloader">Zend_Loader_PluginLoader</link>
  54             を使用しており、バリデータやフィルタ、デコレータの場所を指定できます。
  55             それぞれに独自のプラグインローダーが関連付けられており、
  56             アクセサを使用して個別に取得したり変更したりできます。
  57         </para>
  58
  59         <para>
  60             プラグインローダーのメソッドで使用できるローダーの型は
  61             'validate'、'filter' と 'decorator' です。
  62             この型名は大文字小文字を区別しません。
  63         </para>
  64
  65         <para>
  66             プラグインローダーを使用するためのメソッドを以下にまとめます。
  67         </para>
  68
  69         <itemizedlist>
  70             <listitem><para>
  71                 <code>setPluginLoader($loader, $type)</code>:
  72                 <code>$loader</code> はプラグインローダーオブジェクト、
  73                 <code>$type</code> は上であげた型名のいずれかを指定します。
  74                 これは、指定した型に対応するプラグインローダーを新しく設定します。
  75             </para></listitem>
  76
  77             <listitem><para>
  78                 <code>getPluginLoader($type)</code>:
  79                 <code>$type</code> に対応するプラグインローダーを取得します。
  80             </para></listitem>
  81
  82             <listitem><para>
  83                 <code>addPrefixPath($prefix, $path, $type = null)</code>:
  84                 プレフィックスとパスの関連を、
  85                 <code>$type</code> で指定したローダーに追加します。
  86                 <code>$type</code> が <constant>NULL</constant> の場合は、すべてのローダーにパスを追加します。
  87                 その際には、それぞれプレフィックスに
  88                 "_Validate"、"_Filter" そして "_Decorator" を追加し、
  89                 パスには "Validate/"、"Filter/" そして
  90                 "Decorator/" を追加します。
  91                 追加するフォーム要素クラス群をすべて共通の階層に配置する場合は、
  92                 このメソッドでベースプレフィックスを設定すると便利です。
  93             </para></listitem>
  94
  95             <listitem><para>
  96                 <code>addPrefixPaths(array $spec)</code>:
  97                 複数のパスを、ひとつあるいは複数のプラグインローダーに追加します。
  98                 配列の各要素は、キー 'path'、'prefix' および
  99                 'type' を含む配列とします。
 100             </para></listitem>
 101         </itemizedlist>
 102
 103         <para>
 104             独自のバリデータやフィルタ、デコレータを作成すると、
 105             複数のフォームで機能を共有したり独自の機能をカプセル化したりすることが簡単になります。
 106         </para>
 107
 108         <example id="zend.form.elements.loaders.customLabel">
 109             <title>独自のラベル</title>
 110
 111             <para>
 112                 プラグインの使用例としてよくあるのは、
 113                 既存の標準クラス群のかわりとして使用することです。
 114                 たとえば、'Label' デコレータの実装を変更し、
 115                 最後に常にコロンを追加するようにしたくなったとしましょう。
 116                 そんな場合は、独自の 'Label' デコレータを
 117                 クラスプレフィックスつきで作成し、
 118                 それをプレフィックスパスに追加します。
 119             </para>
 120
 121             <para>
 122                 では、独自の Label デコレータを作ってみましょう。
 123                 ここではクラスプレフィックスを "My_Decorator" とします。
 124                 このクラスは、"My/Decorator/Label.php" というファイルで定義されることになります。
 125             </para>
 126
 127             <programlisting language="php"><![CDATA[
 128 class My_Decorator_Label extends Zend_Form_Decorator_Abstract
 129 {
 130     protected $_placement = 'PREPEND';
 131
 132     public function render($content)
 133     {
 134         if (null === ($element = $this->getElement())) {
 135             return $content;
 136         }
 137         if (!method_exists($element, 'getLabel')) {
 138             return $content;
 139         }
 140
 141         $label = $element->getLabel() . ':';
 142
 143         if (null === ($view = $element->getView())) {
 144             return $this->renderLabel($content, $label);
 145         }
 146
 147         $label = $view->formLabel($element->getName(), $label);
 148
 149         return $this->renderLabel($content, $label);
 150     }
 151
 152     public function renderLabel($content, $label)
 153     {
 154         $placement = $this->getPlacement();
 155         $separator = $this->getSeparator();
 156
 157         switch ($placement) {
 158             case 'APPEND':
 159                 return $content . $separator . $label;
 160             case 'PREPEND':
 161             default:
 162                 return $label . $separator . $content;
 163         }
 164     }
 165 }
 166 ]]></programlisting>
 167
 168             <para>
 169                 では、デコレータを探す際にこのプラグインパスを考慮するように
 170                 要素に指定してみましょう。
 171             </para>
 172
 173             <programlisting language="php"><![CDATA[
 174 $element->addPrefixPath('My_Decorator', 'My/Decorator/', 'decorator');
 175 ]]></programlisting>
 176
 177             <para>
 178                 あるいは、フォームレベルでこれを設定してしまうべ、
 179                 すべてのデコレータがこのパスを考慮するようになります。
 180             </para>
 181
 182             <programlisting language="php"><![CDATA[
 183 $form->addElementPrefixPath('My_Decorator', 'My/Decorator/', 'decorator');
 184 ]]></programlisting>
 185
 186             <para>
 187                 このパスにデコレータを追加すれば
 188                 'My/Decorator/' にあるデコレータがまず最初に見つけられることになります。
 189                 つまり、'Label' デコレータが必要となる場面ではそのかわりに
 190                 'My_Decorator_Label' が使われることになるわけです。
 191             </para>
 192         </example>
 193     </sect2>
 194
 195     <sect2 id="zend.form.elements.filters">
 196         <title>フィルタ</title>
 197
 198         <para>
 199             バリデーションの前に、入力の正規化を行えると便利です。
 200             あるいはそれが必要となることもあるでしょう。
 201             たとえば、HTML タグを除去した後の内容を検証したりといった場合です。
 202             あるいは、入力の前後に含まれるスペースを取り除いてから検証を行わないと
 203             StringLength バリデータが正しい判断をできないなどという場合もあります。
 204             これらの操作は
 205             <classname>Zend_Filter</classname> が行います。
 206             <classname>Zend_Form_Element</classname> はフィルタチェインをサポートしているので、
 207             複数のフィルタを順に適用できます。
 208             フィルタリングは、バリデーションの際や要素の値を <code>getValue()</code>
 209             で取得する際に行われます。
 210         </para>
 211
 212         <programlisting language="php"><![CDATA[
 213 $filtered = $element->getValue();
 214 ]]></programlisting>
 215
 216         <para>
 217             フィルタをチェインに追加する方法は、次のふたつです。
 218         </para>
 219
 220         <itemizedlist>
 221             <listitem><para>
 222                 フィルタのインスタンスを渡す
 223             </para></listitem>
 224
 225             <listitem><para>
 226                 フィルタの名前 (短い名前、あるいは完全なクラス名)
 227                 を渡す
 228             </para></listitem>
 229         </itemizedlist>
 230
 231         <para>
 232             では、例を見てみましょう。
 233         </para>
 234
 235         <programlisting language="php"><![CDATA[
 236 // フィルタのインスタンス
 237 $element->addFilter(new Zend_Filter_Alnum());
 238
 239 // 完全なクラス名
 240 $element->addFilter('Zend_Filter_Alnum');
 241
 242 // 短い形式のフィルタ名
 243 $element->addFilter('Alnum');
 244 $element->addFilter('alnum');
 245 ]]></programlisting>
 246
 247         <para>
 248             短い形式の名前とは、通常はフィルタ名からプレフィックスを除いた部分のことです。
 249             デフォルトでは、'Zend_Filter_' を除いた部分を表します。
 250             また、最初の文字は大文字でも小文字でもかまいません。
 251         </para>
 252
 253         <note>
 254             <title>独自のフィルタクラスの使用</title>
 255
 256             <para>
 257                 自作のフィルタクラスを使う場合は、
 258                 <code>addPrefixPath()</code> を用いてそれを
 259                 <classname>Zend_Form_Element</classname> に教えます。
 260                 たとえば、'My_Filter' プレフィックス配下のフィルタを使う場合は
 261                 <classname>Zend_Form_Element</classname> に次のように通知します。
 262             </para>
 263
 264             <programlisting language="php"><![CDATA[
 265 $element->addPrefixPath('My_Filter', 'My/Filter/', 'filter');
 266 ]]></programlisting>
 267
 268             <para>
 269                 (3 番目の引数が、このアクションを行う際のプラグインローダーであったことを思い出しましょう)
 270             </para>
 271         </note>
 272
 273         <para>
 274             フィルタリング前の値がほしい場合は
 275             <code>getUnfilteredValue()</code> メソッドを使用します。
 276         </para>
 277
 278         <programlisting language="php"><![CDATA[
 279 $unfiltered = $element->getUnfilteredValue();
 280 ]]></programlisting>
 281
 282         <para>
 283             フィルタについての詳細な情報は <link
 284                 linkend="zend.filter.introduction">Zend_Filter
 285                 のドキュメント</link> を参照ください。
 286         </para>
 287
 288         <para>
 289             フィルタ関係のメソッドを以下にまとめます。
 290         </para>
 291
 292         <itemizedlist>
 293             <listitem><para>
 294                 <code>addFilter($nameOfFilter, array $options = null)</code>
 295             </para></listitem>
 296
 297             <listitem><para>
 298                 <code>addFilters(array $filters)</code>
 299             </para></listitem>
 300
 301             <listitem><para>
 302                 <code>setFilters(array $filters)</code> (すべてのフィルタを上書きします)
 303             </para></listitem>
 304
 305             <listitem><para>
 306                 <code>getFilter($name)</code> (指定した名前のフィルタオブジェクトを取得します)
 307             </para></listitem>
 308
 309             <listitem><para>
 310                 <code>getFilters()</code> (すべてのフィルタを取得します)
 311             </para></listitem>
 312
 313             <listitem><para>
 314                 <code>removeFilter($name)</code> (指定した名前のフィルタを削除します)
 315             </para></listitem>
 316
 317             <listitem><para>
 318                 <code>clearFilters()</code> (すべてのフィルタを削除します)
 319             </para></listitem>
 320         </itemizedlist>
 321     </sect2>
 322
 323     <sect2 id="zend.form.elements.validators">
 324         <title>バリデータ</title>
 325
 326         <para>
 327             セキュリティ界で有名なお言葉 "入力はフィルタリングせよ。
 328             出力はエスケープせよ。" に賛同する人なら、フォームの入力を検証
 329             ("入力のフィルタリング") したくなるでしょう。
 330             <classname>Zend_Form</classname> では、各要素が個別にバリデータチェインを保持しています。
 331             これは <classname>Zend_Validate_*</classname> のバリデータでできています。
 332         </para>
 333
 334         <para>
 335             バリデータをチェインに追加する方法は、次のふたつです。
 336         </para>
 337
 338         <itemizedlist>
 339             <listitem><para>
 340                 バリデータのインスタンスを渡す
 341             </para></listitem>
 342
 343             <listitem><para>
 344                 バリデータの名前 (短い名前、あるいは完全なクラス名)
 345                 を渡す
 346             </para></listitem>
 347         </itemizedlist>
 348
 349         <para>
 350             では、例を見てみましょう。
 351         </para>
 352
 353         <programlisting language="php"><![CDATA[
 354 // バリデータのインスタンス
 355 $element->addValidator(new Zend_Validate_Alnum());
 356
 357 // 完全なクラス名
 358 $element->addValidator('Zend_Validate_Alnum');
 359
 360 // 短い形式の名前
 361 $element->addValidator('Alnum');
 362 $element->addValidator('alnum');
 363 ]]></programlisting>
 364
 365         <para>
 366             短い形式の名前とは、通常はバリデータ名からプレフィックスを除いた部分のことです。
 367             デフォルトでは、バリデータ名から 'Zend_Validate_' を除いた部分を表します。
 368             また、最初の文字は大文字でも小文字でもかまいません。
 369         </para>
 370
 371         <note>
 372             <title>独自のバリデータクラスの使用</title>
 373
 374             <para>
 375                 自作のバリデータクラスを使う場合は、
 376                 <code>addPrefixPath()</code> を用いてそれを
 377                 <classname>Zend_Form_Element</classname> に教えます。
 378                 たとえば、'My_Validator' プレフィックス配下のバリデータを使う場合は
 379                 <classname>Zend_Form_Element</classname> に次のように通知します。
 380             </para>
 381
 382             <programlisting language="php"><![CDATA[
 383 $element->addPrefixPath('My_Validator', 'My/Validator/', 'validate');
 384 ]]></programlisting>
 385
 386             <para>
 387                 (3 番目の引数が、このアクションを行う際のプラグインローダーであったことを思い出しましょう)
 388             </para>
 389         </note>
 390
 391         <para>
 392             どれかひとつのバリデーションに失敗したときに
 393             それ以降のバリデータを実行しないようにさせるには、2 番目のパラメータに
 394             <constant>TRUE</constant> を渡します。
 395         </para>
 396
 397         <programlisting language="php"><![CDATA[
 398 $element->addValidator('alnum', true);
 399 ]]></programlisting>
 400
 401         <para>
 402             バリデータの名前を指定して追加する場合で
 403             そのバリデータクラスのコンストラクタが引数を受け付ける場合は、
 404             <code>addValidator()</code> の 3 番目のパラメータに配列形式で指定します。
 405         </para>
 406
 407         <programlisting language="php"><![CDATA[
 408 $element->addValidator('StringLength', false, array(6, 20));
 409 ]]></programlisting>
 410
 411         <para>
 412             この方式で引数を渡す場合は、コンストラクタで定義されているとおりの順で指定する必要があります。
 413             上の例では、<classname>Zend_Validate_StringLenth</classname>
 414             クラスのインスタンスを作成する際にパラメータ
 415             <code>$min</code> と <code>$max</code> を指定しています。
 416         </para>
 417
 418         <programlisting language="php"><![CDATA[
 419 $validator = new Zend_Validate_StringLength(6, 20);
 420 ]]></programlisting>
 421
 422         <note>
 423             <title>独自のバリデートエラーメッセージの指定</title>
 424
 425             <para>
 426                 バリデータのエラーメッセージをカスタマイズしたいこともあるでしょう。
 427                 その場合は、<methodname>Zend_Form_Element::addValidator()</methodname> の引数
 428                 <code>$options</code> で、キー 'messages' にメッセージテンプレートを指定します。
 429                 これは キー/値 のペアの配列となります。
 430                 これを使用するには、そのバリデータのさまざまな検証エラーに対応する
 431                 エラーコードを知っておく必要があります。
 432             </para>
 433
 434             <para>
 435                 もっとよいやりかたは、<classname>Zend_Translate_Adapter</classname>
 436                 をフォームで使用することでしょう。エラーコードは、
 437                 デフォルトのエラーデコレータが自動的にアダプタに渡します。
 438                 そこで、バリデータのエラーコードに対応する翻訳文字列を設定すればいいのです。
 439             </para>
 440         </note>
 441
 442         <para>
 443             複数のバリデータを一度に設定するには
 444             <code>addValidators()</code> を使用します。
 445             このメソッドには、配列の配列を渡します。
 446             各配列の要素は 1 から 3 となり、これが
 447             <code>addValidator()</code> に渡されます。
 448         </para>
 449
 450         <programlisting language="php"><![CDATA[
 451 $element->addValidators(array(
 452     array('NotEmpty', true),
 453     array('alnum'),
 454     array('stringLength', false, array(6, 20)),
 455 ));
 456 ]]></programlisting>
 457
 458         <para>
 459             もうすこし詳しくはっきりと書きたい場合は、キー
 460             'validator'、'breakChainOnFailure' そして 'options'
 461             を持つ配列を使用することもできます。
 462         </para>
 463
 464         <programlisting language="php"><![CDATA[
 465 $element->addValidators(array(
 466     array(
 467         'validator'           => 'NotEmpty',
 468         'breakChainOnFailure' => true),
 469     array('validator' => 'alnum'),
 470     array(
 471         'validator' => 'stringLength',
 472         'options'   => array(6, 20)),
 473 ));
 474 ]]></programlisting>
 475
 476         <para>
 477             この使用法は、設定ファイルを用いてバリデータを設定する場合に便利です。
 478         </para>
 479
 480         <programlisting language="ini"><![CDATA[
 481 element.validators.notempty.validator = "NotEmpty"
 482 element.validators.notempty.breakChainOnFailure = true
 483 element.validators.alnum.validator = "Alnum"
 484 element.validators.strlen.validator = "StringLength"
 485 element.validators.strlen.options.min = 6
 486 element.validators.strlen.options.max = 20
 487 ]]></programlisting>
 488
 489         <para>
 490             それが必要か否かにかかわらず、すべての項目がキーを持つことに注意しましょう。
 491             これは、設定ファイルを使用する場合の制限事項となります。
 492             しかし、これにより、その引数がどういう意味なのかをきちんと明示できるようになります。
 493             バリデータのオプションは、正しい順で指定しなければならないことに注意しましょう。
 494         </para>
 495
 496         <para>
 497             要素を検証するには、その値を
 498             <code>isValid()</code> に渡します。
 499         </para>
 500
 501         <programlisting language="php"><![CDATA[
 502 if ($element->isValid($value)) {
 503     // 有効
 504 } else {
 505     // 無効
 506 }
 507 ]]></programlisting>
 508
 509         <note>
 510             <title>フィルタリング後の値の検証</title>
 511
 512             <para>
 513                 <methodname>Zend_Form_Element::isValid()</methodname> は、
 514                 フィルタチェインを通した後の値を検証します。
 515                 詳細は <link
 516                 linkend="zend.form.elements.filters">フィルタの説明
 517                 </link> を参照ください。
 518             </para>
 519         </note>
 520
 521         <note>
 522             <title>バリデーションコンテキスト</title>
 523
 524             <para>
 525                 <methodname>Zend_Form_Element::isValid()</methodname> は、
 526                 追加の引数 <code>$context</code> をサポートしています。
 527                 <methodname>Zend_Form::isValid()</methodname> は、
 528                 フォームをバリデートする際にデータの配列を
 529                 <code>$context</code> に渡します。一方、
 530                 <methodname>Zend_Form_Element::isValid()</methodname>
 531                 はそれを個々のバリデータに渡します。
 532                 つまり、他の要素に渡された内容を使用するバリデータも作成できるということです。
 533                 たとえば、パスワードの確認用の入力欄を持つ登録フォームを考えてみましょう。
 534                 この場合、「パスワード」欄と「パスワード (確認)」
 535                 欄の内容が一致するかどうかを確認することになります。
 536                 このようなバリデータは、次のように書きます。
 537             </para>
 538
 539             <programlisting language="php"><![CDATA[
 540 class My_Validate_PasswordConfirmation extends Zend_Validate_Abstract
 541 {
 542     const NOT_MATCH = 'notMatch';
 543
 544     protected $_messageTemplates = array(
 545         self::NOT_MATCH => 'パスワード (確認) の内容がパスワードと一致しません'
 546     );
 547
 548     public function isValid($value, $context = null)
 549     {
 550         $value = (string) $value;
 551         $this->_setValue($value);
 552
 553         if (is_array($context)) {
 554             if (isset($context['password_confirm'])
 555                 && ($value == $context['password_confirm']))
 556             {
 557                 return true;
 558             }
 559         } elseif (is_string($context) && ($value == $context)) {
 560             return true;
 561         }
 562
 563         $this->_error(self::NOT_MATCH);
 564         return false;
 565     }
 566 }
 567 ]]></programlisting>
 568         </note>
 569
 570         <para>
 571             バリデータは、順番どおりに処理されます。
 572             すべてのバリデータが実行されますが、
 573             <varname>$breakChainOnFailure</varname> が true
 574             の場合はどれかひとつのバリデータが検証に失敗した時点で処理を終了します。
 575             バリデータは、適切な順で指定するようにしましょう。
 576         </para>
 577
 578         <para>
 579             検証に失敗したときは、バリデータチェインから
 580             エラーコードとメッセージを取得できます。
 581         </para>
 582
 583         <programlisting language="php"><![CDATA[
 584 $errors   = $element->getErrors();
 585 $messages = $element->getMessages();
 586 ]]></programlisting>
 587
 588         <para>
 589             (注意: 返されるエラーメッセージは連想配列形式で、
 590             エラーコードとエラーメッセージのペアとなります)
 591         </para>
 592
 593         <para>
 594             バリデータに加えて、ある要素が必須である場合は
 595             <code>setRequired(true)</code> を使用できます。
 596             デフォルトではこのフラグは <constant>FALSE</constant> です。
 597             この場合は、<code>isValid()</code>
 598             に何も値が渡されなかった場合はバリデーションチェインをスキップします。
 599             この振る舞いを変更するにはいくつかの方法があります。
 600         </para>
 601
 602         <itemizedlist>
 603             <listitem>
 604                 <para>
 605                     デフォルトでは、要素が必須の場合は 'allowEmpty' フラグも
 606                     <constant>TRUE</constant> です。この場合、もし空の値が <code>isValid()</code>
 607                     に渡されるとバリデータはスキップされます。
 608                     このフラグを切り替えるには <code>setAllowEmpty($flag)</code>
 609                     を使用します。フラグを <constant>FALSE</constant> にすると、
 610                     値が空の場合でもバリデータが実行されるようになります。
 611                 </para>
 612             </listitem>
 613
 614             <listitem>
 615                 <para>
 616                     デフォルトで、もし要素が必須で 'NotEmpty'
 617                     バリデータが含まれていない場合は、<code>isValid()</code> は
 618                     スタックの最上位にこのバリデータを追加します。そして
 619                     <varname>$breakChainOnFailure</varname> フラグを設定します。
 620                     これにより、必須フラグがその意味どおりに動作するようになります。
 621                     入力が渡されなかった場合は検証がその時点で失敗し、
 622                     結果をユーザに返します。それ以降のバリデータは実行されません。
 623                     値が空である時点で無効な内容であることが確定しているからです。
 624                 </para>
 625
 626                 <para>
 627                     この振る舞いが気に入らない場合は、
 628                     <code>setAutoInsertNotEmptyValidator($flag)</code>
 629                     に <constant>FALSE</constant> を渡せばこの機能を無効にできます。
 630                     この場合、 <code>isValid()</code>
 631                     がバリデータチェインに勝手に
 632                     'NotEmpty' バリデータを追加することはなくなります。
 633                 </para>
 634             </listitem>
 635         </itemizedlist>
 636
 637         <para>
 638             バリデータについての詳細な情報は <link
 639                 linkend="zend.validate.introduction">Zend_Validate
 640                 のドキュメント</link> を参照ください。
 641         </para>
 642
 643         <note>
 644             <title>Zend_Form_Elements の汎用バリデータとしての使用法</title>
 645
 646             <para>
 647                 <classname>Zend_Form_Element</classname> は
 648                 <classname>Zend_Validate_Interface</classname> を実装しています。
 649                 つまり、フォーム以外のバリデータチェインでも
 650                 フォーム要素を使用できるということです。
 651             </para>
 652         </note>
 653
 654         <!-- TODO : to be translated -->
 655         <note>
 656             <title>When is an element detected as empty?</title>
 657
 658             <para>
 659                 As mentioned the 'NotEmpty' validator is used to detect if an element is empty
 660                 or not. But <classname>Zend_Validate_NotEmpty</classname> does, per default, not
 661                 work like <acronym>PHP</acronym>'s method <methodname>empty()</methodname>.
 662             </para>
 663
 664             <para>
 665                 This means when an element contains an integer <emphasis>0</emphasis> or an string
 666                 <emphasis>'0'</emphasis> then the element will be seen as not empty. If you want to
 667                 have a different behaviour you must create your own instance of
 668                 <classname>Zend_Validate_NotEmpty</classname>. There you can define the behaviour of
 669                 this validator. See <ulink
 670                     url="zend.validate.set.notempty">Zend_Validate_NotEmpty</ulink> for details.
 671             </para>
 672         </note>
 673
 674         <para>
 675             検証関係のメソッドを以下にまとめます。
 676         </para>
 677
 678         <itemizedlist>
 679             <listitem><para>
 680                     <code>setRequired($flag)</code> および
 681                     <code>isRequired()</code> は、'required' フラグの状態を設定あるいは取得します。
 682                     これを <constant>TRUE</constant> に設定すると、
 683                     <classname>Zend_Form</classname> が処理したデータにその要素が必須であるものとします。
 684             </para></listitem>
 685
 686             <listitem><para>
 687                     <code>setAllowEmpty($flag)</code> および
 688                     <code>getAllowEmpty()</code> は、オプション要素
 689                     (required フラグが <constant>FALSE</constant> に設定されている要素)
 690                     の挙動を変更します。'allow empty' フラグが <constant>TRUE</constant> の場合、
 691                     値が未入力のときはバリデータチェインに渡しません。
 692             </para></listitem>
 693
 694             <listitem><para>
 695                     <code>setAutoInsertNotEmptyValidator($flag)</code> は、
 696                     その要素が必須項目であるときに
 697                     'NotEmpty' バリデータをバリデータチェインの先頭に追加するかどうかを指定します。
 698                     デフォルトでは、このフラグは <constant>TRUE</constant> です。
 699             </para></listitem>
 700
 701             <listitem><para>
 702                 <methodname>addValidator($nameOrValidator, $breakChainOnFailure = false, array $options = null)</methodname>
 703             </para></listitem>
 704
 705             <listitem><para>
 706                 <methodname>addValidators(array $validators)</methodname>
 707             </para></listitem>
 708
 709             <listitem><para>
 710                 <methodname>setValidators(array $validators)</methodname> (すべてのバリデータを上書きします)
 711             </para></listitem>
 712
 713             <listitem><para>
 714                 <methodname>getValidator($name)</methodname> (指定した名前のバリデータオブジェクトを取得します)
 715             </para></listitem>
 716
 717             <listitem><para>
 718                 <methodname>getValidators()</methodname> (すべてのバリデータを取得します)
 719             </para></listitem>
 720
 721             <listitem><para>
 722                 <methodname>removeValidator($name)</methodname> (指定した名前のバリデータを削除します)
 723             </para></listitem>
 724
 725             <listitem><para>
 726                 <methodname>clearValidators()</methodname> (すべてのバリデータを削除します)
 727             </para></listitem>
 728         </itemizedlist>
 729
 730         <sect3 id="zend.form.elements.validators.errors">
 731             <title>独自のエラーメッセージ</title>
 732
 733             <para>
 734                 時には、要素にアタッチされたバリデータが生成するエラーメッセージではなく
 735                 独自のエラーメッセージを指定したくなることもあるでしょう。
 736                 さらに、時には自分自身でフォームを無効だとマークしたいこともあるでしょう。
 737                 1.6.0 以降、次のメソッドでこの機能を使用できるようになりました。
 738             </para>
 739
 740             <itemizedlist>
 741                 <listitem><para>
 742                     <code>addErrorMessage($message)</code>:
 743                     フォームの検証エラーの際に表示するエラーメッセージを追加します。
 744                     複数回コールすると、新しいメッセージはスタックに追加されます。
 745                 </para></listitem>
 746
 747                 <listitem><para>
 748                     <code>addErrorMessages(array $messages)</code>:
 749                     フォームの検証エラーの際に表示する複数のエラーメッセージを追加します。
 750                 </para></listitem>
 751
 752                 <listitem><para>
 753                     <code>setErrorMessages(array $messages)</code>:
 754                     フォームの検証エラーの際に表示する複数のエラーメッセージを追加します。
 755                     それまでに設定されていたすべてのメッセージを上書きします。
 756                 </para></listitem>
 757
 758                 <listitem><para>
 759                     <code>getErrorMessages()</code>:
 760                     定義済みのカスタムエラーメッセージの一覧を取得します。
 761                 </para></listitem>
 762
 763                 <listitem><para>
 764                     <code>clearErrorMessages()</code>:
 765                     定義済みのカスタムエラーメッセージをすべて削除します。
 766                 </para></listitem>
 767
 768                 <listitem><para>
 769                     <code>markAsError()</code>:
 770                     検証に失敗したものとしてフォームにマークします。
 771                 </para></listitem>
 772
 773                 <listitem><para>
 774                     <code>hasErrors()</code>:
 775                     要素が、検証失敗か無効とマークのいずれかの状態になっているかどうかを取得します。
 776                 </para></listitem>
 777
 778                 <listitem><para>
 779                     <code>addError($message)</code>: add a message to the custom
 780                     エラーメッセージをカスタムエラーメッセージスタックに追加し、
 781                     要素を無効とマークします。
 782                 </para></listitem>
 783
 784                 <listitem><para>
 785                     <code>addErrors(array $messages)</code>:
 786                     複数のエラーメッセージをカスタムエラーメッセージスタックに追加し、
 787                     要素を無効とマークします。
 788                 </para></listitem>
 789
 790                 <listitem><para>
 791                     <code>setErrors(array $messages)</code>:
 792                     指定したメッセージでカスタムエラーメッセージスタックを上書きし、
 793                     要素を無効とマークします。
 794                 </para></listitem>
 795             </itemizedlist>
 796
 797             <para>
 798                 この方式で設定したすべてのエラーは翻訳されることになります。
 799                 さらに、プレースホルダ "%value%" を使用して要素の値を表すこともできます。
 800                 エラーメッセージを取得する際に、この部分が現在の要素の値に置き換えられます。
 801             </para>
 802         </sect3>
 803     </sect2>
 804
 805     <sect2 id="zend.form.elements.decorators">
 806         <title>デコレータ</title>
 807
 808         <para>
 809             多くのウェブ開発者にとって、<acronym>XHTML</acronym>
 810             のフォームを作成することは悩みの種です。
 811             フォームの要素ひとつひとつに対して
 812             ラベルなどのマークアップが必要ですし、
 813             ユーザの使いやすさを考慮して検証エラーメッセージも表示させなければなりません。
 814             要素の数が増えれば増えるほど、この作業量は無視できなくなります。
 815         </para>
 816
 817         <para>
 818             <classname>Zend_Form_Element</classname> は、この問題を解決するために
 819             "デコレータ" を使用します。デコレータは、
 820             要素にアクセスしてその中身をレンダリングするためのメソッドを持つクラスです。
 821             デコレータの動作原理については、<link
 822                 linkend="zend.form.decorators">Zend_Form_Decorator</link>
 823             のセクションを参照ください。
 824         </para>
 825
 826         <para>
 827             <classname>Zend_Form_Element</classname> がデフォルトで使用するデコレータは次のとおりです。
 828         </para>
 829
 830         <itemizedlist>
 831             <listitem><para>
 832                 <emphasis>ViewHelper</emphasis>: 要素のレンダリング用のビューヘルパーを指定します。
 833                 要素の 'helper' 属性を使用して、どのヘルパーを使用するのかを指定します。
 834                 デフォルトで <classname>Zend_Form_Element</classname> は
 835                 'formText' ビューヘルパーを使用しますが、
 836                 サブクラスで別のヘルパーを指定することもできます。
 837             </para></listitem>
 838
 839             <listitem><para>
 840                 <emphasis>Errors</emphasis>:
 841                 <classname>Zend_View_Helper_FormErrors</classname>
 842                 を用いて要素の後にエラーメッセージを追加します。
 843                 エラーが発生していない場合は何も行いません。
 844             </para></listitem>
 845
 846             <listitem><para>
 847                 <emphasis>Description</emphasis>: 要素の後に説明を追加します。
 848                 説明が存在しない場合は何も追加されません。デフォルトでは、
 849                 クラス 'description' を指定した &lt;p&gt; タグでレンダリングされます。
 850             </para></listitem>
 851
 852             <listitem><para>
 853                 <emphasis>HtmlTag</emphasis>:
 854                 ラベルや要素、そしてエラーメッセージを HTML の
 855                 &lt;dd&gt; タグで囲みます。
 856             </para></listitem>
 857
 858             <listitem><para>
 859                 <emphasis>Label</emphasis>:
 860                 <classname>Zend_View_Helper_FormLabel</classname>
 861                 を用いて要素の前にラベルを追加し、それを
 862                 &lt;dt&gt; タグで囲みます。
 863                 ラベルが存在しない場合は、用語定義タグのみをレンダリングします。
 864             </para></listitem>
 865         </itemizedlist>
 866
 867         <note>
 868             <title>読み込み不要なデフォルトのデコレータ</title>
 869
 870             <para>
 871                 デフォルトのデコレータは、
 872                 オブジェクトの初期化時に読み込まれるようになっています。
 873                 この機能を無効にするには、コンストラクタでオプション
 874                 'disableLoadDefaultDecorators' を指定します。
 875             </para>
 876
 877             <programlisting language="php"><![CDATA[
 878 $element = new Zend_Form_Element('foo',
 879                                  array('disableLoadDefaultDecorators' =>
 880                                       true)
 881                                 );
 882 ]]></programlisting>
 883
 884             <para>
 885                 このオプションは、他のオプションと混用することもできます。
 886                 その場合はオプションの配列や <classname>Zend_Config</classname>
 887                 オブジェクトを使用します。
 888             </para>
 889         </note>
 890
 891         <para>
 892             デコレータの実行順序は登録された順によって決まります。
 893             つまり、最初に登録したデコレータから順に実行することになります。
 894             したがって、デコレータを登録するときにはその順番に気をつけなければなりません。
 895             あるいは、placement オプションを明示的に指定して順序を決めることもできます。
 896             例として、デフォルトのデコレータを登録するコードを示します。
 897         </para>
 898
 899         <programlisting language="php"><![CDATA[
 900 $this->addDecorators(array(
 901     array('ViewHelper'),
 902     array('Errors'),
 903     array('Description', array('tag' => 'p', 'class' => 'description')),
 904     array('HtmlTag', array('tag' => 'dd')),
 905     array('Label', array('tag' => 'dt')),
 906 ));
 907 ]]></programlisting>
 908
 909         <para>
 910             最初のコンテンツを作成するのは 'ViewHelper'
 911             デコレータで、これはフォーム要素そのものを作成します。
 912             次に 'Errors' デコレータがその要素のエラーメッセージを取得し、
 913             もしエラーが発生していた場合はそれをビューヘルパー
 914             'FormErrors' に渡してレンダリングさせます。
 915             説明が存在する場合は、'Description' デコレータがクラス 'description'
 916             の段落を追加します。ここには、そのコンテンツの内容を説明するテキストが書き込まれます。
 917             その次のデコレータである 'HtmlTag' は、要素とエラーと説明文を
 918             HTML の &lt;dd&gt; タグで囲みます。最後に、'label'
 919             が要素のラベルを取得します。それをビューヘルパー 'FormLabel'
 920             に渡し、HTML の &lt;dt&gt; で囲みます。
 921             ラベルの内容は、デフォルトでコンテンツの前に付加されます。
 922             出力結果は、基本的にはこのようになります。
 923         </para>
 924
 925         <programlisting language="html"><![CDATA[
 926 <dt><label for="foo" class="optional">Foo</label></dt>
 927 <dd>
 928     <input type="text" name="foo" id="foo" value="123" />
 929     <ul class="errors">
 930         <li>"123" is not an alphanumeric value</li>
 931     </ul>
 932     <p class="description">
 933         This is some descriptive text regarding the element.
 934     </p>
 935 </dd>
 936 ]]></programlisting>
 937
 938         <para>
 939             デコレータについての詳細な情報は <link
 940                 linkend="zend.form.decorators">Zend_Form_Decorator
 941                 のセクション</link> を参照ください。
 942         </para>
 943
 944         <note>
 945             <title>同じ型の複数のデコレータの使用法</title>
 946
 947             <para>
 948                 内部的には、<classname>Zend_Form_Element</classname>
 949                 はデコレータのクラス名をもとにしてデコレータを取得しています。
 950                 つまり、同じ型のデコレータを複数登録することはできないということです。
 951                 複数回登録すると、それまでに登録されていたデコレータを上書きします。
 952             </para>
 953
 954             <para>
 955                 これを回避するには、<emphasis>エイリアス</emphasis> を使用します。
 956                 デコレータやデコレータ名を <code>addDecorator()</code>
 957                 の最初の引数として渡すのではなく、ひとつの要素からなる配列を渡します。
 958                 この配列には、デコレータオブジェクトあるいはデコレータ名を指すエイリアスを指定します。
 959             </para>
 960
 961             <programlisting language="php"><![CDATA[
 962 // 'FooBar' へのエイリアス
 963 $element->addDecorator(array('FooBar' => 'HtmlTag'),
 964                        array('tag' => 'div'));
 965
 966 // 後で、このように取得できます
 967 $decorator = $element->getDecorator('FooBar');
 968 ]]></programlisting>
 969
 970             <para>
 971                 <code>addDecorators()</code> メソッドおよび
 972                 <code>setDecorators()</code> メソッドでは、
 973                 デコレータを表す配列を 'decorator' オプションに渡す必要があります。
 974             </para>
 975
 976             <programlisting language="php"><![CDATA[
 977 // ふたつの 'HtmlTag' デコレータを使用するため、片方に 'FooBar' というエイリアスを指定します
 978 $element->addDecorators(
 979     array('HtmlTag', array('tag' => 'div')),
 980     array(
 981         'decorator' => array('FooBar' => 'HtmlTag'),
 982         'options' => array('tag' => 'dd')
 983     ),
 984 );
 985
 986 // 後で、このように取得できます
 987 $htmlTag = $element->getDecorator('HtmlTag');
 988 $fooBar  = $element->getDecorator('FooBar');
 989 ]]></programlisting>
 990         </note>
 991
 992         <para>
 993             デコレータ関連のメソッドを以下にまとめます。
 994         </para>
 995
 996         <itemizedlist>
 997             <listitem><para>
 998                 <code>addDecorator($nameOrDecorator, array $options = null)</code>
 999             </para></listitem>
1000
1001             <listitem><para>
1002                 <code>addDecorators(array $decorators)</code>
1003             </para></listitem>
1004
1005             <listitem><para>
1006                 <code>setDecorators(array $decorators)</code> (すべてのデコレータを上書きします)
1007             </para></listitem>
1008
1009             <listitem><para>
1010                 <code>getDecorator($name)</code> (指定した名前のデコレータオブジェクトを取得します)
1011             </para></listitem>
1012
1013             <listitem><para>
1014                 <code>getDecorators()</code> (すべてのデコレータを取得します)
1015             </para></listitem>
1016
1017             <listitem><para>
1018                 <code>removeDecorator($name)</code> (指定した名前のデコレータを削除します)
1019             </para></listitem>
1020
1021             <listitem><para>
1022                 <code>clearDecorators()</code> (すべてのデコレータを削除します)
1023             </para></listitem>
1024         </itemizedlist>
1025
1026         <para>
1027             <classname>Zend_Form_Element</classname> は、
1028             オーバーロードを使用して特定のデコレータをレンダリングすることもできます。
1029             'render' で始まる名前のメソッドを <code>__call()</code>
1030             で捕捉し、メソッド名の残りの部分にもとづいてデコレータを探します。
1031             見つかった場合は、そのデコレータ
1032             <emphasis>だけ</emphasis> をレンダリングします。
1033             引数を渡すと、それがデコレータの
1034             <code>render()</code> メソッドにコンテンツとして渡されます。次の例を参照ください。
1035         </para>
1036
1037         <programlisting language="php"><![CDATA[
1038 // ViewHelper デコレータのみをレンダリングします
1039 echo $element->renderViewHelper();
1040
1041 // HtmlTag デコレータにコンテンツを渡してレンダリングします
1042 echo $element->renderHtmlTag("This is the html tag content");
1043 ]]></programlisting>
1044
1045         <para>
1046             デコレータが存在しない場合は、例外が発生します。
1047         </para>
1048     </sect2>
1049
1050     <sect2 id="zend.form.elements.metadata">
1051         <title>メタデータおよび属性</title>
1052
1053         <para>
1054             <classname>Zend_Form_Element</classname> は、
1055             要素の属性やメタデータを処理できます。
1056             基本的な属性には次のようなものがあります。
1057         </para>
1058
1059         <itemizedlist>
1060             <listitem><para>
1061                 <emphasis>name</emphasis>:
1062                 要素名。
1063                 <code>setName()</code> および <code>getName()</code>
1064                 でアクセスします。
1065             </para></listitem>
1066
1067             <listitem><para>
1068                 <emphasis>label</emphasis>:
1069                 要素のラベル。
1070                 <code>setLabel()</code> および <code>getLabel()</code>
1071                 でアクセスします。
1072             </para></listitem>
1073
1074             <listitem><para>
1075                 <emphasis>order</emphasis>:
1076                 要素がフォーム内で登場する際のインデックス。
1077                 <code>setOrder()</code> および
1078                 <code>getOrder()</code> でアクセスします。
1079             </para></listitem>
1080
1081             <listitem><para>
1082                 <emphasis>value</emphasis>:
1083                 現在の要素の値。
1084                 <code>setValue()</code> および <code>getValue()</code>
1085                 でアクセスします。
1086             </para></listitem>
1087
1088             <listitem><para>
1089                 <emphasis>description</emphasis>: 要素の説明。
1090                 ツールチップや javascript のコンテキストヒントで用いられるもので、
1091                 その要素の使用目的などを説明します。
1092                 <code>setDescription()</code> および <code>getDescription()</code>
1093                 でアクセスします。
1094             </para></listitem>
1095
1096             <listitem><para>
1097                 <emphasis>required</emphasis>:
1098                 バリデーション時にその要素を必須とみなすかどうか。
1099                 <code>setRequired()</code> および <code>getRequired()</code>
1100                 でアクセスします。このフラグはデフォルトでは <constant>FALSE</constant> です。
1101             </para></listitem>
1102
1103             <listitem><para>
1104                 <emphasis>allowEmpty</emphasis>:
1105                 必須でない (オプションの) 要素が未入力のときに検証を行うかどうか。
1106                 このフラグが <constant>TRUE</constant> で required フラグが <constant>FALSE</constant> の場合は、
1107                 値が未入力ならバリデータチェインにその要素を渡さず、
1108                 検証に成功したものとみなします。
1109                 <code>setAllowEmpty()</code> および <code>getAllowEmpty()</code>
1110                 でアクセスします。このフラグはデフォルトでは <constant>TRUE</constant> です。
1111             </para></listitem>
1112
1113             <listitem><para>
1114                 <emphasis>autoInsertNotEmptyValidator</emphasis>:
1115                 要素が必須であるときに 'NotEmpty' バリデータを追加するかどうかを表すフラグ。
1116                 デフォルトではこのフラグは <constant>TRUE</constant> です。フラグを設定するには
1117                 <code>setAutoInsertNotEmptyValidator($flag)</code>、
1118                 値を調べるには <code>autoInsertNotEmptyValidator()</code> を使用します。
1119             </para></listitem>
1120         </itemizedlist>
1121
1122         <para>
1123             フォームの要素の中にはメタデータを要するものもあります。たとえば
1124             <acronym>XHTML</acronym> のフォーム要素では、class や id といった属性を指定することになるでしょう。
1125             これは、次のメソッドで行います。
1126         </para>
1127
1128         <itemizedlist>
1129             <listitem><para>
1130                 <emphasis>setAttrib($name, $value)</emphasis>: 属性を追加します。
1131             </para></listitem>
1132
1133             <listitem><para>
1134                 <emphasis>setAttribs(array $attribs)</emphasis>:
1135                 addAttribs() と似ていますが、すべて上書きします。
1136             </para></listitem>
1137
1138             <listitem><para>
1139                 <emphasis>getAttrib($name)</emphasis>:
1140                 特定の属性の値を取得します。
1141             </para></listitem>
1142
1143             <listitem><para>
1144                 <emphasis>getAttribs()</emphasis>:
1145                 すべての属性を キー/値 のペアで取得します。
1146             </para></listitem>
1147         </itemizedlist>
1148
1149         <para>
1150             しかし、たいていの場合はもっとシンプルにオブジェクトのプロパティとしてアクセスすることになるでしょう。
1151             <classname>Zend_Form_Element</classname> はオーバーロードを使用してこの機能を実現しています。
1152         </para>
1153
1154         <programlisting language="php"><![CDATA[
1155 // $element->setAttrib('class', 'text') と同じ意味です
1156 $element->class = 'text;
1157 ]]></programlisting>
1158
1159         <para>
1160             デフォルトでは、すべての属性がビューヘルパーに渡され、
1161             要素の描画時に使用します。これらの属性は、要素タグの
1162             HTML 属性として設定されます。
1163         </para>
1164     </sect2>
1165
1166     <sect2 id="zend.form.elements.standard">
1167         <title>標準の要素</title>
1168
1169         <para>
1170             <classname>Zend_Form</classname> には、標準的な要素が同梱されています。詳細は
1171             <link linkend="zend.form.standardElements">標準要素</link>
1172             の章を参照ください。
1173         </para>
1174     </sect2>
1175
1176     <sect2 id="zend.form.elements.methods">
1177         <title>Zend_Form_Element のメソッド</title>
1178
1179         <para>
1180             <classname>Zend_Form_Element</classname> には非常にたくさんのメソッドがあります。
1181             以下に、それらのシグネチャを種類別に分けて簡単にまとめました。
1182         </para>
1183
1184         <itemizedlist>
1185             <listitem><para>設定</para>
1186                 <itemizedlist>
1187                     <listitem><para><methodname>setOptions(array $options)</methodname></para></listitem>
1188                     <listitem><para><methodname>setConfig(Zend_Config $config)</methodname></para></listitem>
1189                 </itemizedlist>
1190             </listitem>
1191
1192             <listitem><para>I18n</para>
1193                 <itemizedlist>
1194                     <listitem><para><methodname>setTranslator(Zend_Translate_Adapter $translator = null)</methodname></para></listitem>
1195                     <listitem><para><methodname>getTranslator()</methodname></para></listitem>
1196                     <listitem><para><methodname>setDisableTranslator($flag)</methodname></para></listitem>
1197                     <listitem><para><methodname>translatorIsDisabled()</methodname></para></listitem>
1198                 </itemizedlist>
1199             </listitem>
1200
1201             <listitem><para>プロパティ</para>
1202                 <itemizedlist>
1203                     <listitem><para><methodname>setName($name)</methodname></para></listitem>
1204                     <listitem><para><methodname>getName()</methodname></para></listitem>
1205                     <listitem><para><methodname>setValue($value)</methodname></para></listitem>
1206                     <listitem><para><methodname>getValue()</methodname></para></listitem>
1207                     <listitem><para><methodname>getUnfilteredValue()</methodname></para></listitem>
1208                     <listitem><para><methodname>setLabel($label)</methodname></para></listitem>
1209                     <listitem><para><methodname>getLabel()</methodname></para></listitem>
1210                     <listitem><para><methodname>setDescription($description)</methodname></para></listitem>
1211                     <listitem><para><methodname>getDescription()</methodname></para></listitem>
1212                     <listitem><para><methodname>setOrder($order)</methodname></para></listitem>
1213                     <listitem><para><methodname>getOrder()</methodname></para></listitem>
1214                     <listitem><para><methodname>setRequired($flag)</methodname></para></listitem>
1215                     <listitem><para><methodname>getRequired()</methodname></para></listitem>
1216                     <listitem><para><methodname>setAllowEmpty($flag)</methodname></para></listitem>
1217                     <listitem><para><methodname>getAllowEmpty()</methodname></para></listitem>
1218                     <listitem><para><methodname>setAutoInsertNotEmptyValidator($flag)</methodname></para></listitem>
1219                     <listitem><para><methodname>autoInsertNotEmptyValidator()</methodname></para></listitem>
1220                     <listitem><para><methodname>setIgnore($flag)</methodname></para></listitem>
1221                     <listitem><para><methodname>getIgnore()</methodname></para></listitem>
1222                     <listitem><para><methodname>getType()</methodname></para></listitem>
1223                     <listitem><para><methodname>setAttrib($name, $value)</methodname></para></listitem>
1224                     <listitem><para><methodname>setAttribs(array $attribs)</methodname></para></listitem>
1225                     <listitem><para><methodname>getAttrib($name)</methodname></para></listitem>
1226                     <listitem><para><methodname>getAttribs()</methodname></para></listitem>
1227                 </itemizedlist>
1228             </listitem>
1229
1230             <listitem><para>プラグインローダーとパス</para>
1231                 <itemizedlist>
1232                     <listitem><para><methodname>setPluginLoader(Zend_Loader_PluginLoader_Interface $loader, $type)</methodname></para></listitem>
1233                     <listitem><para><methodname>getPluginLoader($type)</methodname></para></listitem>
1234                     <listitem><para><methodname>addPrefixPath($prefix, $path, $type = null)</methodname></para></listitem>
1235                     <listitem><para><methodname>addPrefixPaths(array $spec)</methodname></para></listitem>
1236                 </itemizedlist>
1237             </listitem>
1238
1239             <listitem><para>検証</para>
1240                 <itemizedlist>
1241                     <listitem><para><methodname>addValidator($validator, $breakChainOnFailure = false, $options = array())</methodname></para></listitem>
1242                     <listitem><para><methodname>addValidators(array $validators)</methodname></para></listitem>
1243                     <listitem><para><methodname>setValidators(array $validators)</methodname></para></listitem>
1244                     <listitem><para><methodname>getValidator($name)</methodname></para></listitem>
1245                     <listitem><para><methodname>getValidators()</methodname></para></listitem>
1246                     <listitem><para><methodname>removeValidator($name)</methodname></para></listitem>
1247                     <listitem><para><methodname>clearValidators()</methodname></para></listitem>
1248                     <listitem><para><methodname>isValid($value, $context = null)</methodname></para></listitem>
1249                     <listitem><para><methodname>getErrors()</methodname></para></listitem>
1250                     <listitem><para><methodname>getMessages()</methodname></para></listitem>
1251                 </itemizedlist>
1252             </listitem>
1253
1254             <listitem><para>フィルタ</para>
1255                 <itemizedlist>
1256                     <listitem><para><methodname>addFilter($filter, $options = array())</methodname></para></listitem>
1257                     <listitem><para><methodname>addFilters(array $filters)</methodname></para></listitem>
1258                     <listitem><para><methodname>setFilters(array $filters)</methodname></para></listitem>
1259                     <listitem><para><methodname>getFilter($name)</methodname></para></listitem>
1260                     <listitem><para><methodname>getFilters()</methodname></para></listitem>
1261                     <listitem><para><methodname>removeFilter($name)</methodname></para></listitem>
1262                     <listitem><para><methodname>clearFilters()</methodname></para></listitem>
1263                 </itemizedlist>
1264             </listitem>
1265
1266             <listitem><para>レンダリング</para>
1267                 <itemizedlist>
1268                     <listitem><para><methodname>setView(Zend_View_Interface $view = null)</methodname></para></listitem>
1269                     <listitem><para><methodname>getView()</methodname></para></listitem>
1270                     <listitem><para><methodname>addDecorator($decorator, $options = null)</methodname></para></listitem>
1271                     <listitem><para><methodname>addDecorators(array $decorators)</methodname></para></listitem>
1272                     <listitem><para><methodname>setDecorators(array $decorators)</methodname></para></listitem>
1273                     <listitem><para><methodname>getDecorator($name)</methodname></para></listitem>
1274                     <listitem><para><methodname>getDecorators()</methodname></para></listitem>
1275                     <listitem><para><methodname>removeDecorator($name)</methodname></para></listitem>
1276                     <listitem><para><methodname>clearDecorators()</methodname></para></listitem>
1277                     <listitem><para><methodname>render(Zend_View_Interface $view = null)</methodname></para></listitem>
1278                 </itemizedlist>
1279             </listitem>
1280         </itemizedlist>
1281     </sect2>
1282
1283     <sect2 id="zend.form.elements.config">
1284         <title>設定</title>
1285
1286         <para>
1287             <classname>Zend_Form_Element</classname> のコンストラクタには、配列あるいは
1288             <classname>Zend_Config</classname> オブジェクトでオプションを指定できます。
1289             また、<methodname>setOptions()</methodname> や
1290             <methodname>setConfig()</methodname> で設定を変更することもできます。
1291             一般に、キーの名前は次のようになります。
1292         </para>
1293
1294         <itemizedlist>
1295             <listitem><para>
1296                 'set' + キーの名前のメソッドが <classname>Zend_Form_Element</classname>
1297                 にあれば、値をそのメソッドに渡します。
1298             </para></listitem>
1299
1300             <listitem><para>
1301                 それ以外の場合は、属性を使用して値を設定します。
1302             </para></listitem>
1303         </itemizedlist>
1304
1305         <para>
1306             このルールには、次のような例外があります。
1307         </para>
1308
1309         <itemizedlist>
1310             <listitem><para>
1311                 <property>prefixPath</property> は
1312                 <methodname>addPrefixPaths()</methodname> に渡されます。
1313             </para></listitem>
1314
1315             <listitem>
1316                 <para>
1317                     以下のセッターはこの方式では設定できません。
1318                 </para>
1319
1320                 <itemizedlist>
1321                     <listitem><para>
1322                             <property>setAttrib</property> (ただし、
1323                             <property>setAttribs</property> は
1324                             <emphasis>動作します</emphasis>)
1325                     </para></listitem>
1326
1327                     <listitem><para><property>setConfig</property></para></listitem>
1328
1329                     <listitem><para><property>setOptions</property></para></listitem>
1330
1331                     <listitem><para><property>setPluginLoader</property></para></listitem>
1332
1333                     <listitem><para><property>setTranslator</property></para></listitem>
1334
1335                     <listitem><para><property>setView</property></para></listitem>
1336                 </itemizedlist>
1337             </listitem>
1338         </itemizedlist>
1339
1340         <para>
1341             例として、すべての型の設定データを渡すファイルを見てみましょう。
1342         </para>
1343
1344         <programlisting language="ini"><![CDATA[
1345 [element]
1346 name = "foo"
1347 value = "foobar"
1348 label = "Foo:"
1349 order = 10
1350 required = true
1351 allowEmpty = false
1352 autoInsertNotEmptyValidator = true
1353 description = "Foo elements are for examples"
1354 ignore = false
1355 attribs.id = "foo"
1356 attribs.class = "element"
1357 ; sets 'onclick' attribute
1358 onclick = "autoComplete(this, '/form/autocomplete/element')"
1359 prefixPaths.decorator.prefix = "My_Decorator"
1360 prefixPaths.decorator.path = "My/Decorator/"
1361 disableTranslator = 0
1362 validators.required.validator = "NotEmpty"
1363 validators.required.breakChainOnFailure = true
1364 validators.alpha.validator = "alpha"
1365 validators.regex.validator = "regex"
1366 validators.regex.options.pattern = "/^[A-F].*/$"
1367 filters.ucase.filter = "StringToUpper"
1368 decorators.element.decorator = "ViewHelper"
1369 decorators.element.options.helper = "FormText"
1370 decorators.label.decorator = "Label"
1371 ]]></programlisting>
1372     </sect2>
1373
1374     <sect2 id="zend.form.elements.custom">
1375         <title>カスタム要素</title>
1376
1377         <para>
1378             独自の要素を作成するには <classname>Zend_Form_Element</classname>
1379             クラスを継承したクラスを作成します。
1380             独自の要素を作成することになるのは、たとえば次のような場合です。
1381         </para>
1382
1383         <itemizedlist>
1384             <listitem><para>
1385                 共通のバリデータやフィルタを持つ要素を作成する
1386             </para></listitem>
1387
1388             <listitem><para>
1389                 独自のデコレータ機能を持つ要素を作成する
1390             </para></listitem>
1391         </itemizedlist>
1392
1393         <para>
1394             要素を継承する際に主に使用するメソッドは次の 2 つです。
1395             <methodname>init()</methodname> で独自の初期化ロジックをあなたの要素に追加し、
1396             <methodname>loadDefaultDecorators()</methodname>
1397             でデフォルトのデコレータのリストをあなたの要素に設定します。,
1398         </para>
1399
1400         <para>
1401             たとえば、あなたが作成するフォーム上のテキストボックスでは、すべて
1402             <classname>StringTrim</classname> フィルタが必要で、
1403             かつ正規表現による入力検証を行うことになるとしましょう。
1404             ついでに、表示用に独自のデコレータ 'My_Decorator_TextItem'
1405             も使用するものとします。さらに、標準の属性
1406             'size' や 'maxLength'、そして 'class' なども設定します。
1407             このような要素は、次のように定義します。
1408         </para>
1409
1410         <programlisting language="php"><![CDATA[
1411 class My_Element_Text extends Zend_Form_Element
1412 {
1413     public function init()
1414     {
1415         $this->addPrefixPath('My_Decorator', 'My/Decorator/', 'decorator')
1416              ->addFilters('StringTrim')
1417              ->addValidator('Regex', false, array('/^[a-z0-9]{6,}$/i'))
1418              ->addDecorator('TextItem')
1419              ->setAttrib('size', 30)
1420              ->setAttrib('maxLength', 45)
1421              ->setAttrib('class', 'text');
1422     }
1423 }
1424 ]]></programlisting>
1425
1426         <para>
1427             それから、フォームオブジェクトに対して
1428             この要素のプレフィックスパスを登録した上で要素を作成します。
1429         </para>
1430
1431         <programlisting language="php"><![CDATA[
1432 $form->addPrefixPath('My_Element', 'My/Element/', 'element')
1433      ->addElement('text', 'foo');
1434 ]]></programlisting>
1435
1436         <para>
1437             'foo' 要素はこれで <classname>My_Element_Text</classname>
1438             型となりました。先ほど説明したような機能を持つテキストボックスです。
1439         </para>
1440
1441         <para>
1442             <classname>Zend_Form_Element</classname> を継承したクラスでオーバーライドしたくなる
1443             その他のメソッドとして、<methodname>loadDefaultDecorators()</methodname>
1444             があります。このメソッドは、条件付きで
1445             要素にデフォルトのデコレータセットを読み込みます。
1446             継承したクラスで、このデコレータ群を置き換えることができます。
1447         </para>
1448
1449         <programlisting language="php"><![CDATA[
1450 class My_Element_Text extends Zend_Form_Element
1451 {
1452     public function loadDefaultDecorators()
1453     {
1454         $this->addDecorator('ViewHelper')
1455              ->addDecorator('DisplayError')
1456              ->addDecorator('Label')
1457              ->addDecorator('HtmlTag',
1458                             array('tag' => 'div', 'class' => 'element'));
1459     }
1460 }
1461 ]]></programlisting>
1462
1463         <para>
1464             要素のカスタマイズにはさまざまな方法があります。
1465             <classname>Zend_Form_Element</classname> の <acronym>API</acronym> ドキュメントを熟読し、
1466             どんな機能が使用できるのかを覚えていきましょう。
1467         </para>
1468     </sect2>
1469 </sect1>
1470 <!--
1471 vim:se ts=4 sw=4 tw=80 et:
1472 -->