View Scripts
Zend_View
Programmer's Reference Guide

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().

Note: 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.

Note: 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. 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:

    1. // '1' and '0' as checked/unchecked options; not checked
    2. 'foo');
    3.  
    4. // '1' and '0' as checked/unchecked options; checked
    5. 'foo''checked'// 'bar' and '0' as checked/unchecked options; not checked
    6. 'foo', 'bar');
    7.  
    8. // 'bar' and '0' as checked/unchecked options; checked
    9. 'foo', 'bar''checked'// 'bar' and 'baz' as checked/unchecked options; unchecked
    10. 'foo''bar', 'baz'));
    11.  
    12. // 'bar' and 'baz' as checked/unchecked options; unchecked
    13. 'foo''checked' => 'bar',
    14.     'unChecked' => 'baz'
    15. ));
    16.  
    17. // 'bar' and 'baz' as checked/unchecked options; checked
    18. 'foo', 'bar''bar', 'baz''foo''checked''bar', 'baz'));
    19.  
    20. // 'bar' and 'baz' as checked/unchecked options; unchecked
    21. 'foo', 'baz''bar', 'baz''foo''checked''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.

    1. span style="color: #ff0000;">'foo',
    2.     'bar''src' => 'images/button.png',
    3.         'alt' => 'Button',
    4.     )
    5. );
    6. // Output: <input type="image" name="foo" id="foo" src="images/button.png" value="bar" alt="Button" />

  • 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.

    1. // Using list separator ($listsep):
    2. '<ul><li>''foo''class' => 'baz''One',
    3.         2 => 'Two',
    4.         3 => 'Three',
    5.     ),
    6.     "</li>\n<li>"'</li></ul>';
    7.  
    8. /*
    9. Output:
    10. <ul>
    11.     <li>
    12.         <label for="foo-1">
    13.             <input type="checkbox" name="foo[]" id="foo-1" value="1" class="baz" />One
    14.         </label>
    15.     </li>
    16.     <li>
    17.         <label for="foo-2">
    18.             <input type="checkbox" name="foo[]" id="foo-2" value="2" checked="checked" class="baz" />Two
    19.         </label>
    20.     </li>
    21.     <li>
    22.         <label for="foo-3">
    23.             <input type="checkbox" name="foo[]" id="foo-3" value="3" class="baz" />Three</label>
    24.         </li>
    25.     </ul>
    26. */
    27.  
    28. // Using options for label elements:
    29. 'foo''label_placement' => 'prepend',
    30.         'label_class'     => 'baz''One',
    31.         2 => 'Two',
    32.         3 => 'Three',
    33.     )
    34. );
    35.  
    36. /*
    37. Output:
    38. <label class="baz" for="foo-1">
    39.     One<input type="checkbox" name="foo[]" id="foo-1" value="1" />
    40. </label>
    41. <br />
    42. <label class="baz" for="foo-2">
    43.     Two<input type="checkbox" name="foo[]" id="foo-2" value="2" checked="checked" />
    44. </label>
    45. <br />
    46. <label class="baz" for="foo-3">
    47.     Three<input type="checkbox" name="foo[]" id="foo-3" value="3" />
    48. </label>
    49. */

  • formNote($name, $value = null): Creates a simple text note. (e.g. as element for headlines in a Zend_Form object)

    1. span style="color: #ff0000;">'This is an example text.');
    2. // 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.

    1. // Using list separator ($listsep)
    2. '<ul><li>''foo''class' => 'baz''One',
    3.         2 => 'Two',
    4.         3 => 'Three',
    5.     ),
    6.     "</li>\n<li>"'</li></ul>';
    7.  
    8. /*
    9. Output:
    10. <ul>
    11.     <li>
    12.         <label for="foo-1">
    13.             <input type="radio" name="foo" id="foo-1" value="1" class="baz" />One
    14.         </label>
    15.     </li>
    16.     <li>
    17.         <label for="foo-2">
    18.             <input type="radio" name="foo" id="foo-2" value="2" checked="checked" class="baz" />Two
    19.         </label>
    20.     </li>
    21.     <li>
    22.         <label for="foo-3">
    23.             <input type="radio" name="foo" id="foo-3" value="3" class="baz" />Three
    24.         </label>
    25.     </li>
    26. </ul>
    27. */
    28.  
    29. // Using options for label elements:
    30. 'foo''label_placement' => 'prepend',
    31.         'label_class'     => 'baz''One',
    32.         2 => 'Two',
    33.         3 => 'Three',
    34.     )
    35. );
    36.  
    37. /*
    38. Output:
    39. <label class="baz" for="foo-1">
    40.     One<input type="radio" name="foo" id="foo-1" value="1" />
    41. </label>
    42. <br />
    43. <label class="baz" for="foo-2">
    44.     Two<input type="radio" name="foo" id="foo-2" value="2" checked="checked" />
    45. </label>
    46. <br />
    47. <label class="baz" for="foo-3">
    48.     Three<input type="radio" name="foo" id="foo-3" value="3" />
    49. </label>
    50. */

  • 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.

    1. // Using option groups:
    2. 'foo''class' => 'baz''One',
    3.         'Two''2.1' => 'One',
    4.             '2.2' => 'Two',
    5.             '2.3' => 'Three',
    6.         ),
    7.         3     => 'Three',
    8.     )
    9. );
    10.  
    11. /*
    12. Output:
    13. <select name="foo" id="foo" class="baz">
    14.     <option value="1" label="One">One</option>
    15.     <optgroup id="foo-optgroup-Two" label="Two">
    16.         <option value="2.1" label="One">One</option>
    17.         <option value="2.2" label="Two">Two</option>
    18.         <option value="2.3" label="Three">Three</option>
    19.     </optgroup>
    20.     <option value="3" label="Three">Three</option>
    21. </select>
    22. */
    23.  
    24. // First example with 'multiple' option:
    25. 'foo[]''One',
    26.         2 => 'Two',
    27.         3 => 'Three',
    28.     )
    29. );
    30.  
    31. /*
    32. Output:
    33. <select name="foo[]" id="foo" multiple="multiple">
    34.     <option value="1" label="One">One</option>
    35.     <option value="2" label="Two" selected="selected">Two</option>
    36.     <option value="3" label="Three">Three</option>
    37. </select>
    38. */
    39.  
    40. // Second example with 'multiple' option:
    41. 'foo''multiple''One',
    42.         2 => 'Two',
    43.         3 => 'Three',
    44.     )
    45. );
    46.  
    47. /*
    48. Output:
    49. <select name="foo[]" id="foo" multiple="multiple">
    50.     <option value="1" label="One" selected="selected">One</option>
    51.     <option value="2" label="Two" selected="selected">Two</option>
    52.     <option value="3" label="Three">Three</option>
    53. </select>
    54. */

  • 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.

    1. // Using without options: (current request is: user/id/1)
    2. // Output: user/info/id/1
    3.  
    4. // Set URL options:
    5. 'controller' => 'user', 'action' => 'info', 'username' => 'foobar')
    6. );
    7. // Output: user/info/username/foobar
    8.  
    9. // Using a route:
    10. $router->addRoute(
    11.     'user''user/:username''controller' => 'user',
    12.             'action'     => 'info''name' => 'foobar'), 'user');
    13. // Output: user/foobar
    14.  
    15. // Using reset: (current request is: user/id/1)
    16. 'controller' => 'user', 'action' => 'info'// Output: user/info/id/1
    17. 'controller' => 'user', 'action' => 'info'// Output: user/info
    18.  
    19. // Using encode:
    20. 'controller' => 'user', 'action' => 'info', 'username' => 'John Doe'// Output: user/info/username/John Doe
    21. 'controller' => 'user', 'action' => 'info', 'username' => 'John Doe'// Output: user/info/username/John+Doe

  • serverUrl($requestUri = null): Helper for returning the current server URL (optionally with request URI).

    1. // Current server URL in the example is: http://www.example.com/foo.html
    2. // Output: http://www.example.com
    3. // Output: http://www.example.com/foo.html
    4. '/foo/bar');
    5. // Output: http://www.example.com/foo/bar
    6. // Output: www.example.com
    7. // Output: http
    8.  
    9. $this->serverUrl()->setHost('www.foo.com');
    10. $this->serverUrl()->setScheme('https'// 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.

  1. // inside your view script, $this refers to the Zend_View instance.
  2. //
  3. // say that you have already assigned a series of select options under
  4. // the name $countries as array('us' => 'United States', 'il' =>
  5. // 'Israel', 'de' => 'Germany').
  6. "action.php" method="post"'email', '[email protected]''size''country', 'us''opt_in', 'yes''yes', 'no'

The resulting output from the view script will look something like this:

  1. span style="color: #ff0000;">"action.php" method="post""text" name="email" value="[email protected]" size="32""country">
  2.             <option value="us" selected="selected""il">Israel</option>
  3.             <option value="de">Germany</option>
  4.         </select>
  5.     </label></p>
  6.     <p><label>Would you like to opt in?
  7.         <input type="hidden" name="opt_in" value="no" />
  8.         <input type="checkbox" name="opt_in" value="yes" checked="checked"

Action View Helper

The Action view helper enables view scripts to dispatch a given controller action; the result of the response object following the dispatch is then returned. These can be used when a particular action could generate re-usable content or "widget-ized" content.

Actions that result in a _forward() or redirect are considered invalid, and will return an empty string.

The API for the Action view helper follows that of most MVC components that invoke controller actions: action($action, $controller, $module = null, array $params = array()). $action and $controller are required; if no module is specified, the default module is assumed.

Example #1 Basic Usage of Action View Helper

As an example, you may have a CommentController with a listAction() method you wish to invoke in order to pull a list of comments for the current request:

  1. <div id="sidebar right""item"'list',
  2.                                  'comment''count'

BaseUrl Helper

While most URLs generated by the framework have the base URL prepended automatically, developers will need to prepend the base URL to their own URLs in order for paths to resources to be correct.

Usage of the BaseUrl helper is very straightforward:

  1. /*
  2. * The following assume that the base URL of the page/application is "/mypage".
  3. */
  4.  
  5. /*
  6. * Prints:
  7. * <base href="/mypage/" />
  8. */"<?php echo $this->baseUrl(); ?>" />
  9.  
  10. /*
  11. * Prints:
  12. * <link rel="stylesheet" type="text/css" href="/mypage/css/base.css" />
  13. */"stylesheet" type="text/css"
  14.      href="<?php echo $this->baseUrl('css/base.css'); ?>" />

Note: For simplicity's sake, we strip out the entry PHP file (e.g., "index.php") from the base URL that was contained in Zend_Controller. However, in some situations this may cause a problem. If one occurs, use $this->getHelper('BaseUrl')->setBaseUrl() to set your own BaseUrl.

Currency Helper

Displaying localized currency values is a common task; the Zend_Currency view helper is intended to simply this task. See the Zend_Currency documentation for specifics on this localization feature. In this section, we will focus simply on usage of the view helper.

There are several ways to initiate the Currency view helper:

  • Registered, through a previously registered instance in Zend_Registry.

  • Afterwards, through the fluent interface.

  • Directly, through instantiating the class.

A registered instance of Zend_Currency is the preferred usage for this helper. Doing so, you can select the currency to be used prior to adding the adapter to the registry.

There are several ways to select the desired currency. First, you may simply provide a currency string; alternately, you may specify a locale. The preferred way is to use a locale as this information is automatically detected and selected via the HTTP client headers provided when a user accesses your application, and ensures the currency provided will match their locale.

Note: We are speaking of "locales" instead of "languages" because a language may vary based on the geographical region in which it is used. For example, English is spoken in different dialects: British English, American English, etc. As a currency always correlates to a country you must give a fully-qualified locale, which means providing both the language and region. Therefore, we say "locale" instead of "language."

Example #2 Registered instance

To use a registered instance, simply create an instance of Zend_Currency and register it within Zend_Registry using Zend_Currency as its key.

  1. // our example currency
  2. 'de_AT''Zend_Currency', $currency);
  3.  
  4. // within your view
  5. // this returns '€ 1.234,56'

