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 Helpers Zend_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. $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'. 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. 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. formPassword($name, $value, $attribs): Creates an <input type="password" /> element. formRadio($name, $value, $attribs, $options): 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. 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): Creates a URL string based on a named route. $urlOptions should be an associative array of key/value pairs used by the particular route. 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.