Navigation Guard

In the previous two posts (here and here), I covered the AngularJS factory, saNavigationGuard that I had created. This factory provides a simple way to guard against inconvenient page navigation in our Angular applications. However, up until now, I have not demonstrated one of the coolest uses for this. Before we look at this awesome use of saNavigationGuard, let us take a short trip into late last year.

I was getting started on my first big project with AngularJS and I had added a busy indicator to my user experience. To control when the indicator was active, I used a counter. This counter was incremented and decremented before and after using Angular resources. It was a nest of promises and error handlers, just to make sure the counter worked properly. I was not entirely happy with it but it was the best I could work out from my knowledge of Angular and JavaScript, so I submitted a pull request. My colleague reviewed the work and, looking at the busy indicator and the code to control the counter, stated, "there must be a better way."

I did not know at the time, but he was right, there is a better way and it uses an Angular feature called "interceptors".

Interceptors

Interceptors provide hooks into web requests, responses and their errors allowing us to modify or handle them in different ways. They are provided via an AngularJS provider such as a factory or service and injected into the $httpProvider using config as follows.

angular.module('somewhatabstract').config(['$httpProvider', function($httpProvider) {
	$httpProvider.interceptors.push('saHttpActivityInterceptor');
}]);

In this snippet, the name of the interceptor, saHttpActivityInterceptor, is added to the array of interceptors on $httpProvider.

The interceptor itself is a little more complex.

angular.module('somewhatabstract').factory('saHttpActivityInterceptor', ['$q', 'saNavigationGuard', function($q, saNavigationGuard) {
	var pendingRequestsCounter = 0;

	var updateCounter = function(method, delta) {
		if (method != 'POST' && method != 'PUT' && method != 'DELETE') {
		    return false;
		}
		pendingRequestsCounter += delta;
		return true;
	};

	saNavigationGuard.registerGuardian(function() {
		return pendingRequestsCounter > 0 ? 'There are changes pending.' : undefined;
	});

	return {
		request: function(request) {
			request.saTracked = updateCounter(request.method, 1);
			return request;
		},

		response: function(response) {
			if (response.config && response.config.saTracked) {
				updateCounter(response.config.method, -1);
			}
			return response;
		},

		responseError: function(rejection) {
			if (rejection.config && rejection.config.saTracked) {
				updateCounter(response.config.method, -1);
			}
			return $q.reject(rejection);
		}
	};
}]);

The interceptor factory returns an object that, in this case, has three methods: request, response and responseError. A fourth method, requestError, can also be included in interceptors if needed. Before returning our interceptor, the interceptor factory registers a guardian with saNavigationGuard that will guard against navigation if the pendingRequestsCounter is greater than zero.

The interceptor monitors requests and responses. On each request, the request method is checked, if it is POST, PUT or DELETE, the pendingRequestsCounter variable is incremented by one and the request is tagged to indicate it is being tracked. We flag it so that we know to pay attention when the corresponding response or response error occurs. In the response and response error handlers, we decrement our counter based on the tracking flag and the method.

Finally…

The outcome of using this interceptor is that if the user tries to navigate away from the page after a request has been made but before its response has been received, they will see a message asking them to consider postponing the navigation.

In the next post, we will look at testing both this interceptor and the saNavigationGuard functionality using my preferred combination of jasmine, CoffeeScript and jasmine-given.

As always, please consider leaving a comment if you have found this post useful or have any alternatives.