The navigation helpers are used for rendering navigational elements from Zend\Navigation\Navigation 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
All built-in helpers extend Zend\View\Helper\Navigation\AbstractHelper, which adds integration with ACL and translation. The abstract class implements the interface
Zend\View\Helper\Navigation\HelperInterface, 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\Permissions\Acl\AclInterface) instance and role
(String or Zend\Permissions\Acl\Role\RoleInterface) 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
- 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\AbstractPage 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 container is not explicitly set, the helper will create an empty Zend\Navigation\Navigation
container when calling $helper->getContainer().
Navigation view helpers use the magic method __call() to proxy method calls to the navigation container that is
registered in the view helper.
'type' => 'uri',
'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\I18n\Translator in the helper using $helper->setTranslator($translator).
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.
There is no translation in the sitemap helper, since there are no page labels or titles involved in an XML
Integration with ACL
All navigational view helpers support ACL inherently from the class
Zend\View\Helper\Navigation\AbstractHelper. An object implementing Zend\Permissions\Acl\AclInterface can be
assigned to a helper instance with $helper->setAcl($acl), and role with $helper->setRole(‘member’) or
$helper->setRole(new Zend\Permissions\Acl\Role\GenericRole(‘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.