Coding Smackdown TV

Hailing All Frequencies – Communicating in AngularJS with the Pub/Sub Design Pattern

Jim Lavin — Tue, 30 Apr 2013 00:03:51 +0000

Hailing All Frequencies! Is anybody out there? This is the USS AngularJS, we have a problem our services are speaking in Klingon and our controllers can’t communicate with their Ferengi directives. Can anyone help us!

I don’t know how many times I’ve seen a question about what is the best way to communicate between components in AngularJS. A lot of the time the resulting answer is to use the $rootScope object to $broadcast a message to anyone who might be listening for it. But, that really isn’t the best way to do it. Broadcasting messages between components means that they need to know too much about how things are coded reducing their modularity and re-use.

In this article I show you how to use the Pub/Sub Design Pattern for inter-component communications in AngularJS.

AngularJS has several ways that you can use to communicate between components, but the most used methods require your components to know too much about those they are communicating with, which increases the coupling between components and decreases their modularity and cohesion. This makes it hard to reuse your components in other applications.

By using the Publish/Subscribe design pattern we can decrease the coupling between components and encapsulate the details used for component communications. This will help increase your component’s modularity, testability and reuse.

The implementation of the Publish/Subscribe pattern I’ll be covering was devised by Eric Burley, @eburley, in his post angularjs.org watch, on pub sub, and you..

The example application, I’ll be describing, shows how you can use the Publish/Subscribe pattern for inter-controller communications and controller to service communications. You can find the source code out on GitHub under my repository angularjs-pubsub.

First We Need a Channel to Communicate Through

First let’s talk about the service that is used by the publishers and subscribers to communicate with each other. I’ve defined a service that will provide an interface that has a publish and subscribe method for each message we want to send.

In the code below I have defined two internal messages; _EDIT_DATA_, used to indicate that we need to edit the item passed in the message and _DATA_UPDATED_, used to indicate that our data has changed. Since these are defined internally to our service none of the consumers of the service will have access to them, helping to keep the implementation details hidden.

Each message in turn, has two methods; one to publish the message to the subscribers and another one that the subscribers will user to register a callback method that will be called when the message is received.

The methods to publish the messages to the subscribers are editData, on line 9, and dataUpated, on line 19. They use the $rootScope.$broadcast method to publish the private notification message to the event handlers.

The event registration methods, use the $scope.$on methods to set up a watch that will get called whenever the message is broadcast and in turn call the event handler that was passed when the subscriber registered with the service. Since the subscriber also passes in its own scope, we can use it to perform the watch on the message and avoid the heavy code needed to manage a list of listeners. The registration methods are onEditData, on line 13 and onDataUpdated on line 23.

To hide the implementation details, I’ve used a Revealing Module Pattern to only return back the methods that I want to be accessible by the consumers.

angular.module(['application.services'])
    // define the request notification channel for the pub/sub service
    .factory('requestNotificationChannel', ['$rootScope', function ($rootScope) {
        // private notification messages
        var _EDIT_DATA_ = '_EDIT_DATA_';
        var _DATA_UPDATED_ = '_DATA_UPDATED_';

        // publish edit data notification
        var editData = function (item) {
            $rootScope.$broadcast(_EDIT_DATA_, {item: item});
        };
        //subscribe to edit data notification
        var onEditData = function($scope, handler) {
            $scope.$on(_EDIT_DATA_, function(event, args) {
               handler(args.item);
            });
        };
        // publish data changed notification
        var dataUpdated = function () {
            $rootScope.$broadcast(_DATA_UPDATED_);
        };
        // subscribe to data changed notification
        var onDataUpdated = function ($scope, handler) {
            $scope.$on(_DATA_UPDATED_, function (event) {
                handler();
            });
        };
        // return the publicly accessible methods
        return {
            editData: editData,
            onEditData: onEditData,
            dataUpdated: dataUpdated,
            onDataUpdated: onDataUpdated
        };
    }])

Publishing a Message

To publish a message is pretty simple, first we need to include a dependency to the requestNotificationChannel in our controller, service or directive. You can see this in line 2 in the dataService definition below. When an event occurs in the component that needs to signal others that a change has occurred, you just need to call the appropriate notification method on the requestNotificationChannel. If you look at the saveHop, deleteHop and addHop methods of the dataService, you’ll see they all call the dataUpdated method on the requestNotificationChannel which will then signal the listeners who have registered with the onDataUpdated method.

    // define the data service that manages the data
    .factory('dataService', ['requestNotificationChannel', function (requestNotificationChannel) {
        // private data
        var hops = [
            { "_id": { "$oid": "50ae677361d118e3646d7d6c"}, "Name": "Admiral", "Origin": "United Kingdom", "Alpha": 14.75, "Amount": 0.0, "Use": "Boil", "Time": 0.0, "Notes": "Bittering hops derived from Wye Challenger.  Good high-alpha bittering hops. Use for: Ales Aroma: Primarily for bittering Substitutions: Target, Northdown, Challenger", "Type": "Bittering", "Form": "Pellet", "Beta": 5.6, "HSI": 15.0, "Humulene": 0.0, "Caryophyllene": 0.0, "Cohumulone": 0.0, "Myrcene": 0.0, "Substitutes": ""} ,
            { "_id": { "$oid": "50ae677361d118e3646d7d6d"}, "Name": "Ahtanum", "Origin": "U.S.", "Alpha": 6.0, "Amount": 0.0, "Use": "Boil", "Time": 0.0, "Notes": "Distinctive aromatic hops with moderate bittering power from Washington. Use for: Distinctive aroma Substitutes: N/A", "Type": "Aroma", "Form": "Pellet", "Beta": 5.25, "HSI": 30.0, "Humulene": 0.0, "Caryophyllene": 0.0, "Cohumulone": 0.0, "Myrcene": 0.0, "Substitutes": ""} ,
            { "_id": { "$oid": "50ae677361d118e3646d7d6e"}, "Name": "Amarillo Gold", "Origin": "U.S.", "Alpha": 8.5, "Amount": 0.0, "Use": "Boil", "Time": 0.0, "Notes": "Unknown origin, but character similar to Cascade. Use for: IPAs, Ales Aroma: Citrus, Flowery Substitutions: Cascade, Centennial", "Type": "Aroma", "Form": "Pellet", "Beta": 6.0, "HSI": 25.0, "Humulene": 0.0, "Caryophyllene": 0.0, "Cohumulone": 0.0, "Myrcene": 0.0, "Substitutes": ""} ,
            { "_id": { "$oid": "50ae677361d118e3646d7d6f"}, "Name": "Aquila", "Origin": "U.S.", "Alpha": 6.5, "Amount": 0.0, "Use": "Boil", "Time": 0.0, "Notes": "Aroma hops developed in 1988.  Limited use due to high cohumolone.Used for: Aroma hops Substitutes: ClusterNo longer commercially grown.", "Type": "Aroma", "Form": "Pellet", "Beta": 3.0, "HSI": 35.0, "Humulene": 0.0, "Caryophyllene": 0.0, "Cohumulone": 0.0, "Myrcene": 0.0, "Substitutes": ""} ,
            { "_id": { "$oid": "50ae677361d118e3646d7d70"}, "Name": "Auscha (Saaz)", "Origin": "Czech Republic", "Alpha": 3.3, "Amount": 0.0, "Use": "Boil", "Time": 0.0, "Notes": " Use for: Pilsners and Bohemian style lagers Aroma: Delicate, mild, clean, somewhat floral -- Noble hops Substitute: Tettnanger, LublinExamples: Pulsner Urquell", "Type": "Aroma", "Form": "Pellet", "Beta": 3.5, "HSI": 42.0, "Humulene": 0.0, "Caryophyllene": 0.0, "Cohumulone": 0.0, "Myrcene": 0.0, "Substitutes": ""} ,
        ];
        // sends notification that data has been updated
        var saveHop = function(hop) {
            requestNotificationChannel.dataUpdated();
        };
        // removes the item from the array and sends a notification that data has been updated
        var deleteHop = function(hop) {
            for(var i = 0; i < hops.length; i++) {
                if(hops[i]._id.$oid === hop._id.$oid) {
                    hops.splice(i, 1);
                    requestNotificationChannel.dataUpdated();
                    return;
                }
            };
        };
        // internal function to generate a random number guid generation
        var S4 = function() {
            return (((1+Math.random())*0x10000)|0).toString(16).substring(1);
        };
        // generates a guid for adding items to array
        var guid = function () {
          return (S4() + S4() + "-" + S4() + "-4" + S4().substr(0,3) + "-" + S4() + "-" + S4() + S4() + S4()).toLowerCase();
        };
        // function to add a hop to the array and sends a notification that data has been updated
        var addHop = function(hop) {
            hops.id.$oid = guid();
            hops.push(hop);
            requestNotificationChannel.dataUpdated();
        };
        // returns the array of hops
        var getHops = function() {
            return hops;
        };
        // returns a specific hop with the given id
        var getHop = function(id) {
            for(var i = 0; i < hops.length; i++) {
                if(hops[i]._id.$oid === id) {
                    return hops[i];
                }
            };
        };
        // return the publicly accessible methods
        return {
            getHops: getHops,
            getHop: getHop,
            saveHop: saveHop,
            deleteHop: deleteHop,
            addHop: addHop
        }
    }]);

Receiving Notification Events

Receiving event notifications from the requestNotificationChannel is just as simple, except we need to pass in a callBack handler that will do something with the notification once the message is sent. Again we will need to add a dependency to the requestNotificationChannel to our controller, service or directive, you can see this on line 2 of the code for the view1-controller below. Next we need to define an event callback handler that will respond to the event notification, you can see this on line 5 below. Next we need to register our callback handler with the requestNotificationChannel by calling onDataUpdated and passing in the scope from our controller and the callback handler, we do this on line 9 below.

    //define the controller for view1
    .controller('view1-controller', ['$scope', 'dataService', 'requestNotificationChannel', function($scope, dataService, requestNotificationChannel) {
        $scope.hops = dataService.getHops();

        var onDataUpdatedHandler = function() {
            $scope.hops = dataService.getHops();
        }

        requestNotificationChannel.onDataUpdated($scope, onDataUpdatedHandler);

        $scope.onEdit = function(hop) {
            requestNotificationChannel.editData(hop);
        }

        $scope.onDelete = function(hop) {
            dataService.deleteHop(hop);
        }
    }]);

Controller to Controller Communication

We can use the requestNotificationChannel to communicate between controllers as well. We just need to have one controller act as a publisher and one as a subscriber. If you look at the onEdit method of the view1-controller on line 11 above, it sends an editData message with the item that needs to be edited using the requestNotificationChannel. The view2-controller below registers its onEditDataHandler with the requestNotificationChannel on lines 5 thru 9 below. So whenever the view1-controller sends the editData message with the item to edit, the view2-controller gets notified of the editData request and takes the item received and assigns it to its model.

    //define the controller for view1
    .controller('view2-controller', ['$scope', 'dataService', 'requestNotificationChannel', function($scope, dataService, requestNotificationChannel) {
        $scope.hop = null;

        var onEditDataHandler = function(item) {
            $scope.hop = item;
        };

        requestNotificationChannel.onEditData($scope, onEditDataHandler);

        $scope.onSave = function() {
            dataService.saveHop($scope.hop);
            $scope.hop = null;
        }

        $scope.onCancel = function() {
            $scope.hop = null;
        }
    }]);

Always Have Well Documented Interfaces

