A form is nothing without its elements. Zend_Form
ships with some default elements that render XHTML via
Zend_View helpers. These are as follows:
button
checkbox (or many checkboxes at once with multiCheckbox)
hidden
image
password
radio
reset
select (both regular and multi-select types)
submit
text
textarea
You have two options for adding elements to a form: you can
instantiate concrete elements and pass in these objects, or you can
pass in simply the element type and have Zend_Form
instantiate an object of the correct type for you.
Some examples:
<?php
// Instantiating an element and passing to the form object:
$form->addElement(new Zend_Form_Element_Text('username'));
// Passing a form element type to the form object:
$form->addElement('text', 'username');
By default, these do not have any validators or filters. This means
you will need to configure your elements with at least validators,
and potentially filters. You can either do this (a) before you pass
the element to the form, (b) via configuration options passed in
when creating an element via Zend_Form, or (c) by
pulling the element from the form object and configuring it after
the fact.
Let's first look at creating validators for a concrete element
instance. You can either pass in Zend_Validate_*
objects, or the name of a validator to utilize:
<?php
$username = new Zend_Form_Element_Text('username');
// Passing a Zend_Validate_* object:
$username->addValidator(new Zend_Validate_Alnum());
// Passing a validator name:
$username->addValidator('alnum');
When using this second option, you can pass constructor arguments in an array as the third parameter if the validator can accept tem:
<?php
// Pass a pattern
$username->addValidator('regex', false, array('/^[a-z]/i'));
(The second parameter is used to indicate whether or not failure of
this validator should prevent later validators from running; by
default, this is FALSE.)
You may also wish to specify an element as required. This can be done using an accessor or passing an option when creating the element. In the former case:
<?php
// Make this element required:
$username->setRequired(true);
When an element is required, a 'NotEmpty' validator is added to the top of the validator chain, ensuring that the element has a value when required.
Filters are registered in basically the same way as validators. For illustration purposes, let's add a filter to lowercase the final value:
<?php
$username->addFilter('StringtoLower');
The final element setup might look like this:
<?php
$username->addValidator('alnum')
->addValidator('regex', false, array('/^[a-z]/'))
->setRequired(true)
->addFilter('StringToLower');
// or, more compactly:
$username->addValidators(array('alnum',
array('regex', false, '/^[a-z]/i')
))
->setRequired(true)
->addFilters(array('StringToLower'));
Simple as this is, repeating it this for every element in a form
can be a bit tedious. Let's try option (b) from above. When we
create a new element using Zend_Form::addElement() as
a factory, we can optionally pass in configuration options. These
can include validators and filters. To do all of the
above implicitly, try the following:
<?php
$form->addElement('text', 'username', array(
'validators' => array(
'alnum',
array('regex', false, '/^[a-z]/i')
),
'required' => true,
'filters' => array('StringToLower'),
));
Note
If you find you are setting up elements using the same options in
many locations, you may want to consider creating your own
Zend_Form_Element subclass and utilizing that class
instead; this will save you typing in the long-run.