View Helpers¶
Introduction¶
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 navigational helpers.
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()
andsetContainer()
gets and sets the navigation container the helper should operate on by default, andhasContainer()
checks if the helper has container registered.getTranslator()
andsetTranslator()
gets and sets the translator used for translating labels and titles.isTranslatorEnabled()
andsetTranslatorEnabled()
controls whether the translator should be enabled. The methodhasTranslator()
checks if the helper has a translator registered.getAcl()
,setAcl()
,getRole()
andsetRole()
, gets and sets ACL (Zend\Permissions\Acl\AclInterface
) instance and role (String
orZend\Permissions\Acl\Role\RoleInterface
) used for filtering out pages when rendering.getUseAcl()
andsetUseAcl()
controls whether ACL should be enabled. The methodshasAcl()
andhasRole()
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()
andsetIndent()
gets and sets indentation. The setter accepts aString
or anInteger
. In the case of anInteger
, 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()
andsetMinDepth()
gets and sets the minimum depth a page must have to be included by the helper. SettingNULL
means no minimum depth.getMaxDepth()
andsetMaxDepth()
gets and sets the maximum depth a page can have to be included by the helper. SettingNULL
means no maximum depth.getRenderInvisible()
andsetRenderInvisible()
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 fromgetMinDepth()
andgetMaxDepth()
. 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 aZend\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 Role 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()
.
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->setTranslatorEnabled(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\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.