One of the things that may not be apparent, is that we are using an interface to communicate between components, and with any interface, they need to be well documented in order to be properly used. In the example above, without the right documentation, consumers of the onEditData message would never know that an item is passed to the call back handler. So as you start to use the pattern, its good practice to document the methods so those consuming your notification services know what to expect.

The Wrap Up

So I've covered how to use the Publish/Subscribe pattern for component communications in your AngularJS App. The pattern allows you to decouple your components from internal messages and promotes better reuse. You can take using the Publish/Subscribe pattern even farther by replacing all communication between your components. This pattern works especially well when you have a lot of asynchronous requests in your services and want to cache the data in your service to reduce communications with the server side.

I hope you find this helpful, as always you can find the code out on my GitHub site under my repository angularjs-pubsub.

Localizing Your AngularJS Apps: Yet Another Update

Jim Lavin — Wed, 24 Apr 2013 19:26:52 +0000

So you are probably really jazzed about the addition of the new directive to the angularjs-localizationservice project and the fixes to help improve it’s performance. But, now that you are probably using the project I bet you are probably saying the same thing my devs and designers were saying, “Hey Jim, this new directive really works great, but how do we do translations for placeholders and titles?”

Well, this post is going to cover a new directive that’s been added to the project just to handle such things.

The i18n Attribute Directive

In the beginning there was the localize service which provided you with localized resource strings, but did nothing for binding them into your HTML. Next came along the i18n filter which did a good job of binding the localized string into your HTML, but proved to be a performance pig and couldn’t handle dynamic values in a localize string. Then came along the i18n directive which helped to improve performance and handle dynamic values in localized strings.

But, then came the need to have all text within the page localized, even that text which was hidden away from the end user, and so, along came the i18n Attribute directive, which handle just such a problem.

The Code

The i18n Attribute directive is pretty much the same as the i18n directive except it expects an additional parameter to be appended to the localization resource string token which indicates which attribute to set the value when the localized string is returned.

If you want to pass dynamic values for the string, those should come after the attribute parameter. Then the directive will walk through and replace the numbered place holders with their values.

    .directive('i18nAttr', ['localize', function (localize) {
        var i18NAttrDirective = {
            restrict: "EAC",
            updateText:function(elm, token){
                var values = token.split('|');
                // construct the tag to insert into the element
                var tag = localize.getLocalizedString(values[0]);
                // update the element only if data was returned
                if ((tag !== null) && (tag !== undefined) && (tag !== '')) {
                    if (values.length > 2) {
                        for (var index = 2; index < values.length; index++) {
                            var target = '{' + (index - 2) + '}';
                            tag = tag.replace(target, values[index]);
                        }
                    }
                    // insert the text into the element
                    elm.attr(values[1], tag);
                }
            },
            link: function (scope, elm, attrs) {
                scope.$on('localizeResourcesUpdated', function() {
                    i18NAttrDirective.updateText(elm, attrs.i18nAttr);
                });

                attrs.$observe('i18nAttr', function (value) {
                    i18NAttrDirective.updateText(elm, value);
                });
            }
        };

        return i18NAttrDirective;
    }]);

How to Use It

Using the i18n Attribute directive is pretty much the same as using the i18n directive. The only difference is that the name of the attribute you want to populate.

So if we have a local resource file that looks like below:

[
    {
        "key":"_Greeting_",
        "value":"Site localization example using the resource localization service",
        "description":"Home page greeting text"
    },
    {
        "key":"_HomeTitle_",
        "value":"Resource Localization Service",
        "description":"Home page title text"
    },
    {
        "key":"_HomeControllerTitle_",
        "value":"List Example",
        "description":"Home Pane Title"
    },
    {
        "key":"_HomeControllerBlob_",
        "value":"Now is the time for all good men to come to the aide of their country.",
        "description":"text example"
    },
    {
        "key":"_FormControllerTitle_",
        "value":"Form example",
        "description":"Add/Edit Person Form Title"
    },
    {
        "key":"_FirstNameLabel_",
        "value":"First Name",
        "description":"Label for first name field"
    },
    {
        "key":"_LastNameLabel_",
        "value":"Last Name",
        "description":"Label for last name field"
    },
    {
        "key":"_EMailLabel_",
        "value":"Email",
        "description":"Label for email field"
    },
    {
        "key":"_BioLabel_",
        "value":"Bio (tell us something about you) ",
        "description":"Label for biography field"
    },
    {
        "key":"_SaveButtonLabel_",
        "value":"Save",
        "description":"Label for Save button"
    },
    {
        "key":"_CancelButtonLabel_",
        "value":"Cancel",
        "description":"Label for Cancel button"
    },
    {
        "key":"_NameHeader_",
        "value":"Name",
        "description":"Person List Name Header"
    },
    {
        "key":"_EmailHeader_",
        "value":"Email",
        "description":"Person List Name Header"
    },
    {
        "key":"_BioHeader_",
        "value":"Biography",
        "description":"Person List Bio Header"
    }
]

We can set the placeholders of a registration form like so:

You can do the same with any other attribute where you need the text to change with the language.

Updating values dynamically is as easy as setting up your resource string with the numbered placeholders, such as; “This is a multi replace test response {0} {1}” and add the parameters to the end of the localization token like so, TEST_ITEM2|title|ABC|123, which will result in the title attribute to be set to title=”This is a multi replace test response ABC 123”.

The Wrap Up

Hopefully, the changes I’ve made to the library will provide you what you need to address the heavy lifting of making your app support multiple languages and you find it useful.

As part of the latest update I’ve also added unit tests for the service, filter and both directives to give you an idea how things work and as always you have the sample app to play with as well.

If you find an issue or come up with an enhancement you’d like to see included in the library, file an issue or send me a pull request and I’ll work on getting it resolved or added into the library.

Good Luck!

Localizing Your AngularJS Apps: Update

Jim Lavin — Tue, 23 Apr 2013 20:20:53 +0000

In my previous article on Localization, Localizing Your AngularJS App, I provided a simple service and filter that allows you to provide language translations based on a translation file. Initially this worked for about 50% of our transalation needs, however once we started looking at the overall performance of our AngualrJS App it was apparent that I needed to tweak things a bit.

This article covers the additional changes that has been made to my angularjs-localizationservice project out on GitHub.

The new service, has the following new features:

A new directive to help improve performance and handle dynamic localized resource strings
Updated the localize service to allow changing of the language on the fly
Fixed an issue with getLocalizedResourceString to be more efficient and simpler

Filters Degrade Performance

One of the first things we found out when we had a large page to provide translations for, is that the more filters you use on a page the slower your page becomes and performance will degrade significantly. This is mainly due to the fact that the filters are being re-evaluated with every watch cycle. So, I created a directive that provided the translation functionality.

.directive('i18n', ['localize', function(localize){
        var i18nDirective = {
            restrict:"EAC",
            updateText:function(elm, token){
                var values = token.split('|');
                if (values.length <= 1) {
                    // construct the tag to insert into the element
                    var tag = localize.getLocalizedString(values[0]);
                    // update the element only if data was returned
                    if ((tag !== null) && (tag !== undefined) && (tag !== '')) {
                        if (values.length > 1) {
                            for (var index = 1; index < values.length; index++) {
                                var target = '{' + (index - 1) + '}';
                                tag = tag.replace(target, values[index]);
                            }
                        }
                        // insert the text into the element
                        elm.text(tag);
                    };
                }
            },

            link:function (scope, elm, attrs) {
                scope.$on('localizeResourcesUpdates', function() {
                    i18nDirective.updateText(elm, attrs.i18n);
                });

                attrs.$observe('i18n', function (value) {
                    i18nDirective.updateText(elm, attrs.i18n);
                });
            }
        };

        return i18nDirective;
    }]);

So let’s discuss what’s going on in this new directive.

First off, we have set a dependency on the localize service so we can look up the translated strings. I have also restricted the directive to Elements, Attributes and Classes, this should pretty much cover everything you need in an HTML app.

Second, I added the updateText function which is responsible for looking up the localized text and update the attached element’s text. This function first splits the passed in token on ‘|’ boundaries in order to handle dynamic strings formatted as “First Name: {0}, Last Name: {1}”. If there are additional values passed in token such as “_WELCOME_STRING_|Jim|Lavin” the resulting string would end up as “First Name: Jim, Last Name: Lavin” based on the previous example.

If a valid string is returned from the localize service, the updateText function will parse the returned string for dynamic values and then update the elment’s text value. If the localize service does not have a matching resource string, it will not update the element.text value.

Finally, The link function sets up two observers. The first observer will call the updateText function whenever the localize Service broadcasts the ‘localizeResourcesUpdates’ message. This allows you to change languages on the fly without having to refresh the web page. We will discuss changing languages on the fly later in this article. The second observer will call the updateText function whenever the i18n attribute changes. This allows you to dynamically change the translated text by binding the value to your controller’s model.

You can now use the directive as shown below:

Notice the data-i18n attributes that contain the tokens for the resource strings. The nice thing about moving to the directive is that since I am using observers to watch the translation token values, the directive will only be called during the link phase, when the language changes or when the attribute value changes, keeping execution down to a minimum.

Updates to the Localize Service

Based on feedback from the GitHub community and tweaks to handle an initial load issue, I’ve made some updates to the localize service and will highlight them below.

    .factory('localize', ['$http', '$rootScope', '$window', '$filter', function ($http, $rootScope, $window, $filter) {
        var localize = {
            // use the $window service to get the language of the user's browser
            language:$window.navigator.userLanguage || $window.navigator.language,
            // array to hold the localized resource string entries
            dictionary:[],
            // flag to indicate if the service hs loaded the resource file
            resourceFileLoaded:false,

            successCallback:function (data) {
                // store the returned array in the dictionary
                localize.dictionary = data;
                // set the flag that the resource are loaded
                localize.resourceFileLoaded = true;
                // broadcast that the file has been loaded
                $rootScope.$broadcast('localizeResourcesUpdates');
            },

            setLanguage: function(value) {
                localize.language = value;
                localize.initLocalizedResources();
            },

            initLocalizedResources:function () {
                // build the url to retrieve the localized resource file
                var url = '/i18n/resources-locale_' + localize.language + '.js';
                // request the resource file
                $http({ method:"GET", url:url, cache:false }).success(localize.successCallback).error(function () {
                    // the request failed set the url to the default resource file
                    var url = '/i18n/resources-locale_default.js';
                    // request the default resource file
                    $http({ method:"GET", url:url, cache:false }).success(localize.successCallback);
                });
            },

            getLocalizedString: function(value) {
                // default the result to an empty string
                var result = '';

                // make sure the dictionary has valid data
                if ((localize.dictionary !== []) && (localize.dictionary.length > 0)) {
                    // use the filter service to only return those entries which match the value
                    // and only take the first result
                    var entry = $filter('filter')(localize.dictionary, function(element) {
                            return element.key === value;
                        }
                    )[0];

                    // set the result
                    result = entry.value;
                }
                // return the value to the call
                return result;
            }
        };

        // return the local instance when called
        return localize;
    } ]);

First, I added a setLanguage function that allows you to set the culture of the app on demand. It will change the internal language variable and call initLocalizedResources to load the correct language resource file from the server.

Second, based on an issue filed by Stein Desmet, I have changed the getLocalizedString function to pass a function to the $filter method which determines if the localized resource’s key matches the value passed in. This is needed since by default the AngularJS $filter function uses substring matching which required a lot of extra code to find the matching value if an array of matches were returned. The new method returns a single match and there is no need for the extra code, simplifying the overall solution.

The Wrap Up

