View Helpers
In your view scripts, often it is necessary to perform certain
complex functions over and over: e.g., formatting a date,
generating form elements, or displaying action links. You can
use helper classes to perform these behaviors for you.
A helper is simply a class. Let's say we want a helper named 'fooBar'.
By default, the class is prefixed with 'Zend_View_Helper_'
(you can specify a custom prefix when setting a helper path), and the
last segment of the class name is the helper name; this segment should
be TitleCapped; the full class name is then:
Zend_View_Helper_FooBar. This class should contain at the
minimum a single method, named after the helper, and camelCased:
fooBar().
Watch the Case
Helper names are always camelCased, i.e., they never begin with an
uppercase character. The class name itself is MixedCased, but the
method that is actually executed is camelCased.
Default Helper Path
The default helper path always points to the Zend Framework view
helpers, i.e., 'Zend/View/Helper/'. Even if you call
setHelperPath() to overwrite the existing paths, this
path will be set to ensure the default helpers work.
To use a helper in your view script, call it using
$this->helperName(). Behind the scenes,
Zend_View will load the
Zend_View_Helper_HelperName class, create an object
instance of it, and call its helperName() method. The
object instance is persistent within the Zend_View
instance, and is reused for all future calls to
$this->helperName().
Initial HelpersZend_View comes with an initial set of helper classes,
most of which relate to form element generation and perform
the appropriate output escaping automatically. In addition, there
are helpers for creating route-based URLs and HTML
lists, as well as declaring variables. The currently shipped helpers include:
declareVars(): Primarily for use when using
strictVars(), this helper can be used to declare
template variables that may or may not already be set in the
view object, as well as to set default values. Arrays passed as
arguments to the method will be used to set default values;
otherwise, if the variable does not exist, it is set to an empty string.
fieldset($name, $content, $attribs): Creates an
XHTML fieldset. If $attribs contains a
'legend' key, that value will be used for the fieldset legend. The
fieldset will surround the $content as provided to
the helper.
form($name, $attribs, $content): Generates an
XHTML form. All $attribs are escaped and
rendered as XHTML attributes of the form tag. If
$content is present and not a boolean
FALSE, then that content is rendered within the start and
close form tags; if $content is a boolean
FALSE (the default), only the opening form tag is
generated.
formButton($name, $value, $attribs): Creates an
<button /> element.
formCheckbox($name, $value, $attribs, $options):
Creates an <input type="checkbox" /> element.
By default, when no $value is provided and no $options are
present, '0' is assumed to be the unchecked value, and '1'
the checked value. If a $value is passed, but no $options
are present, the checked value is assumed to be the value
passed. The unchecked value is implemented by rendering a
hidden input element before rendering the checkbox.
$options should be an array. If the array is indexed, the
first value is the checked value, and the second the
unchecked value; all other values are ignored. You may also
pass an associative array with the keys 'checked' and
'unChecked'. The key 'disableHidden' can be set to true to
prevent rendering of the hidden field for the unchecked value.
If $options has been passed, if $value matches the checked
value, then the element will be marked as checked. You may
also mark the element as checked or unchecked by passing a
boolean value for the attribute 'checked'.
The above is probably best summed up with some examples:
formCheckbox('foo');
// '1' and '0' as checked/unchecked options; checked
echo $this->formCheckbox('foo', null, array('checked' => true));
// 'bar' and '0' as checked/unchecked options; not checked
echo $this->formCheckbox('foo', 'bar');
// 'bar' and '0' as checked/unchecked options; checked
echo $this->formCheckbox('foo', 'bar', array('checked' => true));
// 'bar' and 'baz' as checked/unchecked options; unchecked
echo $this->formCheckbox('foo', null, null, array('bar', 'baz'));
// 'bar' and 'baz' as checked/unchecked options; unchecked
echo $this->formCheckbox('foo', null, null, array(
'checked' => 'bar',
'unChecked' => 'baz'
));
// 'bar' and 'baz' as checked/unchecked options; checked
echo $this->formCheckbox('foo', 'bar', null, array('bar', 'baz'));
echo $this->formCheckbox('foo',
null,
array('checked' => true),
array('bar', 'baz'));
// 'bar' and 'baz' as checked/unchecked options; unchecked
echo $this->formCheckbox('foo', 'baz', null, array('bar', 'baz'));
echo $this->formCheckbox('foo',
null,
array('checked' => false),
array('bar', 'baz'));
]]>
In all cases, the markup prepends a hidden element with the
unchecked value; this way, if the value is unchecked, you
will still get a valid value returned to your form.
formErrors($errors, $options): Generates an
XHTML unordered list to show errors.
$errors should be a string or an array of strings;
$options should be any attributes you want
placed in the opening list tag.
You can specify alternate opening, closing, and separator
content when rendering the errors by calling several methods
on the helper:
setElementStart($string); default is
'<ul class="errors"%s"><li>', where %s
is replaced with the attributes as specified in
$options.
setElementSeparator($string); default
is '</li><li>'.
setElementEnd($string); default is
'</li></ul>'.
formFile($name, $attribs): Creates an
<input type="file" /> element.
formHidden($name, $value, $attribs): Creates an
<input type="hidden" /> element.
formImage($name, $value, $attribs): Creates an
<input type="image" /> element.
formImage(
'foo',
'bar',
array(
'src' => 'images/button.png',
'alt' => 'Button',
)
);
// Output:
]]>formLabel($name, $value, $attribs): Creates a
<label> element, setting the for attribute to
$name, and the actual label text to
$value. If disable is passed in
attribs, nothing will be returned.
formMultiCheckbox($name, $value, $attribs, $options,
$listsep): Creates a list of checkboxes.
$options should be an associative array, and may be
arbitrarily deep. $value may be a single value or
an array of selected values that match the keys in the
$options array. $listsep is an
HTML break ("<br />") by default. By default, this
element is treated as an array; all checkboxes share the same name, and are
submitted as an array.
*/
]]>formNote($name, $value = null): Creates a
simple text note. (e.g. as element for headlines in a
Zend_Form object)
formNote(null, 'This is an example text.');
// Output: This is an example text.
]]>formPassword($name, $value, $attribs): Creates an
<input type="password" /> element.
formRadio($name, $value, $attribs, $options, $listsep):
Creates a series of <input type="radio" /> elements, one
for each of the $options elements. In the $options array, the
element key is the radio value, and the element value is the
radio label. The $value radio will be preselected for you.
*/
]]>formReset($name, $value, $attribs): Creates an
<input type="reset" /> element.
formSelect($name, $value, $attribs, $options):
Creates a <select>...</select> block, with one
<option>one for each of the $options elements. In the
$options array, the element key is the option value, and the
element value is the option label. The $value option(s) will be
preselected for you.
formSelect(
'foo',
2,
array(
'class' => 'baz',
),
array(
1 => 'One',
'Two' => array(
'2.1' => 'One',
'2.2' => 'Two',
'2.3' => 'Three',
),
3 => 'Three',
)
);
/*
Output:
*/
// First example with 'multiple' option:
echo $this->formSelect(
'foo[]',
2,
null,
array(
1 => 'One',
2 => 'Two',
3 => 'Three',
)
);
/*
Output:
*/
// Second example with 'multiple' option:
echo $this->formSelect(
'foo',
array(
1,
2,
),
array(
'multiple' => true,
),
array(
1 => 'One',
2 => 'Two',
3 => 'Three',
)
);
/*
Output:
*/
]]>formSubmit($name, $value, $attribs): Creates an
<input type="submit" /> element.
formText($name, $value, $attribs): Creates an
<input type="text" /> element.
formTextarea($name, $value, $attribs): Creates a
<textarea>...</textarea> block.
url($urlOptions, $name, $reset, $encode): Creates a
URL string based on a named route.
$urlOptions should be an associative array of key/value pairs
used by the particular route.
url();
// Output: user/info/id/1
// Set URL options:
echo $this->url(
array('controller' => 'user', 'action' => 'info', 'username' => 'foobar')
);
// Output: user/info/username/foobar
// Using a route:
$router->addRoute(
'user',
new Zend_Controller_Router_Route(
'user/:username',
array(
'controller' => 'user',
'action' => 'info',
)
)
);
echo $this->url(array('name' => 'foobar'), 'user');
// Output: user/foobar
// Using reset: (current request is: user/id/1)
echo $this->url(array('controller' => 'user', 'action' => 'info'), null, false);
// Output: user/info/id/1
echo $this->url(array('controller' => 'user', 'action' => 'info'), null, true);
// Output: user/info
// Using encode:
echo $this->url(
array('controller' => 'user', 'action' => 'info', 'username' => 'John Doe'), null, true, false
);
// Output: user/info/username/John Doe
echo $this->url(
array('controller' => 'user', 'action' => 'info', 'username' => 'John Doe'), null, true, false
);
// Output: user/info/username/John+Doe
]]>serverUrl($requestUri = null): Helper
for returning the current server URL (optionally with request URI).
serverUrl();
// Output: http://www.example.com
echo $this->serverUrl(true);
// Output: http://www.example.com/foo.html
echo $this->serverUrl('/foo/bar');
// Output: http://www.example.com/foo/bar
echo $this->serverUrl()->getHost();
// Output: www.example.com
echo $this->serverUrl()->getScheme();
// Output: http
$this->serverUrl()->setHost('www.foo.com');
$this->serverUrl()->setScheme('https');
echo $this->serverUrl();
// Output: https://www.foo.com
]]>htmlList($items, $ordered, $attribs, $escape):
generates unordered and ordered lists based on the $items
passed to it. If $items is a multidimensional
array, a nested list will be built. If the $escape
flag is TRUE (default), individual items will be escaped
using the view objects registered escaping mechanisms; pass a
FALSE value if you want to allow markup in your lists.
Using these in your view scripts is very easy, here is an example.
Note that you all you need to do is call them; they will load
and instantiate themselves as they are needed.
'United States', 'il' =>
// 'Israel', 'de' => 'Germany').
?>
]]>
The resulting output from the view script will look something like this:
]]>Helper Paths
As with view scripts, your controller can specify a stack of paths
for Zend_View to search for helper classes. By default,
Zend_View looks in "Zend/View/Helper/*" for helper
classes. You can tell Zend_View to look in other
locations using the setHelperPath() and
addHelperPath() methods. Additionally, you can
indicate a class prefix to use for helpers in the path provided, to
allow namespacing your helper classes. By default, if no class
prefix is provided, 'Zend_View_Helper_' is assumed.
setHelperPath('/path/to/more/helpers', 'My_View_Helper');
]]>
In fact, you can "stack" paths using the
addHelperPath() method. As you add paths to the stack,
Zend_View will look at the most-recently-added path for
the requested helper class. This allows you to add to (or even
override) the initial distribution of helpers with your own custom
helpers.
addHelperPath('/path/to/some/helpers', 'My_View_Helper');
// Add /other/path/to/helpers with class prefix 'Your_View_Helper'
$view->addHelperPath('/other/path/to/helpers', 'Your_View_Helper');
// now when you call $this->helperName(), Zend_View will look first for
// "/path/to/some/helpers/HelperName" using class name
// "Your_View_Helper_HelperName", then for
// "/other/path/to/helpers/HelperName.php" using class name
// "My_View_Helper_HelperName", and finally for
// "Zend/View/Helper/HelperName.php" using class name
// "Zend_View_Helper_HelperName".
]]>Writing Custom Helpers
Writing custom helpers is easy; just follow these rules:
While not strictly necessary, we recommend either implementing
Zend_View_Helper_Interface or extending
Zend_View_Helper_Abstract when creating your
helpers. Introduced in 1.6.0, these simply define a
setView() method; however, in upcoming releases, we
plan to implement a strategy pattern that will simplify much of
the naming schema detailed below. Building off these now will
help you future-proof your code.
The class name must, at the very minimum, end with the helper
name itself, using MixedCaps. E.g., if you were writing a
helper called "specialPurpose", the class name would minimally
need to be "SpecialPurpose". You may, and should, give the class
name a prefix, and it is recommended that you use 'View_Helper'
as part of that prefix: "My_View_Helper_SpecialPurpose". (You
will need to pass in the prefix, with or without the trailing
underscore, to addHelperPath() or
setHelperPath()).
The class must have a public method that matches the
helper name; this is the method that will be called when
your template calls "$this->specialPurpose()". In our
"specialPurpose" helper example, the required method
declaration would be "public function specialPurpose()".
In general, the class should not echo or print or otherwise
generate output. Instead, it should return values to be
printed or echoed. The returned values should be escaped
appropriately.
The class must be in a file named after the helper class. Again
using our "specialPurpose" helper example, the file has to be
named "SpecialPurpose.php".
Place the helper class file somewhere in your helper path stack, and
Zend_View will automatically load, instantiate,
persist, and execute it for you.
Here is an example of our SpecialPurpose helper code:
_count++;
$output = "I have seen 'The Jerk' {$this->_count} time(s).";
return htmlspecialchars($output);
}
}
]]>
Then in a view script, you can call the SpecialPurpose
helper as many times as you like; it will be instantiated once, and
then it persists for the life of that Zend_View
instance.
specialPurpose();
echo $this->specialPurpose();
echo $this->specialPurpose();
]]>
The output would look something like this:
Sometimes you will need access to the calling Zend_View
object -- for instance, if you need to use the registered encoding,
or want to render another view script as part of your helper. To get
access to the view object, your helper class should have a
setView($view) method, like the following:
view = $view;
}
public function scriptPath($script)
{
return $this->view->getScriptPath($script);
}
}
]]>
If your helper class has a setView() method, it will be
called when the helper class is first instantiated, and passed the
current view object. It is up to you to persist the object in your
class, as well as determine how it should be accessed.
If you are extending Zend_View_Helper_Abstract, you do
not need to define this method, as it is defined for you.
Registering Concrete Helpers
Sometimes it is convenient to instantiate a view helper, and then register it with the
view. As of version 1.10.0, this is now possible using the
registerHelper() method, which expects two arguments: the
helper object, and the name by which it will be registered.
registerHelper($helper, 'foo');
]]>
If the helper has a setView() method, the view object will call
this and inject itself into the helper on registration.
Helper name should match a method
The second argument to registerHelper() is the name of the
helper. A corresponding method name should exist in the helper; otherwise,
Zend_View will call a non-existent method when invoking the
helper, raising a fatal PHP error.