Friday, November 28, 2014

The Top 5 Mistakes AngularJS Developers Make Part 2: Abusing $watch

This is the second part in a five-part series that covers common AngularJS mistakes. To recap, the top five mistakes I see people make are:

  1. Heavy reliance on $scope (not using controller as) 
  2. Abusing $watch
  3. Overusing $broadcast and $emit
  4. Hacking the DOM
  5. Failing to Test

When I posted the first article, one comment suggested that using controller as is fine for smaller controllers but large, complex controllers with dependencies might not work out as well. I disagree, and you’ll see why later in this series. I’ll get more into dependencies in the next post, but for now I’d like to take the concept of $scope one step further to discuss the second mistake.

Abusing $watch

There are plenty of reasons why you want to watch for changes to certain properties and respond. It is quite common on a complex form to render information or process an algorithm based on a selection. To keep the example simple I created a contrived scenario, but bear with me because I think you’ll see how it extrapolates to common, real world examples.

Let’s assume you are rendering a drop-down that enables the user to select gender. In a real world example you might have some specific algorithms to run or text to display based on the selection, but for our example we’ll simply display some different text based on the gender they choose.

<div ng-app="myApp">
    <div ng-controller="badCtrl">
        <select ng-options="g as g for g in genders"
                ng-model="selectedGender"></select>
        It's a {{genderText}}!
    </div>
</
div>

The script simply keeps track of two lists and watches for changes. If the gender changes, a property is updated to show the corresponding label.

(function (app) {
 
    var genders = ['Male', 'Female'],
        labels = ['boy', 'girl'];
    function BadController($scope) {
        $scope.genders = genders;
        $scope.selectedGender = genders[0];
        $scope.$watch('selectedGender', function () {
            $scope.genderText =
                $scope.selectedGender === genders[0]
                ? labels[0] : labels[1];
        });
    }

    app.controller('badCtrl', BadController);
})(angular.module('myApp', []));

I’ve had to build the controller with $scope because I have to $watch for the changes and the only way to $watch is by having a reference to $scope, right? Perhaps. When we run this example the watch tree looks like this:

watchtree1

For performance the majority of time is spent with the model watch, and the least amount of time on the watch for the property selectedGender that we added explicitly. That time can grow, however, and add complexity as I’ll get to in a moment. Is it even possible to “watch” for a change using controller as? Here is some new HTML:

<div ng-app="myApp">
    <div ng-controller="goodCtrl as ctrl">
        <select ng-options="g as g for g in ctrl.genders"
                ng-model="ctrl.selectedGender"></select>
        It's a {{ctrl.genderText}}!
    </div>
</
div>

Here is the watch tree when running the new example:

watchtree2

As you can see, there is one less watch. Performance-wise the existing watches are about the same but we’ve completely eliminated the overhead of the explicit watch. Although it was only milliseconds on a desktop browser, if we extrapolate to a complex controller with dozens of watches you can imagine it adds up quickly and will be noticeable on a mobile device.

In this case, the combined watches on the bad controller averaged about 5.264ms of overhead, while the combined watches on the good controller averaged about 4.312ms of overhead. Doesn’t seem like much? The second approach averaged a 20% improvement for just one property. Consider controllers with multiple watches and eventually you will see tangible differences in the response time of your application. This is also testing in a browser; the overhead becomes amplified when you are running Angular on a mobile device.

Speaking of mobile: not only does this approach improve performance, but it also reduces memory overhead because AngularJS doesn’t have to keep track of as many references. So how did I achieve this? Here is the code for the second example:

(function (app) {
 
    var genders = ['Male', 'Female'],
        labels = ['boy', 'girl']
    function GoodController() {
        this.genders = genders;
        this._selectedGender = genders[0];
        this.genderText = labels[0];
    }
    Object.defineProperty(GoodController.prototype,
        "selectedGender", {
        enumerable: true,
        configurable: false,
        get: function () {
            return this._selectedGender;
        },
        set: function (val) {
            if (val !== this._selectedGender) {
                this._selectedGender = val;
                this.genderText =
                    val === this.genders[0]
                    ? labels[0] : labels[1];
            }
        }
    });
    app.controller('goodCtrl', GoodController);
})(angular.module('myApp', []));

Instead of using a $watch I’m taking advantage of properties that were introduced in ECMAScript 5. The property manages the selection and when the selection changes, updates the corresponding label. The reason this works is because of the way Angular handles data-binding. Angular operates on a digest loop. When the model is mutated (i.e. by the user changing a selection), Angular automatically re-evaluates other properties to determine if the UI needs to be updated. Angular is already doing the work, and when you add a $watch you are simply plugging into the loop so you can react yourself.

The problem is that Angular must now hold a reference to your watch. If the model mutates, Angular will re-evaluate the expression in your watch and call your function if it changes. Of course, because your code might mutate the model further, Angular must then re-evaluate all expressions again to make sure there aren’t further dependent changes. This can exponentially add to the overhead of your application.

On the other hand, using properties makes it simple. When the user mutates the model by changing the gender, Angular will automatically re-evaluate properties like the gender text to see if it needs to update the UI. Because the gender selection updated the property, Angular will recognize the change and refresh the UI. In this approach, you allow Angular to do the work instead of having to plug into the digest loop yourself and add overhead to the entire process.

There are a few more lines of code with this approach, but even that can be simplified tremendously if you use a tool like TypeScript to create the property definitions. It also enables you to build pure JavaScript objects and even test for the updates without involving Angular. That keeps your tests simple and ensures they run quickly with little overhead (i.e. “Given controller when the selected gender changes to male then the gender text should be updated to boy.”)

