Formfeed-UK / nova-breadcrumbs

Augments Nova 4 Breadcrumbs with nesting and resource/static override methods
MIT License
20 stars 9 forks source link
breadcrumbs laravel laravel-nova nova nova-4

Nova 4 Breadcrumbs

This Laravel Nova package extends the breadcrumbs functionality of the First Party Nova breadcrumbs.

Tests repo can be found here: https://github.com/Formfeed-UK/nova-breadcrumbs-tests

Version 2.x Changes

Version 2.x is a significant change from previous versions, this package now augments the existing nova breadcrumbs to offer:

Breaking changes from 1.x

Requirements >= v2.x

Requirements <= v1.x

Features

This package adds automated breadcrumbs to the top of Nova 4 resources.

It supports:

Installation

1) Install the package in to a Laravel app that uses Nova via composer:

composer require formfeed-uk/nova-breadcrumbs

2) Publish the config file (optional)

php artisan vendor:publish --tag=nova-breadcrumbs-config

Usage

General

1) Enable Nova Breadcrumbs in the same way as the first party Nova Breadcrumbs in your NovaServiceProvider boot method:


    public function boot() {
        parent::boot();

        Nova::withBreadcrumbs(true);
    }

2) Optionally configure a parent method on your Model to explicitly define the relationship the package should query. The name of this function can be changed in the configuration file.


class MyModel extends Model {

    ...

    public function parent() {
        return $this->config();
    }   

    public function config() {
        return $this->belongsTo(Config::class, "config_id");
    }

    ...

}

Resource Methods

You can optionally override the default behaviour of the breadcrumbs package on a per resource basis by adding methods to your Nova Resource. These methods should all return an instance of Breadcrumb or an array of Breadcrumb instances.

For Dashboards, you can use the following method:

Example


class MyResource extends Resource {

    // Change the name of the breadcrumb
    public function detailBreadcrumb(NovaRequest $request, Breadcrumbs $breadcrumbs, Breadcrumb $detailBreadcrumb) {
        return $detailBreadcrumb->name = _('My Custom Name');
    }

    // Remove all previous breadcrumbs and add a new root
    public function resourceBreadcrumbs(NovaRequest $request, Breadcrumbs $breadcrumbs, array $breadcrumbArray) {
        $breadcrumbs->items = [Breadcrumb::make('Home', '/')];
        return $breadcrumbArray;
    }

    // Prevent the group breadcrumb for this resource
    public function groupBreadcrumb(NovaRequest $request, Breadcrumbs $breadcrumbs, Breadcrumb $groupBreadcrumb) {
        return null;
    }
}

Static Callbacks

You can override the default behaviour of the breadcrumbs globally by using the following static methods on the Breadcrumbs class. They should be provided within a boot method on a service provider.

These methods will be overriden by any per resource methods.

The closure provided should return either an instance of Breadcrumb or an array of Breadcrumb instances.

Example


use FormFeed\Breadcrumbs\Breadcrumb;
use FormFeed\Breadcrumbs\Breadcrumbs;

class NovaServiceProvider extends ServiceProvider {

    public function boot() {
        parent::boot();

        Nova::withBreadcrumbs(true);

        Breadcrumbs::detailCallback(function(NovaRequest $request, Breadcrumbs $breadcrumbs, Breadcrumb $detailBreadcrumb) {
            return $detailBreadcrumb->name = _('My Custom Name');
        });

        Breadcrumbs::rootCallback(function(NovaRequest $request, Breadcrumbs $breadcrumbs, Breadcrumb $rootBreadcrumb) {
            return Breadcrumb::make(_('My Custom Root Breadcrumb'), "/my-root");
        });
    }
}

Configuration Options

Please see the included config file for a full list of configuration options (it's well commented).

In addition to these options you can also specify the following options in the resource itself:

Link To parent

This determines if the breadcrumb should link to the parent resource regardless of if the current resource's index is navigable from the main menu:

public static $linkToParent = true|false;

Disable Parent Breadcrumbs

Resolving Parent breadcrumbs can be disabled by adding the following static variable to a resource:

public static $resolveParentBreadcrumbs = false;

Invoking Reflection

Determining the parent via invoking reflected blank model methods and checking the returned type is now disabled by default.

It is highly recommended that this functionality be left off, and either a parent method, form field, or a defined relationship return type be used instead.

However if needed you can still enable this functionality by doing the following:

You can also set this on a per-resource basis with the following static:

public static $invokingReflection = true|false;

Issues/Todo

If you have any requests for functionality or find any bugs please open an issue or submit a Pull Request. Pull requests will be actioned faster than Issues.

License

Nova Breadcrumbs is open-sourced software licensed under the MIT license.