Advanced Zend_Form UsageZend_Form has a wealth of functionality, much of it aimed
at experienced developers. This chapter aims to document some of this
functionality with examples and use cases.
Array Notation
Many experienced web developers like to group related form elements
using array notation in the element names. For example, if you have
two addresses you wish to capture, a shipping and a billing address,
you may have identical elements; by grouping them in an array, you
can ensure they are captured separately. Take the following form,
for example:
]]>
In this example, the billing and shipping address contain some
identical fields, which means one would overwrite the other. We can
solve this solution using array notation:
]]>
In the above sample, we now get separate addresses. In the submitted
form, we'll now have three elements, the 'save' element for the
submit, and then two arrays, 'shipping' and 'billing', each with
keys for their various elements.
Zend_Form attempts to automate this process with its
sub forms. By
default, sub forms render using the array notation as shown in the
previous HTML form listing, complete with ids. The array name is
based on the sub form name, with the keys based on the elements
contained in the sub form. Sub forms may be nested arbitrarily deep,
and this will create nested arrays to reflect the structure.
Additionally, the various validation routines in
Zend_Form honor the array structure, ensuring that your
form validates correctly, no matter how arbitrarily deep you nest
your sub forms. You need do nothing to benefit from this; this
behaviour is enabled by default.
Additionally, there are facilities that allow you to turn on array
notation conditionally, as well as specify the specific array to
which an element or collection belongs:
Zend_Form::setIsArray($flag): By setting the
flag TRUE, you can indicate that an entire form should be
treated as an array. By default, the form's name will be
used as the name of the array, unless
setElementsBelongTo() has been called. If the
form has no specified name, or if
setElementsBelongTo() has not been set, this
flag will be ignored (as there is no array name to which
the elements may belong).
You may determine if a form is being treated as an array
using the isArray() accessor.
Zend_Form::setElementsBelongTo($array):
Using this method, you can specify the name of an array to
which all elements of the form belong. You can determine the
name using the getElementsBelongTo() accessor.
Additionally, on the element level, you can specify individual
elements may belong to particular arrays using
Zend_Form_Element::setBelongsTo() method.
To discover what this value is -- whether set explicitly or
implicitly via the form -- you may use the
getBelongsTo() accessor.
Multi-Page Forms
Currently, Multi-Page forms are not officially supported in
Zend_Form; however, most support for implementing them
is available and can be utilized with a little extra tooling.
The key to creating a multi-page form is to utilize sub forms, but
to display only one such sub form per page. This allows you to
submit a single sub form at a time and validate it, but not process
the form until all sub forms are complete.
Registration Form Example
Let's use a registration form as an example. For our purposes,
we want to capture the desired username and password on the
first page, then the user's metadata -- given name, family name,
and location -- and finally allow them to decide what mailing
lists, if any, they wish to subscribe to.
First, let's create our own form, and define several sub forms
within it:
addElements(array(
new Zend_Form_Element_Text('username', array(
'required' => true,
'label' => 'Username:',
'filters' => array('StringTrim', 'StringToLower'),
'validators' => array(
'Alnum',
array('Regex',
false,
array('/^[a-z][a-z0-9]{2,}$/'))
)
)),
new Zend_Form_Element_Password('password', array(
'required' => true,
'label' => 'Password:',
'filters' => array('StringTrim'),
'validators' => array(
'NotEmpty',
array('StringLength', false, array(6))
)
)),
));
// Create demographics sub form: given name, family name, and
// location
$demog = new Zend_Form_SubForm();
$demog->addElements(array(
new Zend_Form_Element_Text('givenName', array(
'required' => true,
'label' => 'Given (First) Name:',
'filters' => array('StringTrim'),
'validators' => array(
array('Regex',
false,
array('/^[a-z][a-z0-9., \'-]{2,}$/i'))
)
)),
new Zend_Form_Element_Text('familyName', array(
'required' => true,
'label' => 'Family (Last) Name:',
'filters' => array('StringTrim'),
'validators' => array(
array('Regex',
false,
array('/^[a-z][a-z0-9., \'-]{2,}$/i'))
)
)),
new Zend_Form_Element_Text('location', array(
'required' => true,
'label' => 'Your Location:',
'filters' => array('StringTrim'),
'validators' => array(
array('StringLength', false, array(2))
)
)),
));
// Create mailing lists sub form
$listOptions = array(
'none' => 'No lists, please',
'fw-general' => 'Zend Framework General List',
'fw-mvc' => 'Zend Framework MVC List',
'fw-auth' => 'Zend Framwork Authentication and ACL List',
'fw-services' => 'Zend Framework Web Services List',
);
$lists = new Zend_Form_SubForm();
$lists->addElements(array(
new Zend_Form_Element_MultiCheckbox('subscriptions', array(
'label' =>
'Which lists would you like to subscribe to?',
'multiOptions' => $listOptions,
'required' => true,
'filters' => array('StringTrim'),
'validators' => array(
array('InArray',
false,
array(array_keys($listOptions)))
)
)),
));
// Attach sub forms to main form
$this->addSubForms(array(
'user' => $user,
'demog' => $demog,
'lists' => $lists
));
}
}
]]>
Note that there are no submit buttons, and that we have done
nothing with the sub form decorators -- which means that by
default they will be displayed as fieldsets. We will need to be
able to override these as we display each individual sub form,
and add in submit buttons so we can actually process them --
which will also require action and method properties. Let's add
some scaffolding to our class to provide that information:
{$spec};
} elseif ($spec instanceof Zend_Form_SubForm) {
$subForm = $spec;
} else {
throw new Exception('Invalid argument passed to ' .
__FUNCTION__ . '()');
}
$this->setSubFormDecorators($subForm)
->addSubmitButton($subForm)
->addSubFormActions($subForm);
return $subForm;
}
/**
* Add form decorators to an individual sub form
*
* @param Zend_Form_SubForm $subForm
* @return My_Form_Registration
*/
public function setSubFormDecorators(Zend_Form_SubForm $subForm)
{
$subForm->setDecorators(array(
'FormElements',
array('HtmlTag', array('tag' => 'dl',
'class' => 'zend_form')),
'Form',
));
return $this;
}
/**
* Add a submit button to an individual sub form
*
* @param Zend_Form_SubForm $subForm
* @return My_Form_Registration
*/
public function addSubmitButton(Zend_Form_SubForm $subForm)
{
$subForm->addElement(new Zend_Form_Element_Submit(
'save',
array(
'label' => 'Save and continue',
'required' => false,
'ignore' => true,
)
));
return $this;
}
/**
* Add action and method to sub form
*
* @param Zend_Form_SubForm $subForm
* @return My_Form_Registration
*/
public function addSubFormActions(Zend_Form_SubForm $subForm)
{
$subForm->setAction('/registration/process')
->setMethod('post');
return $this;
}
}
]]>
Next, we need to add some scaffolding in our action controller,
and have several considerations. First, we need to make sure we
persist form data between requests, so that we can determine
when to quit. Second, we need some logic to determine what form
segments have already been submitted, and what sub form to
display based on that information. We'll use
Zend_Session_Namespace to persist data, which will
also help us answer the question of which form to submit.
Let's create our controller, and add a method for retrieving a
form instance:
_form) {
$this->_form = new My_Form_Registration();
}
return $this->_form;
}
}
]]>
Now, let's add some functionality for determining which form to
display. Basically, until the entire form is considered valid,
we need to continue displaying form segments. Additionally, we
likely want to make sure they're in a particular order: user,
demog, and then lists. We can determine what data has been
submitted by checking our session namespace for particular keys
representing each subform.
_session) {
$this->_session =
new Zend_Session_Namespace($this->_namespace);
}
return $this->_session;
}
/**
* Get a list of forms already stored in the session
*
* @return array
*/
public function getStoredForms()
{
$stored = array();
foreach ($this->getSessionNamespace() as $key => $value) {
$stored[] = $key;
}
return $stored;
}
/**
* Get list of all subforms available
*
* @return array
*/
public function getPotentialForms()
{
return array_keys($this->getForm()->getSubForms());
}
/**
* What sub form was submitted?
*
* @return false|Zend_Form_SubForm
*/
public function getCurrentSubForm()
{
$request = $this->getRequest();
if (!$request->isPost()) {
return false;
}
foreach ($this->getPotentialForms() as $name) {
if ($data = $request->getPost($name, false)) {
if (is_array($data)) {
return $this->getForm()->getSubForm($name);
break;
}
}
}
return false;
}
/**
* Get the next sub form to display
*
* @return Zend_Form_SubForm|false
*/
public function getNextSubForm()
{
$storedForms = $this->getStoredForms();
$potentialForms = $this->getPotentialForms();
foreach ($potentialForms as $name) {
if (!in_array($name, $storedForms)) {
return $this->getForm()->getSubForm($name);
}
}
return false;
}
}
]]>
The above methods allow us to use notations such as "$subForm =
$this->getCurrentSubForm();" to retrieve the current
sub form for validation, or "$next =
$this->getNextSubForm();" to get the next one to
display.
Now, let's figure out how to process and display the various sub
forms. We can use getCurrentSubForm() to determine
if any sub forms have been submitted (FALSE return values
indicate none have been displayed or submitted), and
getNextSubForm() to retrieve a form to display. We
can then use the form's prepareSubForm() method to
ensure the form is ready for display.
When we have a form submission, we can validate the sub form,
and then check to see if the entire form is now valid. To do
these tasks, we'll need additional methods that ensure that
submitted data is added to the session, and that when validating
the form entire, we validate against all segments from the
session:
getName();
if ($subForm->isValid($data)) {
$this->getSessionNamespace()->$name = $subForm->getValues();
return true;
}
return false;
}
/**
* Is the full form valid?
*
* @return bool
*/
public function formIsValid()
{
$data = array();
foreach ($this->getSessionNamespace() as $key => $info) {
$data[$key] = $info;
}
return $this->getForm()->isValid($data);
}
}
]]>
Now that we have the legwork out of the way, let's build the
actions for this controller. We'll need a landing page for the
form, and then a 'process' action for processing the form.
getCurrentSubForm()) {
$form = $this->getNextSubForm();
}
$this->view->form = $this->getForm()->prepareSubForm($form);
}
public function processAction()
{
if (!$form = $this->getCurrentSubForm()) {
return $this->_forward('index');
}
if (!$this->subFormIsValid($form,
$this->getRequest()->getPost())) {
$this->view->form = $this->getForm()->prepareSubForm($form);
return $this->render('index');
}
if (!$this->formIsValid()) {
$form = $this->getNextSubForm();
$this->view->form = $this->getForm()->prepareSubForm($form);
return $this->render('index');
}
// Valid form!
// Render information in a verification page
$this->view->info = $this->getSessionNamespace();
$this->render('verification');
}
}
]]>
As you'll notice, the actual code for processing the form is
relatively simple. We check to see if we have a current sub form
submission, and if not, we go back to the landing page. If we do
have a sub form, we attempt to validate it, redisplaying it if
it fails. If the sub form is valid, we then check to see if the
form is valid, which would indicate we're done; if not, we
display the next form segment. Finally, we display a
verification page with the contents of the session.
The view scripts are very simple:
Registration
form ?>
Thank you for registering!
Here is the information you provided:
info as $info):
foreach ($info as $form => $data): ?>
:
$value): ?>
$val): ?>
escape($value) ?>
]]>
Upcoming releases of Zend Framework will include components to
make multi page forms simpler by abstracting the session and
ordering logic. In the meantime, the above example should serve
as a reasonable guideline on how to accomplish this task for
your site.