| blob | 3878e5aa9df6899f82237577b9bbc089dad29868 |
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!-- Reviewed: no -->
3 <sect1 id="zend.form.standardElements">
4 <title>Standard Form Elements Shipped With Zend Framework</title>
6 <para>
7 Zend Framework ships with concrete element classes covering most HTML
8 form elements. Most simply specify a particular view helper for use when
9 decorating the element, but several offer additional functionality. The
10 following is a list of all such classes, as well as descriptions of the
11 functionality they offer.
12 </para>
14 <sect2 id="zend.form.standardElements.button">
15 <title>Zend_Form_Element_Button</title>
17 <para>
18 Used for creating HTML button elements,
19 <classname>Zend_Form_Element_Button</classname> extends <link
20 linkend="zend.form.standardElements.submit">Zend_Form_Element_Submit</link>,
21 specifying some custom functionality. It specifies the 'formButton'
22 view helper for decoration.
23 </para>
25 <para>
26 Like the submit element, it uses the element's label as the element
27 value for display purposes; in other words, to set the text of the
28 button, set the value of the element. The label will be translated
29 if a translation adapter is present.
30 </para>
32 <para>
33 Because the label is used as part of the element, the button element
34 uses only the <link
35 linkend="zend.form.standardDecorators.viewHelper">ViewHelper</link>
36 and <link
37 linkend="zend.form.standardDecorators.dtDdWrapper">DtDdWrapper</link>
38 decorators.
39 </para>
41 <para>
42 After populating or validating a form, you can check if the given
43 button was clicked using the <methodname>isChecked()</methodname> method.
44 </para>
45 </sect2>
47 <sect2 id="zend.form.standardElements.captcha">
48 <title>Zend_Form_Element_Captcha</title>
50 <para>
51 CAPTCHAs are used to prevent automated submission of forms by bots
52 and other automated processes.
53 </para>
55 <para>
56 The Captcha form element allows you to specify which <link
57 linkend="zend.captcha.adapters">Zend_Captcha adapter</link> you
58 wish to utilize as a form CAPTCHA. It then sets this adapter as a
59 validator to the object, and uses a Captcha decorator for rendering
60 (which proxies to the CAPTCHA adapter).
61 </para>
63 <para>
64 Adapters may be any adapters in <classname>Zend_Captcha</classname>, as well
65 as any custom adapters you may have defined elsewhere. To allow
66 this, you may pass an additional plugin loader type key, 'CAPTCHA'
67 or 'captcha', when specifying a plugin loader prefix path:
68 </para>
70 <programlisting language="php"><![CDATA[
71 $element->addPrefixPath('My_Captcha', 'My/Captcha/', 'captcha');
72 ]]></programlisting>
74 <para>
75 Captcha's may then be registered using the <methodname>setCaptcha()</methodname>
76 method, which can take either a concrete CAPTCHA instance, or the
77 short name of a CAPTCHA adapter:
78 </para>
80 <programlisting language="php"><![CDATA[
81 // Concrete instance:
82 $element->setCaptcha(new Zend_Captcha_Figlet());
84 // Using shortnames:
85 $element->setCaptcha('Dumb');
86 ]]></programlisting>
88 <para>
89 If you wish to load your element via configuration, specify either
90 the key 'captcha' with an array containing the key 'captcha', or
91 both the keys 'captcha' and 'captchaOptions':
92 </para>
94 <programlisting language="php"><![CDATA[
95 // Using single captcha key:
96 $element = new Zend_Form_Element_Captcha('foo', array(
97 'label' => "Please verify you're a human",
98 'captcha' => array(
99 'captcha' => 'Figlet',
100 'wordLen' => 6,
101 'timeout' => 300,
102 ),
103 ));
105 // Using both captcha and captchaOptions:
106 $element = new Zend_Form_Element_Captcha('foo', array(
107 'label' => "Please verify you're a human",
108 'captcha' => 'Figlet',
109 'captchaOptions' => array(
110 'captcha' => 'Figlet',
111 'wordLen' => 6,
112 'timeout' => 300,
113 ),
114 ));
115 ]]></programlisting>
117 <para>
118 The decorator used is determined by querying the captcha adapter. By
119 default, the <link
120 linkend="zend.form.standardDecorators.captcha">Captcha
121 decorator</link> is used, but an adapter may specify a different
122 one via its <methodname>getDecorator()</methodname> method.
123 </para>
125 <para>
126 As noted, the captcha adapter itself acts as a validator for the
127 element. Additionally, the NotEmpty validator is not used, and the
128 element is marked as required. In most cases, you should need to do
129 nothing else to have a captcha present in your form.
130 </para>
131 </sect2>
133 <sect2 id="zend.form.standardElements.checkbox">
134 <title>Zend_Form_Element_Checkbox</title>
136 <para>
137 HTML checkboxes allow you return a specific value, but basically
138 operate as booleans. When checked, the checkbox's value is submitted.
139 When the checkbox is not checked, nothing is submitted. Internally,
140 <classname>Zend_Form_Element_Checkbox</classname> enforces this state.
141 </para>
143 <para>
144 By default, the checked value is '1', and the unchecked value '0'.
145 You can specify the values to use using the <methodname>setCheckedValue()</methodname>
146 and <methodname>setUncheckedValue()</methodname> accessors, respectively. Internally,
147 any time you set the value, if the provided value matches the checked value, then it is
148 set, but any other value causes the unchecked value to be set.
149 </para>
151 <para>
152 Additionally, setting the value sets the <code>checked</code>
153 property of the checkbox. You can query this using
154 <methodname>isChecked()</methodname> or simply accessing the property. Using the
155 <methodname>setChecked($flag)</methodname> method will both set the state of the
156 flag as well as set the appropriate checked or unchecked value in the
157 element. Please use this method when setting the checked state of a
158 checkbox element to ensure the value is set properly.
159 </para>
161 <para>
162 <classname>Zend_Form_Element_Checkbox</classname> uses the 'formCheckbox' view
163 helper. The checked value is always used to populate it.
164 </para>
165 </sect2>
167 <sect2 id="zend.form.standardElements.file">
168 <title>Zend_Form_Element_File</title>
170 <para>
171 The File form element provides a mechanism for supplying file upload
172 fields to your form. It utilizes <link
173 linkend="zend.file.transfer.introduction">Zend_File_Transfer</link>
174 internally to provide this functionality, and the
175 <code>FormFile</code> view helper as also the <code>File</code>
176 decorator to display the form element.
177 </para>
179 <para>
180 By default, it uses the <code>Http</code> transfer adapter, which
181 introspects the <varname>$_FILES</varname> array and allows you to attach
182 validators and filters. Validators and filters attached to the form
183 element are in turn attached to the transfer adapter.
184 </para>
186 <example id="zend.form.standardElements.file.usage">
187 <title>File form element usage</title>
189 <para>
190 The above explanation of using the File form element may seem
191 arcane, but actual usage is relatively trivial:
192 </para>
194 <programlisting language="php"><![CDATA[
195 $element = new Zend_Form_Element_File('foo');
196 $element->setLabel('Upload an image:')
197 ->setDestination('/var/www/upload');
198 // ensure only 1 file
199 $element->addValidator('Count', false, 1);
200 // limit to 100K
201 $element->addValidator('Size', false, 102400);
202 // only JPEG, PNG, and GIFs
203 $element->addValidator('Extension', false, 'jpg,png,gif');
204 $form->addElement($element, 'foo');
205 ]]></programlisting>
207 <para>
208 You also need to ensure that the correct encoding type is provided to
209 the form; you should use 'multipart/form-data'. You can do this
210 by setting the 'enctype' attribute on the form:
211 </para>
213 <programlisting language="php"><![CDATA[
214 $form->setAttrib('enctype', 'multipart/form-data');
215 ]]></programlisting>
217 <para>
218 After the form is validated successfully, you must receive the file
219 to store it in the final destination using <methodname>receive()</methodname>.
220 Additionally you can determinate the final location using
221 <methodname>getFileName()</methodname>:
222 </para>
224 <programlisting language="php"><![CDATA[
225 if (!$form->isValid()) {
226 print "Uh oh... validation error";
227 }
229 if (!$form->foo->receive()) {
230 print "Error receiving the file";
231 }
233 $location = $form->foo->getFileName();
234 ]]></programlisting>
235 </example>
237 <note>
238 <title>Default Upload Location</title>
240 <para>
241 By default, files are uploaded to the system temp directory.
242 </para>
243 </note>
245 <note>
246 <title>File values</title>
248 <para>
249 Within <acronym>HTTP</acronym> a file element has no value. For this reason and
250 because of security concerns <methodname>getValue()</methodname> returns only the
251 uploaded filename and not the complete path. If you need the file path, call
252 <methodname>getFileName()</methodname>, which returns both the path and the name of
253 the file.
254 </para>
255 </note>
257 <para>
258 Per default the file will automatically be received when you call
259 <methodname>getValues()</methodname> on the form. The reason behind this behaviour is,
260 that the file itself is the value of the file element.
261 </para>
263 <programlisting language="php"><![CDATA[
264 $form->getValues();
265 ]]></programlisting>
267 <note>
268 <para>
269 Therefor another call of <methodname>receive()</methodname> after calling
270 <methodname>getValues()</methodname> will not have an effect. Also creating a
271 instance of <classname>Zend_File_Transfer</classname> will not have an effect as
272 there no file anymore to receive.
273 </para>
274 </note>
276 <para>
277 Still, sometimes you may want to call <methodname>getValues()</methodname> without
278 receiving the file. You can archive this by calling
279 <methodname>setValueDisabled(true)</methodname>. To get the actual value of this flag
280 you can call <methodname>isValueDisabled()</methodname>.
281 </para>
283 <example id="zend.form.standardElements.file.retrievement">
284 <title>Explicit file retrievement</title>
286 <para>
287 First call <methodname>setValueDisabled(true)</methodname>.
288 </para>
290 <programlisting language="php"><![CDATA[
291 $element = new Zend_Form_Element_File('foo');
292 $element->setLabel('Upload an image:')
293 ->setDestination('/var/www/upload')
294 ->setValueDisabled(true);
295 ]]></programlisting>
297 <para>
298 Now the file will not be received when you call
299 <methodname>getValues()</methodname>. So you must call
300 <methodname>receive()</methodname> on the file element, or an instance of
301 <classname>Zend_File_Transfer</classname> yourself.
302 </para>
304 <programlisting language="php"><![CDATA[
305 $values = $form->getValues();
307 if ($form->isValid($form->getPost())) {
308 if (!$form->foo->receive()) {
309 print "Upload error";
310 }
311 }
312 ]]></programlisting>
313 </example>
315 <para>
316 There are several states of the uploaded file which can be checked
317 with the following methods:
318 </para>
320 <itemizedlist>
321 <listitem>
322 <para>
323 <methodname>isUploaded()</methodname>: Checks if the file element has
324 been uploaded or not.
325 </para>
326 </listitem>
328 <listitem>
329 <para>
330 <methodname>isReceived()</methodname>: Checks if the file element has
331 already been received.
332 </para>
333 </listitem>
335 <listitem>
336 <para>
337 <methodname>isFiltered()</methodname>: Checks if the filters have already
338 been applied to the file element or not.
339 </para>
340 </listitem>
341 </itemizedlist>
343 <example id="zend.form.standardElements.file.isuploaded">
344 <title>Checking if an optional file has been uploaded</title>
346 <programlisting language="php"><![CDATA[
347 $element = new Zend_Form_Element_File('foo');
348 $element->setLabel('Upload an image:')
349 ->setDestination('/var/www/upload')
350 ->setRequired(false);
351 $element->addValidator('Size', false, 102400);
352 $form->addElement($element, 'foo');
354 // The foo file element is optional but when it's given go into here
355 if ($form->foo->isUploaded()) {
356 // foo file given... do something
357 }
358 ]]></programlisting>
359 </example>
361 <para>
362 <classname>Zend_Form_Element_File</classname> also supports multiple files.
363 By calling the <methodname>setMultiFile($count)</methodname> method you can set
364 the number of file elements you want to create. This keeps you
365 from setting the same settings multiple times.
366 </para>
368 <example id="zend.form.standardElements.file.multiusage">
369 <title>Setting multiple files</title>
371 <para>
372 Creating a multifile element is the same as setting a single element.
373 Just call <methodname>setMultiFile()</methodname> after the element is created:
374 </para>
376 <programlisting language="php"><![CDATA[
377 $element = new Zend_Form_Element_File('foo');
378 $element->setLabel('Upload an image:')
379 ->setDestination('/var/www/upload');
380 // ensure minimum 1, maximum 3 files
381 $element->addValidator('Count', false, array('min' => 1, 'max' => 3));
382 // limit to 100K
383 $element->addValidator('Size', false, 102400);
384 // only JPEG, PNG, and GIFs
385 $element->addValidator('Extension', false, 'jpg,png,gif');
386 // defines 3 identical file elements
387 $element->setMultiFile(3);
388 $form->addElement($element, 'foo');
389 ]]></programlisting>
391 <para>
392 You now have 3 identical file upload elements
393 with the same settings. To get the set multifile number simply call
394 <methodname>getMultiFile()</methodname>.
395 </para>
397 </example>
399 <note>
400 <title>File elements in Subforms</title>
402 <para>
403 When you use file elements in subforms you must set unique names.
404 For example, if you name a file element in subform1 "file", you must give
405 any file element in subform2 a different name.
406 </para>
408 <para>
409 If there are 2 file elements with the same name, the second
410 element is not be displayed or submitted.
411 </para>
413 <para>
414 Additionally, file elements are not rendered within the sub-form. So when
415 you add a file element into a subform, then the element will be rendered
416 within the main form.
417 </para>
418 </note>
420 <para>
421 To limit the size of the file uploaded, you can
422 specify the maximum file size by setting the <constant>MAX_FILE_SIZE</constant>
423 option on the form. When you set this value by using the
424 <methodname>setMaxFileSize($size)</methodname> method, it will be rendered with the
425 file element.
426 </para>
428 <programlisting language="php"><![CDATA[
429 $element = new Zend_Form_Element_File('foo');
430 $element->setLabel('Upload an image:')
431 ->setDestination('/var/www/upload')
432 ->addValidator('Size', false, 102400) // limit to 100K
433 ->setMaxFileSize(102400); // limits the filesize on the client side
434 $form->addElement($element, 'foo');
435 ]]></programlisting>
437 <note>
438 <title>MaxFileSize with Multiple File Elements</title>
440 <para>
441 When you use multiple file elements in your form you should set
442 the <constant>MAX_FILE_SIZE</constant> only once. Setting it again will
443 overwrite the previous value.
444 </para>
446 <para>
447 Note, that this is also the case when you use multiple forms.
448 </para>
449 </note>
450 </sect2>
452 <sect2 id="zend.form.standardElements.hidden">
453 <title>Zend_Form_Element_Hidden</title>
455 <para>
456 Hidden elements inject data that should be submitted, but that should not manipulated by
457 the user . <classname>Zend_Form_Element_Hidden</classname> accomplishes this with the
458 'formHidden' view helper.
459 </para>
460 </sect2>
462 <sect2 id="zend.form.standardElements.hash">
463 <title>Zend_Form_Element_Hash</title>
465 <para>
466 This element provides protection from CSRF attacks on forms,
467 ensuring the data is submitted by the user session that generated
468 the form and not by a rogue script. Protection is achieved by adding
469 a hash element to a form and verifying it when the form is
470 submitted.
471 </para>
473 <para>
474 The name of the hash element should be unique. We recommend using
475 the <literal>salt</literal> option for the element- two hashes with
476 same names and different salts would not collide:
477 </para>
479 <programlisting language="php"><![CDATA[
480 $form->addElement('hash', 'no_csrf_foo', array('salt' => 'unique'));
481 ]]></programlisting>
483 <para>
484 You can set the salt later using the <methodname>setSalt($salt)</methodname>
485 method.
486 </para>
488 <para>
489 Internally, the element stores a unique identifier using
490 <classname>Zend_Session_Namespace</classname>, and checks for it at
491 submission (checking that the TTL has not expired). The 'Identical'
492 validator is then used to ensure the submitted hash matches the
493 stored hash.
494 </para>
496 <para>
497 The 'formHidden' view helper is used to render the element in the
498 form.
499 </para>
500 </sect2>
502 <sect2 id="zend.form.standardElements.Image">
503 <title>Zend_Form_Element_Image</title>
505 <para>
506 Images can be used as form elements, and you can use these images as
507 graphical elements on form buttons.
508 </para>
510 <para>
511 Images need an image source. <classname>Zend_Form_Element_Image</classname>
512 allows you to specify this by using the <methodname>setImage()</methodname>
513 accessor (or 'image' configuration key). You can also optionally specify a value to use
514 when submitting the image using the <methodname>setImageValue()</methodname> accessor
515 (or 'imageValue' configuration key). When the value set for the
516 element matches the <code>imageValue</code>, then the accessor
517 <methodname>isChecked()</methodname> will return <constant>TRUE</constant>.
518 </para>
520 <para>
521 Image elements use the
522 <link linkend="zend.form.standardDecorators.image">Image
523 Decorator</link> for rendering, in addition to the standard Errors,
524 HtmlTag, and Label decorators. You can optionally specify a tag to
525 the <code>Image</code> decorator that will then wrap the image
526 element.
527 </para>
528 </sect2>
530 <sect2 id="zend.form.standardElements.multiCheckbox">
531 <title>Zend_Form_Element_MultiCheckbox</title>
533 <para>
534 Often you have a set of related checkboxes, and you wish to group
535 the results. This is much like a <link
536 linkend="zend.form.standardElements.multiselect">Multiselect</link>,
537 but instead of them being in a dropdown list, you need to show
538 checkbox/value pairs.
539 </para>
541 <para>
542 <classname>Zend_Form_Element_MultiCheckbox</classname> makes this a snap. Like
543 all other elements extending the base Multi element, you can specify
544 a list of options, and easily validate against that same list. The
545 'formMultiCheckbox' view helper ensures that these are returned as
546 an array in the form submission.
547 </para>
549 <para>
550 By default, this element registers an <code>InArray</code> validator
551 which validates against the array keys of registered options. You
552 can disable this behavior by either calling
553 <methodname>setRegisterInArrayValidator(false)</methodname>, or by passing a
554 <constant>FALSE</constant> value to the <code>registerInArrayValidator</code>
555 configuration key.
556 </para>
558 <para>
559 You may manipulate the various checkbox options using the following
560 methods:
561 </para>
563 <itemizedlist>
564 <listitem>
565 <para><methodname>addMultiOption($option, $value)</methodname></para>
566 </listitem>
568 <listitem>
569 <para><methodname>addMultiOptions(array $options)</methodname></para>
570 </listitem>
572 <listitem>
573 <para>
574 <methodname>setMultiOptions(array $options)</methodname> (overwrites existing
575 options)
576 </para>
577 </listitem>
579 <listitem><para><methodname>getMultiOption($option)</methodname></para></listitem>
580 <listitem><para><methodname>getMultiOptions()</methodname></para></listitem>
581 <listitem><para><methodname>removeMultiOption($option)</methodname></para></listitem>
582 <listitem><para><methodname>clearMultiOptions()</methodname></para></listitem>
583 </itemizedlist>
585 <para>
586 To mark checked items, you need to pass an array of values to
587 <methodname>setValue()</methodname>. The following will check the values "bar"
588 and "bat":
589 </para>
591 <programlisting language="php"><![CDATA[
592 $element = new Zend_Form_Element_MultiCheckbox('foo', array(
593 'multiOptions' => array(
594 'foo' => 'Foo Option',
595 'bar' => 'Bar Option',
596 'baz' => 'Baz Option',
597 'bat' => 'Bat Option',
598 );
599 ));
601 $element->setValue(array('bar', 'bat'));
602 ]]></programlisting>
604 <para>
605 Note that even when setting a single value, you must pass an array.
606 </para>
607 </sect2>
609 <sect2 id="zend.form.standardElements.multiselect">
610 <title>Zend_Form_Element_Multiselect</title>
612 <para>
613 <acronym>XHTML</acronym> <code>select</code> elements allow a 'multiple' attribute,
614 indicating multiple options may be selected for submission, instead
615 of the usual one. <classname>Zend_Form_Element_Multiselect</classname> extends
616 <link
617 linkend="zend.form.standardElements.select">Zend_Form_Element_Select</link>,
618 and sets the <code>multiple</code> attribute to 'multiple'. Like
619 other classes that inherit from the base
620 <classname>Zend_Form_Element_Multi</classname> class, you can manipulate the
621 options for the select using:
622 </para>
624 <itemizedlist>
625 <listitem>
626 <para><methodname>addMultiOption($option, $value)</methodname></para>
627 </listitem>
629 <listitem>
630 <para><methodname>addMultiOptions(array $options)</methodname></para>
631 </listitem>
633 <listitem>
634 <para>
635 <methodname>setMultiOptions(array $options)</methodname> (overwrites existing
636 options)
637 </para>
638 </listitem>
640 <listitem><para><methodname>getMultiOption($option)</methodname></para></listitem>
641 <listitem><para><methodname>getMultiOptions()</methodname></para></listitem>
642 <listitem><para><methodname>removeMultiOption($option)</methodname></para></listitem>
643 <listitem><para><methodname>clearMultiOptions()</methodname></para></listitem>
644 </itemizedlist>
646 <para>
647 If a translation adapter is registered with the form and/or element,
648 option values will be translated for display purposes.
649 </para>
651 <para>
652 By default, this element registers an <code>InArray</code> validator
653 which validates against the array keys of registered options. You
654 can disable this behavior by either calling
655 <methodname>setRegisterInArrayValidator(false)</methodname>, or by passing a
656 <constant>FALSE</constant> value to the <code>registerInArrayValidator</code>
657 configuration key.
658 </para>
659 </sect2>
661 <sect2 id="zend.form.standardElements.password">
662 <title>Zend_Form_Element_Password</title>
664 <para>
665 Password elements are basically normal text elements -- except that
666 you typically do not want the submitted password displayed in error
667 messages or the element itself when the form is re-displayed.
668 </para>
670 <para>
671 <classname>Zend_Form_Element_Password</classname> achieves this by calling
672 <methodname>setObscureValue(true)</methodname> on each validator (ensuring that
673 the password is obscured in validation error messages), and using
674 the 'formPassword' view helper (which does not display the value
675 passed to it).
676 </para>
677 </sect2>
679 <sect2 id="zend.form.standardElements.radio">
680 <title>Zend_Form_Element_Radio</title>
682 <para>
683 Radio elements allow you to specify several options, of which you
684 need a single value returned. <classname>Zend_Form_Element_Radio</classname>
685 extends the base <classname>Zend_Form_Element_Multi</classname> class,
686 allowing you to specify a number of options, and then uses the
687 <code>formRadio</code> view helper to display these.
688 </para>
690 <para>
691 By default, this element registers an <code>InArray</code> validator
692 which validates against the array keys of registered options. You
693 can disable this behavior by either calling
694 <methodname>setRegisterInArrayValidator(false)</methodname>, or by passing a
695 <constant>FALSE</constant> value to the <code>registerInArrayValidator</code>
696 configuration key.
697 </para>
699 <para>
700 Like all elements extending the Multi element base class, the
701 following methods may be used to manipulate the radio options
702 displayed:
703 </para>
705 <itemizedlist>
706 <listitem>
707 <para><methodname>addMultiOption($option, $value)</methodname></para>
708 </listitem>
710 <listitem>
711 <para><methodname>addMultiOptions(array $options)</methodname></para>
712 </listitem>
714 <listitem>
715 <para>
716 <methodname>setMultiOptions(array $options)</methodname>
717 (overwrites existing options)
718 </para>
719 </listitem>
721 <listitem><para><methodname>getMultiOption($option)</methodname></para></listitem>
722 <listitem><para><methodname>getMultiOptions()</methodname></para></listitem>
723 <listitem><para><methodname>removeMultiOption($option)</methodname></para></listitem>
724 <listitem><para><methodname>clearMultiOptions()</methodname></para></listitem>
725 </itemizedlist>
726 </sect2>
728 <sect2 id="zend.form.standardElements.reset">
729 <title>Zend_Form_Element_Reset</title>
731 <para>
732 Reset buttons are typically used to clear a form, and are not part
733 of submitted data. However, as they serve a purpose in the display,
734 they are included in the standard elements.
735 </para>
737 <para>
738 <classname>Zend_Form_Element_Reset</classname> extends <link
739 linkend="zend.form.standardElements.submit">Zend_Form_Element_Submit</link>.
740 As such, the label is used for the button display, and will be
741 translated if a translation adapter is present. It utilizes only the
742 'ViewHelper' and 'DtDdWrapper' decorators, as there should never be
743 error messages for such elements, nor will a label be necessary.
744 </para>
745 </sect2>
747 <sect2 id="zend.form.standardElements.select">
748 <title>Zend_Form_Element_Select</title>
750 <para>
751 Select boxes are a common way of limiting to specific choices for a
752 given form datum. <classname>Zend_Form_Element_Select</classname> allows you
753 to generate these quickly and easily.
754 </para>
756 <para>
757 By default, this element registers an <code>InArray</code> validator
758 which validates against the array keys of registered options. You
759 can disable this behavior by either calling
760 <methodname>setRegisterInArrayValidator(false)</methodname>, or by passing a
761 <constant>FALSE</constant> value to the <code>registerInArrayValidator</code>
762 configuration key.
763 </para>
765 <para>
766 As it extends the base Multi element, the following methods may be
767 used to manipulate the select options:
768 </para>
770 <itemizedlist>
771 <listitem>
772 <para><methodname>addMultiOption($option, $value)</methodname></para>
773 </listitem>
775 <listitem>
776 <para><methodname>addMultiOptions(array $options)</methodname></para>
777 </listitem>
779 <listitem>
780 <para>
781 <methodname>setMultiOptions(array $options)</methodname>
782 (overwrites existing options)
783 </para>
784 </listitem>
786 <listitem><para><methodname>getMultiOption($option)</methodname></para></listitem>
787 <listitem><para><methodname>getMultiOptions()</methodname></para></listitem>
788 <listitem><para><methodname>removeMultiOption($option)</methodname></para></listitem>
789 <listitem><para><methodname>clearMultiOptions()</methodname></para></listitem>
790 </itemizedlist>
792 <para>
793 <classname>Zend_Form_Element_Select</classname> uses the 'formSelect' view
794 helper for decoration.
795 </para>
796 </sect2>
798 <sect2 id="zend.form.standardElements.submit">
799 <title>Zend_Form_Element_Submit</title>
801 <para>
802 Submit buttons are used to submit a form. You may use multiple
803 submit buttons; you can use the button used to submit the form to
804 decide what action to take with the data submitted.
805 <classname>Zend_Form_Element_Submit</classname> makes this decisioning easy,
806 by adding a <methodname>isChecked()</methodname> method; as only one button
807 element will be submitted by the form, after populating or
808 validating the form, you can call this method on each submit button
809 to determine which one was used.
810 </para>
812 <para>
813 <classname>Zend_Form_Element_Submit</classname> uses the label as the "value"
814 of the submit button, translating it if a translation adapter is
815 present. <methodname>isChecked()</methodname> checks the submitted value against
816 the label in order to determine if the button was used.
817 </para>
819 <para>
820 The <link
821 linkend="zend.form.standardDecorators.viewHelper">ViewHelper</link>
822 and <link
823 linkend="zend.form.standardDecorators.dtDdWrapper">DtDdWrapper</link>
824 decorators to render the element. No label decorator is used, as the
825 button label is used when rendering the element; also, typically,
826 you will not associate errors with a submit element.
827 </para>
828 </sect2>
830 <sect2 id="zend.form.standardElements.text">
831 <title>Zend_Form_Element_Text</title>
833 <para>
834 By far the most prevalent type of form element is the text element,
835 allowing for limited text entry; it's an ideal element for most data
836 entry. <classname>Zend_Form_Element_Text</classname> simply uses the
837 'formText' view helper to display the element.
838 </para>
839 </sect2>
841 <sect2 id="zend.form.standardElements.textarea">
842 <title>Zend_Form_Element_Textarea</title>
844 <para>
845 Textareas are used when large quantities of text are expected, and
846 place no limits on the amount of text submitted (other than maximum
847 size limits as dictated by your server or <acronym>PHP</acronym>).
848 <classname>Zend_Form_Element_Textarea</classname> uses the 'textArea' view
849 helper to display such elements, placing the value as the content of
850 the element.
851 </para>
852 </sect2>
853 </sect1>
854 <!--
855 vim:se ts=4 sw=4 tw=80 et:
856 -->