Standard Form Elements Shipped With Zend FrameworkZend Framework ships with concrete element classes covering most HTML form elements. Most simply specify a particular view helper for use when decorating the element, but several offer additional functionality. The following is a list of all such classes, as well as descriptions of the functionality they offer. Zend_Form_Element_ButtonUsed for creating HTML button elements, Zend_Form_Element_Button extends Zend_Form_Element_Submit, specifying some custom functionality. It specifies the 'formButton' view helper for decoration. Like the submit element, it uses the element's label as the element value for display purposes; in other words, to set the text of the button, set the value of the element. The label will be translated if a translation adapter is present. Because the label is used as part of the element, the button element uses only the ViewHelper and DtDdWrapper decorators. Zend_Form_Element_CaptchaCAPTCHAs are used to prevent automated submission of forms by bots and other automated processes. The Captcha form element allows you to specify which Zend_Captcha adapter you wish to utilize as a form CAPTCHA. It then sets this adapter as a validator to the object, and uses a Captcha decorator for rendering (which proxies to the CAPTCHA adapter). Adapters may be any adapters in Zend_Captcha, as well as any custom adapters you may have defined elsewhere. To allow this, you may pass an additional plugin loader type key, 'CAPTCHA' or 'captcha', when specifying a plugin loader prefix path:
Captcha's may then be registered using the setCaptcha() method, which can take either a concrete CAPTCHA instance, or the short name of a CAPTCHA adapter:
If you wish to load your element via configuration, specify either the key 'captcha' with an array containing the key 'captcha', or both the keys 'captcha' and 'captchaOptions':
The decorator used is determined by querying the captcha adapter. By default, the Captcha decorator is used, but an adapter may specify a different one via its getDecorator() method. As noted, the captcha adapter itself acts as a validator for the element. Additionally, the NotEmpty validator is not used, and the element is marked as required. In most cases, you should need to do nothing else to have a captcha present in your form. Zend_Form_Element_CheckboxHTML checkboxes allow you return a specific value, but basically operate as booleans. When checked, the checkbox's value is submitted. When the checkbox is not checked, nothing is submitted. Internally, Zend_Form_Element_Checkbox enforces this state. By default, the checked value is '1', and the unchecked value '0'. You can specify the values to use using the setCheckedValue() and setUncheckedValue() accessors, respectively. Internally, any time you set the value, if the provided value matches the checked value, then it is set, but any other value causes the unchecked value to be set. Additionally, setting the value sets the checked property of the checkbox. You can query this using isChecked() or simply accessing the property. Using the setChecked($flag) method will both set the state of the flag as well as set the appropriate checked or unchecked value in the element. Please use this method when setting the checked state of a checkbox element to ensure the value is set properly. Zend_Form_Element_Checkbox uses the 'formCheckbox' view helper. The checked value is always used to populate it. Zend_Form_Element_FileThe File form element provides a mechanism for supplying file upload fields to your form. It utilizes Zend_File_Transfer internally to provide this functionality, and the FormFile view helper as also the File decorator to display the form element. By default, it uses the Http transfer adapter, which introspects the $_FILES array and allows you to attach validators and filters. Validators and filters attached to the form element are in turn attached to the transfer adapter. Example #1 File form element usage The above explanation of using the File form element may seem arcane, but actual usage is relatively trivial:
You also need to ensure that the correct encoding type is provided to the form; you should use 'multipart/form-data'. You can do this by setting the 'enctype' attribute on the form:
After the form is validated successfully, you must receive the file to store it in the final destination using receive(). Additionally you can determinate the final location using getFileName():
Per default the file will automatically be received when you call getValues() on the form. The reason behind this behaviour is, that the file itself is the value of the file element.
Still, sometimes you may want to call getValues() without receiving the file. You can archive this by calling setValueDisabled(true). To get the actual value of this flag you can call isValueDisabled(). Example #2 Explicit file retrievement First call setValueDisabled(true).
Now the file will not be received when you call getValues(). So you must call receive() on the file element, or an instance of Zend_File_Transfer yourself.
There are several states of the uploaded file which can be checked with the following methods:
Example #3 Checking if an optional file has been uploaded
Zend_Form_Element_File also supports multiple files. By calling the setMultiFile($count) method you can set the number of file elements you want to create. This keeps you from setting the same settings multiple times. Example #4 Setting multiple files Creating a multifile element is the same as setting a single element. Just call setMultiFile() after the element is created:
You now have 3 identical file upload elements with the same settings. To get the set multifile number simply call getMultiFile().
To limit the size of the file uploaded, you can specify the maximum file size by setting the MAX_FILE_SIZE option on the form. When you set this value by using the setMaxFileSize($size) method, it will be rendered with the file element.
Zend_Form_Element_HashThis element provides protection from CSRF attacks on forms, ensuring the data is submitted by the user session that generated the form and not by a rogue script. Protection is achieved by adding a hash element to a form and verifying it when the form is submitted. The name of the hash element should be unique. We recommend using the salt option for the element- two hashes with same names and different salts would not collide:
You can set the salt later using the setSalt($salt) method. Internally, the element stores a unique identifier using Zend_Session_Namespace, and checks for it at submission (checking that the TTL has not expired). The 'Identical' validator is then used to ensure the submitted hash matches the stored hash. The 'formHidden' view helper is used to render the element in the form.
|
|