If you are more familiar with the fluent interface, then you can also create an instance within your view and configure the helper afterwards.

Example #3 Within the view

To use the fluent interface, create an instance of Zend_Currency, call the helper without a parameter, and call the setCurrency() method.

  1. // within your view
  2. 'de_AT');
  3. $this->currency()->setCurrency($currency)->currency(1234.56);
  4. // this returns '€ 1.234,56'

If you are using the helper without Zend_View then you can also use it directly.

Example #4 Direct usage

  1. // our example currency
  2. 'de_AT');
  3.  
  4. // initiate the helper
  5. // this returns '€ 1.234,56'

As already seen, the currency() method is used to return the currency string. Just call it with the value you want to display as a currency. It also accepts some options which may be used to change the behaviour and output of the helper.

Example #5 Direct usage

  1. // our example currency
  2. 'de_AT');
  3.  
  4. // initiate the helper
  5. // this returns '€ 1.234,56'
  6. 'precision' => 1));
  7. // this returns '€ 1.234,6'

For details about the available options, search for Zend_Currency's toCurrency() method.

Cycle Helper

The Cycle helper is used to alternate a set of values.

Example #6 Cycle Helper Basic Usage

To add elements to cycle just specify them in constructor or use assign(array $data) function

  1. span style="color: #ff0000;">"background-color:<?php echo $this->cycle(array("#F0F0F0",
  2.                                                             "#FFFFFF"">
  3.   <td><?php echo $this->escape($book['author']) ?></td>
  4. </tr>
  5. <?php endforeach;?>
  6.  
  7. // Moving in backwards order and assign function
  8. $this->cycle()->assign(array("#F0F0F0","#FFFFFF"));

The output

  1. <tr style="background-color:'#F0F0F0'">
  2.    <td>First</td>
  3. </tr>
  4. <tr style="background-color:'#FFFFFF'">
  5.    <td>Second</td>
  6. </tr>

Example #7 Working with two or more cycles

To use two cycles you have to specify the names of cycles. Just set second parameter in cycle method. $this->cycle(array("#F0F0F0","#FFFFFF"),'cycle2'). You can also use setName($name) function.

  1. span style="color: #ff0000;">"background-color:<?php echo $this->cycle(array("#F0F0F0",
  2.                                                             "#FFFFFF"">
  3.   <td><?php echo $this->cycle(array(1,2,3),'number')->next()?></td>
  4.   <td><?php echo $this->escape($book['author'])?></td>
  5. </tr>
  6. <?php endforeach;?>

Partial Helper

The Partial view helper is used to render a specified template within its own variable scope. The primary use is for reusable template fragments with which you do not need to worry about variable name clashes. Additionally, they allow you to specify partial view scripts from specific modules.

A sibling to the Partial, the PartialLoop view helper allows you to pass iterable data, and render a partial for each item.

Note: PartialLoop Counter
 The PartialLoop view helper assigns a variable to the view named partialCounter which passes the current position of the array to the view script. This provides an easy way to have alternating colors on table rows for example.

Example #8 Basic Usage of Partials

Basic usage of partials is to render a template fragment in its own view scope. Consider the following partial script:

  1. span style="color: #808080; font-style: italic;">// partial.phtml ?>

You would then call it from your view script using the following:

  1. span style="color: #ff0000;">'partial.phtml''from' => 'Team Framework',
  2.     'subject' => 'view partials'

Which would then render:

  1. <ul>
  2.     <li>From: Team Framework</li>
  3.     <li>Subject: view partials</li>
  4. </ul>

Note: What is a model?
 A model used with the Partial view helper can be one of the following:

  • Array. If an array is passed, it should be associative, as its key/value pairs are assigned to the view with keys as view variables.

  • Object implementing toArray() method. If an object is passed an has a toArray() method, the results of toArray() will be assigned to the view object as view variables.

  • Standard object. Any other object will assign the results of object_get_vars() (essentially all public properties of the object) to the view object.

If your model is an object, you may want to have it passed as an object to the partial script, instead of serializing it to an array of variables. You can do this by setting the 'objectKey' property of the appropriate helper:
  1. // Tell partial to pass objects as 'model' variable
  2. 'model');
  3.  
  4. // Tell partial to pass objects from partialLoop as 'model' variable
  5. // in final partial view script:
  6. 'model');
This technique is particularly useful when passing Zend_Db_Table_Rowsets to partialLoop(), as you then have full access to your row objects within the view scripts, allowing you to call methods on them (such as retrieving values from parent or dependent rows).

Example #9 Using PartialLoop to Render Iterable Models

Typically, you'll want to use partials in a loop, to render the same content fragment many times; this way you can put large blocks of repeated content or complex display logic into a single location. However this has a performance impact, as the partial helper needs to be invoked once for each iteration.

The PartialLoop view helper helps solve this issue. It allows you to pass an iterable item (array or object implementing Iterator) as the model. It then iterates over this, passing, the items to the partial script as the model. Items in the iterator may be any model the Partial view helper allows.

Let's assume the following partial view script:

  1. span style="color: #808080; font-style: italic;">// partialLoop.phtml ?>

And the following "model":

  1. span style="color: #ff0000;">'key' => 'Mammal', 'value' => 'Camel''key' => 'Bird', 'value' => 'Penguin''key' => 'Reptile', 'value' => 'Asp''key' => 'Fish', 'value' => 'Flounder'),
  2. );

In your view script, you could then invoke the PartialLoop helper:

  1. span style="color: #ff0000;">'partialLoop.phtml'
  1. <dl>
  2.     <dt>Mammal</dt>
  3.     <dd>Camel</dd>
  4.  
  5.     <dt>Bird</dt>
  6.     <dd>Penguin</dd>
  7.  
  8.     <dt>Reptile</dt>
  9.     <dd>Asp</dd>
  10.  
  11.     <dt>Fish</dt>
  12.     <dd>Flounder</dd>
  13. </dl>

Example #10 Rendering Partials in Other Modules

Sometime a partial will exist in a different module. If you know the name of the module, you can pass it as the second argument to either partial() or partialLoop(), moving the $model argument to third position.

For instance, if there's a pager partial you wish to use that's in the 'list' module, you could grab it as follows:

  1. span style="color: #ff0000;">'pager.phtml', 'list'

In this way, you can re-use partials created specifically for other modules. That said, it's likely a better practice to put re-usable partials in shared view script paths.

Placeholder Helper

The Placeholder view helper is used to persist content between view scripts and view instances. It also offers some useful features such as aggregating content, capturing view script content for later use, and adding pre- and post-text to content (and custom separators for aggregated content).

Example #11 Basic Usage of Placeholders

Basic usage of placeholders is to persist view data. Each invocation of the Placeholder helper expects a placeholder name; the helper then returns a placeholder container object that you can either manipulate or simply echo out.

  1. span style="color: #ff0000;">'foo')->set("Some text for later"'foo');
  2.     // outputs "Some text for later"

Example #12 Using Placeholders to Aggregate Content

Aggregating content via placeholders can be useful at times as well. For instance, your view script may have a variable array from which you wish to retrieve messages to display later; a later view script can then determine how those will be rendered.

The Placeholder view helper uses containers that extend ArrayObject, providing a rich featureset for manipulating arrays. In addition, it offers a variety of methods for formatting the content stored in the container:

  • setPrefix($prefix) sets text with which to prefix the content. Use getPrefix() at any time to determine what the current setting is.

  • setPostfix($prefix) sets text with which to append the content. Use getPostfix() at any time to determine what the current setting is.

  • setSeparator($prefix) sets text with which to separate aggregated content. Use getSeparator() at any time to determine what the current setting is.

  • setIndent($prefix) can be used to set an indentation value for content. If an integer is passed, that number of spaces will be used; if a string is passed, the string will be used. Use getIndent() at any time to determine what the current setting is.

  1. span style="color: #ff0000;">'foo'
  1. span style="color: #ff0000;">'foo')->setPrefix("<ul>\n    <li>")
  2.                          ->setSeparator("</li><li>\n""</li></ul>\n"'foo');
  3.     // outputs as unordered list with pretty indentation

Because the Placeholder container objects extend ArrayObject, you can also assign content to a specific key in the container easily, instead of simply pushing it into the container. Keys may be accessed either as object properties or as array keys.

  1. span style="color: #ff0000;">'foo''foo''foo''bar'

Example #13 Using Placeholders to Capture Content

