<commit_before># UI-Router-Breadcrumbs
[![Build Status](https://travis-ci.org/interval-braining/angular-ui-router-breadcrumbs.png?branch=master)](https://travis-ci.org/interval-braining/angular-ui-router-breadcrumbs)

UI-Router-Breadcrumbs provides a service and directive that allow for the
creation of navigational breadcrumbs that are flexible and ready for customization.

**Note:** *This library is under active development and is most definitely
subject to change.*

## Getting Started

**(1)** Get UI-Router-Breadcrumbs by cloning and building this repository:
```bash
git clone <EMAIL>:interval-braining/angular-ui-router-breadcrumbs.git
cd angular-ui-router-breadcrumbs
npm install
bower install
```

**(2)** Include `angular-ui-router-breadcrumbs.js` (or
`angular-ui-router-breadcrumbs.min.js`) with your javascripts, after including
Angular itself.

**(3)** Add `'ui.router.breadcrumbs'` to your main module's list of dependencies.

## Usage
UI-Router-Breadcrumbs is split into two components: A breadcrumbs service and
a simple breadcrumbs directive that's primary function is to make the breadcrumbs
service available to the directive's scope.

### Breadcrumbs Service
The breadcrumbs service handles traversing the ui-router state hierarchy to
build an array of breadcrumb data for common use. This is done by walking from
the current state on up the tree from state to parent state until a state is
reached that does not have a parent. It should be noted that this means that
breadcrumbs will not be available for all states, but only for those states
that are ancestors of the current state.

By default, the service examines the current and each ancestor state for a
`breadcrumb` attribute to process. If a breadcrumb attribute is present and it
is a string, the service assumes the string is the text for the breadcrumb and
stores an object with the text and the name of the associated state. If the
breadcrumb attribute is not a string, but some other object, the service stores
the given object as the data for the breadcrumb. If the breadcrumb attribute is
null or undefined, it is assumed the state has no breadcrumb.

To add a breadcrumb to a state, simply add a breadcrumb attribute to the state
object where it is defined. For example:
```javascript
  $stateProvider.state('a', {
    breadcrumb: 'State A',
    url: '/a',
  }).state('a.b', {
    breadcrumb: {
      class: 'alternate',
      stateName: 'a.b',
      text: 'State B',
    },
    url: '/b'
  });
```

UI-Router supports [custom data](https://github.com/angular-ui/ui-router/wiki#wiki-attach-custom-data-to-state-objects),
though it suggests storing custom data under a `data` attribute. I've chosen not
to follow this recommendation because breadcrumbs seem to me like state metadata
whereas I would expect the data attribute to contain data for the underlying
state. This does however bring us to the next point: customization.

#### Customization
During the configuration phase, the `breadcrumbsProvider` can be
configured to use a custom compiler to extract breadcrumb information from each
state in the current ancestory. A custom compiler function can be used by
passing the compiler function to `breadcrumbsProvider.compileWith()`. For
example, to pull breadcrumb data from state.data.breadcrumbs instead of
state.breadcrumbs you could use:

```javascript
var yourApp = angular.module('yourApp', ['ui.router.breadcrumbs']);
yourApp.config(['breadcrumbsProvider', function(breadcrumbsProvider) {
  breadcrumbsProvider.compileWith(function(state) {
    return state.data && state.data.breadcrumbs;
  });
});
```

Though the example is contrived it should illustrate the flexibility of the
breadcrumbs service.

### Breadcrumbs Directive
The breadcrumbs directive is very simple and primarily serves to make the
breadcrumbs service available to the scope of the directive during the
prelinking phase. This allows for other directives, including ui-router<commit_msg>Update README regarding state.data usage<commit_after># UI-Router-Breadcrumbs
[![Build Status](https://travis-ci.org/interval-braining/angular-ui-router-breadcrumbs.png?branch=master)](https://travis-ci.org/interval-braining/angular-ui-router-breadcrumbs)

UI-Router-Breadcrumbs provides a service and directive that allow for the
creation of navigational breadcrumbs that are flexible and ready for customization.

**Note:** *This library is under active development and is most definitely
subject to change.*

## Getting Started

**(1)** Get UI-Router-Breadcrumbs by cloning and building this repository:
```bash
git clone <EMAIL>:interval-braining/angular-ui-router-breadcrumbs.git
cd angular-ui-router-breadcrumbs
npm install
bower install
```

**(2)** Include `angular-ui-router-breadcrumbs.js` (or
`angular-ui-router-breadcrumbs.min.js`) with your javascripts, after including
Angular itself.

**(3)** Add `'ui.router.breadcrumbs'` to your main module's list of dependencies.

## Usage
UI-Router-Breadcrumbs is split into two components: A breadcrumbs service and
a simple breadcrumbs directive that's primary function is to make the breadcrumbs
service available to the directive's scope.

### Breadcrumbs Service
The breadcrumbs service handles traversing the ui-router state hierarchy to
build an array of breadcrumb data for common use. This is done by walking from
the current state on up the tree from state to parent state until a state is
reached that does not have a parent. It should be noted that this means that
breadcrumbs will not be available for all states, but only for those states
that are ancestors of the current state.

By default, the service examines the current and each ancestor state for a
`breadcrumb` attribute to process. If a breadcrumb attribute is present and it
is a string, the service assumes the string is the text for the breadcrumb and
stores an object with the text and the name of the associated state. If the
breadcrumb attribute is not a string, but some other object, the service stores
the given object as the data for the breadcrumb. If the breadcrumb attribute is
null or undefined, it is assumed the state has no breadcrumb.

To add a breadcrumb to a state, simply add a breadcrumb attribute to the state
object where it is defined. For example:
```javascript
  $stateProvider.state('a', {
    breadcrumb: 'State A',
    url: '/a',
  }).state('a.b', {
    breadcrumb: {
      class: 'alternate',
      stateName: 'a.b',
      text: 'State B',
    },
    url: '/b'
  });
```

This is more or less supported by UI-Router as UI-Router supports
[custom data](https://github.com/angular-ui/ui-router/wiki#wiki-attach-custom-data-to-state-objects),
though typically on a `data` attribute. Breadcrumbs are stored elsewhere because
nested states inherit custom data from parent states and this behavior is not
especially intuitive given this approach to breadcrumbs. For example, storing
breadcrumbs as part of a state's `data` attribute would require having to
explicitly define a null breadcrumb for some child states or else handle
duplicate breadcrumbs when a child state doesn't override the inherited breadcrumb.

#### Customization
During the configuration phase, the `breadcrumbsProvider` can be
configured to use a custom compiler to extract breadcrumb information from each
state in the current ancestory. A custom compiler function can be used by
passing the compiler function to `breadcrumbsProvider.compileWith()`. For
example, to create a custom compiler that expects a breadcrumbs function,
something like this might work:

```javascript
var yourApp = angular.module('yourApp', ['ui.router.breadcrumbs']);
yourApp.config(['breadcrumbsProvider', function(breadcrumbsProvider) {
  breadcrumbsProvider.compileWith(function(state) {
    return state.breadcrumbs && state.breadcrumbs();
  });
});
```

Though the example is contrived it should illustrate the flexibility of the
breadcrumbs service.

### Breadcrumbs Directive
The breadcrumbs directive is very simple and primarily serves to make the
breadcrumbs service available to the scope of the directive during the
prelinking phase. This allows for other directives, including ui-router
{'fraction_non_alphanumeric': 0.07479156449239824, 'fraction_numerical': 0.0007356547327121138, 'mean_word_length': 4.8725701943844495, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 5, 'https://': 6, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4949554', 'n_tokens_mistral': 2211, 'n_tokens_neox': 2206, 'n_words': 1011}