Package Exports

ngx-breadcrumbs-rxjs6

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (ngx-breadcrumbs-rxjs6) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

Ngx-Breadcrumbs

An Angular (4+) module generating breadcrumbs based on the routing state.

Installation

# install via npm
$ npm --save install ngx-breadcrumbs

# install via yarn
$ yarn add ngx-breadcrumbs

Usage

Import the McBreadcrumbsModule in your root module (app.module.ts) after importing the router module.

import { RouterModule } from '@angular/router';
import { McBreadcrumbsModule } from 'ngx-breadcrumbs';

@NgModule({
  imports: [
    RouterModule.forRoot(myRoutes),
    McBreadcrumbsModule.forRoot()
  ],  
})
export class AppModule {}

Place the mc-breadcrumbs component, which will render the breadcrumbs, somewhere in your markup.

@Component({
  selector: 'app-root',
  template: `
    <div class="container">
      <mc-breadcrumbs></mc-breadcrumbs>
      <router-outlet></router-outlet>
    </div>`
})
export class AppComponent {}

Usage of the mc-breadcrumbs render component is optional. If a different markup output is desired, a custom component can be created that subscribes to the McBreadcrumbsService.crumbs$ observable.

Routing Configuration

Breadcrumbs links are generated based on the route configuration. If a route entry contains a data.breadcrumbs property the breadcrumbs service assumes breadcrumbs should be created whenever this route or one its child routes are active.

const myRoutes : Route[] = {
  {
    path: '',
    component: HomeComponent,
    data: {
      // Uses static text (Home)
      breadcrumbs: 'Home' 
    }
  },
  {
    path: 'about',
    component: AboutComponent,
    data: {
      // Uses last urlfragment (about) as text
      breadcrumbs: true 
    }
  },
  {
    path: 'person',
    data: {
      // Uses text property (Person)
      breadcrumbs: true,
      text: 'Person'
    },
    children: [
      {
          path: '',
          component: PersonListComponent
      },
      {
          path: ':id',
          component: PersonDetailComponent,
          data: {
            // Interpolates values resolved by the router 
            breadcrumbs: '{{ person.name }}'
          },
          resolve: {
            person: PersonResolver
          }
      } 
    ]
  },    
  {
    path: 'folder',
    data: {
      // Uses static text 'Folder'
      breadcrumbs: 'Folder'
    },
    children: [
      {
      path: '',
      component: FolderComponent
      },
      {
        path: ':id',
        component: FolderComponent,
        data: {
          // Resolves the breadcrumbs for this route by
          // implementing a McBreadcrumbsResolver class.
          breadcrumbs: FolderBreadcrumbsResolver
        }
      }
    ]
  }
};

API

IBreadcrumb

The IBreadcrumb interface defines the properties of the breadcrumb items.

export interface IBreadcrumb {
  text: string,  // The text to display 
  path: string   // The associated path
}

McBreadcrumbsComponent

The component simply renders the list of the IBreadcrumb items provided by the McBreadcrumbsService. The HTML output matches that of Bootstrap 4 markup.

A custom breadcrumb component is easily created by injecting the breadcrumb service and iterating over the breadcrumb items.

McBreadcrumbsService

The service has one public property crumbs$. It's an observable stream of IBreadcrumb[], which is updated after each route change.

McBreadcrumbsResolver

If needed, a custom resolver can be implemented which is activated whenever a certain route becomes active. This can be useful whenever the route configuration cannot match the desired breadcrumb hierachy.

The signature of the resolver implements Resolve<T> from the Angular Router and needs to resolve an array of IBreadcrumb items.

To associate a route with a certain resolver, it breadcrumbs data property in the route configuration should point to the resolver:

const myRoutes = [
  {
    path: 'somepath',
    component: SomeComponent,
    data: {
      breadcrumbs: MyBreadcrumbsResolver
    }
  }
];

Members

// Should resolve zero or more IBreadcrumb items.
function resolve(route: ActivatedRouteSnapshot, state: RouterStateSnapshot)
  : Observable<T>|Promise<T>|T

// Helper function that returns the full path for the provided route snapshot.
function getFullPath(route: ActivatedRouteSnapshot) 
  : string

Example

@Injectable()
export class MyBreadcrumbsResolver inherits McBreadcrumbsResolver {

  // Optional: inject any required dependencies
  constructor(private myService: MyService) {}

  resolve(route: ActivatedRouteSnapshot, state: RouterStateSnapshot) {
    
    const myFolderId = route.params.id;
    const myCrumbs = 
      this.myService.getFolders(myFolderId)
                    .map((folder) => ({
                      text: folder.title,
                      path: super.getFullPath(route.parent) + '/' + folder.id
                    });

    // Note: the resolve method can return any of the following types:
    //
    //   * IBreadcrumb[]
    //   * Observable<IBreadcrumb[]>
    //   * Promise<IBreadcrumb>

    return myCrumbs; 
  }
}

McBreadcrumbsConfig

The configuration of the breadcrumbs module.

Members

postProcess

Callback function with the following signature:

function (crumbs: IBreadcrumb[]) : Promise<IBreadcrumb[]> | Observable<IBreadcrumb[]> | IBreadcrumb[];

Can be used to make custom changes to the breadcrumb array after the service has constructed the breadcrumb trail.

Example:

@NgModule({
  /* ... */
})
export class AppModule {
  constructor(breadcrumbsConfig: McBreadcrumbsConfig) {

    breadcrumbsConfig.postProcess = (x) => {

      // Ensure that the first breadcrumb always points to home

      let y = x;

      if(x.length && x[0].text !== 'Home') {
        y = [
          {
            text: 'Home',
            path: ''
          }
        ].concat(x);
      }

      return y;
    };
  }
}