This post summarizes a talk I gave at the AngularJS Meetup Berlin in October 2014.

Controllers are are a vital but widely misunderstood part of AngularJS. Thousands of clueless articles and very unfortunate examples in the official documentation are helping to spread confusion instead of clarity about the proper use of controllers.

I want to shed some light on the issue and present how we use controllers successfully in the Contentful user interface.

History

To understand controllers and the confusion around them, we need to have a look at their history.

Before Angular 1.0, controllers were just global functions, or functions on the scope, that got executed by either the ngController directive or the router to initialize their part of the scope.

These days, controllers are actually instantiated objects, with the Controller functions being the constructors for these objects, instead of simple initializers for the scope.

What do you want on your scope?

To keep an Angular app maintainable, you should avoid stuffing a lot of properties onto your scope. You don’t want scope properties to provide too much of the input to your functions. Using the scope this way is almost as bad as using global variables: It’s very hard to understand where all these values are coming from and under which circumstances they might change.

So, you try to restrict yourself to two kinds of things on your scope:

  • Model objects
  • Handlers that you bind to events on your DOM nodes, allowing users to perform actions inside your app.

Such a function might just look like this:

$scope.addUser = function(group, user){
  return user.setGroupId(group.id)
  .then(function(){
    return group.reload();
  })
  .then(function(){
    return Notification.success("Added successfully");
  }, function(){
    Notification.fail("There was a problem");
    return $q.reject();
  });
}

These functions seem harmless but they are actually problematic and you can end up with quite a lot of them on your scope. You will end up having these functions everywhere, without knowing where they’re coming from.

If a function has to maintain some state, it needs to store that state on the scope as well:

$scope.inProgress = false;
$scope.addUser = function(group, user){
  if ($scope.inProgress) return $q.reject();
  $scope.inProgress = true;
  return user.setGroupId(group.id)
  .then(function(){
    return group.reload();
  })
  .then(function(){
    return Notification.success(...);
    $scope.inProgress = false;
  });
}

This variant of the function prevents multiple simultaneous requests by storing the inProgress variable on the scope. Great, even more stuff on the scope! The name inProgress is pretty generic, someone else could easily come along, use the same property name for something different and create bugs that can be very hard to track down.

How can you prevent this?

Introducing: Workers

You could put these functions into small stateful objects, that group related functions together and also store their state. Let’s see how the example might look when we do that:

function GroupWorker(){
  this._inProgress = false;
}

GroupWorker.prototype.addUser = function(group, user){
  var self = this;
  if (this._inProgress) return $q.reject();
  this._inProgress = true;

  return user.setGroupId(group.id)
  .then(function(){
    return group.reload();
  })
  .then(function(){
    return Notification.success(...);
    self._inProgress = false;
  });
}

$scope.groupWorker = new GroupWorker()

Now our function is attached to the worker and also stores its state inside the worker. We’re not polluting the scope and nobody can accidentally mess with the progress flag.

Whenever you need a worker, you can instantiate one and call their methods like this:

<button ng-click="groupWorker.addUser(group, user)">
  Add  to 
</button>

Workers should contain all the methods and state you need in the context of your app, that are not directly attached to or part of your models. The addUser function from the example, used to add users to groups, can’t really go into either of these models because it has a dependency on the Notification service. Models should not have dependencies on services that are not related to their actual purpose. So, addUser is a perfect candidate for an action that you define in a GroupWorker, together with all the other methods related to users and/or groups.

Defining “Workers”

How do you define a Worker? You could define GroupWorkers by yourself, using a combination of services to store the worker’s constructor, and link functions to create the instances:

myModule.value("GroupWorker", function GroupWorker(){
  ...
});

myModule.directive("group", function(GroupWorker) {
  return {
    ...
    link: function(scope, element, attributes) {
      scope.groupWorker = new GroupWorker();
      ...
    }
    ...
  };
});

But Angular already has a facility for declaring workers and makes this much easier for you. You probably guessed it already: What I called “Workers” until now are actually Controllers.

The code you’d actually write in AngularJS to define </strike>workers</strike> Controllers will be this instead:

myModule.controller("GroupController", function GroupController($scope){
  ...
});

myModule.directive("group", function() {
  return {
    ...
    controller: 'GroupController',
    controllerAs: 'groupController',
    link: function(scope, element, attributes) {
      ...
    }
    ...
  };
});