The changes to the localization service and components makes it a great resource when you need to have an AngularJS app that supports multiple languages. Hopefully you’ll find it as useful as I have in my projects.

Good Luck!

Using Response Interceptors to Show and Hide a Loading Widget: Redux

Jim Lavin — Sun, 21 Apr 2013 04:13:12 +0000

In my previous post Using Response Interceptors to Show and Hide a Loading Widget I showed how to display a loading widget whenever an Ajax request started and hide it when all the requests completed by using a $http resource interceptor.

Unfortunately, I violated one of the core tenets of AngularJS’ best practices by modifying the DOM outside of a directive. I want to thank everyone who brought that to my attention and provided examples on how to clean up the code.

This post will walk through the revised code to show how to do it properly. I will also provide a second solution, that I think is even better structured, that uses a Publish/Subscribe pattern to encapsulate the whole messaging solution and keep the publishers and subscribers from having to know anything about the notification mechanism.

Using $rootScope to Send Notifications

The first solution I’m going to cover, uses the $rootScope $broadcast method to broadcast to all children in the scope tree. This way, any controllers or directives further down the scope that are interested in the messages can set up scope $on methods for the event message and can react to it.

Below is the revised code from the Sample01 solution:

'use strict';

// Declare app level module which depends on filters, and services
var app = angular.module('myApp', ['mongolabResourceHttp', 'data.services']);

app.constant('_START_REQUEST_', '_START_REQUEST_');
app.constant('_END_REQUEST_', '_END_REQUEST_');

app.config(['$httpProvider', '_START_REQUEST_', '_END_REQUEST_', function ($httpProvider, _START_REQUEST_, _END_REQUEST_) {
    var $http,
        interceptor = ['$q', '$injector', function ($q, $injector) {
            var rootScope;

            function success(response) {
                // get $http via $injector because of circular dependency problem
                $http = $http || $injector.get('$http');
                // don't send notification until all requests are complete
                if ($http.pendingRequests.length < 1) {
                    // get $rootScope via $injector because of circular dependency problem
                    rootScope = rootScope || $injector.get('$rootScope');
                    // send a notification requests are complete
                    rootScope.$broadcast(_END_REQUEST_);
                }
                return response;
            }

            function error(response) {
                // get $http via $injector because of circular dependency problem
                $http = $http || $injector.get('$http');
                // don't send notification until all requests are complete
                if ($http.pendingRequests.length < 1) {
                    // get $rootScope via $injector because of circular dependency problem
                    rootScope = rootScope || $injector.get('$rootScope');
                    // send a notification requests are complete
                    rootScope.$broadcast(_END_REQUEST_);
                }
                return $q.reject(response);
            }

            return function (promise) {
                // get $rootScope via $injector because of circular dependency problem
                rootScope = rootScope || $injector.get('$rootScope');
                // send notification a request has started
                rootScope.$broadcast(_START_REQUEST_);
                return promise.then(success, error);
            }
        }];

    $httpProvider.responseInterceptors.push(interceptor);
}]);

app.directive('loadingWidget', ['_START_REQUEST_', '_END_REQUEST_', function (_START_REQUEST_, _END_REQUEST_) {
    return {
        restrict: "A",
        link: function (scope, element) {
            // hide the element initially
            element.hide();

            scope.$on(_START_REQUEST_, function () {
                // got the request start notification, show the element
                element.show();
            });

            scope.$on(_END_REQUEST_, function () {
                // got the request end notification, hide the element
                element.hide();
            });
        }
    };
}]);

app.filter('startFrom', function () {
    return function (input, start) {
        start = +start; //parse to int
        return input.slice(start);
    }
});

app.controller('myController', ['$scope', 'YeastResource', function ($scope, YeastResource) {
    $scope.yeasts = [];
    $scope.currentPage = 0;
    $scope.pageSize = 10;

    $scope.numberOfPages = function () {
        return Math.ceil($scope.yeasts.length / $scope.pageSize);
    };

    $scope.init = function () {
        YeastResource.query({}, {sort: {Type: 1, Name: 1}}).then(function (yeast) {
            $scope.yeasts = yeast;
        });
    };

    $scope.init();
}]);

The first change is that I’ve added two constants on lines 6 and 7, these will be used as the event messages sent by the http resource interceptor.

On line 9, I add the two constants as dependencies to the config function so they can be used by the interceptor.

On line 12, I define a variable to hold a reference to the $rootScope, which will be used to broadcast the notification messages. You might wonder why we didn’t put the $rootScope as a parameter to the config function, this is because at the time the config function is called the $rootScope doesn’t exist. Later when we need the $rootScope we get it by making a call to $injector.get(). You can see this on lines 20, 33 and 40.

Next we define the success and error handlers. Both methods work similar, we use $injector.get() to get a reference to the $http service and check to see if all the requests have completed and if so we use the reference to the $rootScope to broadcast the _END_REQUEST_ notification. You can see this on lines 18 thru 23 and on lines 31 thru 36.

Finally, we use the reference to the $rootScope to broadcast the _START_REQUEST_ in the final method of the resource interceptor on lines 41 thru 44.

The Loading Widget Directive

Instead of having to put logic into a controller to show or hide the loading widget each time a notification is received, I’ve created a directive that handles showing and hiding any element that it is applied to. Let’s discuss the code below:

app.directive('loadingWidget', ['_START_REQUEST_', '_END_REQUEST_', function (_START_REQUEST_, _END_REQUEST_) {
    return {
        restrict: "A",
        link: function (scope, element) {
            // hide the element initially
            element.hide();

            scope.$on(_START_REQUEST_, function () {
                // got the request start notification, show the element
                element.show();
            });

            scope.$on(_END_REQUEST_, function () {
                // got the request end notification, hide the element
                element.hide();
            });
        }
    };
}]);

I again add dependencies for the _START_REQUEST_ and _END_REQUEST_ constants to the directive, this way the directive can add message handlers for each notification message. The _START_REQUEST_ handler is defined on lines 59 thru 62 and the _END_REQUEST_ handler is defined on lines 64 thru 67. Each handler shows or hides the attached element based on notification message. By default the directive hides the attached element until it receives the _START_REQUEST_ notification message.

HTML Changes

The only change made to the original index.html file occurs on the div element that contains the loading widget at lines 25 thru 31, where we added the new directive to the div element at line 25.

Now that is pretty much all you need to do get the loading widget to display and hide whenever an $http request begins or ends.

Applying the Publish/Subscribe Pattern to the Loading Widget

Our solution works great, but there are some issues with the solution as it now sits.

Both the $http resource interceptor and the directive have to have knowledge of the notification message in order to communicate with each other. This means that the modularity of the solution is too tightly coupled to be reused in other scenarios where we might need it.

If we wanted to display the widget whenever we had a lengthy computation execute, we would have to couple the computation service to the same two notification messages in order to make it work. But what if we wanted to move the computation engine to another application that used different notification messages? We’d have to change the dependencies we inject into the service or make some code changes to wire up the service with the new notification code.

That’s not a good thing. What we really want are code components with high cohesion and high modularity, and with minimal coupling between them. To achieve this we need to use a different mechanism that can abstract out the specifics around the notification messages and provide a standard interface that can be implemented for any type of notifications that we might want to implement.

We can use the Publish/Subscribe Pattern to encapsulate the notification details and instead provide a standard interface that any component can use to show the widget as needed.

The implementation of the Publish/Subscribe pattern I built my service on was created for AngularJS by Eric Burley, @eburley, his original post can be found at angularjs.org watch, on pub sub, and you., I just wrapped the implementation into a service that could be injected into the publishers and subscribers.

So let’s take a look at the new code from Sample02 solution:

'use strict';

// Declare app level module which depends on filters, and services
var app = angular.module('myApp', ['mongolabResourceHttp', 'data.services']);

app.config(['$httpProvider', function ($httpProvider) {
    var $http,
        interceptor = ['$q', '$injector', function ($q, $injector) {
            var notificationChannel;

            function success(response) {
                // get $http via $injector because of circular dependency problem
                $http = $http || $injector.get('$http');
                // don't send notification until all requests are complete
                if ($http.pendingRequests.length < 1) {
                    // get requestNotificationChannel via $injector because of circular dependency problem
                    notificationChannel = notificationChannel || $injector.get('requestNotificationChannel');
                    // send a notification requests are complete
                    notificationChannel.requestEnded();
                }
                return response;
            }

            function error(response) {
                // get $http via $injector because of circular dependency problem
                $http = $http || $injector.get('$http');
                // don't send notification until all requests are complete
                if ($http.pendingRequests.length < 1) {
                    // get requestNotificationChannel via $injector because of circular dependency problem
                    notificationChannel = notificationChannel || $injector.get('requestNotificationChannel');
                    // send a notification requests are complete
                    notificationChannel.requestEnded();
                }
                return $q.reject(response);
            }

            return function (promise) {
                // get requestNotificationChannel via $injector because of circular dependency problem
                notificationChannel = notificationChannel || $injector.get('requestNotificationChannel');
                // send a notification requests are complete
                notificationChannel.requestStarted();
                return promise.then(success, error);
            }
        }];

    $httpProvider.responseInterceptors.push(interceptor);
}]);

app.factory('requestNotificationChannel', ['$rootScope', function($rootScope){
    // private notification messages
    var _START_REQUEST_ = '_START_REQUEST_';
    var _END_REQUEST_ = '_END_REQUEST_';

    // publish start request notification
    var requestStarted = function() {
        $rootScope.$broadcast(_START_REQUEST_);
    };
    // publish end request notification
    var requestEnded = function() {
        $rootScope.$broadcast(_END_REQUEST_);
    };
    // subscribe to start request notification
    var onRequestStarted = function($scope, handler){
        $scope.$on(_START_REQUEST_, function(event){
            handler();
        });
    };
    // subscribe to end request notification
    var onRequestEnded = function($scope, handler){
        $scope.$on(_END_REQUEST_, function(event){
            handler();
        });
    };

    return {
        requestStarted:  requestStarted,
        requestEnded: requestEnded,
        onRequestStarted: onRequestStarted,
        onRequestEnded: onRequestEnded
    };
}]);

app.directive('loadingWidget', ['requestNotificationChannel', function (requestNotificationChannel) {
    return {
        restrict: "A",
        link: function (scope, element) {
            // hide the element initially
            element.hide();

            var startRequestHandler = function() {
                // got the request start notification, show the element
                element.show();
            };

            var endRequestHandler = function() {
                // got the request start notification, show the element
                element.hide();
            };

            requestNotificationChannel.onRequestStarted(scope, startRequestHandler);

            requestNotificationChannel.onRequestEnded(scope, endRequestHandler);
        }
    };
}]);

app.filter('startFrom', function () {
    return function (input, start) {
        start = +start; //parse to int
        return input.slice(start);
    }
});

app.controller('myController', ['$scope', 'YeastResource', function ($scope, YeastResource) {
    $scope.yeasts = [];
    $scope.currentPage = 0;
    $scope.pageSize = 10;

    $scope.numberOfPages = function () {
        return Math.ceil($scope.yeasts.length / $scope.pageSize);
    };

    $scope.init = function () {
        YeastResource.query({}, {sort: {Type: 1, Name: 1}}).then(function (yeast) {
            $scope.yeasts = yeast;
        });
    };

    $scope.init();
}]);

First off, We’ve removed the constant declarations and the dependencies on them across the code.

$http Resource Interceptor Changes

Starting on line 9, I’ve changed the variable that referenced the $rootScope instance to now hold a new reference to the Publish/Subscribe implementation called notificationChannel. Then I changed the Success, Error, and $http Resource Interceptor functions to request an instance of the new notification service on lines 17, 30, and 39.