There is one more advantage. This approach allows Angular to handle the watches, and Angular is great about managing those watches appropriately. If you add the $watch yourself, you are now responsible for de-registering the $watch when it is no longer needed. If you don’t, it will continue to add overhead.

The full source code is available in this jsFiddle of the two controllers running side-by-side.

Keep this technique in mind because I see another practice that adds overhead and doesn’t have to when it comes to communicating between controllers. Have you seen a model where a controller does a $watch and then uses $broadcast or $emit to notify other controllers something has changed? Once again, this approach forces you to depend on the $scope and adds another layer of complexity by relying on the messaging mechanism of $scope to communicate between controllers. In my next post, I’ll show you how to avoid this third common mistake.

signature[1]

Wednesday, November 26, 2014

The Top 5 Mistakes AngularJS Developers Make Part 1: Relying on $scope

Although AngularJS is an extraordinarily popular framework, there is plenty of discussion and controversy over whether or not it truly adds value to projects. Having witnessed its value firsthand as I described in my recent post, Angular from a Different Angle, I believe it can be a powerful tool when used correctly. Voltaire said, “With great power comes great responsibility.” A tool like Angular can be easily abused. This series is designed to help you avoid common traps and pitfalls before they become a problem.

The top five mistakes I see people make are:

  1. Heavy reliance on $scope (not using controller as) 
  2. Abusing $watch
  3. Overusing $broadcast and $emit
  4. Hacking the DOM
  5. Failing to Test

In this series I’ll cover examples of both how these items are abused and my suggested “better practice.” Let’s get started with the first mistake.

Relying on $scope (Not Using Controller As)

The canonical Angular tutorial inevitably introduces controllers and forces them to take on a dependency to $scope, like this:

<div ng-app="myApp">
    <div ng-controller="badCtrl">
        <input placeholder="Type your name" ng-model="name" />
        <button ng-click="greetMe()" ng-disabled="notValid()">Greet Me!</button>
    </div>
</
div>
(function () {
    var app = angular.module('myApp', []);
    function BadController($scope) {
        $scope.notValid = function () {
            var bad = !!$scope.name;
            return !bad || $scope.name.length < 1;
        };
        $scope.greetMe = function () {
            if ($scope.notValid()) {
                return;
            }
            alert('Hello, ' + $scope.name);
            $scope.name = '';
        };
    }

    app.controller('badCtrl', BadController);
    
})();

A controller in Angular is really what I would refer to as a “view model.” In the diagram below, just replace “XAML” with “HTML” to visualize the relationship.

main[1]

A controller in the traditional sense marshals activity between the application model and view but typically does so in a more active fashion. A view model, on the other hand, simply exposes properties and functions for data-binding. I like this approach because it allows your view models to simply exist as “state bags” – they may interact with services to grab lists or other items but in the end they just expose it. You can then bind to that data and represent it however you like.

Taking on the dependency to $scope does two things. First, it requires the controller to be aware that it is participating in data-binding when it doesn’t have to. It certainly simplifies things when you can just expose a list as a list and a selected item as a property and test that in isolation without worrying about what the glue looks like. The controller defined earlier really just exists as a proxy with the sole purpose of passing setup onto the $scope. Why take on that extra work?

Second, it complicates the testing story because now you have to ensure that a $scope is created and passed in to do something. The controller really becomes a facade to the $scope so you end up with a lot of code marshalling values between the two.

(queue Dr. Evil voice … “If only there were a way for the controller to BE the $scope…”)

Wait! There is! Using the controller as syntax enables you to treat and test controllers as standalone plain old JavaScript objects (POJOs). Consider this example:

<div ng-controller="goodCtrl as ctrl">
    <input placeholder="Type your name" 
            ng-model="ctrl.name" />
    <button ng-click="ctrl.greetMe()" 
            ng-disabled="ctrl.notValid()">Greet Me! </button>
</
div>
(function () {
    var app = angular.module('myApp', []);
    function GoodController() {
    }
    angular.extend(GoodController.prototype, {
        notValid: function () {
            var bad = !!this.name;
            return !bad || name.length < 1;
        },
        greetMe: function () {
            if (this.notValid()) {
                return;
            }
            alert('Hello, ' + this.name);
            this.name = '';
        }
    });
    app.controller('goodCtrl', GoodController);
})();

Although it uses angular.extend, the controller could just as easily have been defined via the constructor function prototype. This makes it a pure JavaScript object. It has no dependencies, and why should it? We haven’t written a controller complicated enough to warrant dependencies yet. $scope just muddies the waters.

I made a fiddle to demonstrate the $scope vs. “controller as” approaches side-by-side.

In fact, if you are taking a test-driven development (TDD) approach, you don’t even have to worry about Angular at first. You can create your controller as a POJO and write plenty of tests, then introduce it as a controller to the application. This provides more flexibility and less reliance on what version is running or even what the UI looks like.

An added bonus is that you can alias the controller in your code so that you either segregate it per section by name, or give it a common name like ctrl to make it easier to build boilerplate HTML code. This syntax is also available from your routes.

Of course, the first response I typically get when I mention not using $scope is “What about watches?” My reply is, “What about them?” Angular does a lot of watching for you, so the real question is whether you really need those watches, or if there is a better way. There may be, and that’s what I’ll cover in the next part of this series.

signature[1]