API Reference

Provider $breadcrumbProvider

Description

Provider that returns an instance of $breadcrumb service. It contains the global configuration of the module.

Options

Property	Default	Details
prefixStateName	null	Contains an existing state name (usually the home page of the app). If defined, the state is the first step of the breadcrumb, whatever the current state. Not necessary if all states are children of a root "homepage" state. It can be defined with a state's name or a function returning a state's name. It accepts url params with the same syntax as the UI-router uiSref directive.
template	'bootstrap3'	Contains a predefined template name (see the template page for the list) or HTML for a custom template. This property is ignored if templateUrl is defined.
templateUrl	null	Contains the path to a template file. This property takes precedence over the template property.
templateLast	'default'	Contains a predefined template for the directive ncyBreadcrumbLast or HTML for a custom template. This property is ignored if templateUrl is defined.
templateLastUrl	null	Contains the path to a template file for the directive ncyBreadcrumbLast. This property takes precedence over the templateLast property.
includeAbstract	false	If true, abstract states are included in the breadcrumb. This option has a lower priority than the state-specific option skip

See the template page for more information about template.

Methods

setOptions

Setter for options defined in a module.config block. For example :

myAppModule.config(function($breadcrumbProvider) {
    $breadcrumbProvider.setOptions({
      prefixStateName: 'home',
      template: 'bootstrap2'
    });
  })

Service $breadcrumb

Description

This service is responsible for access to $state and for directive configuration.

Methods

getStatesChain

Returns the state chain to the current state (i.e. all the steps of the breadcrumb). It's an array of state object enriched with the module-specific property ncyBreadcrumbLink (the href for the breadcrumb step).

getLastStep

Return the last step of the breadcrumb, generally the one relative to the current state, expect if it is configured as skipped (the method returns its parent). As getStatesChain, the state object is enriched with ncyBreadcrumbLink.

Directive ncyBreadcrumb

Description

The directive asks for the state chain from the $breadcrumb service and displays the corresponding breadcrumb.

### Usage

<div ncy-breadcrumb></div>

The directive does not require attribute value. The configuration is done by the $breadcrumbProvider.

Directive ncyBreadcrumbLast

Description

The directive renders the last step of the breadcrumb (generally the current state). If the last state is configured as skipped, the directive displays the previous step of the breadcrumb (if it exists).

### Usage

<span ncy-breadcrumb-last></span>

The directive can have an optional attribute value: the template of the directive. As the AngularJS directive ngBindTemplate, it is useful when the HTML element can't accept child element (like title or option):

<title ncy-breadcrumb-last="Sample app: {{ncyBreadcrumbLabel}}"></title>

New in 0.5.x: For even more flexibility, you can use the global options templateLast and templateLastUrl in the same way as the main directive ncyBreadcrumb. It allows use of others directives, HTML, etc.:

myAppModule.config(function($breadcrumbProvider) {
    $breadcrumbProvider.setOptions({
      templateLast: '<i ng-bind-html="ncyBreadcrumbLabel"></i>'
    });
  })

<span ncy-breadcrumb-last></span>

Directive ncyBreadcrumbText

Description

The directive renders the breadcrumb as text content of an element. The directive ships all the functionalities of the classic breadcrumb (label's bindings, skipped states, ...). The output text can be customized by changing the separator (default /) and by specifying a template.

Usage

<span ncy-breadcrumb-text></span>
<!-- Render "State A / State B / State C" -->

The default separator can be overridden by using a configuration attribute ncy-breadcrumb-text-separator:

<span ncy-breadcrumb-text ncy-breadcrumb-text-separator=" > "></span>
<!-- Render "State A > State B > State C" -->

As the previous directive ncyBreadcrumbLast, this directive can have an optional attribute value: the template of the directive. Please note that the variable ncyBreadcrumbLabel is the full breadcrumb here (a bit 💩 but PR is welcome):

<span ncy-breadcrumb-text="My app - {{ncyBreadcrumbLabel}}"></span>
<!-- Render "My app - State A / State B / State C" -->

Provider $stateProvider (external)

Description

The UI-Router's $stateProvider contains the "state-specific" configuration. It is added to each state object under the ncyBreadcrumb key :

$stateProvider.state('home', {
  url: '/home',
  templateUrl: 'views/home.html',
  controller: 'HomeCtrl',
  ncyBreadcrumb: {
    label: 'Home page' // angular-breadcrumb's configuration
  }
})

All the properties listed below are optional but the main one label is strongly recommended in each state definition (except the abstract states).

State options

label

Contains the label for the step in the breadcrumb. The state name is used if not defined.

The property ncyBreadcrumbLabel can contains bindings which are evaluated against the scope of the current state controller. For example, this state's config :

$stateProvider.state('home', {
  url: '/home',
  templateUrl: 'views/home.html',
  controller: function($scope) {
    $scope.foo='bar';
  },
  ncyBreadcrumb: {
    label: 'State {{foo}}'
  }
})

... will produces State bar.

parent

Overrides the parent state (only for the breadcrumb).

It is useful when 2 states are not parent in states configuration but must be parent in the breadcrumb. For example, in UI-Router sample: contact.list and contact.detail are configured as siblings but must be parent/child in breadcrumb : contact.list > contact.detail

To do that, the state contact.detail must defined the property parent:

$stateProvider.state('contact.detail', {
  url: '/{contactId:[0-9]{1,4}}',
  views: [...],
  ncyBreadcrumb: {
    parent: 'contacts.list' // Override the parent state (only for the breadcrumb).
  }
})

This property can be defined with a function returning the name of the parent state. The function can accept a scope as first argument: it is the scope of the current state controller (the same used for labels interpolation):

$stateProvider.state('contact.detail', {
  url: '/{contactId:[0-9]{1,4}}',
  views: [...],
  ncyBreadcrumb: {
    parent: function($scope) {
      return $scope.cameFromUnrelatedState ? 'unrelated.state' : 'contact.list';
    }
  }
})

Both declarations (string or function) accept url params. The syntax is the same as the UI-router uiSref directive :

$stateProvider.state('product.detail', {
  url: '/{productId}',
  views: [...],
  ncyBreadcrumb: {
    parent: 'category.list({cat: "product"})'
  }
})

skip

When defined to true, the state is never included in the chain of states and never appears in the breadcrumb. It is useful when a state doesn't interfere with the main browsing (side panel, modal, ...).

$stateProvider.state('contact.detail.picture', {
  url: '/img{imgId}',
  template: [...],
  ncyBreadcrumb: {
    skip: true // Never display this state in breadcrumb.
  }
})