crumble

A highly customizable breadcrumb service for AngularJS 1.x with ngRoute. Gets you back home the way you want.

crumble allows you to generate dynamic breadcrumbs for your application. It provides sensible defaults but also allows you to customize every detail of the service to match your app's structure.

Setup

Using a Module System

Install crumble using your favourite package manager

yarn add angular-crumble || npm i -S angular-crumble

Require crumble in your AngularJS module's dependencies

angular.module('app', [require('angular-crumble')]);

crumble follows the conventions described in this npm blog post.

Using Plain Old Script Tags

Have ngRoute up and running.

Download crumble using Bower or just manually.

bower install angular-crumble --save

Load crumble.js from your HTML.

<script src="path/to/crumble.js"></script>

Require crumble in your AngularJS module's dependencies

angular.module('app', ['crumble']);

Usage

Set route labels

With the default configuration your only job here is to label your routes, so crumble knows what to display. Labels will be passed through $interpolate. See next section for how to set the interpolation context.

angular.module('app')
  .config(function ($routeProvider) {

    $routeProvider
      .when('/', {
        templateUrl: 'views/home.html',
        controller: 'HomeCtrl',
        // The label can be a simple string...
        label: 'Home',
      })

      .when('/things/:thingId', {
        templateUrl: 'views/things/view.html',
        controller: 'ThingViewCtrl',
        // ...or markup as consumed by $interpolate
        label: '{{thing.title}}',
      })

      .otherwise({ redirectTo: '/' });
  });

Update the breadcrumb trail

In the preceding section we saw that we can use $interpolate markup to create dynamic breadcrumb labels. But that also means we have to set an interpolation context.

angular.module('app')
  .controller('ThingViewCtrl', function ($scope, $routeParams, crumble, things) {

    var thing = things.get($routeParams.thingId) || { title: 'Unknown Thing' };

    // Updates the breadcrumb trail with the given context
    crumble.update({thing: thing});

    // Instead you could also build up context in place before calling update
    crumble.context = {thing: thing};
    crumble.update();

  });

If you have a lot of static views without dedicated controllers, you might find creating a controller just for calling crumble.update() quite cumbersome. So if you don't mind the little flash of incomplete breadcrumbs on your dynamic views, just setup your own auto updating.

// In your application's run method
$rootScope.$on('$routeChangeSuccess', function() {
  crumble.update();
});

Display the breadcrumb trail

To render the breadcrumbs, attach crumble to your view's scope and put something like the code below in the corresponding template.

<ol>
  <li ng-repeat="bc in crumble.trail">
    <a ng-href="#{{bc.path}}">{{bc.label}}</a>
  </li>
</ol>

Omit the hash mark in the link if you are using HTML5 mode.

Customization

If you bore with me to this point then you probably want to know about crumble's promised customizability. Well, here we go!

Customizing the parent relationship

We interpret your application as a rooted tree. Each view is a node that either has a parent or is the root of the tree. Each node is identified by its path. The parent of a node with path path is defined by the result of a call to crumble.getParent(path). If the return value is falsy, the node is considered as the root.

"What do I care?", you say? Well, by default the root is / and the parent is determined by simply dropping the last path segment of the current node (e.g. / is the parent of /foo which is the parent of /foo/bar). But you can completely customize this behavior by replacing crumble.getParent with your own implementation. Just take care that you don't create any cycles.

Here's an example on how to configure crumble so that you can override standard parents by adding a parent property to a route

// Put this in your run method
var getDefaultParent = crumble.getParent;
crumble.getParent = function (path) {
  var route = crumble.getRoute(path);
  return route && angular.isDefined(route.parent)
    ? route.parent
    : getDefaultParent(path);
};

Customizing the breadcrumb objects

The entries in crumble.trail are the results of calling crumble.getCrumb for each node, passing that node's path as an argument. So again, if you want to add custom properties to the breadcrumbs (think title attributes and stuff), just override that function.

Simplified, the standard implementation looks like this:

crumble.getCrumb = function (path) {
  // You can use that function for your own implementations too
  // It returns the matching route object for a given path
  var route = crumble.getRoute(path);
  return {
    path: $interpolate(path)(crumble.context),
    label: $interpolate(route.label)(crumble.context),
  };
};

Running tests

npm install
npm test

Check coverage/ directory created after running the tests to see code coverage.

Contributing

This repository uses the Node.js Style Guide. Contributions have to follow it too. You can use npm run lint to check your code for style guide conformance. Please use aptly named topic branches for pull requests.

License

Copyright (c) 2014–2017 Raphael von der Grün. Licensed under the MIT License.