documentation/manual/en/module_specs/Zend_Form-Forms.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.form.forms">
   4     <title>Creating Forms Using Zend_Form</title>
   5
   6     <para>
   7         The <classname>Zend_Form</classname> class is used to aggregate form elements,
   8         display groups, and subforms. It can then perform the following actions
   9         on those items:
  10     </para>
  11
  12     <itemizedlist>
  13         <listitem>
  14             <para>
  15                 Validation, including retrieving error codes and messages
  16             </para>
  17         </listitem>
  18
  19         <listitem>
  20             <para>
  21                 Value aggregation, including populating items and retrieving both
  22                 filtered and unfiltered values from all items
  23             </para>
  24         </listitem>
  25
  26         <listitem>
  27             <para>
  28                 Iteration over all items, in the order in which they are entered or
  29                 based on the order hints retrieved from each item
  30             </para>
  31         </listitem>
  32
  33         <listitem>
  34             <para>
  35                 Rendering of the entire form, either via a single decorator that
  36                 performs custom rendering or by iterating over each item in the form
  37             </para>
  38         </listitem>
  39     </itemizedlist>
  40
  41     <para>
  42         While forms created with <classname>Zend_Form</classname> may be complex, probably
  43         the best use case is for simple forms; its best use is for Rapid
  44         Application Development (RAD) and prototyping.
  45     </para>
  46
  47     <para>
  48         At its most basic, you simply instantiate a form object:
  49     </para>
  50
  51     <programlisting language="php"><![CDATA[
  52 // Generic form object:
  53 $form = new Zend_Form();
  54
  55 // Custom form object:
  56 $form = new My_Form()
  57 ]]></programlisting>
  58
  59     <para>
  60         You can optionally pass in a instance of <classname>Zend_Config</classname> or an array,
  61         which will be used to set object state and potentially create new elements:
  62     </para>
  63
  64     <programlisting language="php"><![CDATA[
  65 // Passing in configuration options:
  66 $form = new Zend_Form($config);
  67 ]]></programlisting>
  68
  69     <para>
  70         <classname>Zend_Form</classname> is iterable, and will iterate over elements,
  71         display groups, and subforms, using the order they were registered and
  72         any order index each may have. This is useful in cases where you wish to
  73         render the elements manually in the appropriate order.
  74     </para>
  75
  76     <para>
  77         <classname>Zend_Form</classname>'s magic lies in its ability to serve as a factory
  78         for elements and display groups, as well as the ability to render itself
  79         through decorators.
  80     </para>
  81
  82     <sect2 id="zend.form.forms.plugins">
  83         <title>Plugin Loaders</title>
  84
  85         <para>
  86             <classname>Zend_Form</classname> makes use of
  87             <classname>Zend_Loader_PluginLoader</classname> to allow developers to specify
  88             the locations of alternate elements and decorators. Each has its own
  89             plugin loader associated with it, and general accessors are used to
  90             retrieve and modify each.
  91         </para>
  92
  93         <para>
  94             The following loader types are used with the various plugin loader
  95             methods: 'element' and 'decorator'. The type names are case
  96             insensitive.
  97         </para>
  98
  99         <para>
 100             The methods used to interact with plugin loaders are as follows:
 101         </para>
 102
 103         <itemizedlist>
 104             <listitem>
 105                 <para>
 106                     <methodname>setPluginLoader($loader, $type)</methodname>: $loader is the
 107                     plugin loader object itself, while type is one of the types
 108                     specified above. This sets the plugin loader for the given type
 109                     to the newly specified loader object.
 110                 </para>
 111             </listitem>
 112
 113             <listitem>
 114                 <para>
 115                     <methodname>getPluginLoader($type)</methodname>: retrieves the plugin loader
 116                     associated with $type.
 117                 </para>
 118             </listitem>
 119
 120             <listitem>
 121                 <para>
 122                     <methodname>addPrefixPath($prefix, $path, $type = null)</methodname>: adds a
 123                     prefix/path association to the loader specified by $type. If
 124                     $type is <constant>NULL</constant>, it will attempt to add the path to all
 125                     loaders, by appending the prefix with each of "_Element" and
 126                     "_Decorator"; and appending the path with "Element/" and
 127                     "Decorator/". If you have all your extra form element classes
 128                     under a common hierarchy, this is a convenience method for
 129                     setting the base prefix for them.
 130                 </para>
 131             </listitem>
 132
 133             <listitem>
 134                 <para>
 135                     <methodname>addPrefixPaths(array $spec)</methodname>: allows you to add many
 136                     paths at once to one or more plugin loaders. It expects each
 137                     array item to be an array with the keys 'path', 'prefix', and
 138                     'type'.
 139                 </para>
 140             </listitem>
 141         </itemizedlist>
 142
 143         <para>
 144             Additionally, you can specify prefix paths for all elements and
 145             display groups created through a <classname>Zend_Form</classname> instance
 146             using the following methods:
 147         </para>
 148
 149         <itemizedlist>
 150             <listitem>
 151                 <para>
 152                     <methodname>addElementPrefixPath($prefix, $path, $type = null)</methodname>:
 153                     Just like <methodname>addPrefixPath()</methodname>, you must specify a class
 154                     prefix and a path. <varname>$type</varname>, when specified, must be
 155                     one of the plugin loader types specified by
 156                     <classname>Zend_Form_Element</classname>; see the <link
 157                         linkend="zend.form.elements.loaders">element plugins
 158                         section</link> for more information on valid
 159                     <varname>$type</varname> values. If no <varname>$type</varname> is
 160                     specified, the method will assume it is a general prefix for all
 161                     types.
 162                 </para>
 163             </listitem>
 164
 165             <listitem>
 166                 <para>
 167                     <methodname>addDisplayGroupPrefixPath($prefix, $path)</methodname>:
 168                     Just like <methodname>addPrefixPath()</methodname>, you must specify a class
 169                     prefix and a path; however, since display groups only support
 170                     decorators as plugins, no <varname>$type</varname> is necessary.
 171                 </para>
 172             </listitem>
 173         </itemizedlist>
 174
 175         <para>
 176             Custom elements and decorators are an easy way to share
 177             functionality between forms and encapsulate custom functionality.
 178             See the <link
 179                 linkend="zend.form.elements.loaders.customLabel">Custom Label
 180                 example</link> in the elements documentation for an example of
 181             how custom elements can be used as replacements for standard
 182             classes.
 183         </para>
 184     </sect2>
 185
 186     <sect2 id="zend.form.forms.elements">
 187         <title>Elements</title>
 188
 189         <para>
 190             <classname>Zend_Form</classname> provides several accessors for adding and
 191             removing form elements from a form. These can take element object
 192             instances or serve as factories for instantiating the element
 193             objects themselves.
 194         </para>
 195
 196         <para>
 197             The most basic method for adding an element is
 198             <methodname>addElement()</methodname>. This method can take either an object of
 199             type <classname>Zend_Form_Element</classname> (or of a class extending
 200             <classname>Zend_Form_Element</classname>), or arguments for building a new
 201             element -- including the element type, name, and any configuration
 202             options.
 203         </para>
 204
 205         <para>
 206             Some examples:
 207         </para>
 208
 209         <programlisting language="php"><![CDATA[
 210 // Using an element instance:
 211 $element = new Zend_Form_Element_Text('foo');
 212 $form->addElement($element);
 213
 214 // Using a factory
 215 //
 216 // Creates an element of type Zend_Form_Element_Text with the
 217 // name of 'foo':
 218 $form->addElement('text', 'foo');
 219
 220 // Pass label option to the element:
 221 $form->addElement('text', 'foo', array('label' => 'Foo:'));
 222 ]]></programlisting>
 223
 224         <note>
 225             <title>addElement() Implements Fluent Interface</title>
 226
 227             <para>
 228                 <methodname>addElement()</methodname> implements a fluent interface; that is
 229                 to say, it returns the <classname>Zend_Form</classname> object, and not
 230                 the element. This is done to allow you to chain together
 231                 multiple addElement() methods or other form methods that
 232                 implement the fluent interface (all setters in <classname>Zend_Form</classname>
 233                 implement the pattern).
 234             </para>
 235
 236             <para>
 237                 If you wish to return the element instead, use
 238                 <methodname>createElement()</methodname>, which is outlined below. Be aware,
 239                 however, that <methodname>createElement()</methodname> does not attach the
 240                 element to the form.
 241             </para>
 242
 243             <para>
 244                 Internally, <methodname>addElement()</methodname> actually uses
 245                 <methodname>createElement()</methodname> to create the element before
 246                 attaching it to the form.
 247             </para>
 248         </note>
 249
 250         <para>
 251             Once an element has been added to the form, you can retrieve it by
 252             name. This can be done either by using the <methodname>getElement()</methodname>
 253             method or by using overloading to access the element as an object
 254             property:
 255         </para>
 256
 257         <programlisting language="php"><![CDATA[
 258 // getElement():
 259 $foo = $form->getElement('foo');
 260
 261 // As object property:
 262 $foo = $form->foo;
 263 ]]></programlisting>
 264
 265         <para>
 266             Occasionally, you may want to create an element without attaching it
 267             to the form (for instance, if you wish to make use of the various
 268             plugin paths registered with the form, but wish to later attach the
 269             object to a sub form). The <methodname>createElement()</methodname> method
 270             allows you to do so:
 271         </para>
 272
 273         <programlisting language="php"><![CDATA[
 274 // $username becomes a Zend_Form_Element_Text object:
 275 $username = $form->createElement('text', 'username');
 276 ]]></programlisting>
 277
 278         <sect3 id="zend.form.forms.elements.values">
 279             <title>Populating and Retrieving Values</title>
 280
 281             <para>
 282                 After validating a form, you will typically need to retrieve the
 283                 values so you can perform other operations, such as updating a
 284                 database or notifying a web service. You can retrieve all values
 285                 for all elements using <methodname>getValues()</methodname>;
 286                 <methodname>getValue($name)</methodname> allows you to retrieve a single
 287                 element's value by element name:
 288             </para>
 289
 290             <programlisting language="php"><![CDATA[
 291 // Get all values:
 292 $values = $form->getValues();
 293
 294 // Get only 'foo' element's value:
 295 $value = $form->getValue('foo');
 296 ]]></programlisting>
 297
 298             <para>
 299                 Sometimes you'll want to populate the form with specified values
 300                 prior to rendering. This can be done with either the
 301                 <methodname>setDefaults()</methodname> or <methodname>populate()</methodname>
 302                 methods:
 303             </para>
 304
 305             <programlisting language="php"><![CDATA[
 306 $form->setDefaults($data);
 307 $form->populate($data);
 308 ]]></programlisting>
 309
 310             <para>
 311                 On the flip side, you may want to clear a form after populating
 312                 or validating it; this can be done using the
 313                 <methodname>reset()</methodname> method:
 314             </para>
 315
 316             <programlisting language="php"><![CDATA[
 317 $form->reset();
 318 ]]></programlisting>
 319         </sect3>
 320
 321         <sect3 id="zend.form.forms.elements.global">
 322             <title>Global Operations</title>
 323
 324             <para>
 325                 Occasionally you will want certain operations to affect all
 326                 elements. Common scenarios include needing to set plugin prefix
 327                 paths for all elements, setting decorators for all elements, and
 328                 setting filters for all elements. As examples:
 329             </para>
 330
 331             <example id="zend.form.forms.elements.global.allpaths">
 332                 <title>Setting Prefix Paths for All Elements</title>
 333
 334                 <para>
 335                     You can set prefix paths for all elements by type, or using
 336                     a global prefix. Some examples:
 337                 </para>
 338
 339                 <programlisting language="php"><![CDATA[
 340 // Set global prefix path:
 341 // Creates paths for prefixes My_Foo_Filter, My_Foo_Validate,
 342 // and My_Foo_Decorator
 343 $form->addElementPrefixPath('My_Foo', 'My/Foo/');
 344
 345 // Just filter paths:
 346 $form->addElementPrefixPath('My_Foo_Filter',
 347                             'My/Foo/Filter',
 348                             'filter');
 349
 350 // Just validator paths:
 351 $form->addElementPrefixPath('My_Foo_Validate',
 352                             'My/Foo/Validate',
 353                             'validate');
 354
 355 // Just decorator paths:
 356 $form->addElementPrefixPath('My_Foo_Decorator',
 357                             'My/Foo/Decorator',
 358                             'decorator');
 359 ]]></programlisting>
 360             </example>
 361
 362             <example id="zend.form.forms.elements.global.decorators">
 363                 <title>Setting Decorators for All Elements</title>
 364
 365                 <para>
 366                     You can set decorators for all elements.
 367                     <methodname>setElementDecorators()</methodname> accepts an array of
 368                     decorators, just like <methodname>setDecorators()</methodname>, and will
 369                     overwrite any previously set decorators in each element. In
 370                     this example, we set the decorators to simply a ViewHelper
 371                     and a Label:
 372                 </para>
 373
 374                 <programlisting language="php"><![CDATA[
 375 $form->setElementDecorators(array(
 376     'ViewHelper',
 377     'Label'
 378 ));
 379 ]]></programlisting>
 380             </example>
 381
 382             <example id="zend.form.forms.elements.global.decoratorsFilter">
 383                 <title>Setting Decorators for Some Elements</title>
 384
 385                 <para>
 386                     You can also set decorators for a subset of elements,
 387                     either by inclusion or exclusion. The second argument to
 388                     <methodname>setElementDecorators()</methodname> may be an array of
 389                     element names; by default, specifying such an array will
 390                     set the specified decorators on those elements only. You
 391                     may also pass a third argument, a flag indicating whether
 392                     this list of elements is for inclusion or exclusion
 393                     purposes. If the flag is <constant>FALSE</constant>, it will decorate all
 394                     elements <emphasis>except</emphasis> those in the passed list.
 395                     As with standard usage of the method, any decorators passed
 396                     will overwrite any previously set decorators in each
 397                     element.
 398                 </para>
 399
 400                 <para>
 401                     In the following snippet, we indicate that we want only the
 402                     ViewHelper and Label decorators for the 'foo' and 'bar'
 403                     elements:
 404                 </para>
 405
 406                 <programlisting language="php"><![CDATA[
 407 $form->setElementDecorators(
 408     array(
 409         'ViewHelper',
 410         'Label'
 411     ),
 412     array(
 413         'foo',
 414         'bar'
 415     )
 416 );
 417 ]]></programlisting>
 418
 419                 <para>
 420                     On the flip side, with this snippet, we'll now indicate
 421                     that we want to use only the ViewHelper and Label
 422                     decorators for every element <emphasis>except</emphasis>
 423                     the 'foo' and 'bar' elements:
 424                 </para>
 425
 426                 <programlisting language="php"><![CDATA[
 427 $form->setElementDecorators(
 428     array(
 429         'ViewHelper',
 430         'Label'
 431     ),
 432     array(
 433         'foo',
 434         'bar'
 435     ),
 436     false
 437 );
 438 ]]></programlisting>
 439             </example>
 440
 441             <note>
 442                 <title>Some Decorators are Inappropriate for Some Elements</title>
 443
 444                 <para>
 445                     While <methodname>setElementDecorators()</methodname> may seem like
 446                     a good solution, there are some cases where it may
 447                     actually end up with unexpected results. For example,
 448                     the various button elements (Submit, Button, Reset)
 449                     currently use the label as the value of the button,
 450                     and only use ViewHelper and DtDdWrapper decorators --
 451                     preventing an additional labels, errors, and hints from
 452                     being rendered. The example above would duplicate some
 453                     content (the label) for button elements.
 454                 </para>
 455
 456                 <para>
 457                     You can use the inclusion/exclusion array to overcome
 458                     this issue as noted in the previous example.
 459                 </para>
 460
 461                 <para>
 462                     So, use this method wisely, and realize that you may
 463                     need to exclude some elements or manually change some elements' decorators
 464                     to prevent unwanted output.
 465                 </para>
 466             </note>
 467
 468             <example id="zend.form.forms.elements.global.filters">
 469                 <title>Setting Filters for All Elements</title>
 470
 471                 <para>
 472                     In some cases, you may want to apply the same filter to all
 473                     elements; a common case is to <methodname>trim()</methodname> all values:
 474                 </para>
 475
 476         <programlisting language="php"><![CDATA[
 477 $form->setElementFilters(array('StringTrim'));
 478 ]]></programlisting>
 479             </example>
 480         </sect3>
 481
 482         <sect3 id="zend.form.forms.elements.methods">
 483             <title>Methods For Interacting With Elements</title>
 484
 485             <para>
 486                 The following methods may be used to interact with elements:
 487             </para>
 488
 489             <itemizedlist>
 490                 <listitem>
 491                     <para>
 492                         <methodname>createElement($element, $name = null, $options =
 493                             null)</methodname>
 494                     </para>
 495                 </listitem>
 496
 497                 <listitem>
 498                     <para>
 499                         <methodname>addElement($element, $name = null, $options = null)</methodname>
 500                     </para>
 501                 </listitem>
 502
 503                 <listitem>
 504                     <para>
 505                         <methodname>addElements(array $elements)</methodname>
 506                     </para>
 507                 </listitem>
 508
 509                 <listitem>
 510                     <para>
 511                         <methodname>setElements(array $elements)</methodname>
 512                     </para>
 513                 </listitem>
 514
 515                 <listitem>
 516                     <para>
 517                         <methodname>getElement($name)</methodname>
 518                     </para>
 519                 </listitem>
 520
 521                 <listitem>
 522                     <para>
 523                         <methodname>getElements()</methodname>
 524                     </para>
 525                 </listitem>
 526
 527                 <listitem>
 528                     <para>
 529                         <methodname>removeElement($name)</methodname>
 530                     </para>
 531                 </listitem>
 532
 533                 <listitem>
 534                     <para>
 535                         <methodname>clearElements()</methodname>
 536                     </para>
 537                 </listitem>
 538
 539                 <listitem>
 540                     <para>
 541                         <methodname>setDefaults(array $defaults)</methodname>
 542                     </para>
 543                 </listitem>
 544
 545                 <listitem>
 546                     <para>
 547                         <methodname>setDefault($name, $value)</methodname>
 548                     </para>
 549                 </listitem>
 550
 551                 <listitem>
 552                     <para>
 553                         <methodname>getValue($name)</methodname>
 554                     </para>
 555                 </listitem>
 556
 557                 <listitem>
 558                     <para>
 559                         <methodname>getValues()</methodname>
 560                     </para>
 561                 </listitem>
 562
 563                 <listitem>
 564                     <para>
 565                         <methodname>getUnfilteredValue($name)</methodname>
 566                     </para>
 567                 </listitem>
 568
 569                 <listitem>
 570                     <para>
 571                         <methodname>getUnfilteredValues()</methodname>
 572                     </para>
 573                 </listitem>
 574
 575                 <listitem>
 576                     <para>
 577                         <methodname>setElementFilters(array $filters)</methodname>
 578                     </para>
 579                 </listitem>
 580
 581                 <listitem>
 582                     <para>
 583                         <methodname>setElementDecorators(array $decorators)</methodname>
 584                     </para>
 585                 </listitem>
 586
 587                 <listitem>
 588                     <para>
 589                         <methodname>addElementPrefixPath($prefix, $path, $type = null)</methodname>
 590                     </para>
 591                 </listitem>
 592
 593                 <listitem>
 594                     <para>
 595                         <methodname>addElementPrefixPaths(array $spec)</methodname>
 596                     </para>
 597                 </listitem>
 598             </itemizedlist>
 599         </sect3>
 600     </sect2>
 601
 602     <sect2 id="zend.form.forms.displaygroups">
 603         <title>Display Groups</title>
 604
 605         <para>
 606             Display groups are a way to create virtual groupings of elements for
 607             display purposes. All elements remain accessible by name in the
 608             form, but when iterating over the form or rendering, any elements in
 609             a display group are rendered together. The most common use case for
 610             this is for grouping elements in fieldsets.
 611         </para>
 612
 613         <para>
 614             The base class for display groups is
 615             <classname>Zend_Form_DisplayGroup</classname>. While it can be instantiated
 616             directly, it is usually best to use <classname>Zend_Form</classname>'s
 617             <methodname>addDisplayGroup()</methodname> method to do so. This method takes an
 618             array of elements as its first argument, and a name for the display
 619             group as its second argument. You may optionally pass in an array of
 620             options or a <classname>Zend_Config</classname> object as the third argument.
 621         </para>
 622
 623         <para>
 624             Assuming that the elements 'username' and 'password' are already set
 625             in the form, the following code would group these elements in a
 626             'login' display group:
 627         </para>
 628
 629         <programlisting language="php"><![CDATA[
 630 $form->addDisplayGroup(array('username', 'password'), 'login');
 631 ]]></programlisting>
 632
 633         <para>
 634             You can access display groups using the
 635             <methodname>getDisplayGroup()</methodname> method, or via overloading using the
 636             display group's name:
 637         </para>
 638
 639         <programlisting language="php"><![CDATA[
 640 // Using getDisplayGroup():
 641 $login = $form->getDisplayGroup('login');
 642
 643 // Using overloading:
 644 $login = $form->login;
 645 ]]></programlisting>
 646
 647         <note>
 648             <title>Default Decorators Do Not Need to Be Loaded</title>
 649
 650             <para>
 651                 By default, the default decorators are loaded during object
 652                 initialization. You can disable this by passing the
 653                 'disableLoadDefaultDecorators' option when creating a display
 654                 group:
 655             </para>
 656
 657             <programlisting language="php"><![CDATA[
 658 $form->addDisplayGroup(
 659     array('foo', 'bar'),
 660     'foobar',
 661     array('disableLoadDefaultDecorators' => true)
 662 );
 663 ]]></programlisting>
 664
 665             <para>
 666                 This option may be mixed with any other options you pass,
 667                 both as array options or in a <classname>Zend_Config</classname> object.
 668             </para>
 669         </note>
 670
 671         <sect3 id="zend.form.forms.displaygroups.global">
 672             <title>Global Operations</title>
 673
 674             <para>
 675                 Just as with elements, there are some operations which might
 676                 affect all display groups; these include setting decorators and
 677                 setting the plugin path in which to look for decorators.
 678             </para>
 679
 680             <example id="zend.form.forms.displaygroups.global.paths">
 681                 <title>Setting Decorator Prefix Path for All Display Groups</title>
 682
 683                 <para>
 684                     By default, display groups inherit whichever decorator paths
 685                     the form uses; however, if they should look in alternate
 686                     locations, you can use the
 687                     <methodname>addDisplayGroupPrefixPath()</methodname> method.
 688                 </para>
 689
 690                 <programlisting language="php"><![CDATA[
 691 $form->addDisplayGroupPrefixPath('My_Foo_Decorator', 'My/Foo/Decorator');
 692 ]]></programlisting>
 693             </example>
 694
 695             <example id="zend.form.forms.displaygroups.global.decorators">
 696                 <title>Setting Decorators for All Display Groups</title>
 697
 698                 <para>
 699                     You can set decorators for all display groups.
 700                     <methodname>setDisplayGroupDecorators()</methodname> accepts an array of
 701                     decorators, just like <methodname>setDecorators()</methodname>, and will
 702                     overwrite any previously set decorators in each display
 703                     group. In this example, we set the decorators to simply a
 704                     fieldset (the FormElements decorator is necessary to ensure
 705                     that the elements are iterated):
 706                 </para>
 707
 708                 <programlisting language="php"><![CDATA[
 709 $form->setDisplayGroupDecorators(array(
 710     'FormElements',
 711     'Fieldset'
 712 ));
 713 ]]></programlisting>
 714             </example>
 715         </sect3>
 716
 717         <sect3 id="zend.form.forms.displaygroups.customClasses">
 718             <title>Using Custom Display Group Classes</title>
 719
 720             <para>
 721                 By default, <classname>Zend_Form</classname> uses the
 722                 <classname>Zend_Form_DisplayGroup</classname> class for display groups.
 723                 You may find you need to extend this class in order to provided
 724                 custom functionality. <methodname>addDisplayGroup()</methodname> does not
 725                 allow passing in a concrete instance, but does allow specifying
 726                 the class to use as one of its options, using the
 727                 'displayGroupClass' key:
 728             </para>
 729
 730             <programlisting language="php"><![CDATA[
 731 // Use the 'My_DisplayGroup' class
 732 $form->addDisplayGroup(
 733     array('username', 'password'),
 734     'user',
 735     array('displayGroupClass' => 'My_DisplayGroup')
 736 );
 737 ]]></programlisting>
 738
 739             <para>
 740                 If the class has not yet been loaded, <classname>Zend_Form</classname>
 741                 will attempt to do so using <classname>Zend_Loader</classname>.
 742             </para>
 743
 744             <para>
 745                 You can also specify a default display group class to use with
 746                 the form such that all display groups created with the form
 747                 object will use that class:
 748             </para>
 749
 750             <programlisting language="php"><![CDATA[
 751 // Use the 'My_DisplayGroup' class for all display groups:
 752 $form->setDefaultDisplayGroupClass('My_DisplayGroup');
 753 ]]></programlisting>
 754
 755             <para>
 756                 This setting may be specified in configurations as
 757                 'defaultDisplayGroupClass', and will be loaded early to ensure
 758                 all display groups use that class.
 759             </para>
 760         </sect3>
 761
 762         <sect3 id="zend.form.forms.displaygroups.interactionmethods">
 763             <title>Methods for Interacting With Display Groups</title>
 764
 765             <para>
 766                 The following methods may be used to interact with display
 767                 groups:
 768             </para>
 769
 770             <itemizedlist>
 771                 <listitem>
 772                     <para>
 773                         <methodname>addDisplayGroup(array $elements, $name, $options
 774                             = null)</methodname>
 775                     </para>
 776                 </listitem>
 777
 778                 <listitem>
 779                     <para>
 780                         <methodname>addDisplayGroups(array $groups)</methodname>
 781                     </para>
 782                 </listitem>
 783
 784                 <listitem>
 785                     <para>
 786                         <methodname>setDisplayGroups(array $groups)</methodname>
 787                     </para>
 788                 </listitem>
 789
 790                 <listitem>
 791                     <para>
 792                         <methodname>getDisplayGroup($name)</methodname>
 793                     </para>
 794                 </listitem>
 795
 796                 <listitem>
 797                     <para>
 798                         <methodname>getDisplayGroups()</methodname>
 799                     </para>
 800                 </listitem>
 801
 802                 <listitem>
 803                     <para>
 804                         <methodname>removeDisplayGroup($name)</methodname>
 805                     </para>
 806                 </listitem>
 807
 808                 <listitem>
 809                     <para>
 810                         <methodname>clearDisplayGroups()</methodname>
 811                     </para>
 812                 </listitem>
 813
 814                 <listitem>
 815                     <para>
 816                         <methodname>setDisplayGroupDecorators(array $decorators)</methodname>
 817                     </para>
 818                 </listitem>
 819
 820                 <listitem>
 821                     <para>
 822                         <methodname>addDisplayGroupPrefixPath($prefix, $path)</methodname>
 823                     </para>
 824                 </listitem>
 825
 826                 <listitem>
 827                     <para>
 828                         <methodname>setDefaultDisplayGroupClass($class)</methodname>
 829                     </para>
 830                 </listitem>
 831
 832                 <listitem>
 833                     <para>
 834                         <methodname>getDefaultDisplayGroupClass($class)</methodname>
 835                     </para>
 836                 </listitem>
 837             </itemizedlist>
 838         </sect3>
 839
 840         <sect3 id="zend.form.forms.displaygroups.methods">
 841             <title>Zend_Form_DisplayGroup Methods</title>
 842
 843             <para>
 844                 <classname>Zend_Form_DisplayGroup</classname> has the following methods,
 845                 grouped by type:
 846             </para>
 847
 848             <itemizedlist>
 849                 <listitem>
 850                     <para>Configuration:</para>
 851
 852                     <itemizedlist>
 853                         <listitem>
 854                             <para>
 855                                 <methodname>setOptions(array $options)</methodname>
 856                             </para>
 857                         </listitem>
 858
 859                         <listitem>
 860                             <para><methodname>setConfig(Zend_Config $config)</methodname></para>
 861                         </listitem>
 862                     </itemizedlist>
 863                 </listitem>
 864
 865                 <listitem>
 866                     <para>Metadata:</para>
 867
 868                     <itemizedlist>
 869                         <listitem>
 870                             <para><methodname>setAttrib($key, $value)</methodname></para>
 871                         </listitem>
 872
 873                         <listitem>
 874                             <para><methodname>addAttribs(array $attribs)</methodname></para>
 875                         </listitem>
 876
 877                         <listitem>
 878                             <para><methodname>setAttribs(array $attribs)</methodname></para>
 879                         </listitem>
 880
 881                         <listitem><para><methodname>getAttrib($key)</methodname></para></listitem>
 882                         <listitem><para><methodname>getAttribs()</methodname></para></listitem>
 883
 884                         <listitem>
 885                             <para><methodname>removeAttrib($key)</methodname></para>
 886                         </listitem>
 887
 888                         <listitem><para><methodname>clearAttribs()</methodname></para></listitem>
 889                         <listitem><para><methodname>setName($name)</methodname></para></listitem>
 890                         <listitem><para><methodname>getName()</methodname></para></listitem>
 891
 892                         <listitem>
 893                             <para><methodname>setDescription($value)</methodname></para>
 894                         </listitem>
 895
 896                         <listitem><para><methodname>getDescription()</methodname></para></listitem>
 897
 898                         <listitem>
 899                             <para><methodname>setLegend($legend)</methodname></para>
 900                         </listitem>
 901
 902                         <listitem><para><methodname>getLegend()</methodname></para></listitem>
 903                         <listitem><para><methodname>setOrder($order)</methodname></para></listitem>
 904                         <listitem><para><methodname>getOrder()</methodname></para></listitem>
 905                     </itemizedlist>
 906                 </listitem>
 907
 908                 <listitem>
 909                     <para>Elements:</para>
 910
 911                     <itemizedlist>
 912                         <listitem>
 913                             <para>
 914                                 <methodname>createElement($type, $name, array $options
 915                                     = array())</methodname>
 916                             </para>
 917                         </listitem>
 918
 919                         <listitem>
 920                             <para>
 921                                 <methodname>addElement($typeOrElement, $name, array $options =
 922                                     array())</methodname>
 923                             </para>
 924                         </listitem>
 925
 926                         <listitem>
 927                             <para><methodname>addElements(array $elements)</methodname></para>
 928                         </listitem>
 929
 930                         <listitem>
 931                             <para><methodname>setElements(array $elements)</methodname></para>
 932                         </listitem>
 933
 934                         <listitem><para><methodname>getElement($name)</methodname></para></listitem>
 935                         <listitem><para><methodname>getElements()</methodname></para></listitem>
 936
 937                         <listitem>
 938                             <para><methodname>removeElement($name)</methodname></para>
 939                         </listitem>
 940
 941                         <listitem><para><methodname>clearElements()</methodname></para></listitem>
 942                     </itemizedlist>
 943                 </listitem>
 944
 945                 <listitem>
 946                     <para>Plugin loaders:</para>
 947
 948                     <itemizedlist>
 949                         <listitem>
 950                             <para>
 951                                 <methodname>setPluginLoader(Zend_Loader_PluginLoader
 952                                     $loader)</methodname>
 953                             </para>
 954                         </listitem>
 955
 956                         <listitem><para><methodname>getPluginLoader()</methodname></para></listitem>
 957
 958                         <listitem>
 959                             <para><methodname>addPrefixPath($prefix, $path)</methodname></para>
 960                         </listitem>
 961
 962                         <listitem>
 963                             <para><methodname>addPrefixPaths(array $spec)</methodname></para>
 964                         </listitem>
 965                     </itemizedlist>
 966                 </listitem>
 967
 968                 <listitem>
 969                     <para>Decorators:</para>
 970
 971                     <itemizedlist>
 972                         <listitem>
 973                             <para>
 974                                 <methodname>addDecorator($decorator, $options = null)</methodname>
 975                             </para>
 976                         </listitem>
 977
 978                         <listitem>
 979                             <para><methodname>addDecorators(array $decorators)</methodname></para>
 980                         </listitem>
 981
 982                         <listitem>
 983                             <para><methodname>setDecorators(array $decorators)</methodname></para>
 984                         </listitem>
 985
 986                         <listitem>
 987                             <para><methodname>getDecorator($name)</methodname></para>
 988                         </listitem>
 989
 990                         <listitem><para><methodname>getDecorators()</methodname></para></listitem>
 991
 992                         <listitem>
 993                             <para><methodname>removeDecorator($name)</methodname></para>
 994                         </listitem>
 995
 996                         <listitem><para><methodname>clearDecorators()</methodname></para></listitem>
 997                     </itemizedlist>
 998                 </listitem>
 999
