use case: breadcrumbs

[EisenbergEffect]

Enable the navigation model to support breadcrumb UI generation.

[natwallbank]

So, as mentioned briefly via Twitter, I work on an in-house application where we use ui-router for client-side routing, and we dynamically display breadcrumbs in the UI.

I created a directive to encapsulate the breadcrumbs functionality and this required some extensions to ui-router via the data object (I think this is the supported / recommended way to define extra data relating to a state).

So this is the relevant function from my breadcrumbs directive. My directive hooks into the $stateChangeSuccess event and calls deriveBreadcrumbs (passing toState as the parameter):

// attempts to work out what we should display in breadcrumbs for the supplied state
var deriveBreadcrumbs = function (state) {
    // see if we can split the state
    var breadcrumbs = [];

    while (state) {
        // push the statename onto the breadcrumbs stack
        if (state.data && state.data.breadcrumb === true) {
            var stateName = state.name;
            var displayName = state.data.displayName ? state.data.displayName : stateName;
            if (state.data.breadcrumbProxyState) {
                // use the proxy to determine the generated URL
                var proxyState = $state.get(state.data.breadcrumbProxyState);
                if (proxyState)
                    stateName = proxyState.name;
            }
            breadcrumbs.push({ name: $interpolate(displayName)($state.$current.locals.globals), state: stateName });
        }

        // strip out the child state
        var index = state.name.lastIndexOf('.');
        if (index < 0)
            state = undefined;
        else
            state = $state.get(state.name.substring(0, index));
    }

    scope.breadcrumbs = breadcrumbs.reverse();
};

The key things for us are that states are already hierarchical, which fits well with trying to construct some meaningful breadcrumbs. The caveats are that:

• We needed to be able to have 'calculated' breadcrumbs, usually based on one or more properties of resolved object instances attached to the state (or a parent) - hence the use of $interpolate, e.g. you might want the breadcrumb text to be a contact name such as {{contact.forename}} {{contact.lastname}} where contact is resolved via an API call.
• Our home/root state was actually abstract and redirected to a default child state (with empty url), but we still wanted to use the display name from the abstract state. This is why we have the notion of a 'breadcrumbProxyState'. On reflection (it's been a while since I looked at this code) it seems slightly arbitrary, and I'm wondering why we didn't also use the proxy state to generate the ui-sref value for the breadcrumb, in addition to take the name. Hopefully you get the idea though!

I'm not sure if this information helps, but hopefully it sheds some light on some of the strange edge cases that we might be looking for in a new routing solution. Even if both of those issues couldn't be solved 'out of the box', as long as there's enough flexibility to work around it in a similar way then we'd be more than happy with that given the other anticipated benefits of moving to this router when it's available for 1.3!

[dmackerman]

Another related module that does breadcrumbsfor UI-Router fairly well: https://github.com/ncuillery/angular-breadcrumb