diff --git a/en/appendices/5-3-migration-guide.rst b/en/appendices/5-3-migration-guide.rst index 05407014de..45636f935c 100644 --- a/en/appendices/5-3-migration-guide.rst +++ b/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. diff --git a/en/views/helpers/breadcrumbs.rst b/en/views/helpers/breadcrumbs.rst index 08e96c54a7..94036c6611 100644 --- a/en/views/helpers/breadcrumbs.rst +++ b/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