vendor/zendframework/zend-navigation/doc/book/helpers/breadcrumbs.md

   1 # Breadcrumbs
   2
   3 Breadcrumbs are used for indicating where in a sitemap a user is currently browsing, and are
   4 typically rendered like the following:
   5
   6 ```text
   7 You are here: Home > Products > FantasticProduct 1.0
   8 ```
   9
  10 The `breadcrumbs()` helper follows the [Breadcrumbs Pattern](http://developer.yahoo.com/ypatterns/pattern.php?pattern=breadcrumbs)
  11 as outlined in the Yahoo! Design Pattern Library, and allows simple
  12 customization (minimum/maximum depth, indentation, separator, and whether the
  13 last element should be linked), or rendering using a partial view script.
  14
  15 The Breadcrumbs helper finds the deepest active page in a navigation container,
  16 and renders an upwards path to the root. For MVC pages, the "activeness" of a
  17 page is determined by inspecting the request object, as stated in the section on
  18 [MVC pages](../pages.md#mvc-pages).
  19
  20 The helper sets the `minDepth` property to 1 by default, meaning breadcrumbs
  21 will not be rendered if the deepest active page is a root page. If `maxDepth` is
  22 specified, the helper will stop rendering when at the specified depth (e.g. stop
  23 at level 2 even if the deepest active page is on level 3).
  24
  25 Methods in the breadcrumbs helper:
  26
  27 Method signature                           | Description
  28 ------------------------------------------ | -----------
  29 `getSeparator() : string`                  | Retrieves the separator string to use between breadcrumbs; default is ` &gt; `.
  30 `setSeparator(string $separator) : self`   | Set the separator string to use between breadcrumbs.
  31 `getLinkLast() : bool`                     | Retrieve the flag indicating whether the last breadcrumb should be rendered as an anchor; defaults to `false`.
  32 `setLinkLast(bool $flag) : self`           | Set the flag indicating whether the last breadcrumb should be rendered as an anchor.
  33 `getPartial() : string|array`              | Retrieve 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. 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.
  34 `setPartial(string|array $partial) : self` | Set the partial view script to use when rendering breadcrumbs; see `getPartial()` for acceptable values.
  35 `renderStraight()`                         | The default render method used when no partial view script is present.
  36 `renderPartial()`                          | Used for rendering using a partial view script.
  37
  38 ## Basic usage
  39
  40 This example shows how to render breadcrumbs with default settings.
  41
  42 In a view script or layout:
  43
  44 ```php
  45 <?= $this->navigation()->breadcrumbs(); ?>
  46 ```
  47
  48 The call above takes advantage of the magic `__toString()` method, and is
  49 equivalent to:
  50
  51 ```php
  52 <?= $this->navigation()->breadcrumbs()->render(); ?>
  53 ```
  54
  55 Output:
  56
  57 ```html
  58 <a href="/products">Products</a> &gt; <a href="/products/server">Foo Server</a> &gt; FAQ
  59 ```
  60
  61 ## Specifying indentation
  62
  63 This example shows how to render breadcrumbs with initial indentation.
  64
  65 Rendering with 8 spaces indentation:
  66
  67 ```php
  68 <?= $this->navigation()->breadcrumbs()->setIndent(8) ?>
  69 ```
  70
  71 Output:
  72
  73 ```html
  74         <a href="/products">Products</a> &gt; <a href="/products/server">Foo Server</a> &gt; FAQ
  75 ```
  76
  77 ## Customize output
  78
  79 This example shows how to customize breadcrumbs output by specifying multiple options.
  80
  81 In a view script or layout:
  82
  83 ```php
  84 <?= $this->navigation()->breadcrumbs()
  85     ->setLinkLast(true)                   // link last page
  86     ->setMaxDepth(1)                      // stop at level 1
  87     ->setSeparator(' ▶' . PHP_EOL);       // cool separator with newline
  88 ?>
  89 ```
  90
  91 Output:
  92
  93 ```html
  94 <a href="/products">Products</a> ▶
  95 <a href="/products/server">Foo Server</a>
  96 ```
  97
  98 Setting minimum depth required to render breadcrumbs:
  99
 100 ```php
 101 <?= $this->navigation()->breadcrumbs()->setMinDepth(10) ?>
 102 ```
 103
 104 Output: Nothing, because the deepest active page is not at level 10 or deeper.
 105
 106 ## Rendering using a partial view script
 107
 108 This example shows how to render customized breadcrumbs using a partial vew
 109 script. By calling `setPartial()`, you can specify a partial view script that
 110 will be used when calling `render()`.  When a partial is specified, the
 111 `renderPartial()` method will be called when emitting the breadcrumbs. This
 112 method will find the deepest active page and pass an array of pages that leads
 113 to the active page to the partial view script.
 114
 115 In a layout:
 116
 117 ```php
 118 echo $this->navigation()->breadcrumbs()
 119     ->setPartial('my-module/partials/breadcrumbs');
 120 ```
 121
 122 Contents of `module/MyModule/view/my-module/partials/breadcrumbs.phtml`:
 123
 124 ```php
 125 <?= implode(', ', array_map(function ($a) {
 126   return $a->getLabel();
 127 }, $this->pages)); ?>
 128 ```
 129
 130 Output:
 131
 132 ```html
 133 Products, Foo Server, FAQ
 134 ```