1000                 <listitem>
1001                     <para>Rendering:</para>
1002
1003                     <itemizedlist>
1004                         <listitem>
1005                             <para>
1006                                 <methodname>setView(Zend_View_Interface $view = null)</methodname>
1007                             </para>
1008                         </listitem>
1009
1010                         <listitem><para><methodname>getView()</methodname></para></listitem>
1011
1012                         <listitem>
1013                             <para>
1014                                 <methodname>render(Zend_View_Interface $view = null)</methodname>
1015                             </para>
1016                         </listitem>
1017                     </itemizedlist>
1018                 </listitem>
1019
1020                 <listitem>
1021                     <para>I18n:</para>
1022
1023                     <itemizedlist>
1024                         <listitem>
1025                             <para>
1026                                 <methodname>setTranslator(Zend_Translate_Adapter $translator =
1027                                     null)</methodname>
1028                             </para>
1029                         </listitem>
1030
1031                         <listitem><para><methodname>getTranslator()</methodname></para></listitem>
1032
1033                         <listitem>
1034                             <para><methodname>setDisableTranslator($flag)</methodname></para>
1035                         </listitem>
1036
1037                         <listitem>
1038                             <para><methodname>translatorIsDisabled()</methodname></para>
1039                         </listitem>
1040                     </itemizedlist>
1041                 </listitem>
1042             </itemizedlist>
1043         </sect3>
1044     </sect2>
1045
1046     <sect2 id="zend.form.forms.subforms">
1047         <title>Sub Forms</title>
1048
1049         <para>
1050             Sub forms serve several purposes:
1051         </para>
1052
1053         <itemizedlist>
1054             <listitem>
1055                 <para>
1056                     Creating logical element groups. Since sub forms are simply
1057                     forms, you can validate subforms as individual entities.
1058                 </para>
1059             </listitem>
1060
1061             <listitem>
1062                 <para>
1063                     Creating multi-page forms. Since sub forms are simply forms, you
1064                     can display a separate sub form per page, building up multi-page
1065                     forms where each form has its own validation logic. Only once
1066                     all sub forms validate would the form be considered complete.
1067                 </para>
1068             </listitem>
1069
1070             <listitem>
1071                 <para>
1072                     Display groupings. Like display groups, sub forms, when rendered
1073                     as part of a larger form, can be used to group elements. Be
1074                     aware, however, that the master form object will have no
1075                     awareness of the elements in sub forms.
1076                 </para>
1077             </listitem>
1078         </itemizedlist>
1079
1080         <para>
1081             A sub form may be a <classname>Zend_Form</classname> object, or, more
1082             typically, a <classname>Zend_Form_SubForm</classname> object. The latter
1083             contains decorators suitable for inclusion in a larger form (i.e.,
1084             it does not render additional HTML form tags, but does group
1085             elements). To attach a sub form, simply add it to the form and give
1086             it a name:
1087         </para>
1088
1089         <programlisting language="php"><![CDATA[
1090 $form->addSubForm($subForm, 'subform');
1091 ]]></programlisting>
1092
1093         <para>
1094             You can retrieve a sub form using either
1095             <methodname>getSubForm($name)</methodname> or overloading using the sub form
1096             name:
1097         </para>
1098
1099         <programlisting language="php"><![CDATA[
1100 // Using getSubForm():
1101 $subForm = $form->getSubForm('subform');
1102
1103 // Using overloading:
1104 $subForm = $form->subform;
1105 ]]></programlisting>
1106
1107         <para>
1108             Sub forms are included in form iteration, although the elements they
1109             contain are not.
1110         </para>
1111
1112         <sect3 id="zend.form.forms.subforms.global">
1113             <title>Global Operations</title>
1114
1115             <para>
1116                 Like elements and display groups, there are some operations that
1117                 might need to affect all sub forms. Unlike display groups and
1118                 elements, however, sub forms inherit most functionality from the
1119                 master form object, and the only real operation that may need to
1120                 be performed globally is setting decorators for sub forms. For
1121                 this purpose, there is the <methodname>setSubFormDecorators()</methodname>
1122                 method. In the next example, we'll set the decorator for all
1123                 subforms to be simply a fieldset (the FormElements decorator is
1124                 needed to ensure its elements are iterated):
1125             </para>
1126
1127             <programlisting language="php"><![CDATA[
1128 $form->setSubFormDecorators(array(
1129     'FormElements',
1130     'Fieldset'
1131 ));
1132 ]]></programlisting>
1133         </sect3>
1134
1135         <sect3 id="zend.form.forms.subforms.methods">
1136             <title>Methods for Interacting With Sub Forms</title>
1137
1138             <para>
1139                 The following methods may be used to interact with sub forms:
1140             </para>
1141
1142             <itemizedlist>
1143                 <listitem>
1144                     <para>
1145                         <methodname>addSubForm(Zend_Form $form, $name, $order = null)</methodname>
1146                     </para>
1147                 </listitem>
1148
1149                 <listitem>
1150                     <para>
1151                         <methodname>addSubForms(array $subForms)</methodname>
1152                     </para>
1153                 </listitem>
1154
1155                 <listitem>
1156                     <para>
1157                         <methodname>setSubForms(array $subForms)</methodname>
1158                     </para>
1159                 </listitem>
1160
1161                 <listitem>
1162                     <para>
1163                         <methodname>getSubForm($name)</methodname>
1164                     </para>
1165                 </listitem>
1166
1167                 <listitem>
1168                     <para>
1169                         <methodname>getSubForms()</methodname>
1170                     </para>
1171                 </listitem>
1172
1173                 <listitem>
1174                     <para>
1175                         <methodname>removeSubForm($name)</methodname>
1176                     </para>
1177                 </listitem>
1178
1179                 <listitem>
1180                     <para>
1181                         <methodname>clearSubForms()</methodname>
1182                     </para>
1183                 </listitem>
1184
1185                 <listitem>
1186                     <para>
1187                         <methodname>setSubFormDecorators(array $decorators)</methodname>
1188                     </para>
1189                 </listitem>
1190             </itemizedlist>
1191         </sect3>
1192     </sect2>
1193
1194     <sect2 id="zend.form.forms.metadata">
1195         <title>Metadata and Attributes</title>
1196
1197         <para>
1198             While a form's usefulness primarily derives from the elements it
1199             contains, it can also contain other metadata, such as a name (often
1200             used as a unique ID in the HTML markup); the form action and method;
1201             the number of elements, groups, and sub forms it contains; and
1202             arbitrary metadata (usually used to set HTML attributes for the form
1203             tag itself).
1204         </para>
1205
1206         <para>
1207             You can set and retrieve a form's name using the name accessors:
1208         </para>
1209
1210         <programlisting language="php"><![CDATA[
1211 // Set the name:
1212 $form->setName('registration');
1213
1214 // Retrieve the name:
1215 $name = $form->getName();
1216 ]]></programlisting>
1217
1218         <para>
1219             To set the action (url to which the form submits) and method (method
1220             by which it should submit, e.g., 'POST' or 'GET'), use the action
1221             and method accessors:
1222         </para>
1223
1224         <programlisting language="php"><![CDATA[
1225 // Set the action and method:
1226 $form->setAction('/user/login')
1227      ->setMethod('post');
1228 ]]></programlisting>
1229
1230         <para>
1231             You may also specify the form encoding type specifically using the
1232             enctype accessors. <classname>Zend_Form</classname> defines two constants,
1233             <constant>Zend_Form::ENCTYPE_URLENCODED</constant> and
1234             <constant>Zend_Form::ENCTYPE_MULTIPART</constant>, corresponding to the
1235             values 'application/x-www-form-urlencoded' and
1236             'multipart/form-data', respectively; however, you can set this to
1237             any arbitrary encoding type.
1238         </para>
1239
1240         <programlisting language="php"><![CDATA[
1241 // Set the action, method, and enctype:
1242 $form->setAction('/user/login')
1243      ->setMethod('post')
1244      ->setEnctype(Zend_Form::ENCTYPE_MULTIPART);
1245 ]]></programlisting>
1246
1247         <note>
1248             <para>
1249                 The method, action, and enctype are only used internally for rendering,
1250                 and not for any sort of validation.
1251             </para>
1252         </note>
1253
1254         <para>
1255             <classname>Zend_Form</classname> implements the <classname>Countable</classname>
1256             interface, allowing you to pass it as an argument to count:
1257         </para>
1258
1259         <programlisting language="php"><![CDATA[
1260 $numItems = count($form);
1261 ]]></programlisting>
1262
1263         <para>
1264             Setting arbitrary metadata is done through the attribs accessors.
1265             Since overloading in <classname>Zend_Form</classname> is used to access
1266             elements, display groups, and sub forms, this is the only method for
1267             accessing metadata.
1268         </para>
1269
1270         <programlisting language="php"><![CDATA[
1271 // Setting attributes:
1272 $form->setAttrib('class', 'zend-form')
1273      ->addAttribs(array(
1274          'id'       => 'registration',
1275          'onSubmit' => 'validate(this)',
1276      ));
1277
1278 // Retrieving attributes:
1279 $class = $form->getAttrib('class');
1280 $attribs = $form->getAttribs();
1281
1282 // Remove an attribute:
1283 $form->removeAttrib('onSubmit');
1284
1285 // Clear all attributes:
1286 $form->clearAttribs();
1287 ]]></programlisting>
1288     </sect2>
1289
1290     <sect2 id="zend.form.forms.decorators">
1291         <title>Decorators</title>
1292
1293         <para>
1294             Creating the markup for a form is often a time-consuming task,
1295             particularly if you plan on re-using the same markup to show things
1296             such as validation errors, submitted values, etc.
1297             <classname>Zend_Form</classname>'s answer to this issue is
1298             <emphasis>decorators</emphasis>.
1299         </para>
1300
1301         <para>
1302             Decorators for <classname>Zend_Form</classname> objects can be used to render
1303             a form. The FormElements decorator will iterate through all items in
1304             a form -- elements, display groups, and sub forms -- and render
1305             them, returning the result. Additional decorators may then be used
1306             to wrap this content, or append or prepend it.
1307         </para>
1308
1309         <para>
1310             The default decorators for <classname>Zend_Form</classname> are FormElements,
1311             HtmlTag (wraps in a definition list), and Form; the equivalent code
1312             for creating them is as follows:
1313         </para>
1314
1315         <programlisting language="php"><![CDATA[
1316 $form->setDecorators(array(
1317     'FormElements',
1318     array('HtmlTag', array('tag' => 'dl')),
1319     'Form'
1320 ));
1321 ]]></programlisting>
1322
1323         <para>
1324             This creates output like the following:
1325         </para>
1326
1327         <programlisting language="html"><![CDATA[
1328 <form action="/form/action" method="post">
1329 <dl>
1330 ...
1331 </dl>
1332 </form>
1333 ]]></programlisting>
1334
1335         <para>
1336             Any attributes set on the form object will be used as HTML
1337             attributes of the <emphasis>&lt;form&gt;</emphasis> tag.
1338         </para>
1339
1340         <note>
1341             <title>Default Decorators Do Not Need to Be Loaded</title>
1342
1343             <para>
1344                 By default, the default decorators are loaded during object
1345                 initialization. You can disable this by passing the
1346                 'disableLoadDefaultDecorators' option to the constructor:
1347             </para>
1348
1349             <programlisting language="php"><![CDATA[
1350 $form = new Zend_Form(array('disableLoadDefaultDecorators' => true));
1351 ]]></programlisting>
1352
1353             <para>
1354                 This option may be mixed with any other options you pass,
1355                 both as array options or in a <classname>Zend_Config</classname> object.
1356             </para>
1357         </note>
1358
1359         <note>
1360             <title>Using Multiple Decorators of the Same Type</title>
1361
1362             <para>
1363                 Internally, <classname>Zend_Form</classname> uses a decorator's
1364                 class as the lookup mechanism when retrieving decorators. As a
1365                 result, you cannot register multiple decorators of the same
1366                 type; subsequent decorators will simply overwrite those that
1367                 existed before.
1368             </para>
1369
1370             <para>
1371                 To get around this, you can use aliases. Instead of passing a
1372                 decorator or decorator name as the first argument to
1373                 <methodname>addDecorator()</methodname>, pass an array with a single
1374                 element, with the alias pointing to the decorator object or
1375                 name:
1376             </para>
1377
1378             <programlisting language="php"><![CDATA[
1379 // Alias to 'FooBar':
1380 $form->addDecorator(array('FooBar' => 'HtmlTag'), array('tag' => 'div'));
1381
1382 // And retrieve later:
1383 $form = $element->getDecorator('FooBar');
1384 ]]></programlisting>
1385
1386             <para>
1387                 In the <methodname>addDecorators()</methodname> and
1388                 <methodname>setDecorators()</methodname> methods, you will need to pass
1389                 the 'decorator' option in the array representing the decorator:
1390             </para>
1391
1392             <programlisting language="php"><![CDATA[
1393 // Add two 'HtmlTag' decorators, aliasing one to 'FooBar':
1394 $form->addDecorators(
1395     array('HtmlTag', array('tag' => 'div')),
1396     array(
1397         'decorator' => array('FooBar' => 'HtmlTag'),
1398         'options' => array('tag' => 'dd')
1399     ),
1400 );
1401
1402 // And retrieve later:
1403 $htmlTag = $form->getDecorator('HtmlTag');
1404 $fooBar  = $form->getDecorator('FooBar');
1405 ]]></programlisting>
1406         </note>
1407
1408         <para>
1409             You may create your own decorators for generating the form. One
1410             common use case is if you know the exact HTML you wish to use; your
1411             decorator could create the exact HTML and simply return it,
1412             potentially using the decorators from individual elements or display
1413             groups.
1414         </para>
1415
1416         <para>
1417             The following methods may be used to interact with decorators:
1418         </para>
1419
1420         <itemizedlist>
1421                 <listitem>
1422                     <para>
1423                         <methodname>addDecorator($decorator, $options = null)</methodname>
1424                     </para>
1425                 </listitem>
1426
1427                 <listitem>
1428                     <para>
1429                         <methodname>addDecorators(array $decorators)</methodname>
1430                     </para>
1431                 </listitem>
1432
1433                 <listitem>
1434                     <para>
1435                         <methodname>setDecorators(array $decorators)</methodname>
1436                     </para>
1437                 </listitem>
1438
1439                 <listitem>
1440                     <para>
1441                         <methodname>getDecorator($name)</methodname>
1442                     </para>
1443                 </listitem>
1444
1445                 <listitem>
1446                     <para>
1447                         <methodname>getDecorators()</methodname>
1448                     </para>
1449                 </listitem>
1450
1451                 <listitem>
1452                     <para>
1453                         <methodname>removeDecorator($name)</methodname>
1454                     </para>
1455                 </listitem>
1456
1457                 <listitem>
1458                     <para>
1459                         <methodname>clearDecorators()</methodname>
1460                     </para>
1461                 </listitem>
1462         </itemizedlist>
1463
1464         <para>
1465             <classname>Zend_Form</classname> also uses overloading to allow rendering
1466             specific decorators. <methodname>__call()</methodname> will intercept methods
1467             that lead with the text 'render' and use the remainder of the method
1468             name to lookup a decorator; if found, it will then render that
1469             <emphasis>single</emphasis> decorator. Any arguments passed to the
1470             method call will be used as content to pass to the decorator's
1471             <methodname>render()</methodname> method. As an example:
1472         </para>
1473
1474         <programlisting language="php"><![CDATA[
1475 // Render only the FormElements decorator:
1476 echo $form->renderFormElements();
1477
1478 // Render only the fieldset decorator, passing in content:
1479 echo $form->renderFieldset("<p>This is fieldset content</p>");
1480 ]]></programlisting>
1481
1482         <para>
1483             If the decorator does not exist, an exception is raised.
1484         </para>
1485     </sect2>
1486
1487     <sect2 id="zend.form.forms.validation">
1488         <title>Validation</title>
1489
1490         <para>
1491             A primary use case for forms is validating submitted data.
1492             <classname>Zend_Form</classname> allows you to validate an entire form, a partial form,
1493             or responses for XmlHttpRequests (AJAX). If the submitted data is not valid, it has
1494             methods for retrieving the various error codes and messages for
1495             elements and sub forms.
1496         </para>
1497
1498         <para>
1499             To validate a full form, use the <methodname>isValid()</methodname> method:
1500         </para>
1501
1502         <programlisting language="php"><![CDATA[
1503 if (!$form->isValid($_POST)) {
1504     // failed validation
1505 }
1506 ]]></programlisting>
1507
1508         <para>
1509             <methodname>isValid()</methodname> will validate every required element, and any
1510             unrequired element contained in the submitted data.
1511         </para>
1512
1513         <para>
1514             Sometimes you may need to validate only a subset of the data; for
1515             this, use <methodname>isValidPartial($data)</methodname>:
1516         </para>
1517
1518         <programlisting language="php"><![CDATA[
1519 if (!$form->isValidPartial($data)) {
1520     // failed validation
1521 }
1522 ]]></programlisting>
1523
1524         <para>
1525             <methodname>isValidPartial()</methodname> only attempts to validate those items
1526             in the data for which there are matching elements; if an element is
1527             not represented in the data, it is skipped.
1528         </para>
1529
1530         <para>
1531             When validating elements or groups of elements for an <acronym>AJAX</acronym> request,
1532             you will typically be validating a subset of the form, and want the
1533             response back in <acronym>JSON</acronym>. <methodname>processAjax()</methodname> does
1534             precisely that:
1535         </para>
1536
1537         <programlisting language="php"><![CDATA[
1538 $json = $form->processAjax($data);
1539 ]]></programlisting>
1540
1541         <para>
1542             You can then simply send the <acronym>JSON</acronym> response to the client. If the
1543             form is valid, this will be a boolean <constant>TRUE</constant> response. If not, it
1544             will be a javascript object containing key/message pairs, where each
1545             'message' is an array of validation error messages.
1546         </para>
1547
1548         <para>
1549             For forms that fail validation, you can retrieve both error codes
1550             and error messages, using <methodname>getErrors()</methodname> and
1551             <methodname>getMessages()</methodname>, respectively:
1552         </para>
1553
1554         <programlisting language="php"><![CDATA[
1555 $codes = $form->getErrors();
1556 $messages = $form->getMessages();
1557 ]]></programlisting>
1558
1559         <note>
1560             <para>
1561                 Since the messages returned by <methodname>getMessages()</methodname> are an
1562                 array of error code/message pairs, <methodname>getErrors()</methodname> is
1563                 typically not needed.
1564             </para>
1565         </note>
1566
1567         <para>
1568             You can retrieve codes and error messages for individual elements by
1569             simply passing the element name to each:
1570         </para>
1571
1572         <programlisting language="php"><![CDATA[
1573 $codes = $form->getErrors('username');
1574 $messages = $form->getMessages('username');
1575 ]]></programlisting>
1576
1577         <note>
1578             <para>
1579                 Note: When validating elements, <classname>Zend_Form</classname> sends a
1580                 second argument to each element's <methodname>isValid()</methodname> method:
1581                 the array of data being validated. This can then be used by
1582                 individual validators to allow them to utilize other submitted
1583                 values when determining the validity of the data. An example
1584                 would be a registration form that requires both a password and
1585                 password confirmation; the password element could use the
1586                 password confirmation as part of its validation.
1587             </para>
1588         </note>
1589
1590         <sect3 id="zend.form.forms.validation.errors">
1591             <title>Custom Error Messages</title>
1592
1593             <para>
1594                 At times, you may want to specify one or more specific error
1595                 messages to use instead of the error messages generated by the
1596                 validators attached to your elements. Additionally, at times you
1597                 may want to mark the form invalid yourself. This
1598                 functionality is possible via the following methods.
1599             </para>
1600
1601             <itemizedlist>
1602                 <listitem>
1603                     <para>
1604                         <methodname>addErrorMessage($message)</methodname>: add an error message
1605                         to display on form validation errors. You may call this more
1606                         than once, and new messages are appended to the stack.
1607                     </para>
1608                 </listitem>
1609
1610                 <listitem>
1611                     <para>
1612                         <methodname>addErrorMessages(array $messages)</methodname>: add multiple
1613                         error messages to display on form validation errors.
1614                     </para>
1615                 </listitem>
1616
1617                 <listitem>
1618                     <para>
1619                         <methodname>setErrorMessages(array $messages)</methodname>: add multiple
1620                         error messages to display on form validation errors,
1621                         overwriting all previously set error messages.
1622                     </para>
1623                 </listitem>
1624
1625                 <listitem>
1626                     <para>
1627                         <methodname>getErrorMessages()</methodname>: retrieve the list of
1628                         custom error messages that have been defined.
1629                     </para>
1630                 </listitem>
1631
1632                 <listitem>
1633                     <para>
1634                         <methodname>clearErrorMessages()</methodname>: remove all custom error
1635                         messages that have been defined.
1636                     </para>
1637                 </listitem>
1638
1639                 <listitem>
1640                     <para>
1641                         <methodname>markAsError()</methodname>: mark the form as having
1642                         failed validation.
1643                     </para>
1644                 </listitem>
1645
1646                 <listitem>
1647                     <para>
1648                         <methodname>addError($message)</methodname>: add a message to the custom
1649                         error messages stack and flag the form as invalid.
1650                     </para>
1651                 </listitem>
1652
1653                 <listitem>
1654                     <para>
1655                         <methodname>addErrors(array $messages)</methodname>: add several
1656                         messages to the custom error messages stack and flag the
1657                         form as invalid.
1658                     </para>
1659                 </listitem>
1660
1661                 <listitem>
1662                     <para>
1663                         <methodname>setErrors(array $messages)</methodname>: overwrite the
1664                         custom error messages stack with the provided messages and
1665                         flag the form as invalid.
1666                     </para>
1667                 </listitem>
1668             </itemizedlist>
1669
1670             <para>
1671                 All errors set in this fashion may be translated.
1672             </para>
1673         </sect3>
1674
1675         <sect3 id="zend.form.forms.validation.values">
1676             <title>Retrieving Valid Values Only</title>
1677
1678             <para>
1679                 There are scenarios when you want to allow your user to work on a valid form
1680                 in several steps. Meanwhile you allow the user to save the form with any
1681                 set of values inbetween. Then if all the data is specified you can transfer
1682                 the model from the building or prototying stage to a valid stage.
1683             </para>
1684
1685             <para>
1686                 You can retrieve all the valid values that match the submitted data by calling:
1687             </para>
1688
1689             <programlisting language="php"><![CDATA[
1690 $validValues = $form->getValidValues($_POST);
1691 ]]></programlisting>
1692         </sect3>
1693     </sect2>
1694
1695     <sect2 id="zend.form.forms.methods">
1696         <title>Methods</title>
1697
1698         <para>
1699             The following is a full list of methods available to
1700             <classname>Zend_Form</classname>, grouped by type:
1701         </para>
1702
1703         <itemizedlist>
1704             <listitem>
1705                 <para>Configuration and Options:</para>
1706
1707                 <itemizedlist>
1708                     <listitem>
1709                         <para><methodname>setOptions(array $options)</methodname></para>
1710                     </listitem>
1711
1712                     <listitem>
1713                         <para><methodname>setConfig(Zend_Config $config)</methodname></para>
1714                     </listitem>
1715                 </itemizedlist>
1716             </listitem>
1717
1718             <listitem>
1719                 <para>Plugin Loaders and paths:</para>
1720
1721                 <itemizedlist>
1722                     <listitem>
1723                         <para>
1724                             <methodname>setPluginLoader(Zend_Loader_PluginLoader_Interface $loader,
1725                                 $type = null)</methodname>
1726                         </para>
1727                     </listitem>
1728
1729                     <listitem>
1730                         <para><methodname>getPluginLoader($type = null)</methodname></para>
1731                     </listitem>
1732
1733                     <listitem>
1734                         <para>
1735                             <methodname>addPrefixPath($prefix, $path, $type = null) </methodname>
1736                         </para>
1737                     </listitem>
1738
1739                     <listitem>
1740                         <para><methodname>addPrefixPaths(array $spec)</methodname></para>
1741                     </listitem>
1742
1743                     <listitem>
1744                         <para>
1745                             <methodname>addElementPrefixPath($prefix, $path, $type
1746                                 = null)</methodname>
1747                         </para>
1748                     </listitem>
1749
1750                     <listitem>
1751                         <para><methodname>addElementPrefixPaths(array $spec)</methodname></para>
1752                     </listitem>
1753
1754                     <listitem>
1755                         <para>
1756                             <methodname>addDisplayGroupPrefixPath($prefix, $path)</methodname>
1757                         </para>
1758                     </listitem>
1759                 </itemizedlist>
1760             </listitem>
1761
1762             <listitem>
1763                 <para>Metadata:</para>
1764
1765                 <itemizedlist>
1766                     <listitem>
1767                         <para><methodname>setAttrib($key, $value)</methodname></para>
1768                     </listitem>
1769
1770                     <listitem>
1771                         <para><methodname>addAttribs(array $attribs)</methodname></para>
1772                     </listitem>
1773
1774                     <listitem>
1775                         <para><methodname>setAttribs(array $attribs)</methodname></para>
1776                     </listitem>
1777
1778                     <listitem><para><methodname>getAttrib($key)</methodname></para></listitem>
1779                     <listitem><para><methodname>getAttribs()</methodname></para></listitem>
1780                     <listitem><para><methodname>removeAttrib($key)</methodname></para></listitem>
1781                     <listitem><para><methodname>clearAttribs()</methodname></para></listitem>
1782                     <listitem><para><methodname>setAction($action)</methodname></para></listitem>
1783                     <listitem><para><methodname>getAction()</methodname></para></listitem>
1784                     <listitem><para><methodname>setMethod($method)</methodname></para></listitem>
1785                     <listitem><para><methodname>getMethod()</methodname></para></listitem>
1786                     <listitem><para><methodname>setName($name)</methodname></para></listitem>
1787                     <listitem><para><methodname>getName()</methodname></para></listitem>
1788                 </itemizedlist>
1789             </listitem>
1790
1791             <listitem>
1792                 <para>Elements:</para>
1793
1794                 <itemizedlist>
1795                     <listitem>
1796                         <para>
1797                             <methodname>addElement($element, $name = null, $options
1798                                 = null)</methodname>
1799                         </para>
1800                     </listitem>
1801
1802                     <listitem>
1803                         <para><methodname>addElements(array $elements)</methodname></para>
1804                     </listitem>
1805
1806                     <listitem>
1807                         <para><methodname>setElements(array $elements)</methodname></para>
1808                     </listitem>
1809
1810                     <listitem><para><methodname>getElement($name)</methodname></para></listitem>
1811                     <listitem><para><methodname>getElements()</methodname></para></listitem>
1812                     <listitem><para><methodname>removeElement($name)</methodname></para></listitem>
1813                     <listitem><para><methodname>clearElements()</methodname></para></listitem>
1814
1815                     <listitem>
1816                         <para><methodname>setDefaults(array $defaults)</methodname></para>
1817                     </listitem>
1818
1819                     <listitem>
1820                         <para><methodname>setDefault($name, $value)</methodname></para>
1821                     </listitem>
1822
1823                     <listitem><para><methodname>getValue($name)</methodname></para></listitem>
1824                     <listitem><para><methodname>getValues()</methodname></para></listitem>
1825
1826                     <listitem>
1827                         <para><methodname>getUnfilteredValue($name)</methodname></para>
1828                     </listitem>
1829
1830                     <listitem><para><methodname>getUnfilteredValues()</methodname></para></listitem>
1831
1832                     <listitem>
1833                         <para><methodname>setElementFilters(array $filters)</methodname></para>
1834                     </listitem>
1835
1836                     <listitem>
1837                         <para>
1838                             <methodname>setElementDecorators(array $decorators)</methodname>
1839                         </para>
1840                     </listitem>
1841                 </itemizedlist>
1842             </listitem>
1843
1844             <listitem>
1845                 <para>Sub forms:</para>
1846
1847                 <itemizedlist>
1848                     <listitem>
1849                         <para>
1850                             <methodname>addSubForm(Zend_Form $form, $name, $order
1851                                 = null)</methodname>
1852                         </para>
1853                     </listitem>
1854
1855                     <listitem>
1856                         <para><methodname>addSubForms(array $subForms)</methodname></para>
1857                     </listitem>
1858
1859                     <listitem>
1860                         <para><methodname>setSubForms(array $subForms)</methodname></para>
1861                     </listitem>
1862
1863                     <listitem><para><methodname>getSubForm($name)</methodname></para></listitem>
1864                     <listitem><para><methodname>getSubForms()</methodname></para></listitem>
1865                     <listitem><para><methodname>removeSubForm($name)</methodname></para></listitem>
1866                     <listitem><para><methodname>clearSubForms()</methodname></para></listitem>
1867
1868                     <listitem>
1869                         <para>
1870                             <methodname>setSubFormDecorators(array $decorators)</methodname>
1871                         </para>
1872                     </listitem>
1873                 </itemizedlist>
1874             </listitem>
1875
1876             <listitem>
1877                 <para>Display groups:</para>
1878
1879                 <itemizedlist>
1880                     <listitem>
1881                         <para>
1882                             <methodname>addDisplayGroup(array $elements, $name, $options
1883                                 = null)</methodname>
1884                         </para>
1885                     </listitem>
1886
1887                     <listitem>
1888                         <para><methodname>addDisplayGroups(array $groups)</methodname></para>
1889                     </listitem>
1890
1891                     <listitem>
1892                         <para><methodname>setDisplayGroups(array $groups)</methodname></para>
1893                     </listitem>
1894
1895                     <listitem>
1896                         <para><methodname>getDisplayGroup($name)</methodname></para>
1897                     </listitem>
1898
1899                     <listitem><para><methodname>getDisplayGroups()</methodname></para></listitem>
1900
1901                     <listitem>
1902                         <para><methodname>removeDisplayGroup($name)</methodname></para>
1903                     </listitem>
1904
1905                     <listitem><para><methodname>clearDisplayGroups()</methodname></para></listitem>
1906
1907                     <listitem>
1908                         <para>
1909                             <methodname>setDisplayGroupDecorators(array $decorators)</methodname>
1910                         </para>
1911                     </listitem>
1912                 </itemizedlist>
1913             </listitem>
1914
1915             <listitem>
1916                 <para>Validation</para>
1917
1918                 <itemizedlist>
1919                     <listitem>
1920                         <para><methodname>populate(array $values)</methodname></para>
1921                     </listitem>
1922
1923                     <listitem><para><methodname>isValid(array $data)</methodname></para></listitem>
1924
1925                     <listitem>
1926                         <para><methodname>isValidPartial(array $data)</methodname></para>
1927                     </listitem>
1928
1929                     <listitem>
1930                         <para><methodname>processAjax(array $data)</methodname></para>
1931                     </listitem>
1932
1933                     <listitem><para><methodname>persistData()</methodname></para></listitem>
1934
1935                     <listitem>
1936                         <para><methodname>getErrors($name = null)</methodname></para>
1937                     </listitem>
1938
1939                     <listitem>
1940                         <para><methodname>getMessages($name = null)</methodname></para>
1941                     </listitem>
1942                 </itemizedlist>
1943             </listitem>
1944
1945             <listitem>
1946                 <para>Rendering:</para>
1947
1948                 <itemizedlist>
1949                     <listitem>
1950                         <para>
1951                             <methodname>setView(Zend_View_Interface $view = null)</methodname>
1952                         </para>
1953                     </listitem>
1954
1955                     <listitem><para><methodname>getView()</methodname></para></listitem>
1956
1957                     <listitem>
1958                         <para>
1959                             <methodname>addDecorator($decorator, $options = null)</methodname>
1960                         </para>
1961                     </listitem>
1962
1963                     <listitem>
1964                         <para><methodname>addDecorators(array $decorators)</methodname></para>
1965                     </listitem>
1966
1967                     <listitem>
1968                         <para><methodname>setDecorators(array $decorators)</methodname></para>
1969                     </listitem>
1970
1971                     <listitem><para><methodname>getDecorator($name)</methodname></para></listitem>
1972                     <listitem><para><methodname>getDecorators()</methodname></para></listitem>
1973
1974                     <listitem>
1975                         <para><methodname>removeDecorator($name)</methodname></para>
1976                     </listitem>
1977
1978                     <listitem><para><methodname>clearDecorators()</methodname></para></listitem>
1979
1980                     <listitem>
1981                         <para>
1982                             <methodname>render(Zend_View_Interface $view = null)</methodname>
1983                         </para>
1984                     </listitem>
1985                 </itemizedlist>
1986             </listitem>
1987
1988             <listitem>
1989                 <para>I18n:</para>
1990
1991                 <itemizedlist>
1992                     <listitem>
1993                         <para>
1994                             <methodname>setTranslator(Zend_Translate_Adapter $translator
1995                                 = null)</methodname>
1996                         </para>
1997                     </listitem>
1998
1999                     <listitem><para><methodname>getTranslator()</methodname></para></listitem>
2000
2001                     <listitem>
2002                         <para><methodname>setDisableTranslator($flag)</methodname></para>
2003                     </listitem>
2004
2005                     <listitem>
2006                         <para><methodname>translatorIsDisabled()</methodname></para>
2007                     </listitem>
2008                 </itemizedlist>
2009             </listitem>
2010         </itemizedlist>
2011     </sect2>
2012
2013     <sect2 id="zend.form.forms.config">
2014         <title>Configuration</title>
2015
2016         <para>
2017             <classname>Zend_Form</classname> is fully configurable via
2018             <methodname>setOptions()</methodname> and <methodname>setConfig()</methodname> (or by
2019             passing options or a <classname>Zend_Config</classname> object to the
2020             constructor). Using these methods, you can specify form elements,
2021             display groups, decorators, and metadata.
2022         </para>
2023
2024         <para>
2025             As a general rule, if 'set' + the option key refers to a
2026             <classname>Zend_Form</classname> method, then the value provided will be
2027             passed to that method. If the accessor does not exist, the key is
2028             assumed to reference an attribute, and will be passed to
2029             <methodname>setAttrib()</methodname>.
2030         </para>
2031
2032         <para>
2033             Exceptions to the rule include the following:
2034         </para>
2035
2036         <itemizedlist>
2037             <listitem>
2038                 <para>
2039                     <property>prefixPaths</property> will be passed to
2040                     <methodname>addPrefixPaths()</methodname>
2041                 </para>
2042             </listitem>
2043
2044             <listitem>
2045                 <para>
2046                     <property>elementPrefixPaths</property> will be passed to
2047                     <methodname>addElementPrefixPaths()</methodname>
2048                 </para>
2049             </listitem>
2050
2051             <listitem>
2052                 <para>
2053                     <property>displayGroupPrefixPaths</property> will be passed to
2054                     <methodname>addDisplayGroupPrefixPaths()</methodname>
2055                 </para>
2056             </listitem>
2057
2058             <listitem>
2059                 <para>the following setters cannot be set in this way:</para>
2060
2061                 <itemizedlist>
2062                     <listitem>
2063                         <para><property>setAttrib</property> (though setAttribs *will* work)</para>
2064                     </listitem>
2065
2066                     <listitem><para><property>setConfig</property></para></listitem>
2067                     <listitem><para><property>setDefault</property></para></listitem>
2068                     <listitem><para><property>setOptions</property></para></listitem>
2069                     <listitem><para><property>setPluginLoader</property></para></listitem>
2070                     <listitem><para><property>setSubForms</property></para></listitem>
2071                     <listitem><para><property>setTranslator</property></para></listitem>
2072                     <listitem><para><property>setView</property></para></listitem>
2073                 </itemizedlist>
2074             </listitem>
2075         </itemizedlist>
2076
2077         <para>
2078             As an example, here is a config file that passes configuration for
2079             every type of configurable data:
2080         </para>
2081
2082         <programlisting language="ini"><![CDATA[
2083 [element]
2084 name = "registration"
2085 action = "/user/register"
2086 method = "post"
2087 attribs.class = "zend_form"
2088 attribs.onclick = "validate(this)"
2089
2090 disableTranslator = 0
2091
2092 prefixPath.element.prefix = "My_Element"
2093 prefixPath.element.path = "My/Element/"
2094 elementPrefixPath.validate.prefix = "My_Validate"
2095 elementPrefixPath.validate.path = "My/Validate/"
2096 displayGroupPrefixPath.prefix = "My_Group"
2097 displayGroupPrefixPath.path = "My/Group/"
2098
2099 elements.username.type = "text"
2100 elements.username.options.label = "Username"
2101 elements.username.options.validators.alpha.validator = "Alpha"
2102 elements.username.options.filters.lcase = "StringToLower"
2103 ; more elements, of course...
2104
2105 elementFilters.trim = "StringTrim"
2106 ;elementDecorators.trim = "StringTrim"
2107
2108 displayGroups.login.elements.username = "username"
2109 displayGroups.login.elements.password = "password"
2110 displayGroupDecorators.elements.decorator = "FormElements"
2111 displayGroupDecorators.fieldset.decorator = "Fieldset"
2112
2113 decorators.elements.decorator = "FormElements"
2114 decorators.fieldset.decorator = "FieldSet"
2115 decorators.fieldset.decorator.options.class = "zend_form"
2116 decorators.form.decorator = "Form"
2117 ]]></programlisting>
2118
2119         <para>
2120             The above could easily be abstracted to an <acronym>XML</acronym> or
2121             <acronym>PHP</acronym> array-based configuration file.
2122         </para>
2123     </sect2>
2124
2125     <sect2 id="zend.form.forms.custom">
2126         <title>Custom forms</title>
2127
2128         <para>
2129             An alternative to using configuration-based forms is to subclass
2130             <classname>Zend_Form</classname>. This has several benefits:
2131         </para>
2132
2133         <itemizedlist>
2134             <listitem>
2135                 <para>
2136                     You can unit test your form easily to ensure validations and
2137                     rendering perform as expected.
2138                 </para>
2139             </listitem>
2140
2141             <listitem>
2142                 <para>
2143                     Fine-grained control over individual elements.
2144                 </para>
2145             </listitem>
2146
2147             <listitem>
2148                 <para>
2149                     Re-use of form objects, and greater portability (no need to
2150                     track config files).
2151                 </para>
2152             </listitem>
2153
2154             <listitem>
2155                 <para>
2156                     Implementing custom functionality.
2157                 </para>
2158             </listitem>
2159         </itemizedlist>
2160
2161         <para>
2162             The most typical use case would be to use the
2163             <methodname>init()</methodname> method to setup specific form elements and
2164             configuration:
2165         </para>
2166
2167         <programlisting language="php"><![CDATA[
2168 class My_Form_Login extends Zend_Form
2169 {
2170     public function init()
2171     {
2172         $username = new Zend_Form_Element_Text('username');
2173         $username->class = 'formtext';
2174         $username->setLabel('Username:')
2175                  ->setDecorators(array(
2176                      array('ViewHelper',
2177                            array('helper' => 'formText')),
2178                      array('Label',
2179                            array('class' => 'label'))
2180                  ));
2181
2182         $password = new Zend_Form_Element_Password('password');
2183         $password->class = 'formtext';
2184         $password->setLabel('Username:')
2185                  ->setDecorators(array(
2186                      array('ViewHelper',
2187                            array('helper' => 'formPassword')),
2188                      array('Label',
2189                            array('class' => 'label'))
2190                  ));
2191
2192         $submit = new Zend_Form_Element_Submit('login');
2193         $submit->class = 'formsubmit';
2194         $submit->setValue('Login')
2195                ->setDecorators(array(
2196                    array('ViewHelper',
2197                    array('helper' => 'formSubmit'))
2198                ));
2199
2200         $this->addElements(array(
2201             $username,
2202             $password,
2203             $submit
2204         ));
2205
2206         $this->setDecorators(array(
2207             'FormElements',
2208             'Fieldset',
2209             'Form'
2210         ));
2211     }
2212 }
2213 ]]></programlisting>
2214
2215         <para>
2216             This form can then be instantiated with simply:
2217         </para>
2218
2219         <programlisting language="php"><![CDATA[
2220 $form = new My_Form_Login();
2221 ]]></programlisting>
2222
2223         <para>
2224             and all functionality is already setup and ready; no config files
2225             needed. (Note that this example is greatly simplified, as it
2226             contains no validators or filters for the elements.)
2227         </para>
2228
2229         <para>
2230             Another common reason for extension is to define a set of
2231             default decorators. You can do this by overriding the
2232             <methodname>loadDefaultDecorators()</methodname> method:
2233         </para>
2234
2235         <programlisting language="php"><![CDATA[
2236 class My_Form_Login extends Zend_Form
2237 {
2238     public function loadDefaultDecorators()
2239     {
2240         $this->setDecorators(array(
2241             'FormElements',
2242             'Fieldset',
2243             'Form'
2244         ));
2245     }
2246 }
2247 ]]></programlisting>
2248     </sect2>
2249 </sect1>
2250 <!--
2251 vim:se ts=4 sw=4 et:
2252 -->