The Success and Error methods now call the requestEnded() method on the new notification service instead of broadcasting a notification message, (lines 19 and 32). The $http Resource Interceptor function now calls the requestStarted() method instead of broadcasting the notification message on line 41.

The Publish/Subscribe Service

Starting on line 49, I define the a new service that will implement the Publish/Subscribe Pattern. To hide the details of the implementation I’m using a revealing module pattern to return back an object with only four public methods; requestStarted, requestEnded, onRequestStarted and onRequestEnded. The rest of the details and the broadcasting of messages are all hidden from the consumers of the service.

We now define the notification start and end messages on lines 51 and 52. The requestStarted and requestEnded methods broadcast the notification messages and the onRequestStarted and onRequestEnded methods setup the broadcast watchers on the scope that is passed into them. The onRequestStarted and onRequestEnded methods also require that a handler function be passed into the method so we can call it whenever the notification message is received.

At first glance it might look that the new service should have an array of listeners, but since each listener passes in it’s own scope, the service can use it to perform the watch for the notification message and the anonymous function passed to the watch calls the listener’s request handler eliminating the need for an array to hold all of the request handlers.

loadingWidget Directive Changes

The directive now has a dependency on the new Publish/Subscribe Service, requestNotificationChannel. And instead of implementing watches for the notification messages, the directive now has defined two new request handlers; startRequestHandler and endRequestHandler, which now handle showing and hiding the element the directive is attached two. Finally, the directive registers the request handlers with the Publish/Subscribe Service by passing in the directives scope and the appropriate request handler.

The Wrap Up

As I said at the beginning of this post, my original post covered how to use $http request interceptor to display and hide a loading widget. However, there were flaws in the original code. In this article I provided an updated example of the solution that follows the Best Practices of AngularJS. I then provided a second, better solution which uses the Publish/Subscribe Pattern to encapsulate the details of the messaging and improve the overall modularity of the solution.

I’ve revised the code and split both examples into two different examples; Sample01 and Sample02. I’ve also provided a stand alone module that can be used in your applications. You can find all of the source code on my GitHub site.

AngularJS Modules for Great Justice

Jim Lavin — Fri, 19 Apr 2013 06:06:08 +0000

First off I want to thank Joel Hooks of the DFW Area AngularJS Meetup Group for suggesting this topic and providing the title.

“Modules provide an excellent mechanism for cleanly dividing up our code into functional areas. Angular allows us to use modules in many ways. Let’s take a look at modules and some of the approaches we can leverage to produce cleaner more manageable code.” – Joel Hooks

So with that, let’s get started.

AngularJS modules are the core means by how you define the components in your app. Besides defining your components, modules provide a way to indicate the dependencies your components require and they help you organize your components to help you write modular code that can be re-used across applications.

As long as I have been developing with AngularJS there has always been the great best practices debate over how to structure your application. Do you use a package by feature or package by layer approach?

Both have their advantages and disadvantages so let’s take a quick look at each before we get into how to implement each using AngularJS.

Package by Feature

Package by Feature became popular in the Java development camp a few years back. The main tenet is that by keeping all the source code related to a specific feature in a single package, it was easier to develop and promote modularity across your source code. Entire features could be lifted from applications and re-used in others by just taking the source package, there was no need to bring in other packages since all the code for the feature was in one place.

Package-by-feature uses packages to reflect the feature set. It places all items related to a single feature (and only that feature) into a single directory. This results in packages with high cohesion and high modularity, and with minimal coupling between packages. Items that work closely together are placed next to each other. They aren’t spread out all over the application.

A lot of developers feel that by using Package by Feature, development on large projects is also easier since all the code you need to deal with is in one place and as the project grows following the pattern keeps everything well organized.

A good example of Package by Feature, is the angular-sprout seed project. All of the JavaScript files for a particular feature are included in the same directory. So, if we have three different views in our application; User, Movie, and Rating, we’ll have three directories in our source code. Each folder would include the source for the controllers, services, models and templates for the specific feature.

Package by Layer

If you come from a object-oriented development background, you probably are more familiar with the Package by Layer approach. The basic tenets of object-oriented design is to design by layers; data access, business logic, business entities, and user interface. This way your code is organized in layers that communicate with each other via specific interfaces. Depending on how rigid your design and coding rules are, layers only interacted with adjacent layers and never called across boundaries.

In package-by-layer, the highest level packages reflect the various application “layers”, instead of features. Each feature has its implementation spread out over multiple directories, over what might be loosely called “implementation categories”. Each directory contains items that usually aren’t closely related to each other. This results in packages with low cohesion and low modularity, with high coupling between packages.

Package by Layer works great when it comes to code that implements cross cutting concerns, however when you are developing features that span multiple layers development becomes harder since you have to deal with source files in various places. Package by Layer also promotes cross package dependencies which some feel are a bad thing.

A good example of Package by Layer, is the angular-seed project. All of the JavaScript files for a particular type of AngularJS component are included in the same directory or file. So, our application would be divided across the following source folders; controllers, directives, services, models, filter, etc.

So What’s All This Got to do with AngularJS Code

So, you’re probably wondering, “Why should I care, I write web apps?” Actually how you partition your code has a lot to do with how you organize your project source code and how much easier it is to maintain as your project grows.

Depending on the size of your project your are going to have to decide on how you want your code structured. Do you keep everything in a single JavaScript file, do you break your files based on layers, do you break your files based on features, or do you structure your code directories by features and structure your source files by layers?

Tiny Projects

For me, if I have a very small or tiny project that does one thing, I might keep all of my source code in a single file using single module. Below is a picture of the project’s directory structure. Notice we have a single file, app.js which holds our source code and our index.html file which loads and bootstraps our app.

Below is the app.js file, I’ve defined a single module called myApp and used the controller and directive definition methods to define my controller and directive used by my app. Everything is in one place and easy to maintain, which is all you need when writing a very simple application.

        angular.module('myApp', [])

        // register the controller for the app
        .controller('myController',['$scope', function($scope){
            $scope.format = 'M/d/yy h:mm:ss a';
        }])

        // Register the 'myCurrentTime' directive factory method.
        // We inject $timeout and dateFilter service since the factory method is DI.
        .directive('myCurrentTime', function($timeout, dateFilter) {
            // return the directive link function. (compile function not needed)
            return function(scope, element, attrs) {
                var format,  // date format
                    timeoutId; // timeoutId, so that we can cancel the time updates

                // used to update the UI
                function updateTime() {
                    element.text(dateFilter(new Date(), format));
                }

                // watch the expression, and update the UI on change.
                scope.$watch(attrs.myCurrentTime, function(value) {
                    format = value;
                    updateTime();
                });

                // schedule update in one second
                function updateLater() {
                    // save the timeoutId for canceling
                    timeoutId = $timeout(function() {
                        updateTime(); // update DOM
                        updateLater(); // schedule another update
                    }, 1000);
                }

                // listen on DOM destroy (removal) event, and cancel the next UI update
                // to prevent updating time after the DOM element was removed.
                element.bind('$destroy', function() {
                    $timeout.cancel(timeoutId);
                });

                updateLater(); // kick off the UI update process.
            }
        });

Below is the index.html file that instantiates the app and displays an input field that allows you to modify the time format that is used by the myCurrentTime directive to display the current date and time to the user.

        
        
        
            
            
            
        
        
        
            
            Time format is: {{format}}
            Current time is:

Small Projects

As your project starts to get a little more complicated you might want to start organizing your code into multiple modules, but still keep it in a single file. Below is a picture of the project’s directory structure. Notice we still have a single file, app.js which holds our source code and our index.html file which loads and bootstraps our app.

Below is the app.js file, I’ve defined multiple modules one for the controllers, a second for the directives and a third for the app. I have again used the controller and directive definition methods to define my controller and directive used by my app, but now they are defined on specific modules defined for each type of AngularJS component type. I have also added dependencies to the application’s module definition so everything get injected properly. Everything is in one place and easy to maintain, but is ready for when you need to separate your code into multiple files when they get too big to maintain.

        angular.module('myControllers', [])
            // register the controller for the app
            .controller('myController',['$scope', function($scope){
                $scope.format = 'M/d/yy h:mm:ss a';
            }]);

        angular.module('myDirectives', [])
            // Register the 'myCurrentTime' directive factory method.
            // We inject $timeout and dateFilter service since the factory method is DI.
            .directive('myCurrentTime', function($timeout, dateFilter) {
                // return the directive link function. (compile function not needed)
                return function(scope, element, attrs) {
                    var format,  // date format
                        timeoutId; // timeoutId, so that we can cancel the time updates

                    // used to update the UI
                    function updateTime() {
                        element.text(dateFilter(new Date(), format));
                    }

                    // watch the expression, and update the UI on change.
                    scope.$watch(attrs.myCurrentTime, function(value) {
                        format = value;
                        updateTime();
                    });

                    // schedule update in one second
                    function updateLater() {
                        // save the timeoutId for canceling
                        timeoutId = $timeout(function() {
                            updateTime(); // update DOM
                            updateLater(); // schedule another update
                        }, 1000);
                    }

                    // listen on DOM destroy (removal) event, and cancel the next UI update
                    // to prevent updating time after the DOM element was removed.
                    element.bind('$destroy', function() {
                        $timeout.cancel(timeoutId);
                    });

                    updateLater(); // kick off the UI update process.
                }
            });

        angular.module('myApp', ['myControllers', 'myDirectives']);

Notice that the index.html file used in our example below hasn’t changed.

        
        
        
            
            
            
        
        
        
            
            Time format is: {{format}}
            Current time is:

Medium Projects

As your projects get larger and more complex, you might want to follow the angular-seed approach and split your source code across layers. In the sample code, I’ve broken the code out across multiple source files by layer, there is one file for the app, one for the controllers and one for the directives. Depending on how you want to structure your code, you can use a single module or multiple modules. In this example I use a single module that is assigned to a variable that is referenced by the other source files.

Our source code structure has changed. Now, instead of just an app directory there is now a controllers and directives directory.

Below is the contents of the app.js file. All we are doing is declaring the module that will be used by app:

        var myModule = angular.module('myApp', []);

Again, I am using a single module across my entire app so I am assigning it to variable, which I will reference in the other source files to define my controller and directive.

Below is the contents of the controllers.js file. Here we are using the myModule variable to define the controller.

        // register the controller for the app
        myModule.controller('myController',['$scope', function($scope){
            $scope.format = 'M/d/yy h:mm:ss a';
        }]);

Below is the contents of the directives.js file. Again we are using the myModule variable to define the directive.

        myModule.directive('myCurrentTime', function($timeout, dateFilter) {
            // return the directive link function. (compile function not needed)
            return function(scope, element, attrs) {
                var format,  // date format
                    timeoutId; // timeoutId, so that we can cancel the time updates

                // used to update the UI
                function updateTime() {
                    element.text(dateFilter(new Date(), format));
                }

                // watch the expression, and update the UI on change.
                scope.$watch(attrs.myCurrentTime, function(value) {
                    format = value;
                    updateTime();
                });

                // schedule update in one second
                function updateLater() {
                    // save the timeoutId for canceling
                    timeoutId = $timeout(function() {
                        updateTime(); // update DOM
                        updateLater(); // schedule another update
                    }, 1000);
                }

                // listen on DOM destroy (removal) event, and cancel the next UI update
                // to prevent updating time after the DOM element was removed.
                element.bind('$destroy', function() {
                    $timeout.cancel(timeoutId);
                });

                updateLater(); // kick off the UI update process.
            }
        });

