|
 |
Zend Framework 2 Documentation (Manual) |  |
|
File: /_sources/modules/zend.navigation.view.helper.breadcrumbs.txt
Size: | 5423 |
Storage flags: | no_autoload,compress/gzip (33%) |
.. _zend.navigation.view.helper.breadcrumbs:
View Helper - Breadcrumbs
=========================
.. _zend.navigation.view.helpers.breadcrumbs.introduction:
Introduction
------------
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 :ref:`Zend\\Navigation\\Page\\Mvc <zend.navigation.pages.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. Default is *' > '*.
- *{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.
.. _zend.navigation.view.helper.breadcrumbs.basic-usage:
Basic usage
-----------
This example shows how to render breadcrumbs with default settings.
In a view script or layout:
.. code-block:: php
:linenos:
<?php echo $this->navigation()->breadcrumbs(); ?>
The two calls above take advantage of the magic __toString() method,
and are equivalent to:
.. code-block:: php
:linenos:
<?php echo $this->navigation()->breadcrumbs()->render(); ?>
Output:
.. code-block:: html
:linenos:
<a href="/products">Products</a> > <a href="/products/server">Foo Server</a> > FAQ
.. _zend.navigation.view.helper.breadcrumbs.specifying-indentation:
Specifying indentation
----------------------
This example shows how to render breadcrumbs with initial indentation.
Rendering with 8 spaces indentation:
.. code-block:: php
:linenos:
<?php echo $this->navigation()->breadcrumbs()->setIndent(8);?>
Output:
.. code-block:: html
:linenos:
<a href="/products">Products</a> > <a href="/products/server">Foo Server</a> > FAQ
.. _zend.navigation.view.helper.breadcrumbs.customize-output:
Customize output
----------------
This example shows how to customize breadcrumbs output by specifying various options.
In a view script or layout:
.. code-block:: php
:linenos:
<?php
echo $this->navigation()
->breadcrumbs()
->setLinkLast(true) // link last page
->setMaxDepth(1) // stop at level 1
->setSeparator(' ▶' . PHP_EOL); // cool separator with newline
?>
Output:
.. code-block:: html
:linenos:
<a href="/products">Products</a> ▶
<a href="/products/server">Foo Server</a>
Setting minimum depth required to render breadcrumbs:
.. code-block:: php
:linenos:
<?php
$this->navigation()->breadcrumbs()->setMinDepth(10);
echo $this->navigation()->breadcrumbs();
?>
Output:
Nothing, because the deepest active page is not at level 10 or deeper.
.. _zend.navigation.view.helper.breadcrumbs.using-partial:
Rendering 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:
.. code-block:: php
:linenos:
echo $this->navigation()->breadcrumbs()
->setPartial('my-module/partials/breadcrumbs');
Contents of *module/MyModule/view/my-module/partials/breadcrumbs.phtml*:
.. code-block:: php
:linenos:
echo implode(', ', array_map(
function ($a) { return $a->getLabel(); },
$this->pages));
Output:
.. code-block:: html
:linenos:
Products, Foo Server, FAQ
.. _`Breadcrumbs Pattern - Yahoo! Design Pattern Library`: http://developer.yahoo.com/ypatterns/pattern.php?pattern=breadcrumbs
For more information about the PHK package format: http://phk.tekwire.net