| blob | f4b550fa040286c2b92ea4fb7e889b6821d9984a |
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!-- Reviewed: no -->
3 <sect1 id="zend.form.elements">
4 <title>Creating Form Elements Using Zend_Form_Element</title>
6 <para>
7 A form is made of elements that typically correspond to HTML form
8 input. <classname>Zend_Form_Element</classname> encapsulates single form elements, with the
9 following areas of responsibility:
10 </para>
12 <itemizedlist>
13 <listitem>
14 <para>
15 validation (is submitted data valid?)
16 </para>
18 <itemizedlist>
19 <listitem><para>capturing of validation error codes and messages</para></listitem>
20 </itemizedlist>
21 </listitem>
23 <listitem>
24 <para>
25 filtering (how is the element escaped or normalized prior to
26 validation and/or for output?)
27 </para>
28 </listitem>
30 <listitem>
31 <para>rendering (how is the element displayed?)</para>
32 </listitem>
34 <listitem>
35 <para>metadata and attributes (what information further qualifies the element?)</para>
36 </listitem>
37 </itemizedlist>
39 <para>
40 The base class, <classname>Zend_Form_Element</classname>, has reasonable defaults
41 for many cases, but it is best to extend the class for commonly used
42 special purpose elements. Additionally, Zend Framework ships with a
43 number of standard <acronym>XHTML</acronym> elements; you can read about them <link
44 linkend="zend.form.standardElements">in the Standard Elements
45 chapter</link>.
46 </para>
48 <sect2 id="zend.form.elements.loaders">
49 <title>Plugin Loaders</title>
51 <para>
52 <classname>Zend_Form_Element</classname> makes use of <link
53 linkend="zend.loader.pluginloader">Zend_Loader_PluginLoader</link>
54 to allow developers to specify locations of alternate validators,
55 filters, and decorators. Each has its own plugin loader associated
56 with it, and general accessors are used to retrieve and modify
57 each.
58 </para>
60 <para>
61 The following loader types are used with the various plugin loader
62 methods: 'validate', 'filter', and 'decorator'. The type names are
63 case insensitive.
64 </para>
66 <para>
67 The methods used to interact with plugin loaders are as follows:
68 </para>
70 <itemizedlist>
71 <listitem>
72 <para>
73 <methodname>setPluginLoader($loader, $type)</methodname>:
74 <varname>$loader</varname> is the plugin loader object itself, while
75 <varname>$type</varname> is one of the types specified above. This
76 sets the plugin loader for the given type to the newly
77 specified loader object.
78 </para>
79 </listitem>
81 <listitem>
82 <para>
83 <methodname>getPluginLoader($type)</methodname>: retrieves the plugin
84 loader associated with <varname>$type</varname>.
85 </para>
86 </listitem>
88 <listitem>
89 <para>
90 <methodname>addPrefixPath($prefix, $path, $type = null)</methodname>: adds
91 a prefix/path association to the loader specified by
92 <varname>$type</varname>. If <varname>$type</varname> is
93 <constant>NULL</constant>, it will attempt to add the path to all loaders, by
94 appending the prefix with each of "_Validate", "_Filter", and "_Decorator"; and
95 appending the path with "Validate/", "Filter/", and
96 "Decorator/". If you have all your extra form element classes
97 under a common hierarchy, this is a convenience method for
98 setting the base prefix for them.
99 </para>
100 </listitem>
102 <listitem>
103 <para>
104 <methodname>addPrefixPaths(array $spec)</methodname>: allows you to add
105 many paths at once to one or more plugin loaders. It expects
106 each array item to be an array with the keys 'path', 'prefix',
107 and 'type'.
108 </para>
109 </listitem>
110 </itemizedlist>
112 <para>
113 Custom validators, filters, and decorators are an easy way to share
114 functionality between forms and to encapsulate custom functionality.
115 </para>
117 <example id="zend.form.elements.loaders.customLabel">
118 <title>Custom Label</title>
120 <para>
121 One common use case for plugins is to provide replacements for
122 standard classes. For instance, if you want to provide a
123 different implementation of the 'Label' decorator -- for
124 instance, to always append a colon -- you could create your own
125 'Label' decorator with your own class prefix, and then add it to
126 your prefix path.
127 </para>
129 <para>
130 Let's start with a custom Label decorator. We'll give it the
131 class prefix "My_Decorator", and the class itself will be in the
132 file "My/Decorator/Label.php".
133 </para>
135 <programlisting language="php"><![CDATA[
136 class My_Decorator_Label extends Zend_Form_Decorator_Abstract
137 {
138 protected $_placement = 'PREPEND';
140 public function render($content)
141 {
142 if (null === ($element = $this->getElement())) {
143 return $content;
144 }
145 if (!method_exists($element, 'getLabel')) {
146 return $content;
147 }
149 $label = $element->getLabel() . ':';
151 if (null === ($view = $element->getView())) {
152 return $this->renderLabel($content, $label);
153 }
155 $label = $view->formLabel($element->getName(), $label);
157 return $this->renderLabel($content, $label);
158 }
160 public function renderLabel($content, $label)
161 {
162 $placement = $this->getPlacement();
163 $separator = $this->getSeparator();
165 switch ($placement) {
166 case 'APPEND':
167 return $content . $separator . $label;
168 case 'PREPEND':
169 default:
170 return $label . $separator . $content;
171 }
172 }
173 }
174 ]]></programlisting>
176 <para>
177 Now we can tell the element to use this plugin path when looking
178 for decorators:
179 </para>
181 <programlisting language="php"><![CDATA[
182 $element->addPrefixPath('My_Decorator', 'My/Decorator/', 'decorator');
183 ]]></programlisting>
185 <para>
186 Alternately, we can do that at the form level to ensure all
187 decorators use this path:
188 </para>
190 <programlisting language="php"><![CDATA[
191 $form->addElementPrefixPath('My_Decorator', 'My/Decorator/', 'decorator');
192 ]]></programlisting>
194 <para>
195 After it added as in the example above, the 'My/Decorator/' path will be searched
196 first to see if the decorator exists there when you add a decorator. As a result,
197 'My_Decorator_Label' will now be used when the 'Label' decorator is requested.
198 </para>
199 </example>
200 </sect2>
202 <sect2 id="zend.form.elements.filters">
203 <title>Filters</title>
205 <para>
206 It's often useful and/or necessary to perform some normalization on
207 input prior to validation. For example, you may want to strip out
208 all HTML, but run your validations on what remains to ensure the
209 submission is valid. Or you may want to trim empty space surrounding input so that a
210 StringLength validator will use the correct length of the input without counting leading
211 or trailing whitespace characters. These operations may be performed using
212 <classname>Zend_Filter</classname>. <classname>Zend_Form_Element</classname> has support
213 for filter chains, allowing you to specify multiple, sequential filters. Filtering
214 happens both during validation and when you retrieve the element value via
215 <methodname>getValue()</methodname>:
216 </para>
218 <programlisting language="php"><![CDATA[
219 $filtered = $element->getValue();
220 ]]></programlisting>
222 <para>
223 Filters may be added to the chain in two ways:
224 </para>
226 <itemizedlist>
227 <listitem>
228 <para>
229 passing in a concrete filter instance
230 </para>
231 </listitem>
233 <listitem>
234 <para>
235 providing a filter name – either a short name or fully
236 qualified class name
237 </para>
238 </listitem>
239 </itemizedlist>
241 <para>
242 Let's see some examples:
243 </para>
245 <programlisting language="php"><![CDATA[
246 // Concrete filter instance:
247 $element->addFilter(new Zend_Filter_Alnum());
249 // Fully qualified class name:
250 $element->addFilter('Zend_Filter_Alnum');
252 // Short filter name:
253 $element->addFilter('Alnum');
254 $element->addFilter('alnum');
255 ]]></programlisting>
257 <para>
258 Short names are typically the filter name minus the prefix. In the
259 default case, this will mean minus the 'Zend_Filter_' prefix.
260 The first letter can be upper-cased or lower-cased.
261 </para>
263 <note>
264 <title>Using Custom Filter Classes</title>
266 <para>
267 If you have your own set of filter classes, you can tell
268 <classname>Zend_Form_Element</classname> about these using
269 <methodname>addPrefixPath()</methodname>. For instance, if you have
270 filters under the 'My_Filter' prefix, you can tell
271 <classname>Zend_Form_Element</classname> about this as follows:
272 </para>
274 <programlisting language="php"><![CDATA[
275 $element->addPrefixPath('My_Filter', 'My/Filter/', 'filter');
276 ]]></programlisting>
278 <para>
279 (Recall that the third argument indicates which plugin loader
280 on which to perform the action.)
281 </para>
282 </note>
284 <para>
285 If at any time you need the unfiltered value, use the
286 <methodname>getUnfilteredValue()</methodname> method:
287 </para>
289 <programlisting language="php"><![CDATA[
290 $unfiltered = $element->getUnfilteredValue();
291 ]]></programlisting>
293 <para>
294 For more information on filters, see the <link
295 linkend="zend.filter.introduction">Zend_Filter
296 documentation</link>.
297 </para>
299 <para>
300 Methods associated with filters include:
301 </para>
303 <itemizedlist>
304 <listitem>
305 <para>
306 <methodname>addFilter($nameOfFilter, array $options = null)</methodname>
307 </para>
308 </listitem>
310 <listitem>
311 <para>
312 <methodname>addFilters(array $filters)</methodname>
313 </para>
314 </listitem>
316 <listitem>
317 <para>
318 <methodname>setFilters(array $filters)</methodname> (overwrites all filters)
319 </para>
320 </listitem>
322 <listitem>
323 <para>
324 <methodname>getFilter($name)</methodname> (retrieve a filter object by name)
325 </para>
326 </listitem>
328 <listitem>
329 <para>
330 <methodname>getFilters()</methodname> (retrieve all filters)
331 </para>
332 </listitem>
334 <listitem>
335 <para>
336 <methodname>removeFilter($name)</methodname> (remove filter by name)
337 </para>
338 </listitem>
340 <listitem>
341 <para>
342 <methodname>clearFilters()</methodname> (remove all filters)
343 </para>
344 </listitem>
345 </itemizedlist>
346 </sect2>
348 <sect2 id="zend.form.elements.validators">
349 <title>Validators</title>
351 <para>
352 If you subscribe to the security mantra of "filter input, escape
353 output," you'll should use validator to filter input submitted with your form.
354 In <classname>Zend_Form</classname>, each element includes its own validator
355 chain, consisting of <classname>Zend_Validate_*</classname> validators.
356 </para>
358 <para>
359 Validators may be added to the chain in two ways:
360 </para>
362 <itemizedlist>
363 <listitem>
364 <para>
365 passing in a concrete validator instance
366 </para>
367 </listitem>
369 <listitem>
370 <para>
371 providing a validator name – either a short name or fully
372 qualified class name
373 </para>
374 </listitem>
375 </itemizedlist>
377 <para>
378 Let's see some examples:
379 </para>
381 <programlisting language="php"><![CDATA[
382 // Concrete validator instance:
383 $element->addValidator(new Zend_Validate_Alnum());
385 // Fully qualified class name:
386 $element->addValidator('Zend_Validate_Alnum');
388 // Short validator name:
389 $element->addValidator('Alnum');
390 $element->addValidator('alnum');
391 ]]></programlisting>
393 <para>
394 Short names are typically the validator name minus the prefix. In
395 the default case, this will mean minus the 'Zend_Validate_' prefix.
396 As is the case with filters, the first letter can be upper-cased or lower-cased.
397 </para>
399 <note>
400 <title>Using Custom Validator Classes</title>
402 <para>
403 If you have your own set of validator classes, you can tell
404 <classname>Zend_Form_Element</classname> about these using
405 <methodname>addPrefixPath()</methodname>. For instance, if you have
406 validators under the 'My_Validator' prefix, you can tell
407 <classname>Zend_Form_Element</classname> about this as follows:
408 </para>
410 <programlisting language="php"><![CDATA[
411 $element->addPrefixPath('My_Validator', 'My/Validator/', 'validate');
412 ]]></programlisting>
414 <para>
415 (Recall that the third argument indicates which plugin loader
416 on which to perform the action.)
417 </para>
418 </note>
420 <para>
421 If failing a particular validation should prevent later validators
422 from firing, pass boolean <constant>TRUE</constant> as the second parameter:
423 </para>
425 <programlisting language="php"><![CDATA[
426 $element->addValidator('alnum', true);
427 ]]></programlisting>
429 <para>
430 If you are using a string name to add a validator, and the
431 validator class accepts arguments to the constructor, you may pass
432 these to the third parameter of <methodname>addValidator()</methodname> as an
433 array:
434 </para>
436 <programlisting language="php"><![CDATA[
437 $element->addValidator('StringLength', false, array(6, 20));
438 ]]></programlisting>
440 <para>
441 Arguments passed in this way should be in the order in which they
442 are defined in the constructor. The above example will instantiate
443 the <classname>Zend_Validate_StringLenth</classname> class with its
444 <varname>$min</varname> and <varname>$max</varname> parameters:
445 </para>
447 <programlisting language="php"><![CDATA[
448 $validator = new Zend_Validate_StringLength(6, 20);
449 ]]></programlisting>
451 <note>
452 <title>Providing Custom Validator Error Messages</title>
454 <para>
455 Some developers may wish to provide custom error messages for a
456 validator. The <varname>$options</varname> argument of the
457 <methodname>Zend_Form_Element::addValidator()</methodname> method allows you to do
458 so by providing the key 'messages' and mapping it to an array of key/value pairs
459 for setting the message templates. You will need to know the
460 error codes of the various validation error types for the
461 particular validator.
462 </para>
464 <para>
465 A better option is to use a <classname>Zend_Translate_Adapter</classname>
466 with your form. Error codes are automatically passed to the
467 adapter by the default Errors decorator; you can then specify
468 your own error message strings by setting up translations for
469 the various error codes of your validators.
470 </para>
471 </note>
473 <para>
474 You can also set many validators at once, using
475 <methodname>addValidators()</methodname>. The basic usage is to pass an array
476 of arrays, with each array containing 1 to 3 values, matching the
477 constructor of <methodname>addValidator()</methodname>:
478 </para>
480 <programlisting language="php"><![CDATA[
481 $element->addValidators(array(
482 array('NotEmpty', true),
483 array('alnum'),
484 array('stringLength', false, array(6, 20)),
485 ));
486 ]]></programlisting>
488 <para>
489 If you want to be more verbose or explicit, you can use the array
490 keys 'validator', 'breakChainOnFailure', and 'options':
491 </para>
493 <programlisting language="php"><![CDATA[
494 $element->addValidators(array(
495 array(
496 'validator' => 'NotEmpty',
497 'breakChainOnFailure' => true),
498 array('validator' => 'alnum'),
499 array(
500 'validator' => 'stringLength',
501 'options' => array(6, 20)),
502 ));
503 ]]></programlisting>
505 <para>
506 This usage is good for illustrating how you could then configure
507 validators in a config file:
508 </para>
510 <programlisting language="ini"><![CDATA[
511 element.validators.notempty.validator = "NotEmpty"
512 element.validators.notempty.breakChainOnFailure = true
513 element.validators.alnum.validator = "Alnum"
514 element.validators.strlen.validator = "StringLength"
515 element.validators.strlen.options.min = 6
516 element.validators.strlen.options.max = 20
517 ]]></programlisting>
519 <para>
520 Notice that every item has a key, whether or not it needs one; this
521 is a limitation of using configuration files -- but it also helps
522 make explicit what the arguments are for. Just remember that any
523 validator options must be specified in order.
524 </para>
526 <para>
527 To validate an element, pass the value to
528 <methodname>isValid()</methodname>:
529 </para>
531 <programlisting language="php"><![CDATA[
532 if ($element->isValid($value)) {
533 // valid
534 } else {
535 // invalid
536 }
537 ]]></programlisting>
539 <note>
540 <title>Validation Operates On Filtered Values</title>
542 <para>
543 <methodname>Zend_Form_Element::isValid()</methodname> filters values through
544 the provided filter chain prior to validation. See <link
545 linkend="zend.form.elements.filters">the Filters
546 section</link> for more information.
547 </para>
548 </note>
550 <note>
551 <title>Validation Context</title>
553 <para>
554 <methodname>Zend_Form_Element::isValid()</methodname> supports an
555 additional argument, <varname>$context</varname>.
556 <methodname>Zend_Form::isValid()</methodname> passes the entire array of
557 data being processed to <varname>$context</varname> when validating a
558 form, and <methodname>Zend_Form_Element::isValid()</methodname>, in turn,
559 passes it to each validator. This means you can write
560 validators that are aware of data passed to other form
561 elements. As an example, consider a standard registration form
562 that has fields for both password and a password confirmation;
563 one validation would be that the two fields match. Such a
564 validator might look like the following:
565 </para>
567 <programlisting language="php"><![CDATA[
568 class My_Validate_PasswordConfirmation extends Zend_Validate_Abstract
569 {
570 const NOT_MATCH = 'notMatch';
572 protected $_messageTemplates = array(
573 self::NOT_MATCH => 'Password confirmation does not match'
574 );
576 public function isValid($value, $context = null)
577 {
578 $value = (string) $value;
579 $this->_setValue($value);
581 if (is_array($context)) {
582 if (isset($context['password_confirm'])
583 && ($value == $context['password_confirm']))
584 {
585 return true;
586 }
587 } elseif (is_string($context) && ($value == $context)) {
588 return true;
589 }
591 $this->_error(self::NOT_MATCH);
592 return false;
593 }
594 }
595 ]]></programlisting>
596 </note>
598 <para>
599 Validators are processed in order. Each validator is processed,
600 unless a validator created with a <constant>TRUE</constant>
601 <varname>$breakChainOnFailure</varname> value fails its validation. Be
602 sure to specify your validators in a reasonable order.
603 </para>
605 <para>
606 After a failed validation, you can retrieve the error codes and
607 messages from the validator chain:
608 </para>
610 <programlisting language="php"><![CDATA[
611 $errors = $element->getErrors();
612 $messages = $element->getMessages();
613 ]]></programlisting>
615 <para>
616 (Note: error messages returned are an associative array of error
617 code / error message pairs.)
618 </para>
620 <para>
621 In addition to validators, you can specify that an element is
622 required, using <methodname>setRequired(true)</methodname>. By default, this
623 flag is <constant>FALSE</constant>, meaning that your validator chain will be skipped if
624 no value is passed to <methodname>isValid()</methodname>. You can modify this
625 behavior in a number of ways:
626 </para>
628 <itemizedlist>
629 <listitem>
630 <para>
631 By default, when an element is required, a flag,
632 'allowEmpty', is also <constant>TRUE</constant>. This means that if a value
633 evaluating to empty is passed to <methodname>isValid()</methodname>, the
634 validators will be skipped. You can toggle this flag using
635 the accessor <methodname>setAllowEmpty($flag)</methodname>; when the
636 flag is <constant>FALSE</constant> and a value is passed, the validators
637 will still run.
638 </para>
639 </listitem>
641 <listitem>
642 <para>
643 By default, if an element is required but does not contain
644 a 'NotEmpty' validator, <methodname>isValid()</methodname> will add one
645 to the top of the stack, with the
646 <varname>$breakChainOnFailure</varname> flag set. This behavior lends
647 required flag semantic meaning: if no value is passed,
648 we immediately invalidate the submission and notify the
649 user, and prevent other validators from running on what we
650 already know is invalid data.
651 </para>
653 <para>
654 If you do not want this behavior, you can turn it off by
655 passing a <constant>FALSE</constant> value to
656 <methodname>setAutoInsertNotEmptyValidator($flag)</methodname>; this
657 will prevent <methodname>isValid()</methodname> from placing the
658 'NotEmpty' validator in the validator chain.
659 </para>
660 </listitem>
661 </itemizedlist>
663 <para>
664 For more information on validators, see the <link
665 linkend="zend.validate.introduction">Zend_Validate
666 documentation</link>.
667 </para>
669 <note>
670 <title>Using Zend_Form_Elements as general-purpose validators</title>
672 <para>
673 <classname>Zend_Form_Element</classname> implements
674 <classname>Zend_Validate_Interface</classname>, meaning an element may
675 also be used as a validator in other, non-form related
676 validation chains.
677 </para>
678 </note>
680 <note>
681 <title>When is an element detected as empty?</title>
683 <para>
684 As mentioned the 'NotEmpty' validator is used to detect if an element is empty
685 or not. But <classname>Zend_Validate_NotEmpty</classname> does, per default, not
686 work like <acronym>PHP</acronym>'s method <methodname>empty()</methodname>.
687 </para>
689 <para>
690 This means when an element contains an integer <emphasis>0</emphasis> or an string
691 <emphasis>'0'</emphasis> then the element will be seen as not empty. If you want to
692 have a different behaviour you must create your own instance of
693 <classname>Zend_Validate_NotEmpty</classname>. There you can define the behaviour of
694 this validator. See <ulink
695 url="zend.validate.set.notempty">Zend_Validate_NotEmpty</ulink> for details.
696 </para>
697 </note>
699 <para>
700 Methods associated with validation include:
701 </para>
703 <itemizedlist>
704 <listitem>
705 <para>
706 <methodname>setRequired($flag)</methodname> and
707 <methodname>isRequired()</methodname> allow you to set and retrieve the
708 status of the 'required' flag. When set to boolean <constant>TRUE</constant>,
709 this flag requires that the element be in the data processed by
710 <classname>Zend_Form</classname>.
711 </para>
712 </listitem>
714 <listitem>
715 <para>
716 <methodname>setAllowEmpty($flag)</methodname> and
717 <methodname>getAllowEmpty()</methodname> allow you to modify the
718 behaviour of optional elements (i.e., elements where the
719 required flag is <constant>FALSE</constant>). When the 'allow empty' flag is
720 <constant>TRUE</constant>, empty values will not be passed to the validator
721 chain.
722 </para>
723 </listitem>
725 <listitem>
726 <para>
727 <methodname>setAutoInsertNotEmptyValidator($flag)</methodname> allows
728 you to specify whether or not a 'NotEmpty' validator will be
729 prepended to the validator chain when the element is
730 required. By default, this flag is <constant>TRUE</constant>.
731 </para>
732 </listitem>
734 <listitem>
735 <para>
736 <methodname>addValidator($nameOrValidator, $breakChainOnFailure = false, array
737 $options = null)</methodname>
738 </para>
739 </listitem>
741 <listitem>
742 <para>
743 <methodname>addValidators(array $validators)</methodname>
744 </para>
745 </listitem>
747 <listitem>
748 <para>
749 <methodname>setValidators(array $validators)</methodname> (overwrites all
750 validators)
751 </para>
752 </listitem>
754 <listitem>
755 <para>
756 <methodname>getValidator($name)</methodname> (retrieve a validator object by
757 name)
758 </para>
759 </listitem>
761 <listitem>
762 <para>
763 <methodname>getValidators()</methodname> (retrieve all validators)
764 </para>
765 </listitem>
767 <listitem>
768 <para>
769 <methodname>removeValidator($name)</methodname> (remove validator by name)
770 </para>
771 </listitem>
773 <listitem>
774 <para>
775 <methodname>clearValidators()</methodname> (remove all validators)
776 </para>
777 </listitem>
778 </itemizedlist>
780 <sect3 id="zend.form.elements.validators.errors">
781 <title>Custom Error Messages</title>
783 <para>
784 At times, you may want to specify one or more specific error
785 messages to use instead of the error messages generated by the
786 validators attached to your element. Additionally, at times you
787 may want to mark the element invalid yourself. As of 1.6.0, this
788 functionality is possible via the following methods.
789 </para>
791 <itemizedlist>
792 <listitem>
793 <para>
794 <methodname>addErrorMessage($message)</methodname>: add an error message
795 to display on form validation errors. You may call this more
796 than once, and new messages are appended to the stack.
797 </para>
798 </listitem>
800 <listitem>
801 <para>
802 <methodname>addErrorMessages(array $messages)</methodname>: add multiple
803 error messages to display on form validation errors.
804 </para>
805 </listitem>
807 <listitem>
808 <para>
809 <methodname>setErrorMessages(array $messages)</methodname>: add multiple
810 error messages to display on form validation errors,
811 overwriting all previously set error messages.
812 </para>
813 </listitem>
815 <listitem>
816 <para>
817 <methodname>getErrorMessages()</methodname>: retrieve the list of
818 custom error messages that have been defined.
819 </para>
820 </listitem>
822 <listitem>
823 <para>
824 <methodname>clearErrorMessages()</methodname>: remove all custom error
825 messages that have been defined.
826 </para>
827 </listitem>
829 <listitem>
830 <para>
831 <methodname>markAsError()</methodname>: mark the element as having
832 failed validation.
833 </para>
834 </listitem>
836 <listitem>
837 <para>
838 <methodname>hasErrors()</methodname>: determine whether the element has
839 either failed validation or been marked as invalid.
840 </para>
841 </listitem>
843 <listitem>
844 <para>
845 <methodname>addError($message)</methodname>: add a message to the custom
846 error messages stack and flag the element as invalid.
847 </para>
848 </listitem>
850 <listitem>
851 <para>
852 <methodname>addErrors(array $messages)</methodname>: add several
853 messages to the custom error messages stack and flag the
854 element as invalid.
855 </para>
856 </listitem>
858 <listitem>
859 <para>
860 <methodname>setErrors(array $messages)</methodname>: overwrite the
861 custom error messages stack with the provided messages and
862 flag the element as invalid.
863 </para>
864 </listitem>
865 </itemizedlist>
867 <para>
868 All errors set in this fashion may be translated. Additionally,
869 you may insert the placeholder "%value%" to represent the
870 element value; this current element value will be substituted
871 when the error messages are retrieved.
872 </para>
873 </sect3>
874 </sect2>
876 <sect2 id="zend.form.elements.decorators">
877 <title>Decorators</title>
879 <para>
880 One particular pain point for many web developers is the creation
881 of the <acronym>XHTML</acronym> forms themselves. For each element, the developer
882 needs to create markup for the element itself (typically a label)
883 and special markup for displaying
884 validation error messages. The more elements on the page, the less
885 trivial this task becomes.
886 </para>
888 <para>
889 <classname>Zend_Form_Element</classname> tries to solve this issue through
890 the use of "decorators". Decorators are simply classes that have
891 access to the element and a method for rendering content. For more
892 information on how decorators work, please see the section on <link
893 linkend="zend.form.decorators">Zend_Form_Decorator</link>.
894 </para>
896 <para>
897 The default decorators used by <classname>Zend_Form_Element</classname> are:
898 </para>
900 <itemizedlist>
901 <listitem>
902 <para>
903 <emphasis>ViewHelper</emphasis>: specifies a view helper to use
904 to render the element. The 'helper' element attribute can be
905 used to specify which view helper to use. By default,
906 <classname>Zend_Form_Element</classname> specifies the 'formText' view
907 helper, but individual subclasses specify different helpers.
908 </para>
909 </listitem>
911 <listitem>
912 <para>
913 <emphasis>Errors</emphasis>: appends error messages to the
914 element using <classname>Zend_View_Helper_FormErrors</classname>. If none are
915 present, nothing is appended.
916 </para>
917 </listitem>
919 <listitem>
920 <para>
921 <emphasis>Description</emphasis>: appends the element
922 description. If none is present, nothing is appended. By
923 default, the description is rendered in a <p> tag with a
924 class of 'description'.
925 </para>
926 </listitem>
928 <listitem>
929 <para>
930 <emphasis>HtmlTag</emphasis>: wraps the element and errors in
931 an HTML <dd> tag.
932 </para>
933 </listitem>
935 <listitem>
936 <para>
937 <emphasis>Label</emphasis>: prepends a label to the element
938 using <classname>Zend_View_Helper_FormLabel</classname>, and wraps it in a
939 <dt> tag. If no label is provided, just the definition term tag is
940 rendered.
941 </para>
942 </listitem>
943 </itemizedlist>
945 <note>
946 <title>Default Decorators Do Not Need to Be Loaded</title>
948 <para>
949 By default, the default decorators are loaded during object
950 initialization. You can disable this by passing the
951 'disableLoadDefaultDecorators' option to the constructor:
952 </para>
954 <programlisting language="php"><![CDATA[
955 $element = new Zend_Form_Element('foo',
956 array('disableLoadDefaultDecorators' =>
957 true)
958 );
959 ]]></programlisting>
961 <para>
962 This option may be mixed with any other options you pass,
963 both as array options or in a <classname>Zend_Config</classname> object.
964 </para>
965 </note>
967 <para>
968 Since the order in which decorators are registered matters- the first
969 decorator registered is executed first- you will need to make
970 sure you register your decorators in an appropriate order, or
971 ensure that you set the placement options in a sane fashion. To
972 give an example, here is the code that registers the default
973 decorators:
974 </para>
976 <programlisting language="php"><![CDATA[
977 $this->addDecorators(array(
978 array('ViewHelper'),
979 array('Errors'),
980 array('Description', array('tag' => 'p', 'class' => 'description')),
981 array('HtmlTag', array('tag' => 'dd')),
982 array('Label', array('tag' => 'dt')),
983 ));
984 ]]></programlisting>
986 <para>
987 The initial content is created by the 'ViewHelper' decorator, which
988 creates the form element itself. Next, the 'Errors' decorator
989 fetches error messages from the element, and, if any are present,
990 passes them to the 'FormErrors' view helper to render. If a
991 description is present, the 'Description' decorator will append a
992 paragraph of class 'description' containing the descriptive text to
993 the aggregated content. The next decorator, 'HtmlTag', wraps the
994 element, errors, and description in an HTML <dd> tag.
995 Finally, the last decorator, 'label', retrieves the element's label
996 and passes it to the 'FormLabel' view helper, wrapping it in an HTML
997 <dt> tag; the value is prepended to the content by default.
998 The resulting output looks basically like this:
999 </para>
1001 <programlisting language="html"><![CDATA[
1002 <dt><label for="foo" class="optional">Foo</label></dt>
1003 <dd>
1004 <input type="text" name="foo" id="foo" value="123" />
1005 <ul class="errors">
1006 <li>"123" is not an alphanumeric value</li>
1007 </ul>
1008 <p class="description">
1009 This is some descriptive text regarding the element.
1010 </p>
1011 </dd>
1012 ]]></programlisting>
1014 <para>
1015 For more information on decorators, read the <link
1016 linkend="zend.form.decorators">Zend_Form_Decorator section</link>.
1017 </para>
1019 <note>
1020 <title>Using Multiple Decorators of the Same Type</title>
1022 <para>
1023 Internally, <classname>Zend_Form_Element</classname> uses a decorator's
1024 class as the lookup mechanism when retrieving decorators. As a
1025 result, you cannot register multiple decorators of the same
1026 type; subsequent decorators will simply overwrite those that
1027 existed before.
1028 </para>
1030 <para>
1031 To get around this, you can use <emphasis>aliases</emphasis>.
1032 Instead of passing a decorator or decorator name as the first
1033 argument to <methodname>addDecorator()</methodname>, pass an array with a
1034 single element, with the alias pointing to the decorator object
1035 or name:
1036 </para>
1038 <programlisting language="php"><![CDATA[
1039 // Alias to 'FooBar':
1040 $element->addDecorator(array('FooBar' => 'HtmlTag'),
1041 array('tag' => 'div'));
1043 // And retrieve later:
1044 $decorator = $element->getDecorator('FooBar');
1045 ]]></programlisting>
1047 <para>
1048 In the <methodname>addDecorators()</methodname> and
1049 <methodname>setDecorators()</methodname> methods, you will need to pass
1050 the 'decorator' option in the array representing the decorator:
1051 </para>
1053 <programlisting language="php"><![CDATA[
1054 // Add two 'HtmlTag' decorators, aliasing one to 'FooBar':
1055 $element->addDecorators(
1056 array('HtmlTag', array('tag' => 'div')),
1057 array(
1058 'decorator' => array('FooBar' => 'HtmlTag'),
1059 'options' => array('tag' => 'dd')
1060 ),
1061 );
1063 // And retrieve later:
1064 $htmlTag = $element->getDecorator('HtmlTag');
1065 $fooBar = $element->getDecorator('FooBar');
1066 ]]></programlisting>
1067 </note>
1069 <para>
1070 Methods associated with decorators include:
1071 </para>
1073 <itemizedlist>
1074 <listitem>
1075 <para>
1076 <methodname>addDecorator($nameOrDecorator, array $options = null)</methodname>
1077 </para>
1078 </listitem>
1080 <listitem>
1081 <para>
1082 <methodname>addDecorators(array $decorators)</methodname>
1083 </para>
1084 </listitem>
1086 <listitem>
1087 <para>
1088 <methodname>setDecorators(array $decorators)</methodname> (overwrites all
1089 decorators)
1090 </para>
1091 </listitem>
1093 <listitem>
1094 <para>
1095 <methodname>getDecorator($name)</methodname> (retrieve a decorator object by
1096 name)
1097 </para>
1098 </listitem>
1100 <listitem>
1101 <para>
1102 <methodname>getDecorators()</methodname> (retrieve all decorators)
1103 </para>
1104 </listitem>
1106 <listitem>
1107 <para>
1108 <methodname>removeDecorator($name)</methodname> (remove decorator by name)
1109 </para>
1110 </listitem>
1112 <listitem>
1113 <para>
1114 <methodname>clearDecorators()</methodname> (remove all decorators)
1115 </para>
1116 </listitem>
1117 </itemizedlist>
1119 <para>
1120 <classname>Zend_Form_Element</classname> also uses overloading to allow rendering
1121 specific decorators. <methodname>__call()</methodname> will intercept methods
1122 that lead with the text 'render' and use the remainder of the method
1123 name to lookup a decorator; if found, it will then render that
1124 <emphasis>single</emphasis> decorator. Any arguments passed to the
1125 method call will be used as content to pass to the decorator's
1126 <methodname>render()</methodname> method. As an example:
1127 </para>
1129 <programlisting language="php"><![CDATA[
1130 // Render only the ViewHelper decorator:
1131 echo $element->renderViewHelper();
1133 // Render only the HtmlTag decorator, passing in content:
1134 echo $element->renderHtmlTag("This is the html tag content");
1135 ]]></programlisting>
1137 <para>
1138 If the decorator does not exist, an exception is raised.
1139 </para>
1140 </sect2>
1142 <sect2 id="zend.form.elements.metadata">
1143 <title>Metadata and Attributes</title>
1145 <para>
1146 <classname>Zend_Form_Element</classname> handles a variety of attributes and
1147 element metadata. Basic attributes include:
1148 </para>
1150 <itemizedlist>
1151 <listitem>
1152 <para>
1153 <emphasis>name</emphasis>: the element name. Uses the
1154 <methodname>setName()</methodname> and <methodname>getName()</methodname>
1155 accessors.
1156 </para>
1157 </listitem>
1159 <listitem>
1160 <para>
1161 <emphasis>label</emphasis>: the element label. Uses the
1162 <methodname>setLabel()</methodname> and <methodname>getLabel()</methodname>
1163 accessors.
1164 </para>
1165 </listitem>
1167 <listitem>
1168 <para>
1169 <emphasis>order</emphasis>: the index at which an element
1170 should appear in the form. Uses the <methodname>setOrder()</methodname> and
1171 <methodname>getOrder()</methodname> accessors.
1172 </para>
1173 </listitem>
1175 <listitem>
1176 <para>
1177 <emphasis>value</emphasis>: the current element value. Uses the
1178 <methodname>setValue()</methodname> and <methodname>getValue()</methodname>
1179 accessors.
1180 </para>
1181 </listitem>
1183 <listitem>
1184 <para>
1185 <emphasis>description</emphasis>: a description of the element;
1186 often used to provide tooltip or javascript contextual hinting
1187 describing the purpose of the element. Uses the
1188 <methodname>setDescription()</methodname> and
1189 <methodname>getDescription()</methodname> accessors.
1190 </para>
1191 </listitem>
1193 <listitem>
1194 <para>
1195 <emphasis>required</emphasis>: flag indicating whether or not
1196 the element is required when performing form validation. Uses
1197 the <methodname>setRequired()</methodname> and
1198 <methodname>getRequired()</methodname> accessors. This flag is
1199 <constant>FALSE</constant> by default.
1200 </para>
1201 </listitem>
1203 <listitem>
1204 <para>
1205 <emphasis>allowEmpty</emphasis>: flag indicating whether or not
1206 a non-required (optional) element should attempt to validate
1207 empty values. If it is set to <constant>TRUE</constant> and the required flag is
1208 <constant>FALSE</constant>, empty values are not passed to the validator chain
1209 and are presumed <constant>TRUE</constant>. Uses the
1210 <methodname>setAllowEmpty()</methodname> and
1211 <methodname>getAllowEmpty()</methodname> accessors. This flag is
1212 <constant>TRUE</constant> by default.
1213 </para>
1214 </listitem>
1216 <listitem>
1217 <para>
1218 <emphasis>autoInsertNotEmptyValidator</emphasis>: flag
1219 indicating whether or not to insert a 'NotEmpty' validator when
1220 the element is required. By default, this flag is <constant>TRUE</constant>. Set
1221 the flag with <methodname>setAutoInsertNotEmptyValidator($flag)</methodname> and
1222 determine the value with
1223 <methodname>autoInsertNotEmptyValidator()</methodname>.
1224 </para>
1225 </listitem>
1226 </itemizedlist>
1228 <para>
1229 Form elements may require additional metadata. For <acronym>XHTML</acronym> form
1230 elements, for instance, you may want to specify attributes such as
1231 the class or id. To facilitate this are a set of accessors:
1232 </para>
1234 <itemizedlist>
1235 <listitem>
1236 <para>
1237 <emphasis>setAttrib($name, $value)</emphasis>: add an attribute
1238 </para>
1239 </listitem>
1241 <listitem>
1242 <para>
1243 <emphasis>setAttribs(array $attribs)</emphasis>: like
1244 addAttribs(), but overwrites
1245 </para>
1246 </listitem>
1248 <listitem>
1249 <para>
1250 <emphasis>getAttrib($name)</emphasis>: retrieve a single
1251 attribute value
1252 </para>
1253 </listitem>
1255 <listitem>
1256 <para>
1257 <emphasis>getAttribs()</emphasis>: retrieve all attributes as
1258 key/value pairs
1259 </para>
1260 </listitem>
1261 </itemizedlist>
1263 <para>
1264 Most of the time, however, you can simply access them as object
1265 properties, as <classname>Zend_Form_Element</classname> utilizes overloading
1266 to facilitate access to them:
1267 </para>
1269 <programlisting language="php"><![CDATA[
1270 // Equivalent to $element->setAttrib('class', 'text'):
1271 $element->class = 'text;
1272 ]]></programlisting>
1274 <para>
1275 By default, all attributes are passed to the view helper used by
1276 the element during rendering, and rendered as HTML attributes of
1277 the element tag.
1278 </para>
1279 </sect2>
1281 <sect2 id="zend.form.elements.standard">
1282 <title>Standard Elements</title>
1284 <para>
1285 <classname>Zend_Form</classname> ships with a number of standard elements; please read
1286 the <link linkend="zend.form.standardElements">Standard Elements</link>
1287 chapter for full details.
1288 </para>
1289 </sect2>
1291 <sect2 id="zend.form.elements.methods">
1292 <title>Zend_Form_Element Methods</title>
1294 <para>
1295 <classname>Zend_Form_Element</classname> has many, many methods. What follows
1296 is a quick summary of their signatures, grouped by type:
1297 </para>
1299 <itemizedlist>
1300 <listitem>
1301 <para>Configuration:</para>
1303 <itemizedlist>
1304 <listitem>
1305 <para><methodname>setOptions(array $options)</methodname></para>
1306 </listitem>
1308 <listitem>
1309 <para><methodname>setConfig(Zend_Config $config)</methodname></para>
1310 </listitem>
1311 </itemizedlist>
1312 </listitem>
1314 <listitem>
1315 <para>I18n:</para>
1317 <itemizedlist>
1318 <listitem>
1319 <para>
1320 <methodname>setTranslator(Zend_Translate_Adapter $translator
1321 = null)</methodname>
1322 </para>
1323 </listitem>
1325 <listitem><para><methodname>getTranslator()</methodname></para></listitem>
1327 <listitem>
1328 <para><methodname>setDisableTranslator($flag)</methodname></para>
1329 </listitem>
1331 <listitem>
1332 <para><methodname>translatorIsDisabled()</methodname></para>
1333 </listitem>
1334 </itemizedlist>
1335 </listitem>
1337 <listitem>
1338 <para>Properties:</para>
1340 <itemizedlist>
1341 <listitem><para><methodname>setName($name)</methodname></para></listitem>
1342 <listitem><para><methodname>getName()</methodname></para></listitem>
1343 <listitem><para><methodname>setValue($value)</methodname></para></listitem>
1344 <listitem><para><methodname>getValue()</methodname></para></listitem>
1345 <listitem><para><methodname>getUnfilteredValue()</methodname></para></listitem>
1346 <listitem><para><methodname>setLabel($label)</methodname></para></listitem>
1347 <listitem><para><methodname>getLabel()</methodname></para></listitem>
1349 <listitem>
1350 <para><methodname>setDescription($description)</methodname></para>
1351 </listitem>
1353 <listitem><para><methodname>getDescription()</methodname></para></listitem>
1354 <listitem><para><methodname>setOrder($order)</methodname></para></listitem>
1355 <listitem><para><methodname>getOrder()</methodname></para></listitem>
1356 <listitem><para><methodname>setRequired($flag)</methodname></para></listitem>
1357 <listitem><para><methodname>getRequired()</methodname></para></listitem>
1358 <listitem><para><methodname>setAllowEmpty($flag)</methodname></para></listitem>
1359 <listitem><para><methodname>getAllowEmpty()</methodname></para></listitem>
1361 <listitem>
1362 <para><methodname>setAutoInsertNotEmptyValidator($flag)</methodname></para>
1363 </listitem>
1365 <listitem>
1366 <para><methodname>autoInsertNotEmptyValidator()</methodname></para>
1367 </listitem>
1369 <listitem><para><methodname>setIgnore($flag)</methodname></para></listitem>
1370 <listitem><para><methodname>getIgnore()</methodname></para></listitem>
1371 <listitem><para><methodname>getType()</methodname></para></listitem>
1373 <listitem>
1374 <para><methodname>setAttrib($name, $value)</methodname></para>
1375 </listitem>
1377 <listitem>
1378 <para><methodname>setAttribs(array $attribs)</methodname></para>
1379 </listitem>
1381 <listitem><para><methodname>getAttrib($name)</methodname></para></listitem>
1382 <listitem><para><methodname>getAttribs()</methodname></para></listitem>
1383 </itemizedlist>
1384 </listitem>
1386 <listitem>
1387 <para>Plugin loaders and paths:</para>
1389 <itemizedlist>
1390 <listitem>
1391 <para>
1392 <methodname>setPluginLoader(Zend_Loader_PluginLoader_Interface $loader,
1393 $type)</methodname>
1394 </para>
1395 </listitem>
1397 <listitem>
1398 <para><methodname>getPluginLoader($type)</methodname></para>
1399 </listitem>
1401 <listitem>
1402 <para>
1403 <methodname>addPrefixPath($prefix, $path, $type = null)</methodname>
1404 </para>
1405 </listitem>
1407 <listitem>
1408 <para><methodname>addPrefixPaths(array $spec)</methodname></para>
1409 </listitem>
1410 </itemizedlist>
1411 </listitem>
1413 <listitem>
1414 <para>Validation:</para>
1416 <itemizedlist>
1417 <listitem>
1418 <para>
1419 <methodname>addValidator($validator, $breakChainOnFailure = false,
1420 $options = array())</methodname>
1421 </para>
1422 </listitem>
1424 <listitem>
1425 <para><methodname>addValidators(array $validators)</methodname></para>
1426 </listitem>
1428 <listitem>
1429 <para><methodname>setValidators(array $validators)</methodname></para>
1430 </listitem>
1432 <listitem><para><methodname>getValidator($name)</methodname></para></listitem>
1433 <listitem><para><methodname>getValidators()</methodname></para></listitem>
1435 <listitem>
1436 <para><methodname>removeValidator($name)</methodname></para>
1437 </listitem>
1439 <listitem><para><methodname>clearValidators()</methodname></para></listitem>
1441 <listitem>
1442 <para><methodname>isValid($value, $context = null)</methodname></para>
1443 </listitem>
1445 <listitem><para><methodname>getErrors()</methodname></para></listitem>
1446 <listitem><para><methodname>getMessages()</methodname></para></listitem>
1447 </itemizedlist>
1448 </listitem>
1450 <listitem>
1451 <para>Filters:</para>
1453 <itemizedlist>
1454 <listitem>
1455 <para><methodname>addFilter($filter, $options = array())</methodname></para>
1456 </listitem>
1458 <listitem>
1459 <para><methodname>addFilters(array $filters)</methodname></para>
1460 </listitem>
1462 <listitem>
1463 <para><methodname>setFilters(array $filters)</methodname></para>
1464 </listitem>
1466 <listitem><para><methodname>getFilter($name)</methodname></para></listitem>
1467 <listitem><para><methodname>getFilters()</methodname></para></listitem>
1468 <listitem><para><methodname>removeFilter($name)</methodname></para></listitem>
1469 <listitem><para><methodname>clearFilters()</methodname></para></listitem>
1470 </itemizedlist>
1471 </listitem>
1473 <listitem>
1474 <para>Rendering:</para>
1476 <itemizedlist>
1477 <listitem>
1478 <para>
1479 <methodname>setView(Zend_View_Interface $view = null)</methodname>
1480 </para>
1481 </listitem>
1483 <listitem><para><methodname>getView()</methodname></para></listitem>
1485 <listitem>
1486 <para>
1487 <methodname>addDecorator($decorator, $options = null)</methodname>
1488 </para>
1489 </listitem>
1491 <listitem>
1492 <para><methodname>addDecorators(array $decorators)</methodname></para>
1493 </listitem>
1495 <listitem>
1496 <para><methodname>setDecorators(array $decorators)</methodname></para>
1497 </listitem>
1499 <listitem><para><methodname>getDecorator($name)</methodname></para></listitem>
1500 <listitem><para><methodname>getDecorators()</methodname></para></listitem>
1502 <listitem>
1503 <para><methodname>removeDecorator($name)</methodname></para>
1504 </listitem>
1506 <listitem><para><methodname>clearDecorators()</methodname></para></listitem>
1508 <listitem>
1509 <para>
1510 <methodname>render(Zend_View_Interface $view = null)</methodname>
1511 </para>
1512 </listitem>
1513 </itemizedlist>
1514 </listitem>
1515 </itemizedlist>
1516 </sect2>
1518 <sect2 id="zend.form.elements.config">
1519 <title>Configuration</title>
1521 <para>
1522 <classname>Zend_Form_Element</classname>'s constructor accepts either an
1523 array of options or a <classname>Zend_Config</classname> object containing
1524 options, and it can also be configured using either
1525 <methodname>setOptions()</methodname> or <methodname>setConfig()</methodname>. Generally
1526 speaking, keys are named as follows:
1527 </para>
1529 <itemizedlist>
1530 <listitem>
1531 <para>
1532 If 'set' + key refers to a <classname>Zend_Form_Element</classname>
1533 method, then the value provided will be passed to that method.
1534 </para>
1535 </listitem>
1537 <listitem>
1538 <para>
1539 Otherwise, the value will be used to set an attribute.
1540 </para>
1541 </listitem>
1542 </itemizedlist>
1544 <para>
1545 Exceptions to the rule include the following:
1546 </para>
1548 <itemizedlist>
1549 <listitem>
1550 <para>
1551 <property>prefixPath</property> will be passed to
1552 <methodname>addPrefixPaths()</methodname>
1553 </para>
1554 </listitem>
1556 <listitem>
1557 <para>
1558 The following setters cannot be set in this way:
1559 </para>
1561 <itemizedlist>
1562 <listitem>
1563 <para>
1564 <property>setAttrib</property> (though
1565 <property>setAttribs</property> <emphasis>will</emphasis> work)
1566 </para>
1567 </listitem>
1569 <listitem><para><property>setConfig</property></para></listitem>
1570 <listitem><para><property>setOptions</property></para></listitem>
1571 <listitem><para><property>setPluginLoader</property></para></listitem>
1572 <listitem><para><property>setTranslator</property></para></listitem>
1573 <listitem><para><property>setView</property></para></listitem>
1574 </itemizedlist>
1575 </listitem>
1576 </itemizedlist>
1578 <para>
1579 As an example, here is a config file that passes configuration for
1580 every type of configurable data:
1581 </para>
1583 <programlisting language="ini"><![CDATA[
1584 [element]
1585 name = "foo"
1586 value = "foobar"
1587 label = "Foo:"
1588 order = 10
1589 required = true
1590 allowEmpty = false
1591 autoInsertNotEmptyValidator = true
1592 description = "Foo elements are for examples"
1593 ignore = false
1594 attribs.id = "foo"
1595 attribs.class = "element"
1596 ; sets 'onclick' attribute
1597 onclick = "autoComplete(this, '/form/autocomplete/element')"
1598 prefixPaths.decorator.prefix = "My_Decorator"
1599 prefixPaths.decorator.path = "My/Decorator/"
1600 disableTranslator = 0
1601 validators.required.validator = "NotEmpty"
1602 validators.required.breakChainOnFailure = true
1603 validators.alpha.validator = "alpha"
1604 validators.regex.validator = "regex"
1605 validators.regex.options.pattern = "/^[A-F].*/$"
1606 filters.ucase.filter = "StringToUpper"
1607 decorators.element.decorator = "ViewHelper"
1608 decorators.element.options.helper = "FormText"
1609 decorators.label.decorator = "Label"
1610 ]]></programlisting>
1611 </sect2>
1613 <sect2 id="zend.form.elements.custom">
1614 <title>Custom Elements</title>
1616 <para>
1617 You can create your own custom elements by simply extending the
1618 <classname>Zend_Form_Element</classname> class. Common reasons to do so
1619 include:
1620 </para>
1622 <itemizedlist>
1623 <listitem>
1624 <para>
1625 Elements that share common validators and/or filters
1626 </para>
1627 </listitem>
1629 <listitem>
1630 <para>
1631 Elements that have custom decorator functionality
1632 </para>
1633 </listitem>
1634 </itemizedlist>
1636 <para>
1637 There are two methods typically used to extend an element:
1638 <methodname>init()</methodname>, which can be used to add custom initialization
1639 logic to your element, and <methodname>loadDefaultDecorators()</methodname>,
1640 which can be used to set a list of default decorators used by your
1641 element.
1642 </para>
1644 <para>
1645 As an example, let's say that all text elements in a form you are
1646 creating need to be filtered with <classname>StringTrim</classname>,
1647 validated with a common regular expression, and that you want to
1648 use a custom decorator you've created for displaying them,
1649 'My_Decorator_TextItem'. In addition, you have a number of standard
1650 attributes, including 'size', 'maxLength', and 'class' you wish to
1651 specify. You could define an element to accomplish this as follows:
1652 </para>
1654 <programlisting language="php"><![CDATA[
1655 class My_Element_Text extends Zend_Form_Element
1656 {
1657 public function init()
1658 {
1659 $this->addPrefixPath('My_Decorator', 'My/Decorator/', 'decorator')
1660 ->addFilters('StringTrim')
1661 ->addValidator('Regex', false, array('/^[a-z0-9]{6,}$/i'))
1662 ->addDecorator('TextItem')
1663 ->setAttrib('size', 30)
1664 ->setAttrib('maxLength', 45)
1665 ->setAttrib('class', 'text');
1666 }
1667 }
1668 ]]></programlisting>
1670 <para>
1671 You could then inform your form object about the prefix path for
1672 such elements, and start creating elements:
1673 </para>
1675 <programlisting language="php"><![CDATA[
1676 $form->addPrefixPath('My_Element', 'My/Element/', 'element')
1677 ->addElement('text', 'foo');
1678 ]]></programlisting>
1680 <para>
1681 The 'foo' element will now be of type <classname>My_Element_Text</classname>,
1682 and exhibit the behaviour you've outlined.
1683 </para>
1685 <para>
1686 Another method you may want to override when extending
1687 <classname>Zend_Form_Element</classname> is the
1688 <methodname>loadDefaultDecorators()</methodname> method. This method
1689 conditionally loads a set of default decorators for your element;
1690 you may wish to substitute your own decorators in your extending
1691 class:
1692 </para>
1694 <programlisting language="php"><![CDATA[
1695 class My_Element_Text extends Zend_Form_Element
1696 {
1697 public function loadDefaultDecorators()
1698 {
1699 $this->addDecorator('ViewHelper')
1700 ->addDecorator('DisplayError')
1701 ->addDecorator('Label')
1702 ->addDecorator('HtmlTag',
1703 array('tag' => 'div', 'class' => 'element'));
1704 }
1705 }
1706 ]]></programlisting>
1708 <para>
1709 There are many ways to customize elements. Read the <acronym>API</acronym>
1710 documentation of <classname>Zend_Form_Element</classname> to learn about all of the
1711 available methods.
1712 </para>
1713 </sect2>
1714 </sect1>
1715 <!--
1716 vim:se ts=4 sw=4 tw=80 et:
1717 -->