README.md

A navigation helper service for Angular client applications.

Dependencies

• AngularJS - http://angularjs.org
• Lodash - http://lodash.com

Configurable Dependencies

• ng-authentication-service - https://github.com/justinsa/angular-authentication-service

The ng-navigation-service was designed in tandem with the ng-authentication-service, but it is not a hard requirement. The configured security service must support the following API:

1. boolean isAuthenticated()
2. [String] roles()

Basic Setup

Add this module to your app as a dependency:

var app = angular.module('yourApp', ['navigation.service']);

Configure a security service to use with the navigation provider:

app.config(['$navigationProvider', function ($navigationProvider) {
  $navigationProvider.configure({
    securityService: '$authentication'
  });
}]);

Inject $navigation as a parameter in declarations that require it:

app.controller('yourController', function($scope, $navigation){ ... });

Configuration Options

To override the default configuration options, configure the module with an options argument during application configuration and provide overrides for any of the following options.

app.config(['$navigationProvider', function ($navigationProvider) {
  $navigationProvider.configure({
    activeLinkDecorator: undefined,
    inactiveLinkDecorator: undefined,
    securityService: undefined,
    extensions: undefined,
    roleToAudienceMapFunction: function (userRole) {
      return userRole;
    },
    inAudienceValidationFunction: function (userRoles, audiences) {
      var userAudiences = _.flatten(_.map(userRoles, this.roleToAudienceMapFunction));
      return !_.isEmpty(userAudiences) && !_.isEmpty(audiences) &&
        _.some(audiences, function (audience) { return _.includes(userAudiences, audience); });
    }
  });
}]);

extensions

All properties (own and inherited) of the extensions object will be available as native to the $navigation service API. The extensions object is applied using the _.defaults(...) method and cannot overwrite any of the existing API properties. This is intended to provide implementors with a way to add objects or functions that are application specific and should fall within the context of the navigation service to expose, e.g., a hash of link objects or a function to re-write links.

API

inAudience

// returns true if the user is in any of the specified audiences
$navigation.inAudience('X', 'Y', 'Z');

// will flatten provided arrays that are one-level deep in the arguments list
$navigation.inAudience('X', ['Y', 'Z'], ['A']) === $navigation.inAudience('X', 'Y', 'Z', 'A')

isActiveLocation

// returns true if the location is the current active location
// the following will match any location that starts with the /dashboard route
$navigation.isActiveLocation('/dashboard');

// can also handle sub-routes using '/'
// the leading '/' is optional
$navigation.isActiveLocation('dashboard/user');

decorateLink

// $navigation.decorateLink(item, active, inactive);
// returns the active decorator if the location is the current active location (see isActiveLocation).
// returns the inactive decorator if the location is not the current active location.
$navigation.decorateLink('/dashboard', 'active-item', undefined);

// parameters @active and @inactive are optional and if set to a falsy value will be
// overridden by the corresponding configuration values, if those are set:
//   configuration.activeLinkDecorator
//   configuration.inactiveLinkDecorator
$navigation.decorateLink('/dashboard');

goto

// Navigate to a route and optionally push the current location to history.
$navigation.goto(route, noHistory);

back

// Pop and navigate to the previous location from history.
$navigation.back();

Additional Methods

These methods were primarily implemented for testing or utility purposes, but they may be useful in special scenarios and are part of the exposed API.

getConfiguration

// Get the configuration options
$navigation.getConfiguration();

tokenizePath

// $navigation.tokenizePath(location);
// returns an in-order array of lowercase tokens from a location string.
// returns an empty array if no tokens are in the location string.
// returns an in-order array of lowercase tokens from the current active location, if no location parameter is provided.
$navigation.tokenizePath('/dashboard');

// parameter @location is optional and if set to a falsy value will be
// overridden by the value of ``$location.path()``.

Development

After forking you should only have to run npm install from a command line to get your environment setup.

After install you have two gulp commands available to you:

1. gulp js:lint
2. gulp js:test