Occasionally you may have content for a placeholder in a view script that is easiest to template; the Placeholder view helper allows you to capture arbitrary content for later rendering using the following API.

  • captureStart($type, $key) begins capturing content.

    $type should be one of the Placeholder constants APPEND or SET. If APPEND, captured content is appended to the list of current content in the placeholder; if SET, captured content is used as the sole value of the placeholder (potentially replacing any previous content). By default, $type is APPEND.

    $key can be used to specify a specific key in the placeholder container to which you want content captured.

    captureStart() locks capturing until captureEnd() is called; you cannot nest capturing with the same placeholder container. Doing so will raise an exception.

  • captureEnd() stops capturing content, and places it in the container object according to how captureStart() was called.

  1. span style="color: #ff0000;">'foo'"foo"'foo''foo'
  1. span style="color: #ff0000;">'foo')->captureStart('SET', 'data'"foo"'foo''foo'

Concrete Placeholder Implementations

Zend Framework ships with a number of "concrete" placeholder implementations. These are for commonly used placeholders: doctype, page title, and various <head> elements. In all cases, calling the placeholder with no arguments returns the element itself.

Documentation for each element is covered separately, as linked below:

Doctype Helper

Valid HTML and XHTML documents should include a DOCTYPE declaration. Besides being difficult to remember, these can also affect how certain elements in your document should be rendered (for instance, CDATA escaping in <script> and <style> elements.

The Doctype helper allows you to specify one of the following types:

  • XHTML11

  • XHTML1_STRICT

  • XHTML1_TRANSITIONAL

  • XHTML1_FRAMESET

  • XHTML1_RDFA

  • XHTML_BASIC1

  • HTML4_STRICT

  • HTML4_LOOSE

  • HTML4_FRAMESET

  • HTML5

You can also specify a custom doctype as long as it is well-formed.

The Doctype helper is a concrete implementation of the Placeholder helper.

Example #14 Doctype Helper Basic Usage

You may specify the doctype at any time. However, helpers that depend on the doctype for their output will recognize it only after you have set it, so the easiest approach is to specify it in your bootstrap:

  1. span style="color: #ff0000;">'XHTML1_STRICT');

And then print it out on top of your layout script:

  1.  

Example #15 Retrieving the Doctype

If you need to know the doctype, you can do so by calling getDoctype() on the object, which is returned by invoking the helper.

  1.  

Typically, you'll simply want to know if the doctype is XHTML or not; for this, the isXhtml() method will suffice:

  1. span style="color: #808080; font-style: italic;">// do something differently
  2. }

You can also check if the doctype represents an HTML5 document.

  1. span style="color: #808080; font-style: italic;">// do something differently
  2. }

Example #16 Choosing a Doctype to Use with the Open Graph Protocol

To implement the » Open Graph Protocol, you may specify the XHTML1_RDFA doctype. This doctype allows a developer to use the » Resource Description Framework within an XHTML document.

  1. span style="color: #ff0000;">'XHTML1_RDFA');

The RDFa doctype allows XHTML to validate when the 'property' meta tag attribute is used per the Open Graph Protocol spec. Example within a view script:

  1. <?php echo $this->doctype('XHTML1_RDFA'); ?>
  2. <html xmlns="http://www.w3.org/1999/xhtml"
  3.       xmlns:og="http://opengraphprotocol.org/schema/">
  4. <head>
  5.    <meta property="og:type" content="musician" />

In the previous example, we set the property to og:type. The og references the Open Graph namespace we specified in the html tag. The content identifies the page as being about a musician. See the » Open Graph Protocol documentation for supported properties. The HeadMeta helper may be used to programmatically set these Open Graph Protocol meta tags.

Here is how you check if the doctype is set to XHTML1_RDFA:

  1. span style="color: #ff0000;">"http://www.w3.org/1999/xhtml""http://opengraphprotocol.org/schema/"
  2.       xmlns:fb="http://www.facebook.com/2008/fbml"

Gravatar View Helper

The Gravatar view helper is used to received avatars from Gravatar's service.

Example #17 Basic Usage of Gravatar View Helper

  1. // From a view script (using XHTML DOCTYPE):
  3.  
  4. /* results in the following output:
  5.     <img src="http://www.gravatar.com/avatar/23463b99b62a72f26ed677cc556c44e8?s=80&d=mm&r=g" />
  6. */

Note: Of course we can configure this helper. We can change height of image (by default it is 80px), and add CSS class or other attributes to image tag. The above simply shows the most basic usage.

Warning

Use a valid email address!

The email address you provide the helper should be valid. This class does not validate the address (only the rating parameter). It is recommended to validate your email address within your model layer.

Example #18 Advanced Usage of Gravatar View Helper

There are several ways to configure the returned gravatar. In most cases, you may either pass an array of options as a second argument to the helper, or call methods on the returned object in order to configure it.

  • The img_size option can be used to specify an alternate height; alternately, call setImgSize().

  • The secure option can be used to force usage of SSL in the returned image URI by passing a boolean true value (or disabling SSL usage by passing false). Alternately, call the setSecure() method. (By default, the setting follows the same security as the current page request.)

  • To add attributes to the image, pass an array of key/value pairs as the third argument to the helper, or call the setAttribs() method.

  1. // Within the view script (using HTML DOCTYPE)
  2. '[email protected]''imgSize' => 90, 'defaultImg' => 'monsterid', 'secure''class' => 'avatar', 'title' => 'Title for this image')
  3. );
  4.    
  5. // Or use mutator methods
  6. '[email protected]''class' => 'avatar', 'title' => 'Title for this image'));
  7.  
  8. /* Both generate the following output:
  9. <img class="avatar" title="Title for this image"
  10.     src="https://secure.gravatar.com/avatar/23463b99b62a72f26ed677cc556c44e8?s=90&d=monsterid&r=g" >
  11. */

Options

Zend_Service_Gravatar Options

img_size

An integer describing the height of the avatar, in pixels; defaults to "80".

default_img

Image to return if the gravatar service is unable to match the email address provided. Defaults to "mm", the "mystery man" image.

rating

Audience rating to confine returned images to. Defaults to "g"; may be one of "g", "pg", "r", or "x", in order of least offensive to most offensive.

secure

Whether or not to load the image via an SSL connection. Defaults to the what is detected from the current request.

HeadMeta Helper

The HTML <meta> element is used to provide meta information about your HTML document -- typically keywords, document character set, caching pragmas, etc. Meta tags may be either of the 'http-equiv' or 'name' types, must contain a 'content' attribute, and can also have either of the 'lang' or 'scheme' modifier attributes.

The HeadMeta helper supports the following methods for setting and adding meta tags:

  • appendName($keyValue, $content, $conditionalName)

  • offsetSetName($index, $keyValue, $content, $conditionalName)

  • prependName($keyValue, $content, $conditionalName)

  • setName($keyValue, $content, $modifiers)

  • appendHttpEquiv($keyValue, $content, $conditionalHttpEquiv)

  • offsetSetHttpEquiv($index, $keyValue, $content, $conditionalHttpEquiv)

  • prependHttpEquiv($keyValue, $content, $conditionalHttpEquiv)

  • setHttpEquiv($keyValue, $content, $modifiers)

  • setCharset($charset)

The following methods are also supported with XHTML1_RDFA doctype set with the Doctype helper:

  • appendProperty($property, $content, $modifiers)

  • offsetSetProperty($index, $property, $content, $modifiers)

  • prependProperty($property, $content, $modifiers)

  • setProperty($property, $content, $modifiers)

The $keyValue item is used to define a value for the 'name' or 'http-equiv' key; $content is the value for the 'content' key, and $modifiers is an optional associative array that can contain keys for 'lang' and/or 'scheme'.

You may also set meta tags using the headMeta() helper method, which has the following signature: headMeta($content, $keyValue, $keyType = 'name', $modifiers = array(), $placement = 'APPEND'). $keyValue is the content for the key specified in $keyType, which should be either 'name' or 'http-equiv'. $keyType may also be specified as 'property' if the doctype has been set to XHTML1_RDFA. $placement can be 'SET' (overwrites all previously stored values), 'APPEND' (added to end of stack), or 'PREPEND' (added to top of stack).

HeadMeta overrides each of append(), offsetSet(), prepend(), and set() to enforce usage of the special methods as listed above. Internally, it stores each item as a stdClass token, which it later serializes using the itemToString() method. This allows you to perform checks on the items in the stack, and optionally modify these items by simply modifying the object returned.

The HeadMeta helper is a concrete implementation of the Placeholder helper.

Example #20 HeadMeta Helper Basic Usage

You may specify a new meta tag at any time. Typically, you will specify client-side caching rules or SEO keywords.

For instance, if you wish to specify SEO keywords, you'd be creating a meta name tag with the name 'keywords' and the content the keywords you wish to associate with your page:

  1. // setting meta keywords
  2. 'keywords', 'framework, PHP, productivity');

If you wished to set some client-side caching rules, you'd set http-equiv tags with the rules you wish to enforce:

  1. // disabling client-side cache
  2. 'expires',
  3.                                    'Wed, 26 Feb 1997 08:21:57 GMT''pragma', 'no-cache''Cache-Control', 'no-cache');

Another popular use for meta tags is setting the content type, character set, and language:

  1. // setting content type and character set
  2. 'Content-Type',
  3.                                    'text/html; charset=UTF-8''Content-Language', 'en-US');

If you are serving an HTML5 document, you should provide the character set like this:

  1. // setting character set in HTML5
  2. $this->headMeta()->setCharset('UTF-8'); // Will look like <meta charset="UTF-8">

As a final example, an easy way to display a transitional message before a redirect is using a "meta refresh":

  1. // setting a meta refresh for 3 seconds to a new url:
  2. 'Refresh',
  3.                                    '3;URL=http://www.some.org/some.html');

When you're ready to place your meta tags in the layout, simply echo the helper:

  1.  

Example #21 HeadMeta Usage with XHTML1_RDFA doctype

Enabling the RDFa doctype with the Doctype helper enables the use of the 'property' attribute (in addition to the standard 'name' and 'http-equiv') with HeadMeta. This is commonly used with the Facebook » Open Graph Protocol.

For instance, you may specify an open graph page title and type as follows:

  1. span style="color: #ff0000;">'og:title', 'my article title');
  2. $this->headMeta()->setProperty('og:type', 'article'// output is:
  3. //   <meta property="og:title" content="my article title" />
  4. //   <meta property="og:type" content="article" />

HeadScript Helper

The HTML <script> element is used to either provide inline client-side scripting elements or link to a remote resource containing client-side scripting code. The HeadScript helper allows you to manage both.

The HeadScript helper supports the following methods for setting and adding scripts:

  • appendFile($src, $type = 'text/javascript', $attrs = array())

  • offsetSetFile($index, $src, $type = 'text/javascript', $attrs = array())

  • prependFile($src, $type = 'text/javascript', $attrs = array())

  • setFile($src, $type = 'text/javascript', $attrs = array())

  • appendScript($script, $type = 'text/javascript', $attrs = array())

  • offsetSetScript($index, $script, $type = 'text/javascript', $attrs = array())

  • prependScript($script, $type = 'text/javascript', $attrs = array())

  • setScript($script, $type = 'text/javascript', $attrs = array())

In the case of the * File() methods, $src is the remote location of the script to load; this is usually in the form of a URL or a path. For the * Script() methods, $script is the client-side scripting directives you wish to use in the element.

Note: Setting Conditional Comments
 HeadScript allows you to wrap the script tag in conditional comments, which allows you to hide it from specific browsers. To add the conditional tags, pass the conditional value as part of the $attrs parameter in the method calls.

Example #22 Headscript With Conditional Comments

  1. // adding scripts
  2. '/js/prototype.js',
  3.     'text/javascript''conditional' => 'lt IE 7')
  4. );

