howto.md

How To Use

Quick Start

In order to add breadcrumb items, you can simply use the Crumbs facade in your controller's method:

public function index()
{
    Crumbs::add('/users', 'List of Users');
    
    $users = User::all();
    
    return view('users.index', compact('users'));
}

When adding current page, you may use the addCurrent( $title ) method instead of the simple add( $url, $title, $params = [] ):

public function index()
{
    Crumbs::addCurrent('List of Users');
    
    $users = User::all();
    
    return view('users.index', compact('users'));
}

If you use route names, just specify it instead of the URL:

public function show(User $user)
{
    Crumbs::add('users.index', 'List of Users'));
    Crumbs::add("{$user->name}'s Profile"); // is the same as 'addCurrent()'
    
    return view('users.show', compact('user'));
}

When needed, you may specify route parameters as the third parameter, just as you would with the Laravel's route() function:

public function edit(User $user)
{
    Crumbs::add('users.index', 'List of Users'));
    Crumbs::add('users.show', $user->name, $user->id);
    Crumbs::addCurrent($user->name);
    
    return view('users.edit', compact('user'));
}

You may also use the helper function crumbs():

crumbs('/categories', 'Categories')->add('main-category', 'Main Category')->add('Sample Article');

Let's Dig In

Default and Custom Crumbs Templates

You will need to render the created breacrumbs somewhere in your template. To do so you have two options: Crumbs::render($view = '') or the Blade extension @crumbs or @crumbs($view) which is just a shortcut for this Crumbs method.

<div class="column">
    @crumbs
    
    <h1>Welcome!</h1>
</div>

The crumbsView config from /config/crumbs.php is the default template for all your breadcrumb lists. This is what will be used when you just call @crumbs with no arguments. The $view parameter from above rewrites this option.

Templates Overview

Crumbs come with several view files for three popular CSS frameworks: Twitter Bootstrap, Foundation and Semantic UI. Each one also includes a microdata variation (-md suffix).

<ul class="breadcrumbs">
	@foreach ($crumbs as $crumb)
		<li class="{{ $crumb->active(false, 'current') }} {{ $crumb->disabled('unavailable') }}">
			<a href="{{ $crumb->url }}">
				{!! $crumb->title !!}
			</a>
		</li>
	@endforeach
</ul>

Each view template has access to the crumbs variable. Each of its items is an instance of CrumbsItem class which gives you access to:

• $url property
• $title property: is unescaped, so you may also use icons in your breadcrumbs (e.g. the home icon).
• isActive() method
• isDisabled() method
• active($attr = true, $className = '') method
• disabled($className = '') method

isActive()

Checks wheter the crumb item is the current page. Return true or false.

isDisabled()

Returns true if crumb item's URL is equal to '#'.

active()

If $attr is true, returns class="{active}", if false: {active}. {active} being the active item class defined in the /config/crumbs.php file. You may also pass it as a second argument.

disabled()

Returns the disabled class name defined in the /config/crumbs.php file, or you may once again pass it as a second argument.

Autogenerated Crumbs Items

In the /config/crumbs.php file you may find the 'Display Default Crumbs Items' section.

[
    'display_home_page'  => true,
    'display_admin_page' => true,
    'display_both_pages' => false
];

What it does is simply adding to the beginning the 'Home' and 'Admin' sections.

Crumbs::add('users.index', 'List of Users'));
Crumbs::addCurrent("{$user->name}'s Profile");

Becomes:

Home > List of Users > User's Profile

Because of the 'display_home_page' => true. If your current page's URL matches the *admin* pattern (which also is configurable), it will replace the 'Home' with 'Admin':

Admin > List of Users > User's Profile

If 'display_both_pages' => true, it will use both of them, if they are true.

Home > Admin > List of Users > User's Profile

You may configure the home and admin pages' URLs.

Page Title

Since 2.1.7 you may use the Crumbs::pageTitle() method to output structured title string.

<title>{{ crumbs()->pageTitle() }}</title>

It takes uses the Crumbs titles to build a page title.

There is a special configuration option page_title_separator in /config/crumbs.php where you can change the separator for each item. Default: ' » '.