Finally below is the index.html file used to load and instantiate the app. Notice how we now need to include the new source files in order to load all of our code.

        
        
        
            
            
            
            
            
        
        
        
            
            Time format is: {{format}}
            Current time is:

Large to Very Large Projects

As your application starts to grow and include more and more features, it is best to re-structure your source code’s directory structure by using the Package by Feature pattern and then use the Package by Layer pattern for your source files that relate to the feature. Below is a picture of the Large project’s structure. Now, we have created the folder structure based on the features in the app and the source files are based on the different AngularJS layers.

Below is the contents of the app.js file. We are again defining a module for our app. Notice that we have included the names of the other modules which define our features.

        angular.module('myApp', ['my-view-controller', 'time']);

Below is contents of the my-view-controller.js app, which defines our controller for the feature.

        // register the controller for the app
        angular.module('my-view-controller', []).controller('myController',['$scope', function($scope){
            $scope.format = 'M/d/yy h:mm:ss a';
        }]);

Since we are using the Package by Feature pattern to structure our code, we have now created a template that will be used to instantiate our controller. The reason for breaking out the HTML for the feature is because we want to have a fully re-usable package that we can pick up and drop into another application without having to drag other parts of the source application into your new app.

Below is the contents of my-view-partial.html:

        
            
            Time format is: {{format}}
            Current time is:

We have also moved our directive to it’s own feature directory giving us another module that we can reuse in other applications.

        // Register the 'myCurrentTime' directive factory method.
        // We inject $timeout and dateFilter service since the factory method is DI.
        angular.module('time', []).directive('myCurrentTime', function($timeout, dateFilter) {
            // return the directive link function. (compile function not needed)
            return function(scope, element, attrs) {
                var format,  // date format
                    timeoutId; // timeoutId, so that we can cancel the time updates
        
                // used to update the UI
                function updateTime() {
                    element.text(dateFilter(new Date(), format));
                }
        
                // watch the expression, and update the UI on change.
                scope.$watch(attrs.myCurrentTime, function(value) {
                    format = value;
                    updateTime();
                });
        
                // schedule update in one second
                function updateLater() {
                    // save the timeoutId for canceling
                    timeoutId = $timeout(function() {
                        updateTime(); // update DOM
                        updateLater(); // schedule another update
                    }, 1000);
                }
        
                // listen on DOM destroy (removal) event, and cancel the next UI update
                // to prevent updating time after the DOM element was removed.
                element.bind('$destroy', function() {
                    $timeout.cancel(timeoutId);
                });
        
                updateLater(); // kick off the UI update process.
            }
        });

Finally, we have our index.html file which loads our source and instantiates our app. Notice that we have a script tag for each of our source files and that we are using the ng-include directive to load our view’s template.

Use What Works Best for Your App

So we’ve covered several patterns that can be used to organize your source code, which one you use is up to you. Below are a couple of quick guidelines for writing different types of apps or re-usable components:

Directives and Components – If possible try to keep your code to a single module and single source file. If you have templates that your directive or component depends upon, either provide an attribute or method that allows end users to provide a templat Url or include a second JavaScript file that loads the templates via code and adds them to the template cache.
Re-Usable Feature Modules – Use the Package by Feature pattern to keep everything in a single directory that can easily be added to a project. Whether you use separate template files or include them in a source file is up to you, lean towards what works best if the module templates need to be tailored for use in the app they are added to. If you plan on making the module deployable via Bower or npm, plan on including your unit tests so end users can use them to ensure everything works as plan.
Simple Apps – Use a single source module and source file to reduce the number of files that need to be loaded at run time. If you have multiple templates in your app, consider putting them into the index.html file and use ng-show, ng-hide or ng-switch to display them as needed.
Large Complex Apps – Use the Package by Feature pattern to structure your source code into modules and then use the Package by Layer pattern for your source files.

Where Do I Put My Unit Tests?

Another question that comes up when talking about source code structure is “Where do I put my unit tests?”

I’m a believer that unit tests should be under a seperate folder called ‘unittests’ that has the same directory structure as your app. If you structure your app by feature, then your unit tests should also be structured by feature. This helps with maintenance since the directory structure is the same as the source code’s structure.

The only time to I would include the unit tests with the actual source files is if you are create a package that will be distributed by a package manager such as Bower or npm. Then I think it’s more important so the end user has a way to validate your directive or component works as intended.

What you do is ultimately up to you. Those are the decisions that you should make based on your team’s workflow.

The Wrap Up

In this article I’ve covered a couple of different patterns that you can use to organize your AngularJS source code and how modules can be used to help you organize your code and it’s dependencies. Hopefully, this helps you come up with a project structure that works best for you and your team.

Source Code

You can find all of the source code for this article on my GitHub page at https://github.com/lavinjj/angularjs-modules-for-great-justice

Using Response Interceptors to Show and Hide a Loading Widget

Jim Lavin — Wed, 02 Jan 2013 17:44:28 +0000

AngularJS provides extension points which allow you to intercept responses to http requests before they are handed over to the application code. You can use these extension points to provide global exception handling, authentication, or any other type of pre-processing you might need in your app. In this article I’m going to show you how you can use a response interceptor to turn a loading widget on and off as your http requests are made and completed.

The App Overview

I’ve created a simple app that displays a list of different yeast strains used in home brewing. I’ve stored the list of yeast strains in a MongoDB collection out on mongolabs.com and I am using the Promise-aware MongoLab $resource for AngularJS by Pawel Kozlowski out on GitHub at https://github.com/pkozlowski-opensource/angularjs-mongolab-promise to retrieve the collection.

I’ve also added a simple filter that allows us to page through the data to make the data a little easier to deal with.

If you look at code it’s pretty straight forward, the controller makes a call to the data resource which in turn queries the mongolab collection that we assign to an internal array that is used in the ng-repeat to populate the page.

'use strict';

// Declare app level module which depends on filters, and services
var app = angular.module('myApp', ['mongolabResourceHttp', 'data.services', ]);

app.filter('startFrom', function () {
        return function (input, start) {
            start = +start; //parse to int
            return input.slice(start);
        }
    });

function myController($scope, YeastResource) {
    $scope.yeasts = [];
    $scope.currentPage = 0;
    $scope.pageSize = 10;

    $scope.numberOfPages = function () {
        return Math.ceil($scope.yeasts.length / $scope.pageSize);
    };

    $scope.init = function() {
        YeastResource.query({}, {sort: {Type: 1, Name: 1}}).then(function(yeast){
            $scope.yeasts = yeast;
        });
    };

    $scope.init();
}

Below is the HTML Mark up used to display the data on the page. It’s pretty straight forward as well. The only thing to note is how the buttons are used to change the currentPage scope variable to page through the data.


    
        HTTP Interceptor Example
    
    
        Name
        Type
        Form
        Laboratory
        Best For
        Notes
    
    
        {{yeast.Name}}
        {{yeast.Type}}
        {{yeast.Form}}
        {{yeast.Laboratory}}
        {{yeast.BestFor}}
        {{yeast.Notes}}
    
    
    
        
        
        1/Loading..

Adding a Loading Widget

First let’s define our loading widget. We’ll add a DIV to the HTML Mark up and set the id to loadingWidget so we can show and hide it in our response interceptor. All the loading widget does is wrap an image tag that contains our animated gif and the word Loading. By default we use an in-line style to set the DIV to display: none so it will not be visible until we set it visible.


    
        
            
                 Loading
            
        
    
    
        HTTP Interceptor Example
    
    
        Name
        Type
        Form
        Laboratory
        Best For
        Notes
    
    
        {{yeast.Name}}
        {{yeast.Type}}
        {{yeast.Form}}
        {{yeast.Laboratory}}
        {{yeast.BestFor}}
        {{yeast.Notes}}
    
    
    
        
        
        1/Loading..

Next let’s add a response interceptor to show and hide a loading widget while our query is being made against mongolab.com.

To do this we’ll add a configuration item to our app.js file that will define the response interceptor.

app.config(['$httpProvider', function ($httpProvider) {
    var $http,
        interceptor = ['$q', '$injector', function ($q, $injector) {
            var error;

            function success(response) {
                // get $http via $injector because of circular dependency problem
                $http = $http || $injector.get('$http');
                if($http.pendingRequests.length < 1) {
                    $('#loadingWidget').hide();
                }
                return response;
            }

            function error(response) {
                // get $http via $injector because of circular dependency problem
                $http = $http || $injector.get('$http');
                if($http.pendingRequests.length < 1) {
                    $('#loadingWidget').hide();
                }
                return $q.reject(response);
            }

            return function (promise) {
                $('#loadingWidget').show();
                return promise.then(success, error);
            }
        }];

    $httpProvider.responseInterceptors.push(interceptor);
}]);

The interceptor will be called prior to any application code, so we need to provide functions to intercept the success and error callbacks along with a function that is used to insert our success and error functions into the call hierarchy of the promise returned from the call to $http.

We also need to push our interceptor onto the array of response interceptors maintained by the $httpProvider so each call to the $http service calls our code.

Both the success and error functions are very similar, each one gets the $http service via the $injector service to avoid circular dependencies and then checks to see if the number of pending requests is less than one, if so the code hides the loadingWidget element. The Success method then returns the response and the Error method calls reject with the response to indicate the call failed.

The third method shows the loadingWidget and returns the promise with the Success and Error methods inserted into the response chain.

Now every time a call to the $http service is made our interceptor will be called and will display the loadingWidget and hide it accordingly.

Below is the full code of our app.js file:

'use strict';

// Declare app level module which depends on filters, and services
var app = angular.module('myApp', ['mongolabResourceHttp', 'data.services', ]);

app.config(['$httpProvider', function ($httpProvider) {
    var $http,
        interceptor = ['$q', '$injector', function ($q, $injector) {
            var error;

            function success(response) {
                // get $http via $injector because of circular dependency problem
                $http = $http || $injector.get('$http');
                if($http.pendingRequests.length < 1) {
                    $('#loadingWidget').hide();
                }
                return response;
            }

            function error(response) {
                // get $http via $injector because of circular dependency problem
                $http = $http || $injector.get('$http');
                if($http.pendingRequests.length < 1) {
                    $('#loadingWidget').hide();
                }
                return $q.reject(response);
            }

            return function (promise) {
                $('#loadingWidget').show();
                return promise.then(success, error);
            }
        }];

    $httpProvider.responseInterceptors.push(interceptor);
}]);

app.filter('startFrom', function () {
        return function (input, start) {
            start = +start; //parse to int
            return input.slice(start);
        }
    });

function myController($scope, YeastResource) {
    $scope.yeasts = [];
    $scope.currentPage = 0;
    $scope.pageSize = 10;

    $scope.numberOfPages = function () {
        return Math.ceil($scope.yeasts.length / $scope.pageSize);
    };

    $scope.init = function() {
        YeastResource.query({}, {sort: {Type: 1, Name: 1}}).then(function(yeast){
            $scope.yeasts = yeast;
        });
    };

    $scope.init();
}

The Wrap Up

This article shows a simple way to use response interceptors to display and hide a loading widget each time the $http service requests data from a server. It also showed how you can plug your code into the $http service pipeline to provide cross cutting functionality for your AngularJS Apps. To learn more about response interceptors check out the AngularJS $http service API documentation at http://docs.angularjs.org/api/ng.$http

Hopefully, this article helps you to see some of the extensibility points provided by the AngularJS library and helps you think of ways you can code for cross cutting concerns using such extension points.