Note: Preventing HTML style comments or CDATA wrapping of scripts
 By default HeadScript will wrap scripts with HTML comments or it wraps scripts with XHTML cdata. This behavior can be problematic when you intend to use the script tag in an alternative way by setting the type to something other then 'text/javascript'. To prevent such escaping, pass an noescape with a value of true as part of the $attrs parameter in the method calls.

Example #23 Create an jQuery template with the headScript

  1. // jquery template
  2. $template = '<div class="book">{{:title}}</div>''text/x-jquery-tmpl''id='tmpl-book', 'noescape' => true)
  3. );

HeadScript also allows capturing scripts; this can be useful if you want to create the client-side script programmatically, and then place it elsewhere. The usage for this will be showed in an example below.

Finally, you can also use the headScript() method to quickly add script elements; the signature for this is headScript($mode = 'FILE', $spec, $placement = 'APPEND'). The $mode is either 'FILE' or 'SCRIPT', depending on if you're linking a script or defining one. $spec is either the script file to link or the script source itself. $placement should be either 'APPEND', 'PREPEND', or 'SET'.

HeadScript overrides each of append(), offsetSet(), prepend(), and set() to enforce usage of the special methods as listed above. Internally, it stores each item as a stdClass token, which it later serializes using the itemToString() method. This allows you to perform checks on the items in the stack, and optionally modify these items by simply modifying the object returned.

The HeadScript helper is a concrete implementation of the Placeholder helper.

Note: Use InlineScript for HTML Body Scripts
 HeadScript's sibling helper, InlineScript, should be used when you wish to include scripts inline in the HTML body. Placing scripts at the end of your document is a good practice for speeding up delivery of your page, particularly when using 3rd party analytics scripts.

Note: Arbitrary Attributes are Disabled by Default
 By default, HeadScript only will render <script> attributes that are blessed by the W3C. These include 'type', 'charset', 'defer', 'language', and 'src'. However, some javascript frameworks, notably » Dojo, utilize custom attributes in order to modify behavior. To allow such attributes, you can enable them via the setAllowArbitraryAttributes() method:

  1.  

Example #24 HeadScript Helper Basic Usage

You may specify a new script tag at any time. As noted above, these may be links to outside resource files or scripts themselves.

  1. // adding scripts
  2. '/js/prototype.js'

Order is often important with client-side scripting; you may need to ensure that libraries are loaded in a specific order due to dependencies each have; use the various append, prepend, and offsetSet directives to aid in this task:

  1. // Putting scripts in order
  2.  
  3. // place at a particular offset to ensure loaded last
  4. '/js/myfuncs.js');
  5.  
  6. // use scriptaculous effects (append uses next index, 101)
  7. '/js/scriptaculous.js');
  8.  
  9. // but always have base prototype script load first:
  10. '/js/prototype.js');

When you're finally ready to output all scripts in your layout script, simply echo the helper:

  1.  

Example #25 Capturing Scripts Using the HeadScript Helper

Sometimes you need to generate client-side scripts programmatically. While you could use string concatenation, heredocs, and the like, often it's easier just to do so by creating the script and sprinkling in PHP tags. HeadScript lets you do just that, capturing it to the stack:

  1. span style="color: #ff0000;">'<?php echo $this->baseUrl ?>';
  2. $('foo_form'

The following assumptions are made:

  • The script will be appended to the stack. If you wish for it to replace the stack or be added to the top, you will need to pass 'SET' or 'PREPEND', respectively, as the first argument to captureStart().

  • The script MIME type is assumed to be 'text/javascript'; if you wish to specify a different type, you will need to pass it as the second argument to captureStart().

  • If you wish to specify any additional attributes for the <script> tag, pass them in an array as the third argument to captureStart().

HeadStyle Helper

The HTML <style> element is used to include CSS stylesheets inline in the HTML <head> element.

Note: Use HeadLink to link CSS files
 HeadLink should be used to create <link> elements for including external stylesheets. HeadStyle is used when you wish to define your stylesheets inline.

The HeadStyle helper supports the following methods for setting and adding stylesheet declarations:

  • appendStyle($content, $attributes = array())

  • offsetSetStyle($index, $content, $attributes = array())

  • prependStyle($content, $attributes = array())

  • setStyle($content, $attributes = array())

In all cases, $content is the actual CSS declarations. $attributes are any additional attributes you wish to provide to the style tag: lang, title, media, or dir are all permissible.

Note: Setting Conditional Comments
 HeadStyle allows you to wrap the style tag in conditional comments, which allows you to hide it from specific browsers. To add the conditional tags, pass the conditional value as part of the $attributes parameter in the method calls.

Example #26 Headstyle With Conditional Comments

  1. // adding scripts
  2. 'conditional' => 'lt IE 7'));

HeadStyle also allows capturing style declarations; this can be useful if you want to create the declarations programmatically, and then place them elsewhere. The usage for this will be showed in an example below.

Finally, you can also use the headStyle() method to quickly add declarations elements; the signature for this is headStyle($content$placement = 'APPEND', $attributes = array()). $placement should be either 'APPEND', 'PREPEND', or 'SET'.

HeadStyle overrides each of append(), offsetSet(), prepend(), and set() to enforce usage of the special methods as listed above. Internally, it stores each item as a stdClass token, which it later serializes using the itemToString() method. This allows you to perform checks on the items in the stack, and optionally modify these items by simply modifying the object returned.

The HeadStyle helper is a concrete implementation of the Placeholder helper.

Note: UTF-8 encoding used by default
 By default, Zend Framework uses UTF-8 as its default encoding, and, specific to this case, Zend_View does as well. Character encoding can be set differently on the view object itself using the setEncoding() method (or the encoding instantiation parameter). However, since Zend_View_Interface does not define accessors for encoding, it's possible that if you are using a custom view implementation with this view helper, you will not have a getEncoding() method, which is what the view helper uses internally for determining the character set in which to encode.
If you do not want to utilize UTF-8 in such a situation, you will need to implement a getEncoding() method in your custom view implementation.

Example #27 HeadStyle Helper Basic Usage

You may specify a new style tag at any time:

  1. // adding styles

Order is very important with CSS; you may need to ensure that declarations are loaded in a specific order due to the order of the cascade; use the various append, prepend, and offsetSet directives to aid in this task:

  1. // Putting styles in order
  2.  
  3. // place at a particular offset:
  4. $this->headStyle()->offsetSetStyle(100, $customStyles);
  5.  
  6. // place at end:
  7. // place at beginning

When you're finally ready to output all style declarations in your layout script, simply echo the helper:

  1.  

Example #28 Capturing Style Declarations Using the HeadStyle Helper

Sometimes you need to generate CSS style declarations programmatically. While you could use string concatenation, heredocs, and the like, often it's easier just to do so by creating the styles and sprinkling in PHP tags. HeadStyle lets you do just that, capturing it to the stack:

  1.  

The following assumptions are made:

  • The style declarations will be appended to the stack. If you wish for them to replace the stack or be added to the top, you will need to pass 'SET' or 'PREPEND', respectively, as the first argument to captureStart().

  • If you wish to specify any additional attributes for the <style> tag, pass them in an array as the second argument to captureStart().

HeadTitle Helper

The HTML <title> element is used to provide a title for an HTML document. The HeadTitle helper allows you to programmatically create and store the title for later retrieval and output.

The HeadTitle helper is a concrete implementation of the Placeholder helper. It overrides the toString() method to enforce generating a <title> element, and adds a headTitle() method for quick and easy setting and aggregation of title elements. The signature for that method is headTitle($title, $setType = null); by default, the value is appended to the stack (aggregating title segments) if left at null, but you may also specify either 'PREPEND' (place at top of stack) or 'SET' (overwrite stack).

Since setting the aggregating (attach) order on each call to headTitle can be cumbersome, you can set a default attach order by calling setDefaultAttachOrder() which is applied to all headTitle() calls unless you explicitly pass a different attach order as the second parameter.

Example #29 HeadTitle Helper Basic Usage

You may specify a title tag at any time. A typical usage would have you setting title segments for each level of depth in your application: site, controller, action, and potentially resource.

  1. // setting the controller and action name as title segments:
  2. // setting the site in the title; possibly in the layout script:
  3. $this->headTitle('Zend Framework');
  4.  
  5. // setting a separator string for segments:
  6. $this->headTitle()->setSeparator(' / ');

When you're finally ready to render the title in your layout script, simply echo the helper:

  1.  

HTML Object Helpers

The HTML <object> element is used for embedding media like Flash or QuickTime in web pages. The object view helpers take care of embedding media with minimum effort.

There are four initial Object helpers:

  • htmlFlash() Generates markup for embedding Flash files.

  • htmlObject() Generates markup for embedding a custom Object.

  • htmlPage() Generates markup for embedding other (X)HTML pages.

  • htmlQuicktime() Generates markup for embedding QuickTime files.

All of these helpers share a similar interface. For this reason, this documentation will only contain examples of two of these helpers.

Example #30 Flash helper

Embedding Flash in your page using the helper is pretty straight-forward. The only required argument is the resource URI.

  1. span style="color: #ff0000;">'/path/to/flash.swf'

This outputs the following HTML:

  1. <object data="/path/to/flash.swf"
  2.         type="application/x-shockwave-flash"
  3.         classid="clsid:D27CDB6E-AE6D-11cf-96B8-444553540000"
  4.         codebase="http://download.macromedia.com/pub/shockwave/cabs/flash/swflash.cab">
  5. </object>

Additionally you can specify attributes, parameters and content that can be rendered along with the <object>. This will be demonstrated using the htmlObject() helper.

Example #31 Customizing the object by passing additional arguments

The first argument in the object helpers is always required. It is the URI to the resource you want to embed. The second argument is only required in the htmlObject() helper. The other helpers already contain the correct value for this argument. The third argument is used for passing along attributes to the object element. It only accepts an array with key-value pairs. classid and codebase are examples of such attributes. The fourth argument also only takes a key-value array and uses them to create <param> elements. You will see an example of this shortly. Lastly, there is the option of providing additional content to the object. Now for an example which utilizes all arguments.

  1. span style="color: #ff0000;">'/path/to/file.ext',
  2.     'mime/type''attr1' => 'aval1',
  3.         'attr2' => 'aval2''param1' => 'pval1',
  4.         'param2' => 'pval2'
  5.     ),
  6.     'some content'
  7. );
  8.  
  9. /*
  10. This would output:
  11.  
  12. <object data="/path/to/file.ext" type="mime/type"
  13.     attr1="aval1" attr2="aval2">
  14.     <param name="param1" value="pval1" />
  15.     <param name="param2" value="pval2" />
  16.     some content
  17. </object>
  18. */

