___

# Advanced Usage and Performance

This library makes everything possible to make the things simple and effective. 
However, the library cannot know about your application state nor
can undertake deep inspections of your data to detect changes in efficiency
considerations.


## Avoid to pass arrays/objects/jsx in props of `BreadcrumbsItem`

When jsx code like this: `<tag>...</tag>` or `<Component t='...'/>`
is evaluated  the new react element instance is created even if the same props
was passed. Same thing is when code contains `{}` or `[]` - the new object or
array is created in-place. All this cases represents new instance which is
considered as value change event even if this arrays/objects/jsx have same
values in depth.

The Library does not analyze data into depth to detect changes. So when you
pass new react element or newly created array or object to `BreadcrumbsItem`
as props it receives same props with new value. It gives proper result but
applying params will be defered to additional tree rerendering step and
executed after all again.

Full complete list of types allowed as `BreadcrumbsItem` props for better
performance:

* string
* number
* undefined
* boolean
* symbol

So to avoid additional processing you should not specify arrays or objects or react
elements (ie jsx) as props of `BreadcrumbsItem` in `render()` method:

``` javascript
render() {
  return <BreadcrumbsItem to='/' title={<b>Main Page</b>} x={[1,2,3]}/> // bad
}

render() {
  return <BreadcrumbsItem to='/'><b>Main Page</b></BreadcrumbsItem> // bad
}

render() {
  return <BreadcrumbsItem to='/'>Main Page</BreadcrumbsItem> // good
}
```


## Custom update filter

Another way is to use breadcrumbs item update filter. This is achieved by
specifying the function in `shouldBreadcrumbsUpdate` param of
`BreadcrumbsProvider` like this:

``` javascript
const theApp = (
  <BreadcrumbsProvider
    shouldBreadcrumbsUpdate = {
      (prevProps, props) => {
        // custom breadcrumbs item update filter condition
        return prevProps.to != props.to
      }
    }
  />
    <App />
  </BreadcrumbsProvider>
)
```

The item update filter must guarantee that the difference in the params
are really due to different source data. For example condition
`{k:'v'} != {k:'v'}` shows that this is the different data, although in
fact source data is the same and has not been changed.

**Warning:** if update filter determines the data changing at the time when
the original data has been unchanged this forms an infinite loop.

On the other hand, if some data is not recognized as changed, the breadcrumbs
will not be updated and will not look like expected.


## Alternate usage

An alternative, more flexible and at the same time more complicated way is to
update breadcrumbs only when related to breadcrubms item data is changed.
The library provides interface for that. The higher order
component creation function `withBreadcrumbsItem` will integrate `breadcrumbs`
object with `item()` and `items()` functions into props of your `Component`.

**Warning**: Never call `breadcrumbs.item()` or `breadcrumbs.items()` from
`render()` or `componentWillUpdate()` methods or from `constructor()` of your
component. This means breadcrumbs item must be not depend from state of
your current "with breadcrubms" component.

This way allows to specify arrays and objects and react elements (i.e. jsx) in
props but functions `breadcrumbs.item()` or `breadcrumbs.items()` must be
called from the `if` statement, where is the update condition which 
checks for changes the application related to breadcrubms item data.

**Warning:** if update condition determines the data changing at the time when
the original data has been unchanged this forms an infinite loop.


``` javascript
import { withBreadcrumbsItem, Dummy as Item } from 'react-breadcrumbs-dynamic'

@withBreadcrumbsItem
class CustomComponent extends React.Component {
  static propTypes = {
    breadcrumbs: PropTypes.object,
  }

  componentWillMount() {
    this.configureBreadcrumbs(this.props)
  }

  componentWillReceiveProps(nextProps) {
    // mandatory required update filter condition
    if( this.props.slug !== nextProps.slug ) {
      this.configureBreadcrumbs(nextProps)
    }
  }

  configureBreadcrumbs = (props) => {
    props.breadcrumbs.items(
      <div>
        <Item to='/' some={[1,2,3]}><b>Home</b></Item>
        <Item to=`/${props.slug}`><b>{props.slug}</b></Item>
      </div>
    )
  }

  render() {
    return (
      <div />
    )
  }
}
```