Now Angular will take care of creating an instance of our GroupController and exposing it on the scope as groupController. Instantiating controllers also allows you to reference services in the constructor parameters through AngularJS dependency injection mechanism:

myModule.controller('GroupController', function($scope, Notification) {
  ...
});

Requiring Controllers

There are three different ways of getting controllers into your app. The primary one is through custom directives as seen in the last example:

myModule.directive("foo", function(){
  return {
    ...,
    controller:   "FooController",
    controllerAs: "fooController"
  }
});

The legacy way is to use the ngController directive inside your templates to instantiate a Controller:

<div ng-controller="FooController as fooController"></div>

You should really try to avoid this one. Directive are the primary way to divide your apps into independent components and their respective controllers should be responsible for everything inside each component defined those directives.

Sprinkling controllers randomly through the templates with ngController should never be necessary if your app is modular enough. If you ever find yourself in a situation where you think about using ngController, ask yourself if the component you’re working on has too many responsibilities, is too big or too complex.

The third way is to attach a controller to a route:

$routeProvider
  .when('/Book/:bookId', {
    controller:   "BookController",
    controllerAs: "bookController"
    ...
  })

If your app follows a more page-centric architecture and you use Routes to navigate views, the controller and controllerAs parameters in your route definition will instantiate a controller for that route on your view.

Initializing models on the scope

While a Controller’s constructor function is mostly used to set up the controller instance itself, it is also responsible for loading models into the scope, setting up watchers and event handlers.

Any code that

  1. does not touch the DOM (use link functions for that)
  2. needs to run in multiple places in your app (use services for singletons)

should go into a controller. To keep an overview about the functionality inside your Controller, you can follow a few simple rules that help to keep Controllers clean.

Code Organization for Controllers

First, take a look at this controller, I’ll add the explanations below.

'use strict';
angular.module('contentful').controller('FormWidgetsController',
['$scope', "$injector", function($scope, $injector){
  // 1. Self-reference
  var controller = this;

  // 2. requirements
  var editingInterfaces = $injector.get('editingInterfaces');
  var logger            = $injector.get('logger');

  // 3. Do scope stuff

  // 3a. Set up watchers on the scope.
  $scope.$watch(localesWatcher,                          updateWidgets, true);
  $scope.$watch('spaceContext.space.getDefaultLocale()', updateWidgets);
  $scope.$watch('preferences.showDisabledFields',        updateWidgets);
  $scope.$watch('errorPaths',                            updateWidgets);

  // 3b. Expose methods or data on the scope
  $scope.widgets = [];

  // 3c. Listen to events on the scope

  // 4. Expose methods and properties on the controller instance
  this.updateWidgets = updateWidgets;
  this.updateWidgetsFromInterface = updateWidgetsFromInterface;

  // 5. Clean up
  $scope.$on('$destroy', function(){
          // Do whatever cleanup might be necessary
          controller = null; // MEMLEAK FIX
          $scope     = null; // MEMLEAK FIX
  });

  // 6. All the actual implementations go here.
  function updateWidgets() {
    ...
  }

  function updateWidgetsFromInterface(interf) {
    ...
  }
}]);

Let’s go through this, step by step.

1. Self-reference

This is a standard Javascript pattern that you need whenever you use callbacks that are executed in a different context where this can’t be used. Instead of this, the callbacks can refer to controller through their closure to get a reference to the controller instance.

2. Requirements

I much prefer to only depend on locals and the $injector service in the parameters for a service or Controller, loading the rest of the services through $injector.get(). This has three advantages:

  1. The parameter list for the function doesn’t become too long. You avoid line breaks in the parameter list and make it easier to read.
  2. It’s easier to keep the parameters and the Array with the service names for the dependencey injection in sync if both are short.
  3. When you use JSHint to warn about unused variables and parameters, this pattern is more reliable than a parameter list. JSHint can only warn about unused parameters at the end of the list, not in the middle, but will always warn about an unused variable.

3. Scope stuff

There are three different things you can do with the scope:

  1. Set up watchers
  2. Expose methods or data
  3. Listen to events

Keep statements for each of these categories together and stick to the rule of having one line per statement. Event handler or watch functions should not be defined inline, but declared further down in the file and referenced here by name.

