lcharette/uf_breadcrumb

Breadcrumb service provider for UserFrosting V4

Breadcrumb Sprinkle for UserFrosting 4

![UserFrosting Version][uf-version] [][build] ![StyleCI][styleci-badge], _(*1)

This Sprinkle provides an helper service and Twig template to manage simple page breadcrumb for UserFrosting 4., _(*2)

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., _(*3)

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:, _(*4)

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

Run composer update then php bakery bake to install the sprinkle., _(*5)

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:, _(*6)

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

You can also chain multiple methods :, _(*7)

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

The crumbs can also be created using the Crumb object :, _(*8)

$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 :, _(*9)

$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 :, _(*10)

$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:, _(*11)

//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., _(*12)

If you don't add any custom breadcrumbs, it will fallback to the default UserFrosting behaviour., _(*13)

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:, _(*14)

{% 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., _(*15)

Licence

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