Breadcrumb Sprinkle for UserFrosting 4

This Sprinkle provides an helper service and Twig template to manage simple page breadcrumb for UserFrosting 4.

Help and Contributing

If you need help using this sprinkle or found any bug, feels free to open an issue or submit a pull request. You can also find me on the UserFrosting Chat most of the time for direct support.

Installation

Edit UserFrosting app/sprinkles.json file and add the following to the require list : "lcharette/uf_breadcrumb": "^3.0.0". Also add Breadcrumb to the base list. For example:

{
    "require": {
        "lcharette/uf_breadcrumb": "^3.0.0"
    },
    "base": [
        "core",
        "account",
        "admin",
        "Breadcrumb"
    ]
}

Run composer update then php bakery bake to install the sprinkle.

Usage

Adding crumbs

Breadcrumbs hierarchy needs to be manually defined in each controllers. To dynamically add breadcrumbs to the UI, simply use the add method of the breadcrumb service:

// add($name, $uri = "")
$this->ci->breadcrumb->add('Item name', 'path/');

You can also chain multiple methods :

$this->ci->breadcrumb->add("Projects", "projects/")
                     ->add("Project Foo", "projects/foo")
                     ->add("Settings");

The crumbs can also be created using the Crumb object :

$crumb = new Crumb();
$crumb->setTitle('Item name')->setUri('path/');
$this->ci->breadcrumb->addCrumb($crumb);

The item name can also be switched for a translation key :

$this->ci->breadcrumb->add(['TRANSLATION_KEY', ['placeholder' => 'Value']], 'path/');

// or

$crumb = new Crumb();
$crumb->setTitle('TRANSLATION_KEY', ['placeholder' => 'Value'])->setUri('path/');

Path is actually optional if you don't want to provide a link with your crumb. Alternatively, a route name / route pattern placeholders can also be used :

$this->ci->breadcrumb->add('Item name', ['route_name', ['id' => '123']]);

// or

$crumb = new Crumb();
$crumb->setTitle('Item name')->setRoute('route_name', ['id' => '123']);

Prepend crumbs

You can also use the prepend method to add a new item to the beginning of the list:

//prepend($name, $uri = "")
$this->ci->breadcrumb->prepend("Item name", "path/");

// or

$this->ci->breadcrumb->prependCrumb($crumb);

Note that the site index is automatically added to the beginning of the list, whether you use prepend or not.

If you don't add any custom breadcrumbs, it will fallback to the default UserFrosting behaviour.

Custom style

The default UserFrosting layouts and themes will pick up the breadcrumbs automatically. If your UserFrosting theme doesn't include breadcrumbs automatically, simply add this line to your twig files:

{% include 'navigation/breadcrumb.html.twig' with {page_title: block('page_title')} %}

If you want to edit the style of the breadcrumbs, simply copy the templates/navigation/breadcrumb.html.twig file in your own sprinkle and edit according to your styling. No custom assets are included with this sprinkle.

Licence

By Louis Charette. Copyright (c) 2020, free to use in personal and commercial software as per the MIT license.