InlineScript Helper

The HTML <script> element is used to either provide inline client-side scripting elements or link to a remote resource containing client-side scripting code. The InlineScript helper allows you to manage both. It is derived from HeadScript, and any method of that helper is available; however, use the inlineScript() method in place of headScript().

Note: Use InlineScript for HTML Body Scripts
 InlineScript, should be used when you wish to include scripts inline in the HTML body. Placing scripts at the end of your document is a good practice for speeding up delivery of your page, particularly when using 3rd party analytics scripts.
Some JS libraries need to be included in the HTML head; use HeadScript for those scripts.

RenderToPlaceholder Helper

Renders a template (view script) and stores the rendered output as a placeholder variable for later use.

Note: The helper uses the Placeholder helper and his Capture methods.

Example #32 Basic Usage of RenderToPlaceholder

  1. span style="color: #808080; font-style: italic;">// View script (backlink.phtml):
  2. '<p class="older"><a href="%s">Older posts</a></p>''controller' => 'index', 'action' => 'index'// Usage:
  3. 'backlink.phtml', 'link''link');
  4. // Output: <p class="older"><a href="index/index">Older posts</a></p>

JSON Helper

When creating views that return JSON, it's important to also set the appropriate response header. The JSON view helper does exactly that. In addition, by default, it disables layouts (if currently enabled), as layouts generally aren't used with JSON responses.

The JSON helper sets the following header:

  1. Content-Type: application/json

Most AJAX libraries look for this header when parsing responses to determine how to handle the content.

Usage of the JSON helper is very straightforward:

  1.  

Note: Keeping layouts and enabling encoding using Zend_Json_Expr
 Each method in the JSON helper accepts a second, optional argument. This second argument can be a boolean flag to enable or disable layouts, or an array of options that will be passed to Zend_Json::encode() and used internally to encode data.
To keep layouts, the second parameter needs to be boolean TRUE. When the second parameter is an array, keeping layouts can be achieved by including a keepLayouts key with a value of a boolean TRUE.

  1. // Boolean true as second argument enables layouts:
  2. // Or boolean true as "keepLayouts" key:
  3. 'keepLayouts'
Zend_Json::encode allows the encoding of native JSON expressions using Zend_Json_Expr objects. This option is disabled by default. To enable this option, pass a boolean TRUE to the enableJsonExprFinder key of the options array:
  1. span style="color: #ff0000;">'enableJsonExprFinder''keepLayouts'

Note: Sending pre-encoded JSON
 By default, the JSON helper will JSON-encode the data provided to the helper's first parameter. If you wish to pass in data which has already been encoded into JSON, the third parameter needs to be set to boolean FALSE. When the second parameter is an array, disabling JSON encoding can be achived by including a encodeData key with the value of boolean FALSE:

  1. // Boolean false as third argument disables internal JSON encoding of data
  2. // Or boolean false as "encodeData" key:
  3. 'encodeData'

Navigation Helpers

The navigation helpers are used for rendering navigational elements from Zend_Navigation_Container instances.

There are 5 built-in helpers:

  • Breadcrumbs, used for rendering the path to the currently active page.

  • Links, used for rendering navigational head links (e.g. <link rel="next" href="..." />)

  • Menu, used for rendering menus.

  • Sitemap, used for rendering sitemaps conforming to the » Sitemaps XML format.

  • Navigation, used for proxying calls to other navigational helpers.

All built-in helpers extend Zend_View_Helper_Navigation_HelperAbstract, which adds integration with ACL and translation. The abstract class implements the interface Zend_View_Helper_Navigation_Helper, which defines the following methods:

  • getContainer() and setContainer() gets and sets the navigation container the helper should operate on by default, and hasContainer() checks if the helper has container registered.

  • getTranslator() and setTranslator() gets and sets the translator used for translating labels and titles. getUseTranslator() and setUseTranslator() controls whether the translator should be enabled. The method hasTranslator() checks if the helper has a translator registered.

  • getAcl(), setAcl(), getRole() and setRole(), gets and sets ACL (Zend_Acl) instance and role ( String or Zend_Acl_Role_Interface) used for filtering out pages when rendering. getUseAcl() and setUseAcl() controls whether ACL should be enabled. The methods hasAcl() and hasRole() checks if the helper has an ACL instance or a role registered.

  • __toString(), magic method to ensure that helpers can be rendered by echoing the helper instance directly.

  • render(), must be implemented by concrete helpers to do the actual rendering.

In addition to the method stubs from the interface, the abstract class also implements the following methods:

  • getIndent() and setIndent() gets and sets indentation. The setter accepts a String or an Integer . In the case of an Integer , the helper will use the given number of spaces for indentation. I.e., setIndent(4) means 4 initial spaces of indentation. Indentation can be specified for all helpers except the Sitemap helper.

  • getMinDepth() and setMinDepth() gets and sets the minimum depth a page must have to be included by the helper. Setting NULL means no minimum depth.

  • getMaxDepth() and setMaxDepth() gets and sets the maximum depth a page can have to be included by the helper. Setting NULL means no maximum depth.

  • getRenderInvisible() and setRenderInvisible() gets and sets whether to render items that have been marked as invisible or not.

  • __call() is used for proxying calls to the container registered in the helper, which means you can call methods on a helper as if it was a container. See example below.

  • findActive($container, $minDepth, $maxDepth) is used for finding the deepest active page in the given container. If depths are not given, the method will use the values retrieved from getMinDepth() and getMaxDepth(). The deepest active page must be between $minDepth and $maxDepth inclusively. Returns an array containing a reference to the found page instance and the depth at which the page was found.

  • htmlify() renders an 'a' HTML element from a Zend_Navigation_Page instance.

  • accept() is used for determining if a page should be accepted when iterating containers. This method checks for page visibility and verifies that the helper's role is allowed access to the page's resource and privilege.

  • The static method setDefaultAcl() is used for setting a default ACL object that will be used by helpers.

  • The static method setDefaultRole() is used for setting a default ACL that will be used by helpers

If a navigation container is not explicitly set in a helper using $helper->setContainer($nav), the helper will look for a container instance with the key Zend_Navigation in the registry. If a container is not explicitly set or found in the registry, the helper will create an empty Zend_Navigation container when calling $helper->getContainer().

Example #33 Proxying calls to the navigation container

Navigation view helpers use the magic method __call() to proxy method calls to the navigation container that is registered in the view helper.

  1. span style="color: #ff0000;">'type' => 'uri',
  2.     'label' => 'New page'));

The call above will add a page to the container in the Navigation helper.

Translation of labels and titles

The navigation helpers support translation of page labels and titles. You can set a translator of type Zend_Translate or Zend_Translate_Adapter in the helper using $helper->setTranslator($translator), or like with other I18n-enabled components; by adding the translator to the registry by using the key Zend_Translate.

If you want to disable translation, use $helper->setUseTranslator(false).

The proxy helper will inject its own translator to the helper it proxies to if the proxied helper doesn't already have a translator.

Note: There is no translation in the sitemap helper, since there are no page labels or titles involved in an XML sitemap.

Integration with ACL

All navigational view helpers support ACL inherently from the class Zend_View_Helper_Navigation_HelperAbstract. A Zend_Acl object can be assigned to a helper instance with $helper->setAcl($acl), and role with $helper->setRole('member') or $helper->setRole(new Zend_Acl_Role('member')) . If ACL is used in the helper, the role in the helper must be allowed by the ACL to access a page's resource and/or have the page's privilege for the page to be included when rendering.

If a page is not accepted by ACL, any descendant page will also be excluded from rendering.

The proxy helper will inject its own ACL and role to the helper it proxies to if the proxied helper doesn't already have any.

The examples below all show how ACL affects rendering.

Navigation setup used in examples

This example shows the setup of a navigation container for a fictional software company.

Notes on the setup:

  • The domain for the site is www.example.com.

  • Interesting page properties are marked with a comment.

  • Unless otherwise is stated in other examples, the user is requesting the URL http://www.example.com/products/server/faq/, which translates to the page labeled FAQ under Foo Server.

  • The assumed ACL and router setup is shown below the container setup.

  1. /*
  2. * Navigation container (config/array)
  3.  
  4. * Each element in the array will be passed to
  5. * Zend_Navigation_Page::factory() when constructing
  6. * the navigation container below.
  7. */'label'      => 'Home',
  8.         'title'      => 'Go Home',
  9.         'module'     => 'default',
  10.         'controller' => 'index',
  11.         'action'     => 'index',
  12.         'order'      => -100 // make sure home is the first page
  13. 'label'      => 'Special offer this week only!',
  14.         'module'     => 'store',
  15.         'controller' => 'offer',
  16.         'action'     => 'amazing',
  17.         'visible'// not visible
  18. 'label'      => 'Products',
  19.         'module'     => 'products',
  20.         'controller' => 'index',
  21.         'action'     => 'index',
  22.         'pages''label'      => 'Foo Server',
  23.                 'module'     => 'products',
  24.                 'controller' => 'server',
  25.                 'action'     => 'index',
  26.                 'pages''label'      => 'FAQ',
  27.                         'module'     => 'products',
  28.                         'controller' => 'server',
  29.                         'action'     => 'faq',
  30.                         'rel''canonical' => 'http://www.example.com/?page=faq',
  31.                             'alternate''module'     => 'products',
  32.                                 'controller' => 'server',
  33.                                 'action'     => 'faq',
  34.                                 'params''format' => 'xml''label'      => 'Editions',
  35.                         'module'     => 'products',
  36.                         'controller' => 'server',
  37.                         'action'     => 'editions''label'      => 'System Requirements',
  38.                         'module'     => 'products',
  39.                         'controller' => 'server',
  40.                         'action'     => 'requirements''label'      => 'Foo Studio',
  41.                 'module'     => 'products',
  42.                 'controller' => 'studio',
  43.                 'action'     => 'index',
  44.                 'pages''label'      => 'Customer Stories',
  45.                         'module'     => 'products',
  46.                         'controller' => 'studio',
  47.                         'action'     => 'customers''label'      => 'Support',
  48.                         'module'     => 'prodcts',
  49.                         'controller' => 'studio',
  50.                         'action'     => 'support''label'      => 'Company',
  51.         'title'      => 'About us',
  52.         'module'     => 'company',
  53.         'controller' => 'about',
  54.         'action'     => 'index',
  55.         'pages''label'      => 'Investor Relations',
  56.                 'module'     => 'company',
  57.                 'controller' => 'about',
  58.                 'action'     => 'investors''label'      => 'News',
  59.                 'class'      => 'rss', // class
  60.                 'module'     => 'company',
  61.                 'controller' => 'news',
  62.                 'action'     => 'index',
  63.                 'pages''label'      => 'Press Releases',
  64.                         'module'     => 'company',
  65.                         'controller' => 'news',
  66.                         'action'     => 'press''label'      => 'Archive',
  67.                         'route'      => 'archive', // route
  68.                         'module'     => 'company',
  69.                         'controller' => 'news',
  70.                         'action'     => 'archive''label'      => 'Community',
  71.         'module'     => 'community',
  72.         'controller' => 'index',
  73.         'action'     => 'index',
  74.         'pages''label'      => 'My Account',
  75.                 'module'     => 'community',
  76.                 'controller' => 'account',
  77.                 'action'     => 'index',
  78.                 'resource'   => 'mvc:community.account' // resource
  79. 'label' => 'Forums',
  80.                 'uri'   => 'http://forums.example.com/',
  81.                 'class' => 'external' // class
  82. 'label'      => 'Administration',
  83.         'module'     => 'admin',
  84.         'controller' => 'index',
  85.         'action'     => 'index',
  86.         'resource'   => 'mvc:admin', // resource
  87.         'pages''label'      => 'Write new article',
  88.                 'module'     => 'admin',
  89.                 'controller' => 'post',
  90.                 'aciton'     => 'write'
  91.             )
  92.         )
  93.     )
  94. );
  95.  
  96. // Create container from array
  97. // Store the container in the proxy helper:
  98. $view->getHelper('navigation')->setContainer($container);
  99.  
  100. // ...or simply:
  101. $view->navigation($container);
  102.  
  103. // ...or store it in the reigstry:
  104. 'Zend_Navigation', $container);