The “one line per statement” rule keeps the upper part of the controllers neat and tidy and makes it possible to fit all relevant information on one screen.

4. Controller properties

If you want to expose properties and methods on the controller, keep these statements together, just as you did with the scope statements.

5. Clean up

This section is usually not necessary in controllers. But you can use the same rules laid out here to structure link functions. In those you might want to clean up a bit when their part of your the app is being destroyed.

6. Functions

Finally, write down all the definitions for the functions you have referenced so far. Everything from here on is internal to the controller. The external interfaces, everything a user of the controller could interact with, has been defined above this part and can be glanced over quickly.

Advanced Controller patterns

There are two advanced usage patterns I came up with for working with complex controllers. Both make use of the $controller service. Like other services, $controller can be retrieved through the $injector. The $controllrer service is itself an injector, albeit a special one: it returns new instances of Controllers. It is invoked with the name of a controller and an object containing so called locals. Locals are injected into the Controller through the standard dependency injection mechanisms. The locals usually passed into a Controller are $scope and $attrs:

var $controller = $injector.get('$controller');
$scope.groupController = $controller('GroupController', {
  '$scope': $scope,
  '$attrs': $attrs
});

Inheritance

IMPORTANT NOTICE: Due to changes in Angular 1.3, the inheritance pattern described here does not work anymore under most circumstances.

The first pattern is Inheritance. AngularJS performs a complicated process to instantiate controllers. This is done to make dependency injection work and looks like this (simplified pseudocode):

function $controller(constructorName, locals) {
  var ActualConstructor = lookupConstructor(constructorName);
  var dependencies = parseInjectedServices(ActualConstructor, locals);

  var Constructor = function(){};
  Constructor.prototype = ActualConstructor.prototype;
  var instance = new Constructor();
  ActualConstructor.apply(instance, dependencies);
  return instance;
}

Because of this pattern and the fact that the constructor parameters are used for the dependency injection mechanism, using classical JavaScript inheritance patterns is difficult (The code in AngularJS that examines your constructors arguments to inject service instances would never see the arguments for the parent constructor). Luckily the effects of inheritance can be easily faked using the following pattern:

function AbstractController($scope, who) {
  this._who = who
  this.greet = function(){
    return "Hello" + this._who
  }
}

function ConcreteController($scope, $controller) {
  return $controller('AbstractController', {
    $scope: $scope,
    who: 'World',
  })
}

Here we are exploiting that an object returned from a constructor will become the return value of the constructor invocation. This is ensured even by the convoluted mechanism AngularJS uses for the instantiation.

What happens in effect is that a caller attempting to instantiate the ConcreteController, actually an instance of the AbstractController, with its missing parts filled by providing them as locals ($scope and who in the example).

Assembly

This way of implementing inheritance is hard to understand if you’re not very familiar with the finer details of Javascript. A more useful alternative to inheritance is to assemble the functionality of a controller by combining multiple smaller-purpose controllers. You combine controllers by instantiating them, then make them cooperate by

  • Calling each other’s methods,
  • Sending events, or
  • Watching the scope

This is an example where our main controller instantiates two special purpose controllers and puts them on the scope:

function MainController($scope, $controller){
  $scope.listController = $controller('ListController', {$scope: $scope});
  $scope.itemController = $controller('ItemController', {$scope: $scope});

  //...do other stuff...
}

But Assembly even makes sense if you don’t want to expose the smaller controllers. You can use assembly to break up your controllers into several smaller ones simply because they became too large or if you want to share some behavior between different parts of your app (A ListController, that does sorting and filtering might be used in many places). Just store the smaller controllers in local variables (or not at all) and selectively make their methods accessible from the outside if you need to expose them:

function ComplexController($scope, $controller){
  var listController = $controller('ListController', {$scope: $scope});
  var itemController = $controller('ItemController', {$scope: $scope});

  this.clearLists = listController.clearLists.bind(listController);
  this.clearItems = itemController.clearItems.bind(itemController);
}
<button ng-click="complexController.clearLists()">
  Clear lists
</button>

Summary

To make the best use of Controllers in AngularJS

  • Build and work with controller instances
  • Keep your scope clean
  • Keep your controllers small.
    • Give then a single purpose and a small API
    • Use assembly and inheritance to break up controllers that become too large