Code for this example can be found on GitHub at https://github.com/lavinjj/angularjs-spinner

As always, drop me a comment on other AngularJS topics you’d like to see more tutorials on.

Edit: I have provided an updated version of the above example that works better. Please see my new post Using Response Interceptors to Show and Hide a Loading Widget: Redux

Mocking Promises in Unit Tests

Jim Lavin — Fri, 28 Dec 2012 18:45:40 +0000

If you’ve spent some time writing services in AngularJS that front-end Web APIs, you have probably used the $http service. One of the prevalent code patterns that tends to develop involves calling the .then() method on the promise that is returned from the various $http methods. This in effect waits to execute code until the asynchronous request returns and the promise is resolved.

The more complicated the Web API you are interacting with, the more your controller code tends to end up with several bits of code as shown below:

    user.requestCurrentUser().then(function() {
        $scope.currentUser = user.getCurrentUser();
    });

Testing this code can be a bit problemsome for newcomers to AngularJS. This article shows a simple way to mock your services to provide similar functionality so you can unit test your controllers that contain these type of code patterns.

A Simple Service that uses $http

To demonstrate how to test a controller that contains the above code pattern, we first need to create a simple service which uses the $http service and returns the promise from the $http() method.

Below is a simple service that provides an array which holds the returned data and a single method requestPeople which requests the data from the server, returns a promise and then updates the array with the returned data once the request completes:

    angular.module('people.service', []).
        factory('people', ['$http', function($http) {
            var people = {
                peopleStore = [],

                requestPeople: function() {
                    var url = '/data/people.json';

                    return $http.get(url).success(function(data) {
                        peopleStore = data;
                    }).error(function() {
                        peopleStore = [];
                    });
                }
            };

            return people;
        }]);