In addition to the container above, the following setup is assumed:

  1. // Setup router (default routes and 'archive' route):
  2. 'archive''/archive/:year''module'     => 'company',
  3.             'controller' => 'news',
  4.             'action'     => 'archive',
  5.             'year''Y''year' => '\d+')
  6.     )
  7. );
  8.  
  9. // Setup ACL:
  10. 'member''admin''mvc:admin''mvc:community.account'));
  11. $acl->allow('member', 'mvc:community.account');
  12. $acl->allow('admin'// Store ACL and role in the proxy helper:
  13. $view->navigation()->setAcl($acl)->setRole('member');
  14.  
  15. // ...or set default ACL and role statically:
  16. 'member');

Breadcrumbs Helper

Breadcrumbs are used for indicating where in a sitemap a user is currently browsing, and are typically rendered like this: "You are here: Home > Products > FantasticProduct 1.0". The breadcrumbs helper follows the guidelines from » Breadcrumbs Pattern - Yahoo! Design Pattern Library, and allows simple customization (minimum/maximum depth, indentation, separator, and whether the last element should be linked), or rendering using a partial view script.

The Breadcrumbs helper works like this; it finds the deepest active page in a navigation container, and renders an upwards path to the root. For MVC pages, the "activeness" of a page is determined by inspecting the request object, as stated in the section on Zend_Navigation_Page_Mvc.

The helper sets the minDepth property to 1 by default, meaning breadcrumbs will not be rendered if the deepest active page is a root page. If maxDepth is specified, the helper will stop rendering when at the specified depth (e.g. stop at level 2 even if the deepest active page is on level 3).

Methods in the breadcrumbs helper:

  • {get|set}Separator() gets/sets separator string that is used between breadcrumbs. Defualt is ' &gt; '.

  • {get|set}LinkLast() gets/sets whether the last breadcrumb should be rendered as an anchor or not. Default is FALSE.

  • {get|set}Partial() gets/sets a partial view script that should be used for rendering breadcrumbs. If a partial view script is set, the helper's render() method will use the renderPartial() method. If no partial is set, the renderStraight() method is used. The helper expects the partial to be a String or an Array with two elements. If the partial is a String , it denotes the name of the partial script to use. If it is an Array , the first element will be used as the name of the partial view script, and the second element is the module where the script is found.

  • renderStraight() is the default render method.

  • renderPartial() is used for rendering using a partial view script.

Example #34 Rendering breadcrumbs

This example shows how to render breadcrumbs with default settings.

  1. span style="color: #ff0000;">"/products">Products</a> &gt; <a href="/products/server">Foo Server</a> &gt; FAQ

Example #35 Specifying indentation

This example shows how to render breadcrumbs with initial indentation.

  1. span style="color: #ff0000;">"/products">Products</a> &gt; <a href="/products/server">Foo Server</a> &gt; FAQ

Example #36 Customize breadcrumbs output

This example shows how to customze breadcrumbs output by specifying various options.

  1. span style="color: #808080; font-style: italic;">// link last page
  2. // stop at level 1
  3.           ->setSeparator(' &#9654;'// cool separator with newline
  4. "/products">Products</a> &#9654;
  5. <a href="/products/server">Foo Server</a>
  6.  
  7. /////////////////////////////////////////////////////

Example #37 Rendering breadcrumbs using a partial view script

This example shows how to render customized breadcrumbs using a partial vew script. By calling setPartial(), you can specify a partial view script that will be used when calling render(). When a partial is specified, the renderPartial() method will be called. This method will find the deepest active page and pass an array of pages that leads to the active page to the partial view script.

In a layout:

  1. span style="color: #ff0000;">'breadcrumbs.phtml', 'default'));

Contents of application/modules/default/views/breadcrumbs.phtml:

  1. span style="color: #ff0000;">', ''$a', 'return $a->getLabel();'),
  2.         $this->pages));

Output:

  1. Products, Foo Server, FAQ

Menu Helper

The Menu helper is used for rendering menus from navigation containers. By default, the menu will be rendered using HTML UL and LI tags, but the helper also allows using a partial view script.

Methods in the Menu helper:

  • {get|set}UlClass() gets/sets the CSS class used in renderMenu().

  • {get|set}ActiveClass() gets/sets the CSS class for the active elements when rendering.

  • {get|set}OnlyActiveBranch() gets/sets a flag specifying whether only the active branch of a container should be rendered.

  • {get|set}ExpandSiblingNodesOfActiveBranch() gets/sets a flag specifying whether the sibling nodes of all nodes in the active branch should also be expanded and rendered.

  • {get|set}RenderParents() gets/sets a flag specifying whether parents should be rendered when only rendering active branch of a container. If set to FALSE, only the deepest active menu will be rendered.

  • {get|set}Partial() gets/sets a partial view script that should be used for rendering menu. If a partial view script is set, the helper's render() method will use the renderPartial() method. If no partial is set, the renderMenu() method is used. The helper expects the partial to be a String or an Array with two elements. If the partial is a String , it denotes the name of the partial script to use. If it is an Array , the first element will be used as the name of the partial view script, and the second element is the module where the script is found.

  • htmlify() overrides the method from the abstract class to return span elements if the page has no href.

  • renderMenu($container = null, $options = array()) is the default render method, and will render a container as a HTML UL list.

    If $container is not given, the container registered in the helper will be rendered.

    $options is used for overriding options specified temporarily without rsetting the values in the helper instance. It is an associative array where each key corresponds to an option in the helper.

    Recognized options:

    • indent; indentation. Expects a String or an int value.

    • minDepth; minimum depth. Expcects an int or NULL (no minimum depth).

    • maxDepth; maximum depth. Expcects an int or NULL (no maximum depth).

    • ulClass; CSS class for ul element. Expects a String .

    • activeClass; CSS class for for the active elements when rendering. Expects a String .

    • onlyActiveBranch; whether only active branch should be rendered. Expects a Boolean value.

    • expandSiblingNodesOfActiveBranch; whether the sibling nodes of nodes in the active branch should be expanded and rendered. Expects a Boolean value.

    • renderParents; whether parents should be rendered if only rendering active branch. Expects a Boolean value.

    If an option is not given, the value set in the helper will be used.

  • renderPartial() is used for rendering the menu using a partial view script.

  • renderSubMenu() renders the deepest menu level of a container's active branch.

Example #41 Rendering a menu

This example shows how to render a menu from a container registered/found in the view helper. Notice how pages are filtered out based on visibility and ACL.

  1. span style="color: #ff0000;">"navigation">
  2.     <li>
  3.         <a title="Go Home" href="/""active">
  4.         <a href="/products""active">
  5.                 <a href="/products/server""active">
  6.                         <a href="/products/server/faq">FAQ</a>
  7.                     </li>
  8.                     <li>
  9.                         <a href="/products/server/editions">Editions</a>
  10.                     </li>
  11.                     <li>
  12.                         <a href="/products/server/requirements""/products/studio">Foo Studio</a>
  13.                 <ul>
  14.                     <li>
  15.                         <a href="/products/studio/customers">Customer Stories</a>
  16.                     </li>
  17.                     <li>
  18.                         <a href="/prodcts/studio/support">Support</a>
  19.                     </li>
  20.                 </ul>
  21.             </li>
  22.         </ul>
  23.     </li>
  24.     <li>
  25.         <a title="About us" href="/company/about">Company</a>
  26.         <ul>
  27.             <li>
  28.                 <a href="/company/about/investors""rss" href="/company/news""/company/news/press""/archive">Archive</a>
  29.                     </li>
  30.                 </ul>
  31.             </li>
  32.         </ul>
  33.     </li>
  34.     <li>
  35.         <a href="/community">Community</a>
  36.         <ul>
  37.             <li>
  38.                 <a href="/community/account""external" href="http://forums.example.com/"

Example #42 Calling renderMenu() directly

This example shows how to render a menu that is not registered in the view helper by calling the renderMenu() directly and specifying a few options.

  1. span style="color: #808080; font-style: italic;">// render only the 'Community' menu
  2. 'Community''indent'  => 16,
  3.     'ulClass' => 'community'"community">
  4.                     <li>
  5.                         <a href="/community/account""external" href="http://forums.example.com/"

Example #43 Rendering the deepest active menu

This example shows how the renderSubMenu() will render the deepest sub menu of the active branch.

Calling renderSubMenu($container, $ulClass, $indent) is equivalent to calling renderMenu($container, $options) with the following options:

  1. span style="color: #ff0000;">'ulClass''indent'           => $indent,
  2.     'minDepth''maxDepth''onlyActiveBranch''renderParents'
  1. span style="color: #ff0000;">'sidebar''FAQ' or 'Foo Server'"sidebar""active">
  2.             <a href="/products/server/faq">FAQ</a>
  3.         </li>
  4.         <li>
  5.             <a href="/products/server/editions">Editions</a>
  6.         </li>
  7.         <li>
  8.             <a href="/products/server/requirements"

