Creating Form Elements Using Zend_Form_ElementA form is made of elements that typically correspond to HTML form input. Zend_Form_Element encapsulates single form elements, with the following areas of responsibility:
The base class, Zend_Form_Element, has reasonable defaults for many cases, but it is best to extend the class for commonly used special purpose elements. Additionally, Zend Framework ships with a number of standard XHTML elements; you can read about them in the Standard Elements chapter. Plugin LoadersZend_Form_Element makes use of Zend_Loader_PluginLoader to allow developers to specify locations of alternate validators, filters, and decorators. Each has its own plugin loader associated with it, and general accessors are used to retrieve and modify each. The following loader types are used with the various plugin loader methods: 'validate', 'filter', and 'decorator'. The type names are case insensitive. The methods used to interact with plugin loaders are as follows:
Custom validators, filters, and decorators are an easy way to share functionality between forms and to encapsulate custom functionality. Example #1 Custom Label One common use case for plugins is to provide replacements for standard classes. For instance, if you want to provide a different implementation of the 'Label' decorator -- for instance, to always append a colon -- you could create your own 'Label' decorator with your own class prefix, and then add it to your prefix path. Let's start with a custom Label decorator. We'll give it the class prefix "My_Decorator", and the class itself will be in the file "My/Decorator/Label.php".
Now we can tell the element to use this plugin path when looking for decorators:
Alternately, we can do that at the form level to ensure all decorators use this path:
After it added as in the example above, the 'My/Decorator/' path will be searched first to see if the decorator exists there when you add a decorator. As a result, 'My_Decorator_Label' will now be used when the 'Label' decorator is requested. FiltersIt's often useful and/or necessary to perform some normalization on input prior to validation. For example, you may want to strip out all HTML, but run your validations on what remains to ensure the submission is valid. Or you may want to trim empty space surrounding input so that a StringLength validator will use the correct length of the input without counting leading or trailing whitespace characters. These operations may be performed using Zend_Filter. Zend_Form_Element has support for filter chains, allowing you to specify multiple, sequential filters. Filtering happens both during validation and when you retrieve the element value via getValue():
Filters may be added to the chain in two ways:
Let's see some examples:
Short names are typically the filter name minus the prefix. In the default case, this will mean minus the 'Zend_Filter_' prefix. The first letter can be upper-cased or lower-cased.
If at any time you need the unfiltered value, use the getUnfilteredValue() method:
For more information on filters, see the Zend_Filter documentation. Methods associated with filters include:
ValidatorsIf you subscribe to the security mantra of "filter input, escape output," you'll should use validator to filter input submitted with your form. In Zend_Form, each element includes its own validator chain, consisting of Zend_Validate_* validators. Validators may be added to the chain in two ways:
Let's see some examples:
Short names are typically the validator name minus the prefix. In the default case, this will mean minus the 'Zend_Validate_' prefix. As is the case with filters, the first letter can be upper-cased or lower-cased.
If failing a particular validation should prevent later validators from firing, pass boolean TRUE as the second parameter:
If you are using a string name to add a validator, and the validator class accepts arguments to the constructor, you may pass these to the third parameter of addValidator() as an array:
Arguments passed in this way should be in the order in which they are defined in the constructor. The above example will instantiate the Zend_Validate_StringLenth class with its $min and $max parameters:
You can also set many validators at once, using addValidators(). The basic usage is to pass an array of arrays, with each array containing 1 to 3 values, matching the constructor of addValidator():
If you want to be more verbose or explicit, you can use the array keys 'validator', 'breakChainOnFailure', and 'options':
This usage is good for illustrating how you could then configure validators in a config file:
Notice that every item has a key, whether or not it needs one; this is a limitation of using configuration files -- but it also helps make explicit what the arguments are for. Just remember that any validator options must be specified in order. To validate an element, pass the value to isValid():
|
|