README

Framework agnostic breadcrumb container

Installation via composer

The package requires PHP 5.4+, includes a Laravel 5 Service Provider/Facade for quick integration, and abides the FIG standard PSR-4, allowing for a consistent codebase. All Coreplex packages follow these set standards. The repository is also fully unit tested through and continuously integrated through use of Travis CI.

To install Crumbs via composer, simply add it to your composer.json file

"require": {
    "coreplex/crumbs": "~1.0"
},

Then run composer update via the command line. To automatically add this into your composer json, you can simply run composer require coreplex/crumbs, and composer will handle this all for you

The Container

All breadcrumbs are held in a Container class. This allows you to prepare and render a set of breadcrumbs. A container has two dependencies. A Contracts\Crumb instance, and a Contracts\Renderer instance. We provide basic ones in the repository to be used

$container = new Coreplex\Crumbs\Container(new Coreplex\Crumbs\Components\Crumb, new Coreplex\Crumbs\Renderers\Basic);

To add a few breadcrumbs to the container, you can either use the append method directly, like so

$container->append('Homepage', '/home');

Or you can use a closure to group them into their own scope. To do this, just call the prepare method and use any of the container functions on the passed instance

$container->prepare(function($crumbs)
{
    $crumbs->append('Homepage', '/home')
           ->append('Edit');
});

To add a breadcrumb to the start of the container rather than the end, use the alternative prepend method

$container->prepend('The Website', '/');

Rendering The Breadcrumbs

The basic renderer provided will return a simple list-based navigation string. This can be invoked through the main container class by just calling the render method.

echo $container->render();

The render method causes the last breadcrumb to be active by default. To disable this behaviour, pass false as the first parameter when calling render.

echo $container->render(false);

The container can also be rendered by simply echoing out the class, as it will be implicitly type-cast to a string.

echo $container;

Retrieving The Breadcrumbs and the Crumb Component

If you are going to be handling breadcrumbs from the container, you will want to access the numerous properties on the class. To do this, you can use the fluent attribute methods

$container->append('The Website', '//www.website.com');

foreach ($container->crumbs() as $crumb) {
    var_dump($crumb->label()); // returns 'The Website'
    var_dump($crumb->url()); // returns '//www.website.com'
    var_dump($crumb->current()); // returns true
}

There are also respective setters and isSetters for each of the attributes on the class

// Append an empty breadcrumb to the container
$container->append();

foreach ($container->crumbs() as $crumb) {
    var_dump($crumb->label()); // returns null

    if ( ! $crumb->hasLabel()) {
        $crumb->setLabel('The Website')
    }

    var_dump($crumb->url()); // returns null

    if ( ! $crumb->hasUrl()) {
        $crumb->setUrl('//www.website.com')
    }

    var_dump($crumb->current()); // returns true

    if ( ! $crumb->current()) {
        $crumb->setCurrent();
    }

    $crumb->setNotCurrent();

    var_dump($crumb->current()); // returns false
}

Laravel 5 Support

Crumbs has support for Laravel 5 out of the box. Once installed via composer, simply add the service provider to your app.php file

'providers' => [

    'Coreplex\Crumbs\CrumbsServiceProvider',

]

And also publish the config via command line, using the php artisan vendor:publish function. This allows the config to be published to the correct directory

Once these steps have been taken, Crumbs can be dependency injected into any controller constructs like so

/**
 * Make a new controller instance
 *
 * @param \Coreplex\Crumbs\Contracts\Container $breadcrumbs
 * @return void
 */
public function __construct(\Coreplex\Crumbs\Contracts\Container $breadcrumbs)
{
    $this->breadcrumbs = $breadcrumbs;
}

Which will then allow access to the breadcrumbs container via the breadcrumbs class property on the controller

A facade is also provided to those who would opt using this over dependency injection. Simply add it to the aliases array in app.php

'aliases' => [

    'Crumbs' => 'Coreplex\Crumbs\Facades\Crumbs',

],

Which would then allow you to do things like this in your controllers

use Crumbs;

class DashboardController extends Controller {

    public function index()
    {
        Crumbs::prepare(function($crumbs)
        {
            $crumbs->append('Dashboard Home', route('dashboard.index'));
        });

        return view('dashboard.index')->with('breadcrumbs', Crumbs::render());
    }

}

Planned Features

Laravel 4 Integration

coreplex / crumbs

Maintainers

Details