Example #44 Rendering a menu with maximum depth

  1. span style="color: #ff0000;">"navigation">
  2.     <li>
  3.         <a title="Go Home" href="/""active">
  4.         <a href="/products""active">
  5.                 <a href="/products/server">Foo Server</a>
  6.             </li>
  7.             <li>
  8.                 <a href="/products/studio">Foo Studio</a>
  9.             </li>
  10.         </ul>
  11.     </li>
  12.     <li>
  13.         <a title="About us" href="/company/about">Company</a>
  14.         <ul>
  15.             <li>
  16.                 <a href="/company/about/investors""rss" href="/company/news""/community">Community</a>
  17.         <ul>
  18.             <li>
  19.                 <a href="/community/account""external" href="http://forums.example.com/"

Example #45 Rendering a menu with minimum depth

  1. span style="color: #ff0000;">"navigation""active">
  2.         <a href="/products/server""active">
  3.                 <a href="/products/server/faq">FAQ</a>
  4.             </li>
  5.             <li>
  6.                 <a href="/products/server/editions">Editions</a>
  7.             </li>
  8.             <li>
  9.                 <a href="/products/server/requirements""/products/studio">Foo Studio</a>
  10.         <ul>
  11.             <li>
  12.                 <a href="/products/studio/customers">Customer Stories</a>
  13.             </li>
  14.             <li>
  15.                 <a href="/prodcts/studio/support">Support</a>
  16.             </li>
  17.         </ul>
  18.     </li>
  19.     <li>
  20.         <a href="/company/about/investors""rss" href="/company/news""/company/news/press""/archive">Archive</a>
  21.             </li>
  22.         </ul>
  23.     </li>
  24.     <li>
  25.         <a href="/community/account""external" href="http://forums.example.com/"

Example #46 Rendering only the active branch of a menu

  1. span style="color: #ff0000;">"navigation""active">
  2.         <a href="/products""active">
  3.                 <a href="/products/server""active">
  4.                         <a href="/products/server/faq">FAQ</a>
  5.                     </li>
  6.                     <li>
  7.                         <a href="/products/server/editions">Editions</a>
  8.                     </li>
  9.                     <li>
  10.                         <a href="/products/server/requirements"

Example #47 Rendering only the active branch of a menu with minimum depth

  1. span style="color: #ff0000;">"navigation""active">
  2.         <a href="/products/server""active">
  3.                 <a href="/products/server/faq">FAQ</a>
  4.             </li>
  5.             <li>
  6.                 <a href="/products/server/editions">Editions</a>
  7.             </li>
  8.             <li>
  9.                 <a href="/products/server/requirements"

Example #48 Rendering only the active branch of a menu with maximum depth

  1. span style="color: #ff0000;">"navigation""active">
  2.         <a href="/products""active">
  3.                 <a href="/products/server">Foo Server</a>
  4.             </li>
  5.             <li>
  6.                 <a href="/products/studio">Foo Studio</a>
  7.             </li>
  8.         </ul>
  9.     </li>
  10. </ul>

Example #49 Rendering only the active branch of a menu with maximum depth and no parents

  1. span style="color: #ff0000;">"navigation""active">
  2.         <a href="/products/server">Foo Server</a>
  3.     </li>
  4.     <li>
  5.         <a href="/products/studio">Foo Studio</a>
  6.     </li>
  7. </ul>

Example #50 Rendering a custom menu using a partial view script

This example shows how to render a custom menu using a partial vew script. By calling setPartial(), you can specify a partial view script that will be used when calling render(). When a partial is specified, the renderPartial() method will be called. This method will assign the container to the view with the key container.

In a layout:

  1. span style="color: #ff0000;">'menu.phtml', 'default'

In application/modules/default/views/menu.phtml:

  1.  

Output:

  1. <a title="Go Home" href="/">Home</a>
  2. <a href="/products">Products</a>
  3. <a title="About us" href="/company/about">Company</a>
  4. <a href="/community">Community</a>

Example #51 Rendering only the active branch and all siblings of the active branch

  1.  

Output:

  1. span style="color: #ff0000;">"navigation">
  2.     <li>
  3.         <a title="Go Home" href="/""active">
  4.         <a href="/products""active">
  5.                 <a href="/products/server""active">
  6.                         <a href="/products/server/faq">FAQ</a>
  7.                     </li>
  8.                     <li>
  9.                         <a href="/products/server/editions">Editions</a>
  10.                     </li>
  11.                     <li>
  12.                         <a href="/products/server/requirements""/products/studio">Foo Studio</a>
  13.             </li>
  14.         </ul>
  15.     </li>
  16.     <li>
  17.         <a title="About us" href="/company/about">Company</a>
  18.     </li>
  19.     <li>
  20.         <a href="/community">Community</a>
  21.     </li>
  22. </ul>

Sitemap Helper

The Sitemap helper is used for generating XML sitemaps, as defined by the » Sitemaps XML format. Read more about » Sitemaps on Wikpedia.

By default, the sitemap helper uses sitemap validators to validate each element that is rendered. This can be disabled by calling $helper->setUseSitemapValidators(false).

Note: If you disable sitemap validators, the custom properties (see table) are not validated at all.

The sitemap helper also supports » Sitemap XSD Schema validation of the generated sitemap. This is disabled by default, since it will require a request to the Schema file. It can be enabled with $helper->setUseSchemaValidation(true).

Sitemap XML elements
Element Description
loc Absolute URL to page. An absolute URL will be generated by the helper.
lastmod

The date of last modification of the file, in » W3C Datetime format. This time portion can be omitted if desired, and only use YYYY-MM-DD.

The helper will try to retrieve the lastmod value from the page's custom property lastmod if it is set in the page. If the value is not a valid date, it is ignored.

changefreq

How frequently the page is likely to change. This value provides general information to search engines and may not correlate exactly to how often they crawl the page. Valid values are:

  • always

  • hourly

  • daily

  • weekly

  • monthly

  • yearly

  • never

The helper will try to retrieve the changefreq value from the page's custom property changefreq if it is set in the page. If the value is not valid, it is ignored.

priority

The priority of this URL relative to other URLs on your site. Valid values range from 0.0 to 1.0.

The helper will try to retrieve the priority value from the page's custom property priority if it is set in the page. If the value is not valid, it is ignored.

Methods in the sitemap helper:

  • {get|set}FormatOutput() gets/sets a flag indicating whether XML output should be formatted. This corresponds to the formatOutput property of the native DOMDocument class. Read more at » PHP: DOMDocument - Manual. Default is FALSE.

  • {get|set}UseXmlDeclaration() gets/sets a flag indicating whether the XML declaration should be included when rendering. Default is TRUE.

  • {get|set}UseSitemapValidators() gets/sets a flag indicating whether sitemap validators should be used when generating the DOM sitemap. Default is TRUE.

  • {get|set}UseSchemaValidation() gets/sets a flag indicating whether the helper should use XML Schema validation when generating the DOM sitemap. Default is FALSE. If TRUE.

  • {get|set}ServerUrl() gets/sets server URL that will be prepended to non-absolute URLs in the url() method. If no server URL is specified, it will be determined by the helper.

  • url() is used to generate absolute URLs to pages.

  • getDomSitemap() generates a DOMDocument from a given container.

Example #52 Rendering an XML sitemap

This example shows how to render an XML sitemap based on the setup we did further up.

  1. // In a view script or layout:
  2.  
  3. // format output
  4. // default is false
  5.  
  6. // other possible methods:
  7. // ->setUseXmlDeclaration(false); // default is true
  8. // ->setServerUrl('http://my.otherhost.com');
  9. // default is to detect automatically
  10.  
  11. // print sitemap

Notice how pages that are invisible or pages with ACL roles incompatible with the view helper are filtered out:

  1. <?xml version="1.0" encoding="UTF-8"?>
  2. <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
  3.   <url>
  4.     <loc>http://www.example.com/</loc>
  5.   </url>
  6.   <url>
  7.     <loc>http://www.example.com/products</loc>
  8.   </url>
  9.   <url>
  10.     <loc>http://www.example.com/products/server</loc>
  11.   </url>
  12.   <url>
  13.     <loc>http://www.example.com/products/server/faq</loc>
  14.   </url>
  15.   <url>
  16.     <loc>http://www.example.com/products/server/editions</loc>
  17.   </url>
  18.   <url>
  19.     <loc>http://www.example.com/products/server/requirements</loc>
  20.   </url>
  21.   <url>
  22.     <loc>http://www.example.com/products/studio</loc>
  23.   </url>
  24.   <url>
  25.     <loc>http://www.example.com/products/studio/customers</loc>
  26.   </url>
  27.   <url>
  28.     <loc>http://www.example.com/prodcts/studio/support</loc>
  29.   </url>
  30.   <url>
  31.     <loc>http://www.example.com/company/about</loc>
  32.   </url>
  33.   <url>
  34.     <loc>http://www.example.com/company/about/investors</loc>
  35.   </url>
  36.   <url>
  37.     <loc>http://www.example.com/company/news</loc>
  38.   </url>
  39.   <url>
  40.     <loc>http://www.example.com/company/news/press</loc>
  41.   </url>
  42.   <url>
  43.     <loc>http://www.example.com/archive</loc>
  44.   </url>
  45.   <url>
  46.     <loc>http://www.example.com/community</loc>
  47.   </url>
  48.   <url>
  49.     <loc>http://www.example.com/community/account</loc>
  50.   </url>
  51.   <url>
  52.     <loc>http://forums.example.com/</loc>
  53.   </url>
  54. </urlset>

Render the sitemap using no ACL role (should filter out /community/account):

  1.  
  1. <?xml version="1.0" encoding="UTF-8"?>
  2. <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
  3.   <url>
  4.     <loc>http://www.example.com/</loc>
  5.   </url>
  6.   <url>
  7.     <loc>http://www.example.com/products</loc>
  8.   </url>
  9.   <url>
  10.     <loc>http://www.example.com/products/server</loc>
  11.   </url>
  12.   <url>
  13.     <loc>http://www.example.com/products/server/faq</loc>
  14.   </url>
  15.   <url>
  16.     <loc>http://www.example.com/products/server/editions</loc>
  17.   </url>
  18.   <url>
  19.     <loc>http://www.example.com/products/server/requirements</loc>
  20.   </url>
  21.   <url>
  22.     <loc>http://www.example.com/products/studio</loc>
  23.   </url>
  24.   <url>
  25.     <loc>http://www.example.com/products/studio/customers</loc>
  26.   </url>
  27.   <url>
  28.     <loc>http://www.example.com/prodcts/studio/support</loc>
  29.   </url>
  30.   <url>
  31.     <loc>http://www.example.com/company/about</loc>
  32.   </url>
  33.   <url>
  34.     <loc>http://www.example.com/company/about/investors</loc>
  35.   </url>
  36.   <url>
  37.     <loc>http://www.example.com/company/news</loc>
  38.   </url>
  39.   <url>
  40.     <loc>http://www.example.com/company/news/press</loc>
  41.   </url>
  42.   <url>
  43.     <loc>http://www.example.com/archive</loc>
  44.   </url>
  45.   <url>
  46.     <loc>http://www.example.com/community</loc>
  47.   </url>
  48.   <url>
  49.     <loc>http://forums.example.com/</loc>
  50.   </url>
  51. </urlset>

