Merge pull request #8146 from cakephp/breadcrumbs-addmany-docs

Add docs for BreadcrumbsHelper::addMany() and prependMany()

Author: markstory

en/appendices/5-3-migration-guide.rst

@@ -82,6 +82,13 @@ Plugin
   which don't have one, you can use the ``bin/cake bake plugin MyPlugin --class-only``
   command, which will create the file ``plugins/MyPlugin/src/MyPlugin.php``.
 
+View
+----
+
+- Passing an array as the first argument to ``BreadcrumbsHelper::add()`` and
+  ``BreadcrumbsHelper::prepend()`` is deprecated. Use ``addMany()`` and
+  ``prependMany()`` instead.
+
 New Features
 ============
 
@@ -257,3 +264,7 @@ View
   that exceed it. A new ``steps`` option was added to automatically generate limit
   options in multiples of a specific value (e.g., ``['steps' => 10]`` generates
   10, 20, 30... up to maxLimit).
+
+- :php:meth:`BreadcrumbsHelper::addMany()` and :php:meth:`BreadcrumbsHelper::prependMany()`
+  were added. These methods allow adding multiple breadcrumbs at once with support
+  for shared options that apply to all crumbs.

en/views/helpers/breadcrumbs.rst

@@ -29,24 +29,12 @@ In addition to adding to the end of the trail, you can do a variety of operation
         ['controller' => 'products', 'action' => 'index']
     );
 
-    // Add multiple crumbs at the end of the trail
-    $this->Breadcrumbs->add([
-        ['title' => 'Products', 'url' => ['controller' => 'products', 'action' => 'index']],
-        ['title' => 'Product name', 'url' => ['controller' => 'products', 'action' => 'view', 1234]],
-    ]);
-
     // Prepended crumbs will be put at the top of the list
     $this->Breadcrumbs->prepend(
         'Products',
         ['controller' => 'products', 'action' => 'index']
     );
 
-    // Prepend multiple crumbs at the top of the trail, in the order given
-    $this->Breadcrumbs->prepend([
-        ['title' => 'Products', 'url' => ['controller' => 'products', 'action' => 'index']],
-        ['title' => 'Product name', 'url' => ['controller' => 'products', 'action' => 'view', 1234]],
-    ]);
-
     // Insert in a specific slot. If the slot is out of
     // bounds, an exception will be raised.
     $this->Breadcrumbs->insertAt(
@@ -73,6 +61,37 @@ In addition to adding to the end of the trail, you can do a variety of operation
         ['controller' => 'products', 'action' => 'index']
     );
 
+Adding Multiple Crumbs
+----------------------
+
+.. versionadded:: 5.3
+
+You can add or prepend multiple crumbs at once using ``addMany()`` and
+``prependMany()``. These methods accept an array of crumbs and optional shared
+options that apply to all crumbs::
+
+    // Add multiple crumbs at the end of the trail
+    $this->Breadcrumbs->addMany([
+        ['title' => 'Products', 'url' => ['controller' => 'products', 'action' => 'index']],
+        ['title' => 'Product name', 'url' => ['controller' => 'products', 'action' => 'view', 1234]],
+    ]);
+
+    // Prepend multiple crumbs at the top of the trail, in the order given
+    $this->Breadcrumbs->prependMany([
+        ['title' => 'Products', 'url' => ['controller' => 'products', 'action' => 'index']],
+        ['title' => 'Product name', 'url' => ['controller' => 'products', 'action' => 'view', 1234]],
+    ]);
+
+    // Add multiple crumbs with shared options applied to all
+    $this->Breadcrumbs->addMany([
+        ['title' => 'Home', 'url' => '/'],
+        ['title' => 'Products', 'url' => '/products'],
+        ['title' => 'Category'],
+    ], ['class' => 'breadcrumb-item']);
+
+The shared options are merged with any options specified on individual crumbs,
+with individual crumb options taking precedence.
+
 Using these methods gives you the ability to work with CakePHP's 2-step
 rendering process. Since templates and layouts are rendered from the inside out
 (meaning, included elements are rendered first), this allows you to define
@@ -190,7 +209,7 @@ when you want to transform the crumbs and overwrite the list::
         return $crumb;
     })->toArray();
 
-    $this->Breadcrumbs->reset()->add($crumbs);
+    $this->Breadcrumbs->reset()->addMany($crumbs);
 
 .. meta::
     :title lang=en: BreadcrumbsHelper