From 368d7b3a2cd21fe2e648756e5d01d3fe4fbe98e1 Mon Sep 17 00:00:00 2001 From: Dave James Miller Date: Thu, 14 Sep 2017 09:23:50 +0100 Subject: [PATCH] Add 'manager-class' and 'generator-class' config options --- README.md | 83 ++++++++++++++++++------------ config/breadcrumbs.php | 15 ++++++ src/BreadcrumbsServiceProvider.php | 9 ++-- tests/CustomGeneratorTest.php | 38 ++++++++++++++ tests/CustomManagerTest.php | 37 +++++++++++++ 5 files changed, 147 insertions(+), 35 deletions(-) create mode 100644 tests/CustomGeneratorTest.php create mode 100644 tests/CustomManagerTest.php diff --git a/README.md b/README.md index f669587..3959c3b 100644 --- a/README.md +++ b/README.md @@ -677,27 +677,43 @@ $current = Breadcrumbs::generate()->where('current', '!==', 'false)->last(); ``` -### Macros +### Switching views at runtime -The BreadcrumbsManager class is [macroable](https://unnikked.ga/understanding-the-laravel-macroable-trait-dab051f09172), so you can add your own methods. For example: +You can use `Breadcrumbs::view()` in place of `Breadcrumbs::render()` to render a template other than the [default one](#3-choose-a-template): -```php -Breadcrumbs::macro('pageTitle', function () { - $title = ($breadcrumb = Breadcrumbs::current()) ? "{$breadcrumb->title} – " : ''; +```blade +{{ Breadcrumbs::view('partials.breadcrumbs2', 'category', $category) }} +``` - if (($page = (int) request('page')) > 1) { - $title .= "Page $page – "; - } +Or you can override the config setting to affect all future `render()` calls: - return $title . 'Demo App'; -}); +```php +Config::set('breadcrumbs.view', 'partials.breadcrumbs2'); ``` +```php +{{ Breadcrumbs::render('category', $category) }} +``` + +Or you could call `Breadcrumbs::generate()` to get the breadcrumbs Collection and load the view manually: + ```blade -{{ Breadcrumbs::pageTitle() }} +@include('partials.breadcrumbs2', ['breadcrumbs' => Breadcrumbs::generate('category', $category)]) ``` +### Overriding the "current" route + +If you call `Breadcrumbs::render()` or `Breadcrumbs::generate()` with no parameters, it will use the current route name and parameters by default (as returned by Laravel's `Route::current()` method). + +You can override this by calling `Breadcrumbs::setCurrentRoute($name, $param1, $param2...)`. + + +### Checking if a breadcrumb exists + +To check if a breadcrumb with a given name exists, call `Breadcrumbs::exists('name')`, which returns a boolean. + + ### Defining breadcrumbs in a different file If you don't want to use `routes/breadcrumbs.php`, you can change it in the config file. First initialise the config file, if you haven't already: @@ -771,41 +787,40 @@ class MyServiceProvider extends ServiceProvider ``` -### Switching views at runtime - -You can use `Breadcrumbs::view()` in place of `Breadcrumbs::render()` to render a template other than the [default one](#3-choose-a-template): - -```blade -{{ Breadcrumbs::view('partials.breadcrumbs2', 'category', $category) }} -``` +### Macros -Or you can override the config setting to affect all future `render()` calls: +The BreadcrumbsManager class is [macroable](https://unnikked.ga/understanding-the-laravel-macroable-trait-dab051f09172), so you can add your own methods. For example: ```php -Config::set('breadcrumbs.view', 'partials.breadcrumbs2'); -``` +Breadcrumbs::macro('pageTitle', function () { + $title = ($breadcrumb = Breadcrumbs::current()) ? "{$breadcrumb->title} – " : ''; -```php -{{ Breadcrumbs::render('category', $category) }} -``` + if (($page = (int) request('page')) > 1) { + $title .= "Page $page – "; + } -Or you could call `Breadcrumbs::generate()` to get the breadcrumbs Collection and load the view manually: + return $title . 'Demo App'; +}); +``` ```blade -@include('partials.breadcrumbs2', ['breadcrumbs' => Breadcrumbs::generate('category', $category)]) +{{ Breadcrumbs::pageTitle() }} ``` -### Overriding the "current" route - -If you call `Breadcrumbs::render()` or `Breadcrumbs::generate()` with no parameters, it will use the current route name and parameters by default (as returned by Laravel's `Route::current()` method). +### Advanced customisations -You can override this by calling `Breadcrumbs::setCurrentRoute($name, $param1, $param2...)`. +For more advanced customisations you can subclass BreadcrumbsManager and/or BreadcrumbsGenerator, then update the config file with the new class name: +```php + // Manager + 'manager-class' => DaveJamesMiller\Breadcrumbs\BreadcrumbsManager::class, -### Checking if a breadcrumb exists + // Generator + 'generator-class' => DaveJamesMiller\Breadcrumbs\BreadcrumbsGenerator::class, +``` -To check if a breadcrumb with a given name exists, call `Breadcrumbs::exists('name')`, which returns a boolean. +(**Note:** Anything that's not part of the public API (see below) may change between releases, so I suggest you write unit tests to ensure it doesn't break when upgrading.) API Reference @@ -888,6 +903,10 @@ Breadcrumbs::after('name', function (BreadcrumbsGenerator $breadcrumbs) { *Laravel Breadcrumbs uses [Semantic Versioning](http://semver.org/).* +### [v4.1.0](https://github.com/davejamesmiller/laravel-breadcrumbs/tree/4.2.0) (Thu 14 Sep 2017) + +- Add `manager-class` and `generator-class` config options + ### [v4.1.0](https://github.com/davejamesmiller/laravel-breadcrumbs/tree/4.1.0) (Mon 28 Aug 2017) - Add Bulma template diff --git a/config/breadcrumbs.php b/config/breadcrumbs.php index 52970cc..9f740b7 100644 --- a/config/breadcrumbs.php +++ b/config/breadcrumbs.php @@ -52,4 +52,19 @@ // When a named breadcrumb is used but doesn't exist (InvalidBreadcrumbException) 'invalid-named-breadcrumb-exception' => true, + /* + |-------------------------------------------------------------------------- + | Classes + |-------------------------------------------------------------------------- + | + | Subclass the default classes for more advanced customisations. + | + */ + + // Manager + 'manager-class' => DaveJamesMiller\Breadcrumbs\BreadcrumbsManager::class, + + // Generator + 'generator-class' => DaveJamesMiller\Breadcrumbs\BreadcrumbsGenerator::class, + ]; diff --git a/src/BreadcrumbsServiceProvider.php b/src/BreadcrumbsServiceProvider.php index 96afaab..c007761 100644 --- a/src/BreadcrumbsServiceProvider.php +++ b/src/BreadcrumbsServiceProvider.php @@ -33,9 +33,6 @@ public function provides(): array */ public function register() //: void { - // Register Manager class singleton with the app container - $this->app->singleton(BreadcrumbsManager::class); - // Load the default config values $configFile = __DIR__ . '/../config/breadcrumbs.php'; $this->mergeConfigFrom($configFile, 'breadcrumbs'); @@ -43,6 +40,12 @@ public function register() //: void // Publish the config/breadcrumbs.php file $this->publishes([$configFile => config_path('breadcrumbs.php')], 'config'); + // Register Manager class singleton with the app container + $this->app->singleton(BreadcrumbsManager::class, config('breadcrumbs.manager-class')); + + // Register Generator class so it can be overridden + $this->app->bind(BreadcrumbsGenerator::class, config('breadcrumbs.generator-class')); + // Register 'breadcrumbs::' view namespace $this->loadViewsFrom(__DIR__ . '/../views/', 'breadcrumbs'); } diff --git a/tests/CustomGeneratorTest.php b/tests/CustomGeneratorTest.php new file mode 100644 index 0000000..f3162a5 --- /dev/null +++ b/tests/CustomGeneratorTest.php @@ -0,0 +1,38 @@ +assertSame('custom-generator', $breadcrumbs[0]); + } +} + +class CustomGenerator extends BreadcrumbsGenerator +{ + public function generate(array $callbacks, array $before, array $after, string $name, array $params): Collection + { + return new Collection(['custom-generator']); + } + +} diff --git a/tests/CustomManagerTest.php b/tests/CustomManagerTest.php new file mode 100644 index 0000000..c18d67b --- /dev/null +++ b/tests/CustomManagerTest.php @@ -0,0 +1,37 @@ +assertSame('custom-manager', $breadcrumbs[0]); + } +} + +class CustomManager extends BreadcrumbsManager +{ + public function generate(string $name = null, ...$params): Collection + { + return new Collection(['custom-manager']); + } +}