Render the sitemap using a maximum depth of 1.

  1.  
  1. <?xml version="1.0" encoding="UTF-8"?>
  2. <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
  3.   <url>
  4.     <loc>http://www.example.com/</loc>
  5.   </url>
  6.   <url>
  7.     <loc>http://www.example.com/products</loc>
  8.   </url>
  9.   <url>
  10.     <loc>http://www.example.com/products/server</loc>
  11.   </url>
  12.   <url>
  13.     <loc>http://www.example.com/products/studio</loc>
  14.   </url>
  15.   <url>
  16.     <loc>http://www.example.com/company/about</loc>
  17.   </url>
  18.   <url>
  19.     <loc>http://www.example.com/company/about/investors</loc>
  20.   </url>
  21.   <url>
  22.     <loc>http://www.example.com/company/news</loc>
  23.   </url>
  24.   <url>
  25.     <loc>http://www.example.com/community</loc>
  26.   </url>
  27.   <url>
  28.     <loc>http://www.example.com/community/account</loc>
  29.   </url>
  30.   <url>
  31.     <loc>http://forums.example.com/</loc>
  32.   </url>
  33. </urlset>

Note: UTF-8 encoding used by default
 By default, Zend Framework uses UTF-8 as its default encoding, and, specific to this case, Zend_View does as well. Character encoding can be set differently on the view object itself using the setEncoding() method (or the encoding instantiation parameter). However, since Zend_View_Interface does not define accessors for encoding, it's possible that if you are using a custom view implementation with the Dojo view helper, you will not have a getEncoding() method, which is what the view helper uses internally for determining the character set in which to encode.
If you do not want to utilize UTF-8 in such a situation, you will need to implement a getEncoding() method in your custom view implementation.

Navigation Helper

The Navigation helper is a proxy helper that relays calls to other navigational helpers. It can be considered an entry point to all navigation-related view tasks. The aforementioned navigational helpers are in the namespace Zend_View_Helper_Navigation, and would thus require the path Zend/View/Helper/Navigation to be added as a helper path to the view. With the proxy helper residing in the Zend_View_Helper namespace, it will always be available, without the need to add any helper paths to the view.

The Navigation helper finds other helpers that implement the Zend_View_Helper_Navigation_Helper interface, which means custom view helpers can also be proxied. This would, however, require that the custom helper path is added to the view.

When proxying to other helpers, the Navigation helper can inject its container, ACL/role, and translator. This means that you won't have to explicitly set all three in all navigational helpers, nor resort to injecting by means of Zend_Registry or static methods.

  • findHelper() finds the given helper, verifies that it is a navigational helper, and injects container, ACL/role and translator.

  • {get|set}InjectContainer() gets/sets a flag indicating whether the container should be injected to proxied helpers. Default is TRUE.

  • {get|set}InjectAcl() gets/sets a flag indicating whether the ACL/role should be injected to proxied helpers. Default is TRUE.

  • {get|set}InjectTranslator() gets/sets a flag indicating whether the translator should be injected to proxied helpers. Default is TRUE.

  • {get|set}DefaultProxy() gets/sets the default proxy. Default is 'menu'.

  • render() proxies to the render method of the default proxy.

Translate Helper

Often web sites are available in several languages. To translate the content of a site you should simply use Zend_Translate and to integrate Zend_Translate within your view you should use the Translate View Helper.

In all following examples we are using the simple Array Translation Adapter. Of course you can also use any instance of Zend_Translate and also any subclasses of Zend_Translate_Adapter. There are several ways to initiate the Translate View Helper:

  • Registered, through a previously registered instance in Zend_Registry

  • Afterwards, through the fluent interface

  • Directly, through initiating the class

A registered instance of Zend_Translate is the preferred usage for this helper. You can also select the locale to be used simply before you add the adapter to the registry.

Note: We are speaking of locales instead of languages because a language also may contain a region. For example English is spoken in different dialects. There may be a translation for British and one for American English. Therefore, we say "locale" instead of "language."

Example #53 Registered instance

To use a registered instance just create an instance of Zend_Translate or Zend_Translate_Adapter and register it within Zend_Registry using Zend_Translate as its key.

  1. // our example adapter
  2. 'adapter' => 'array',
  3.         'content''simple' => 'einfach'),
  4.         'locale'  => 'de''Zend_Translate', $adapter);
  5.  
  6. // within your view
  7. 'simple');
  8. // this returns 'einfach'

If you are more familiar with the fluent interface, then you can also create an instance within your view and initiate the helper afterwards.

Example #54 Within the view

To use the fluent interface, create an instance of Zend_Translate or Zend_Translate_Adapter, call the helper without a parameter, and call the setTranslator() method.

  1. // within your view
  2. 'adapter' => 'array',
  3.         'content''simple' => 'einfach'),
  4.         'locale'  => 'de'
  5.     )
  6. );
  7. $this->translate()->setTranslator($adapter)->translate('simple');
  8. // this returns 'einfach'

If you are using the helper without Zend_View then you can also use it directly.

Example #55 Direct usage

  1. // our example adapter
  2. 'adapter' => 'array',
  3.         'content''simple' => 'einfach'),
  4.         'locale'  => 'de'
  5.     )
  6. );
  7.  
  8. // initiate the adapter
  9. 'simple'); // this returns 'einfach'

You would use this way if you are not working with Zend_View and need to create translated output.

As already seen, the translate() method is used to return the translation. Just call it with the needed messageid of your translation adapter. But it can also replace parameters within the translation string. Therefore, it accepts variable parameters in two ways: either as a list of parameters, or as an array of parameters. As examples:

Example #56 Single parameter

To use a single parameter just add it to the method.

  1. // within your view
  2. "Monday";
  3. $this->translate("Today is %1\$s"// could return 'Heute ist Monday'

Note: Keep in mind that if you are using parameters which are also text, you may also need to translate these parameters.

Example #57 List of parameters

Or use a list of parameters and add it to the method.

  1. // within your view
  2. "Monday";
  3. $month = "April""11:20:55";
  4. $this->translate("Today is %1\$s in %2\$s. Actual time: %3\$s"// Could return 'Heute ist Monday in April. Aktuelle Zeit: 11:20:55'

Example #58 Array of parameters

Or use an array of parameters and add it to the method.

  1. // within your view
  2. "Monday", "April", "11:20:55");
  3. $this->translate("Today is %1\$s in %2\$s. Actual time: %3\$s"// Could return 'Heute ist Monday in April. Aktuelle Zeit: 11:20:55'

Sometimes it is necessary to change the locale of the translation. This can be done either dynamically per translation or statically for all following translations. And you can use it with both a parameter list and an array of parameters. In both cases the locale must be given as the last single parameter.

Example #59 Change locale dynamically

  1. // within your view
  2. "Monday", "April", "11:20:55");
  3. $this->translate("Today is %1\$s in %2\$s. Actual time: %3\$s"'it');

This example returns the Italian translation for the messageid. But it will only be used once. The next translation will use the locale from the adapter. Normally you will set the desired locale within the translation adapter before you add it to the registry. But you can also set the locale from within the helper:

Example #60 Change locale statically

  1. // within your view
  2. "Monday", "April", "11:20:55"'it');
  3. $this->translate("Today is %1\$s in %2\$s. Actual time: %3\$s"

The above example sets 'it' as the new default locale which will be used for all further translations.

Of course there is also a getLocale() method to get the currently set locale.

Example #61 Get the currently set locale

  1. // within your view
  2. "Monday", "April", "11:20:55");
  3.  
  4. // returns 'de' as set default locale from our above examples
  5. 'it');
  6. $this->translate("Today is %1\$s in %2\$s. Actual time: %3\$s"// returns 'it' as new set default locale
  7. $this->translate()->getLocale();

UserAgent View Helper

Overview

This view helper provides the ability to inject and later retrieve a Zend_Http_UserAgent instance for use in branching display logic based on device capabilities.

Quick Start

In most cases, you can simply retrieve the User-Agent and related device by calling the helper. If the UserAgent was configured in the bootstrap, that instance will be injected already in the helper; otherwise, it will instantiate one for you.

  1.  

If you initialize the UserAgent object manually, you can still inject it into the helper, in one of two ways.

  1. // Pull the helper from the view, and inject:
  2. $helper = $view->getHelper('userAgent');
  3. $helper->setUserAgent($userAgent);
  4.  
  5. // Pass the UserAgent to the helper:
  6. $view->userAgent($userAgent);

Available Methods

userAgent ( Zend_Http_UserAgent $userAgent = null )

Use this method to set or retrieve the UserAgent instance. Passing an instance will set it; passing no arguments will retrieve it. If no previous instance has been registered, one will be lazy-loaded using defaults.

setUserAgent ( Zend_Http_UserAgent $userAgent )

If you have an instance of the helper -- for instance, by calling the view object's getHelper() method -- you may use this method to set the UserAgent instance.

getUserAgent

Retrieves the UserAgent instance; if none is registered, it will lazy-load one using default values.

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.

  1. span style="color: #808080; font-style: italic;">// Set path to /path/to/more/helpers, with prefix 'My_View_Helper'
  2. $view->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.

  1. span style="color: #808080; font-style: italic;">// Add /path/to/some/helpers with class prefix 'My_View_Helper'
  2. $view->addHelperPath('/path/to/some/helpers', 'My_View_Helper');
  3. // Add /other/path/to/helpers with class prefix 'Your_View_Helper'
  4. $view->addHelperPath('/other/path/to/helpers', 'Your_View_Helper');
  5.  
  6. // now when you call $this->helperName(), Zend_View will look first for
  7. // "/path/to/some/helpers/HelperName" using class name
  8. // "Your_View_Helper_HelperName", then for
  9. // "/other/path/to/helpers/HelperName.php" using class name
  10. // "My_View_Helper_HelperName", and finally for
  11. // "Zend/View/Helper/HelperName.php" using class name
  12. // "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:

  1. span style="color: #ff0000;">"I have seen 'The Jerk' {$this->_count} time(s)."

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.

  1. // remember, in a view script, $this refers to the Zend_View instance.

The output would look something like this:

  1. I have seen 'The Jerk''The Jerk''The Jerk'

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:

  1.  

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.

  1. span style="color: #808080; font-style: italic;">// ...do some configuration or dependency injection...
  2.  
  3. $view->registerHelper($helper, 'foo');

If the helper has a setView() method, the view object will call this and inject itself into the helper on registration.

Note: 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.

View Scripts
Zend_View
Programmer's Reference Guide