We will next create a simple app and controller that will use the service.

    angular.module('sampleApp', ['people.service']).
        config(['$routeProvider', function($routeProvider) {
            $routeProvider.
                when('/', {templateUrl:'partials/peoplelist.html', controller:PeopleListController);
        }]);


    function PeopleListController($scope, people) {
        $scope.peopleList = [];

        $scope.init = function() {
            people.requestPeople().then(function() {
                $scope.peopleList = people.peopleStore;
            });
        };
    }

The controller’s init method calls the requestPeople() method of the service and chains a call to the then() method of the returned promise. Once the promise is resolved, the controller populates the peopeList in it’s scope with the data stored in the service.

And below is the contents of the peoplelist.html file, which displays the people using a ng-repeat:

    
        
            People List
        
        
            
                Name
                Email
                Bio

Mocking Out the Service

Now that we have our code, let’s write some unit tests for the controller.

    describe('People List Controller', function() {
        var scope;
        var peopleService;
        var controller;
        var q;
        var deferred;

        // define the mock people service
        beforeEach(function() {
            peopleService = {
                peopleStore = [{FirstName:"Jim", LastName:"Lavin", Email:"jlavin@jimlavin.net", Bio:"Creator and Host of Coding Smackdown TV"}],

                requestPeople: function() {
                    deferred = q.defer();
                    return deferred.promise;
                }
            };
        });

        // inject the required services and instantiate the controller
        beforeEach(inject(function($rootScope, $controller, $q) {
            scope = $rootScope.$new();
            q = $q;
            controller = $controller(PeopleListController, { $scope:scope, people: peopleService });
        }));

        it('should call requestPeople on the people service when init is called' function() {
            spyOn(peopleService, 'requestPeople').andCallThrough();

            scope.init();

            deferred.resolve();

            scope.$root.$digest();

            expect(peopleService.requestPeople).toHaveBeenCalled();
        });

        it('should populate the peopleList when init is called' function() {
            scope.init();

            deferred.resolve();

            scope.$root.$digest();

            expect(scope.peopleList).not.toBe([]);
        });
    });

Although the unit test may seem to be a bit complicated it is rather straight forward.

Initially, we create variables to hold the scope, mock service, a reference to the $q service and a reference of the deferred object created when we call q.defer() in our mock service.

We need to hold on to a reference to the $q service from AngularJS, so that we can call it when ever the requestPeople method of our mock service is called.

We’ll also need to hold on to the deferred object created by the call to q.defer() so we can resolve the promise, which in turn will execute the then() clause in our controller’s code.

Next, we define our mock service in a beforeEach() call so that each time a test is executed we have a clean version of our mock service.

Our mock service is pretty simple. First we make sure that at least each of the properites and methods the controller will access is defined, in this case that would be peopleStore and requestPeople. We then pre-populate the peopleStore with some default data. Finally, we mock out the requestPeople method by creating a deferred object, store the deferred object off and return the promise.

Next we make another call to beforeEach() that injects the services we need from AngularJS, creates the scope for the controller, stores off the $q service so our mock service can call it and then we finally instantiate the PeopleListController passing in the scope and our mock service.

Now we can go about creating our unit test scenarios.

In the first scenario we’ll check to see if the init method of the controller calls the requestPeople method of the people service. To do this we’ll use Jasmine’s spyOn() method which intercepts the call to the requestPeople method and tracks how many times the method is called. We also need to tell Jasmine what to do after it intercepts the call, we can either have it return a value, call a different function or have it call through to the original implementation. In our case we’ll just have it call through to the original implementation of our mock service.

Next we’ll call the init method on the controller, which should invoke our mock service that in turns creates the deferred object and stores it off and returns the promise to the controller which then waits for the promise to be resolved.

We then resolve the promise by calling deferred.resolve() and since we are outside the AngularJS world we have to call digest() on the scope’s root to have AngularJS invoke the then() clause in our controller. Once this happens the code in the then() clause of our controller will be executed and we can execute our assertions to make sure the code performed as we expected it to, in this case we check to see if the the requestPeople method of the service was called.

In the second scenario, we want to make sure that the then() clause was called and that the controller populated the peopleList on it’s scope with the data from the service. This is done in a similar manner, but since we do not care if the requestPeople method is called, we leave out the call to spyOn() and just call the controller’s init method, resolve the promise and call digest on the root scope so the then() clause is executed. Finally, we check to see that the peopleList in the controller’s scope is populated with the test data.

You could use the same scenario to handle reject processing as well by calling deferred.reject() instead of deferred.resolve().

Below is a jsFiddle that has a working example of the code above:

The Wrap Up

So in this article, I covered how to build a simple service that uses the $http service from AngularJS; how to use a promise returned from the $http service to wait until the asynchronous call completes by using the then() method of the promise, as well as how to write a mock service that returns promises so you can unit test your code.

Hopefully, this article will help you to easily write unit tests for your controllers which contain code that uses promises and get you over some of the hurdles of learning a new framework.

As always, drop me a comment on other AngularJS topics you’d like to see more tutorials on.

What Led Me to AngularJS

Jim Lavin — Wed, 19 Dec 2012 22:10:28 +0000

I am sure many of you reading this come from an ASP.NET background or are familiar with how ASP.NET web apps work with the constant post back to the server to update data, process it and redirect the user to the next step of the process. It has worked for the past 10 years and it has worked well. But, there are better ways to interact with the server and update the user.

The growth of JavaScript, jQuery and frameworks such as Backbone, Knockout, and Ember have done an enormous amount for improving client side interaction and asynchronous communications with the business logic back-end.

That is where the app I’m maintaining is, we use ASP.NET REST based services with jQuery to manage user interaction and communicate with the back end. It works and its performance is OK, but it’s not great and it really doesn’t take advantage of today’s browser capabilities.

As I started to research the latest frameworks appearing on the scene I realized, that more of our client side logic could be included in a Single Page Application giving an even better client experience. So, we slowly started migrating logic from the server-side ASP.NET pages to the client using Knockout and ASP.NET MVC into a quasi-Single Page Application.

We practiced the Model-View-Controller partitioning of concerns and we ended up with a faster, nicer and richer client side experience, but the more code I wrote, the more I noticed that I was repeating code and HTML all over the place. I was also adding additional code to take JSON objects and convert them into model objects the framework could bind to and manage.

Then one day as I explained our app to a new developer, I realized that two-thirds of our code was there to just interact with the framework. Only a third of the code had anything to do with our actual business logic. I knew there had to be a better way.

That’s when I came across a post on Google+ about AngularJS and I spent some time checking it out, it looked promising, and it had many of the features I was needing without having to bring in third party libraries from all over the place.

Right from the start the AngularJS examples show you how to bind your model data into your HTML content with very simple markup. There’s no need for special objects to handle the data binding for you and I was able to do away with all of the code to translate our data into objects the framework could interact with, AngularJS just used the data returned from our services without issue.

AngularJS also provides a way to extend your HTML markup through Directives and Filters. With Directives you can create your own HTML tags that binds to your data and outputs markup that automatically updates whenever the data changes.

Filters provide you a way to transform data into whatever subset of data or format you might need. The framework comes standard with filters for currency, data, lowercase, number plus several more to help order your data or break it into subsets based on an easy JSON based syntax.

The Route Provider in AngularJS provides routing and deep linking support important for Single Page Apps. You can define your routes, the templates to display and which controllers to load. Then by using the ng-view directive on your page, your templates will be loaded and displayed automatically without you having to write a single line of code.

AngularJS also includes a whole host of functionality for Form Validation. You can declare validation rules in your form’s mark up and then query the form in your controller to ensure your rules are met before continuing on with your logic. Using the data-binding you can dynamically display errors as they occur giving your end user feedback right when they need it.

All throughout the AngularJS Framework the concept of using services to handle cross cutting concerns is evident. There are services to handle exceptions, services to make asynchronous calls to your back-end services, services to interact with the DOM and mock services to help in testing.

As you build controllers or other services, AngularJS provides you with a built in dependency injection mechanism to get the services your code depends upon without a lot of coding and configuration. The dependency injection in AngularJS allows for extensibility, if you need to replace a service with your own service, all you need to do is declare it in your code and your service will be invoked instead of the framework version.

Finally AngularJS was built with testability in mind. AngularJS provides a full mock library to allow you to isolate your code for testing. There is even an entire portion of the framework devoted to end to end testing.

From my experience working with AngularJS over the past couple of months, I think the following words from the AngularJS site sums it all up.

`Write less code, go have beer sooner.`

Localizing Your AngularJS App

Jim Lavin — Sat, 15 Dec 2012 03:39:54 +0000

Overview

If you plan on being in the Web App development business for any amount of time, sooner or later you are going to be faced with building an app that supports multiple languages. When this time comes you’ll be faced with the localization challenge that so many developers before you have faced.

To solve this challenge some developers have built entire localization frameworks and libraries, while others have resorted to re-creating their entire site in the desired language and redirecting users based on their browser culture.

In this article, I’ll show you an easy way to use an AngularJS Service and Filter to pull localized strings from a resource file and populate the page content based on the user’s browser culture.

Architecture

Our solution is going to be based on a simple architecture. We will use localized resource files for each language we want to support. We will also have a default resource file that will be used to fall back to the site’s native language if a given user’s language is not supported.

We will build an AngularJS Service that will be responsible for checking the user’s browser culture and requesting the appropriate resource based on the language. If the resource file does not exist it will request the default resource file and use it.

The service will also provide a lookup method that will return a localized string for a given key from the loaded resource file.
Since the service may not be called directly by a controller or app module we’ll also provide a mechanism for the service to initialize itself, load the appropriate localized resource file and prepare itself to handle requests.

We will also build an AngularJS Filter that can be used in your HTML as a front-end to the localization service. Using the filter will help you keep your code clean and keep you controllers from having to know about the localization service.

To use the filter you can use an expression such as; {{‘_FormControllerTitle_’ | i18n}} if you want to inject the localized string directly into a tag or you can use the ng-bind=’_FormControllerTitle_’ | i18n” method to inject the localized string into an element, when AngluarJS compiles and links the DOM.

Finally let’s talk a bit about how we’ll store the localized data for the service. Since our service will be requesting the resource files once the app in bootstrapped, we need a place to store them. To keep the overall size of the service small I thought it was best not to embed the strings in the service class, but put them in directory off the root of the site named i18n. This follows the same pattern you see with several libraries where the localized resources are in a directory co-located with the module.

The files also have a specific file naming format; resources-locale_xx-yy.js where xx is the language identifier and yy is the country identifier. So resources-locale_en-US.js would mean the file is for English, United States and resources-locale_es_es.js would mean the file is for Spanish, Spain.

There is one more file naming convention we’ll use and that is for the default resource file. For the default file that will be loaded is a language resource file for language does not exist on your system it will be named resources-locale_default.js

The format of the language resource file is simple. Since we only really need a few pieces of information I’ve kept it to key, value and description. This way if you need to hand the file off to someone for translation they’ll have a general description of what the test is for.

This format will also help other developers on the project. When they are getting ready to add a new string resource they’ll be able to search the file to see if maybe there is already a string they can use. This comes in real handy for buttons, table headers, etc.

Below is an example of the file format:

[
    {
        "key":"_Greeting_",
        "value":"Site localization example using the resource localization service",
        "description":"Home page greeting text"
    },
    {
        "key":"_HomeTitle_",
        "value":"Resource Localization Service",
        "description":"Home page title text"
    }
]

Building the Service

So now that we have covered the architecture of our solution, let’s get to writing some code.

Let’s start by creating a new JavaScript file and calling it localize.js

Then let’s add the skeleton to define both the module and the service.

'use strict';

/*
 * An AngularJS Localization Service
 *
 * Written by Jim Lavin
 * http://codingsmackdown.tv
 *
 */

angular.module('localization', []).
    factory('localize', function ($http, $rootScope, $window, $filter) {

    });

We start off by calling angular.module which will define our module that we’ll name ‘localization’. Since our module does not depend on anything but the built in AngularJS service we will pass in an empty array to the method as well.

Then we chain a factory method off of the module to define our service which we’ll call ‘localize’ and add a function that will be used to define our service. You can see this in the code above.

Next we need to add the services the service is dependent on so Angular can inject them. This will be using the following services:

$http – This will be used to retrieve the localized resource file from the web server.
$rootScope – This will be used to broadcast a message once the localized resource has been retrieved and loaded by the system. I’m using this is in case a controller or other service might use the service directly and needs to know when the service is ready.
$window – This will be used to find out the culture of the user’s browser, which we’ll use to request the appropriate resource file from the web server. There is an Angular service called $locale which should provide this information, but currently it seems to be hard coded to en-us from what I’ve experimented with and from what I’ve read over at Google Groups. If anyone has gotten this to work, please leave me a comment so I can revise the code to use the proper service.
$filter – This will be used to filter the dictionary array and return back only those resource objects that has the desired key the user is looking for.

To add our dependencies and to ensure that any minification doesn’t muck them up, we are going to use the [] around our function to tell Angular what services we depend on. The revised code is below:

'use strict';

/*
 * An AngularJS Localization Service
 *
 * Written by Jim Lavin
 * http://codingsmackdown.tv
 *
 */

angular.module('localization', []).
    factory('localize', ['$http', '$rootScope', '$window', '$filter', function ($http, $rootScope, $window, $filter) {

    });

As you can see each one of the dependencies are specified as an array of strings with the service definition function last. This way Angular will know what to inject into our service without issue. We then also repeat the dependencies in our function declaration so they are visible to our service.

Now let’s define the service interface. We are going to expose two methods:

initLocalizedResources – Responsible for loading the localized resource file from the server.
getLocalizedString – responsible for returning a localized string based on the given key.

So now our service looks as follows:

'use strict';

/*
 * An AngularJS Localization Service
 *
 * Written by Jim Lavin
 * http://codingsmackdown.tv
 *
 */

angular.module('localization', []).
    factory('localize', ['$http', '$rootScope', '$window', '$filter', function ($http, $rootScope, $window, $filter) {

        initLocalizedResources:function() {

        },

        getLocalizedString:function(key) {

        }
    });

Now that we have defined our interface, let's implement the service and discuss what each function does.

'use strict';

/*
 * An AngularJS Localization Service
 *
 * Written by Jim Lavin
 * http://codingsmackdown.tv
 *
 */

angular.module('localization', []).
    factory('localize', ['$http', '$rootScope', '$window', '$filter', function ($http, $rootScope, $window, $filter) {
    var localize = {
        // use the $window service to get the language of the user's browser
        language:$window.navigator.userLanguage || $window.navigator.language,
        // array to hold the localized resource string entries
        dictionary:[],
        // flag to indicate if the service hs loaded the resource file
        resourceFileLoaded:false,

        successCallback:function (data) {
            // store the returned array in the dictionary
            localize.dictionary = data;
            // set the flag that the resource are loaded
            localize.resourceFileLoaded = true;
            // broadcast that the file has been loaded
            $rootScope.$broadcast('localizeResourcesUpdates');
        },

        initLocalizedResources:function () {
            // build the url to retrieve the localized resource file
            var url = '/i18n/resources-locale_' + localize.language + '.js';
            // request the resource file
            $http({ method:"GET", url:url, cache:false }).success(localize.successCallback).error(function () {
                // the request failed set the url to the default resource file
                var url = '/i18n/resources-locale_default.js';
                // request the default resource file
                $http({ method:"GET", url:url, cache:false }).success(localize.successCallback);
            });
        },

        getLocalizedString:function (value) {
            // default the result to an empty string
            var result = '';
            // check to see if the resource file has been loaded
            if (!localize.resourceFileLoaded) {
                // call the init method
                localize.initLocalizedResources();
                // set the flag to keep from looping in init
                localize.resourceFileLoaded = true;
                // return the empty string
                return result;
            }
            // amke sure the dictionary has valid data
            if ((localize.dictionary !== []) && (localize.dictionary.length > 0)) {
                // use the filter service to only return those entries which match the value
                // and only take the first result
                var entry = $filter('filter')(localize.dictionary, {key:value})[0];
                // check to make sure we have a valid entry
                if ((entry !== null) && (entry != undefined)) {
                    // set the result
                    result = entry.value;
                }
            }
            // return the value to the call
            return result;
        }
    };
    // return the local instance when called
    return localize;
} ]);

To begin with we declare the local variable localize that will be used as a wrapper for our object. We then need a couple of internal variables so we can store local data the service will use.

language – stores the user’s browser language. We will use this value to build the Url in order to request the appropriate localized resource file.
dictionary – stores the localized resource file.
resourceFileLoaded – indicates if the service has loaded the localized resource file, and is used to self init the service if needed.

I’ve also added a callback function that will be used when our http request succeeds. It will take the data retrieved from the web server and store it in the dictionary, update the init flag and broadcast that the localized resource file has been loaded.

The initLocalizedResources function takes the language we got from the user’s browser and creates a Url we can use to request the localized resource file from the web server. We also provide an error callback function should the request fail. By default we’ll assume there is no localized resource file and will request the default resource file.

The getLocalizedString function is called by consumers of the service to get the localized string for a specific key. By default we’ll return an empty string if the dictionary has not been loaded or there is no entry in the dictionary for the key.

Next, the function checks to see if the service has been initialized, if not it calls the initLocalizedResources function and then sets the init flag so we do not go into a continuous loop.

Finally, the function checks the dictionary for the key using the $filter service to retrieve the objects that match the filter parameters of key = value and then we further reduce the returned values by only taking the first item in the array. If we have a valid entry then the function returns the value and processing is complete.

Building the Filter

Now that we’ve finished with the service, let’s build the filter so we can easily use the service in our HTML.

First we’ll start off by chaining the filter definition off the factory definition by appending .filter() to the end of method. We’ll then define our filter by setting it’s name to ‘i18n’ along with the filter definition function that will be used to return the filter when called.

Next since the filter will be making calls to the localization service on behalf of our app we need to add the ‘localize’ service to our dependency list and ensure we include it in the filter definition function declaration.

The rest of the code for the filter is pretty simple since all we are doing is passing through the request to the localize service. so we are just going to return a function that calls the localize service with the given input.

That pretty much all we have to do. The final code for both the service and filter is given below:

'use strict';

/*
 * An AngularJS Localization Service
 *
 * Written by Jim Lavin
 * http://codingsmackdown.tv
 *
 */

angular.module('localization', []).
    factory('localize', ['$http', '$rootScope', '$window', '$filter', function ($http, $rootScope, $window, $filter) {
    var localize = {
        // use the $window service to get the language of the user's browser
        language:$window.navigator.userLanguage || $window.navigator.language,
        // array to hold the localized resource string entries
        dictionary:[],
        // flag to indicate if the service hs loaded the resource file
        resourceFileLoaded:false,

        successCallback:function (data) {
            // store the returned array in the dictionary
            localize.dictionary = data;
            // set the flag that the resource are loaded
            localize.resourceFileLoaded = true;
            // broadcast that the file has been loaded
            $rootScope.$broadcast('localizeResourcesUpdates');
        },

        initLocalizedResources:function () {
            // build the url to retrieve the localized resource file
            var url = '/i18n/resources-locale_' + localize.language + '.js';
            // request the resource file
            $http({ method:"GET", url:url, cache:false }).success(localize.successCallback).error(function () {
                // the request failed set the url to the default resource file
                var url = '/i18n/resources-locale_default.js';http://codingsmackdown.tv/?p=104&preview=true
                // request the default resource file
                $http({ method:"GET", url:url, cache:false }).success(localize.successCallback);
            });
        },

        getLocalizedString:function (value) {
            // default the result to an empty string
            var result = '';
            // check to see if the resource file has been loaded
            if (!localize.resourceFileLoaded) {
                // call the init method
                localize.initLocalizedResources();
                // set the flag to keep from looping in init
                localize.resourceFileLoaded = true;
                // return the empty string
                return result;
            }
            // make sure the dictionary has valid data
            if ((localize.dictionary !== []) && (localize.dictionary.length > 0)) {
                // use the filter service to only return those entries which match the value
                // and only take the first result
                var entry = $filter('filter')(localize.dictionary, {key:value})[0];
                // check to make sure we have a valid entry
                if ((entry !== null) && (entry != undefined)) {
                    // set the result
                    result = entry.value;
                }
            }
            // return the value to the call
            return result;
        }
    };
    // return the local instance when called
    return localize;
} ]).
    filter('i18n', ['localize', function (localize) {
    return function (input) {
        return localize.getLocalizedString(input);
    };
}]);

A Sample App

So now we have a service and a filter, but we need to show how to use both in an app. So included in the project on GitHub is a sample app that uses the service and filter to populate all of the text displayed in both the index.html and two partials.

First we need to add a dependency to our app so, it will load our service and filter at bootstrap time. so we are going to add the name of the module, ‘localization’, into the app’s dependency list as shown in the code below:

angular.module('localizeApp', ['localization']).
    config(['$routeProvider', function ($routeProvider) {
    $routeProvider.
        when('/', {templateUrl:'partials/home.html', controller:HomeController}).
        when('/edit/:index', {templateUrl:'partials/form.html', controller:EditPersonController}).
        when('/new', {templateUrl:'partials/form.html', controller:NewPersonController}).
        otherwise({redirectTo:'/'});
}]);

Now when ever we need to pull a localized string, we can use the filter. There are two ways you can call the filter, inside of a ng-bind method and by enclosing it inside of {{ }}. Below is a example of how to use each:

Remember, you must use the {{ }} notation when you are not passing the value to a angular directive, if you don’t then the compiler will not handle the expression correctly and you’ll end up with text like ‘_BioLabel_’ | i18n all over your web page.

Below are two examples of the filter in use, the first is using the default of U.S. English and the second is when you change Chrome’s language to display Spanish. Since I don’t speak Spanish, I’ve converted the resource strings into Pig Latin so you can see the difference.

The Wrap Up

So in this article, I covered how to build a simple service and filter that can be used to localize you application based on the user’s language settings. By using a filter to front-end the service you have separated the concerns and provided a cross cutting service that can be used by your app without any of the controllers needing to deal with the service.

I also covered the basics of defining a service and a filter, injecting dependencies into both the service and filter, as well as how to use a filter in your HTML markup and directives.

Although this service handles a good share of the localization challenge for you a more advanced version would take advantage of Angular’s ng-pluralize directive and $locale service to help handle the harder semantics of language pluralization and gender. Hopefully it will get you started on the way to localizing you AngularJS apps and by following tutorial you’ve learned a little bit more about AngularJS.

Complete source for this tutorial can be found on GitHub at https://github.com/lavinjj/angularjs-localizationservice

I hope this tutorial helps you get started writing AngularJS Services and Filters. Drop me a comment on other AngularJS topics you’d like to see more tutorials on.

Creating a Simple AngularJS Directive

Jim Lavin — Fri, 14 Dec 2012 07:06:03 +0000

One of the core features of AngularJS is the ability to extend the HTML Syntax with directives. Directives allow you to componentize segments of HTML into a single tag that can be re-used throughout your AngularJS app. So instead of repeating the following HTML all over your code:

    
        {{adjunct.Name}}
        {{adjunct.Type}}
        {{adjunct.Use}}
        {{adjunct.Time}}
        {{adjunct.Amount}}
        {{adjunct.UseFor}}
        {{adjunct.Notes}}

With a directive you can use the following HTML:

Now anywhere where you would use the above HTML, you can use the directive instead and be consistent across you entire site. This also saves you time when changes are required. If the amount of data that needs to be displayed changes you only need to update the directive and your done. You don’t have to hunt around your HTML files looking for every occurrence to change.

Directives allow you to not only specify what data from your app to bind to, but they can also handle the work of transforming the data into different formats, removing that responsibility from your controller, helping you to keep to the single responsibility principle.

If you apply this simple principle on bigger scales, directives can be used to build rich components that bind to your app’s data and reduce the amount of HTML you need to create across your entire site.

In this article, I’m going to show you how to write a simple directive that generates an image tag with a user’s avatar from the Gravatar site, http://en.gravatar.com/

The Gravatar Image Directive Overview

Gravatar allows you to upload an image and link it to your email address, so it can be used by the various social networking and forum sites on the web.

If you head over to the Gravatar developer documentation on how to request images, http://en.gravatar.com/site/implement/images/. You’ll see that you need to create a md5 hash of the user’s email and then append that to a Url along with parameters for size, rating, and default image.

So the Url for my email address jlavin@jimlavin.net gets converted into the following image tag:

So we are going to write a directive that will take an email address and inject the resulting image tag into the page. When we are complete the directive will look something like this:

Defining the Directive

To start out we’ll need to create a new JavaScript file and call it gravatardirective.js and we’ll start with the basic skeleton for a directive.

1: 'use strict';
2:
3: /*
4: * An Simple AngularJS Gravatar Directive
5: *
6: * Written by Jim Lavin
7: * http://codingsmackdown.tv
8: *
9: */
10:
11: angular.module('ui-gravatar', []).
12:     directive('gravatarImage', function () {
13:         return {
14:             restrict:"EAC",
15:             link:function (scope, elm, attrs) {
16:         }};
17:     });

So to define a directive we need to create an Angular module, provide a namespace, ‘ui-gravatar’, and include any dependencies the directive might require. In our case there are no dependencies so we can send in an empty array as seen on line 11.

Next we are going to use chaining to declare our directive by appending .directive after the module declaration.

In Angular, you can call your directive in several different ways. You can call it by using an element, an attribute, a class or as a comment. The following are all valid ways to call a directive:

Angular will then replace the dash and convert the name into Camel case format, so we need to ensure we name our directive using Camel case, gravatarImage. so while Angular is parsing the DOM it can find our directive. You can see this on line 12 of the code above.

Next we provide a function that will return a Directive Definition Object that tells Angular about our directive. You can see the declaration starting on line 12 continuing through to line 17.

By default Angular will restrict calling directives to attributes only. To change this you can declare a restrict property and return the ways you want the directive to be called. I do this on line 14 by returning “EAC”, which means you should be able to call directive using an element, attribute or class.

Next, we are going to declare a link function that will be used to update the DOM as the data we are binding to changes. You can see the declaration on line 15.

The link function can take up to 4 parameters; the scope to be used by the directive, the instance element the directive will be modifying, the element attributes and an optional controller instance if a directive on the element has defined one.

Simple Data Binding

So we are going to need an email address in order to formulate the Url to retrieve an avatar image. To do this we can use simple data binding and send the data value or object we want to bind to as part of the directive’s declaration as shown below:

To access the data, we’ll need to use the attributes instance to setup a watch on the data and then as we are notified of changes, we can update the DOM accordingly. The reason we have to setup a watch is because initially the data will come through as undefined as Angular compiles the DOM, only when it runs the linker to bind the data to the DOM will a value be present in our scope.

To do this we will need to modify our directive to add a watch function which will be called each time the value is updated.

1: 'use strict';
2:
3: /*
4: * An Simple AngularJS Gravatar Directive
5: *
6: * Written by Jim Lavin
7: * http://codingsmackdown.tv
8: *
9: */
10:
11: angular.module('ui-gravatar', []).
12:     directive('gravatarImage', function () {
13:         return {
14:             restrict:"EAC",
15:             link:function (scope, elm, attrs) {
16:                 // by default the values will come in as undefined so we need to setup a
17:                 // watch to notify us when the value changes
18:                 scope.$watch(attrs.gravatarImage, function (value) {
19:                     elm.text(value);
20:             });
21:         }};
22:     });

Starting on line 18 we declare the watch function and each time the data updates, we set the element’s text to the updated value.

One thing to notice is we are supplying the value supplied in the attributes instance to the watch, not the scope value, since the scope value is undefined when the link function is called and the watch will never be triggered.

To finish our first version of the directive let’s create the Url and append an image tag to the element so it will retrieve the Gravatar image.

1: 'use strict';
2:
3: /*
4: * An Simple AngularJS Gravatar Directive
5: *
6: * Written by Jim Lavin
7: * http://codingsmackdown.tv
8: *
9: */
10:
11: angular.module('ui-gravatar', []).
12:     directive('gravatarImage', function () {
13:         return {
14:             restrict:"EAC",
15:             link:function (scope, elm, attrs) {
16:                 // by default the values will come in as undefined so we need to setup a
17:                 // watch to notify us when the value changes
18:                 scope.$watch(attrs.gravatarImage, function (value) {
19:                     // let's do nothing if the value comes in empty, null or undefined
20:                     if ((value !== null) && (value !== undefined) && (value !== '')) {
21:                         // convert the value to lower case and then to a md5 hash
22:                         var hash = md5(value.toLowerCase());
23:                         // construct the tag to insert into the element
24:                         var tag = ''
25:                         // insert the tag into the element
26:                         elm.append(tag);
27:                     }
28:             });
29:         }};
30:     });

Now, when the watch function is called, I evaluate the value and if it is not empty, null or undefined, I force it to lower case, create a md5 hash of the email, format the image tag and append it to the element. Which gives us the following result when we use it an app.

Adding Configuration Attributes

Now, our directive works great but what if you want to use different sizes of the avatar at different places in your app or maybe you want to only allow PG rated avatars since you have people of all ages using your app and you don’t want to offend anyone.

We could create various version of the directive and name them gravatar-image-small or gravatar-image-pg, but that won’t do. We need to provide those values when we call the directive.

To do this we’ll need to send additional configuration elements to the directive so we can dynamically tell Gravatar what we need.

So, let’s change our directive to look for specific attributes on the element so we can specify the size, rating and default avatar.

We are going to look for three attributes in our directive; size, rating and default. Now we can do this many ways but the simplest is to use data-xxx attributes in the element and then we can read the values using attrs.xxx. This is because Angular will strip off “data-“ from any attributes as is creates the attributes instance, which make it easy for us.

so now when we call our directive we can use the following HTML:

The code for directive now includes the logic to parse the attributes use their values or supply defaults if they are missing. I’ve also moved the data we are binding to it’s own attribute data-email, which will make things easier if we decide to use the directive as an element.

Below is the new directive, coded to retrieve the attributes and format the Url accordingly:

1: 'use strict';
2:
3: /*
4: * An Simple AngularJS Gravatar Directive
5: *
6: * Written by Jim Lavin
7: * http://codingsmackdown.tv
8: *
9: */
10:
11: angular.module('ui-gravatar', []).
12:     directive('gravatarImage', function () {
13:         return {
14:             restrict:"EAC",
15:             link:function (scope, elm, attrs) {
16:                 // by default the values will come in as undefined so we need to setup a
17:                 // watch to notify us when the value changes
18:                 scope.$watch(attrs.email, function (value) {
19:                     // let's do nothing if the value comes in empty, null or undefined
20:                     if ((value !== null) && (value !== undefined) && (value !== '')) {
21:                         // convert the value to lower case and then to a md5 hash
22:                         var hash = md5(value.toLowerCase());
23:                         // parse the size attribute
24:                         var size = attrs.size;
25:                         // default to 40 pixels if not set
26:                         if((size=== null) || (size == undefined) || (size == '')){
27:                             size = 40;
28:                         }
29:                         // parse the ratings attribute
30:                         var rating = attrs.rating;
31:                         // default to pg if not set
32:                         if((rating === null) || (rating === undefined)|| (rating === '')){
33:                             rating = 'pg';
34:                         }
35:                         // parse the default image url
36:                         var defaultUrl = attrs.default;
37:                         if((defaultUrl === null) || (defaultUrl === undefined)|| (defaultUrl === '')) {
38:                             defaultUrl = '404';
39:                         }
40:                         // construct the tag to insert into the element
41:                         var tag = ''
42:                         // insert the tag into the element
43:                         elm.append(tag);
44:                     }
45:                 });
46:             }};
47:         });

Now, starting at line 24 we parse the size attribute and if it has a value we use it, otherwise we use a default value.

We do the same thing for the rating and default attributes starting on lines 30 and 36.

Line 41 now reflects the tag with all of the various configurations supplied. You might also notice in our watch statement that we changed the watch value from attrs.gravatarImage to attrs.email since we are now passing the data binding value in using the data-email attribute.

Wrap Up

Writing directives in AngularJS can be hard, but by starting out simple, you will learn how things work in AngularJS and as you experiment more you will be able to build very complex components that can extend HTML, which will save you time and decrease the amount of HTML your team needs to write.

The source code for this article, along with a sample app can be found on Github at https://github.com/lavinjj/angularjs-gravatardirective

I hope this tutorial helps you get started writing AngularJS Directives. Drop me a comment on other AngularJS topics you’d like to see more tutorials on.