feat($compile): add more lifecycle hooks to directive controllers

This change adds in the following new lifecycle hooks, which map in some
way to those in Angular 2:

 * `$onChanges(changesObj)` - Called whenever one-way bindings are updated. The `changesObj` is a hash whose keys
   are the names of the bound properties that have changed, and the values are an object of the form
   `{ currentValue: ..., previousValue: ... }`. Use this hook to trigger updates within a component such as
   cloning the bound value to prevent accidental mutation of the outer value.
 * `$onDestroy` - Called on a controller when its containing scope is destroyed. Use this hook for releasing
   external resources, watches and event handlers.
 * `$afterViewInit` - Called after this controller's element and its children been linked. Similar to the post-link
   function this hook can be used to set up DOM event handlers and do direct DOM manipulation.
   Note that child elements that contain `templateUrl` directives will not have been compiled and linked since
   they are waiting for their template to load asynchronously and their own compilation and linking has been
   suspended until that occurs.

Closes #14127
Closes #14030
Closes #14020
Closes #13991

Author: petebacondarwin

docs/content/guide/component.ngdoc

@@ -147,6 +147,27 @@ components should follow a few simple conventions:
       }
     ```
 
+- **Components have a well-defined lifecycle
+Each component can implement "lifecycle hooks", which are methods that will be called at certain points in the life
+of the component. The following hook methods can be implemented:
+
+  * `$onInit()` - Called on each controller after all the controllers on an element have been constructed and
+    had their bindings initialized (and before the pre & post linking functions for the directives on
+    this element). This is a good place to put initialization code for your controller.
+  * `$onChanges(changesObj)` - Called whenever one-way bindings are updated. The `changesObj` is a hash whose keys
+    are the names of the bound properties that have changed, and the values are an object of the form
+    `{ currentValue: ..., previousValue: ... }`. Use this hook to trigger updates within a component such as
+    cloning the bound value to prevent accidental mutation of the outer value.
+  * `$onDestroy` - Called on a controller when its containing scope is destroyed. Use this hook for releasing
+    external resources, watches and event handlers.
+  * `$afterViewInit` - Called after this controller's element and its children been linked. Similar to the post-link
+    function this hook can be used to set up DOM event handlers and do direct DOM manipulation.
+    Note that child elements that contain `templateUrl` directives will not have been compiled and linked since
+    they are waiting for their template to load asynchronously and their own compilation and linking has been
+    suspended until that occurs.
+
+By implementing these methods, you component can take part in its lifecycle.
+
 - **An application is a tree of components:**
 Ideally, the whole application should be a tree of components that implement clearly defined inputs
 and outputs, and minimize two-way data binding. That way, it's easier to predict when data changes and what the state

src/ng/compile.js

@@ -293,9 +293,21 @@
  *    `true` if the specified slot contains content (i.e. one or more DOM nodes).
  *
  * The controller can provide the following methods that act as life-cycle hooks:
- * * `$onInit` - Called on each controller after all the controllers on an element have been constructed and
+ * * `$onInit()` - Called on each controller after all the controllers on an element have been constructed and
  *   had their bindings initialized (and before the pre & post linking functions for the directives on
  *   this element). This is a good place to put initialization code for your controller.
+ * * `$onChanges(changesObj)` - Called whenever one-way bindings are updated. The `changesObj` is a hash whose keys
+ *   are the names of the bound properties that have changed, and the values are an object of the form
+ *   `{ currentValue: ..., previousValue: ... }`. Use this hook to trigger updates within a component such as
+ *   cloning the bound value to prevent accidental mutation of the outer value.
+ * * `$onDestroy` - Called on a controller when its containing scope is destroyed. Use this hook for releasing
+ *   external resources, watches and event handlers.
+ * * `$afterViewInit` - Called after this controller's element and its children been linked. Similar to the post-link
+ *   function this hook can be used to set up DOM event handlers and do direct DOM manipulation.
+ *   Note that child elements that contain `templateUrl` directives will not have been compiled and linked since
+ *   they are waiting for their template to load asynchronously and their own compilation and linking has been
+ *   suspended until that occurs.
+ *
  *
  * #### `require`
  * Require another directive and inject its controller as the fourth argument to the linking function. The
@@ -2349,10 +2361,16 @@ function $CompileProvider($provide, $$sanitizeUriProvider) {
           }
         });
 
-        // Trigger the `$onInit` method on all controllers that have one
+        // Handle the init and destroy lifecycle hooks on all controllers that have them
         forEach(elementControllers, function(controller) {
-          if (isFunction(controller.instance.$onInit)) {
-            controller.instance.$onInit();
+          var controllerInstance = controller.instance;
+          if (isFunction(controllerInstance.$onInit)) {
+            controllerInstance.$onInit();
+          }
+          if (isFunction(controllerInstance.$onDestroy)) {
+            controllerScope.$on('$destroy', function callOnDestroyHook() {
+              controllerInstance.$onDestroy();
+            });
           }
         });
 
@@ -2389,6 +2407,14 @@ function $CompileProvider($provide, $$sanitizeUriProvider) {
           );
         }
 
+        // Trigger $afterViewInit lifecycle hooks
+        forEach(elementControllers, function(controller) {
+          var controllerInstance = controller.instance;
+          if (isFunction(controllerInstance.$afterViewInit)) {
+            controllerInstance.$afterViewInit();
+          }
+        });
+
         // This is the function that is injected as `$transclude`.
         // Note: all arguments are optional!
         function controllersBoundTransclude(scope, cloneAttachFn, futureParentElement, slotName) {
@@ -2984,6 +3010,7 @@ function $CompileProvider($provide, $$sanitizeUriProvider) {
     // only occurs for isolate scopes and new scopes with controllerAs.
     function initializeDirectiveBindings(scope, attrs, destination, bindings, directive) {
       var removeWatchCollection = [];
+      var changes;
       forEach(bindings, function initializeBinding(definition, scopeName) {
         var attrName = definition.attrName,
         optional = definition.optional,
@@ -3070,6 +3097,8 @@ function $CompileProvider($provide, $$sanitizeUriProvider) {
             destination[scopeName] = parentGet(scope);
 
             removeWatch = scope.$watch(parentGet, function parentValueWatchAction(newParentValue) {
+              var oldValue = destination[scopeName];
+              recordChanges(scopeName, newParentValue, oldValue);
               destination[scopeName] = newParentValue;
             }, parentGet.literal);
 
@@ -3090,6 +3119,27 @@ function $CompileProvider($provide, $$sanitizeUriProvider) {
         }
       });
 
+      function recordChanges(key, currentValue, previousValue) {
+        if (isFunction(destination.$onChanges)) {
+          // If we have not already schedule the onChanges hook then do so now
+          if (!changes) {
+            changes = {};
+            scope.$$postDigest(triggerOnChangesHook);
+          }
+          // Store this change
+          changes[key] = {previousValue: previousValue, currentValue: currentValue};
+        }
+      }
+
+      function triggerOnChangesHook() {
+        // We must run this hook in an apply since the $$postDigest runs outside apply
+        scope.$apply(function() {
+          destination.$onChanges(changes);
+          // Now clear the changes so that we schedule onChanges when more changes arrive
+          changes = undefined;
+        });
+      }
+
       return removeWatchCollection.length && function removeWatches() {
         for (var i = 0, ii = removeWatchCollection.length; i < ii; ++i) {
           removeWatchCollection[i]();

test/ng/compileSpec.js

@@ -3515,6 +3515,191 @@ describe('$compile', function() {
     });
   });
 
+  describe('controller lifecycle hooks', function() {
+
+    describe('$onInit', function() {
+
+      it('should call `$onInit`, if provided, after all the controllers on the element have been initialized', function() {
+
+        function check() {
+          /*jshint validthis:true */
+          expect(this.element.controller('d1').id).toEqual(1);
+          expect(this.element.controller('d2').id).toEqual(2);
+        }
+
+        function Controller1($element) { this.id = 1; this.element = $element; }
+        Controller1.prototype.$onInit = jasmine.createSpy('$onInit').and.callFake(check);
+
+        function Controller2($element) { this.id = 2; this.element = $element; }
+        Controller2.prototype.$onInit = jasmine.createSpy('$onInit').and.callFake(check);
+
+        angular.module('my', [])
+          .directive('d1', valueFn({ controller: Controller1 }))
+          .directive('d2', valueFn({ controller: Controller2 }));
+
+        module('my');
+        inject(function($compile, $rootScope) {
+          element = $compile('<div d1 d2></div>')($rootScope);
+          expect(Controller1.prototype.$onInit).toHaveBeenCalledOnce();
+          expect(Controller2.prototype.$onInit).toHaveBeenCalledOnce();
+        });
+      });
+    });
+
+
+    describe('$onDestroy', function() {
+
+      it('should call `$onDestroy`, if provided, on the controller when its scope is destroyed', function() {
+
+        function TestController() { this.count = 0; }
+        TestController.prototype.$onDestroy = function() { this.count++; };
+
+        angular.module('my', [])
+          .directive('d1', valueFn({ scope: true, controller: TestController }))
+          .directive('d2', valueFn({ scope: {}, controller: TestController }))
+          .directive('d3', valueFn({ controller: TestController }));
+
+        module('my');
+        inject(function($compile, $rootScope) {
+
+          element = $compile('<div><d1 ng-if="show[0]"></d1><d2 ng-if="show[1]"></d2><div ng-if="show[2]"><d3></d3></div></div>')($rootScope);
+
+          $rootScope.$apply('show = [true, true, true]');
+          var d1Controller = element.find('d1').controller('d1');
+          var d2Controller = element.find('d2').controller('d2');
+          var d3Controller = element.find('d3').controller('d3');
+
+          expect([d1Controller.count, d2Controller.count, d3Controller.count]).toEqual([0,0,0]);
+          $rootScope.$apply('show = [false, true, true]');
+          expect([d1Controller.count, d2Controller.count, d3Controller.count]).toEqual([1,0,0]);
+          $rootScope.$apply('show = [false, false, true]');
+          expect([d1Controller.count, d2Controller.count, d3Controller.count]).toEqual([1,1,0]);
+          $rootScope.$apply('show = [false, false, false]');
+          expect([d1Controller.count, d2Controller.count, d3Controller.count]).toEqual([1,1,1]);
+        });
+      });
+
+
+      it('should call `$onDestroy` top-down (the same as `scope.$broadcast`)', function() {
+        var log = [];
+        function ParentController() { log.push('parent created'); }
+        ParentController.prototype.$onDestroy = function() { log.push('parent destroyed'); };
+        function ChildController() { log.push('child created'); }
+        ChildController.prototype.$onDestroy = function() { log.push('child destroyed'); };
+        function GrandChildController() { log.push('grand child created'); }
+        GrandChildController.prototype.$onDestroy = function() { log.push('grand child destroyed'); };
+
+        angular.module('my', [])
+          .directive('parent', valueFn({ scope: true, controller: ParentController }))
+          .directive('child', valueFn({ scope: true, controller: ChildController }))
+          .directive('grandChild', valueFn({ scope: true, controller: GrandChildController }));
+
+        module('my');
+        inject(function($compile, $rootScope) {
+
+          element = $compile('<parent ng-if="show"><child><grand-child></grand-child></child></parent>')($rootScope);
+          $rootScope.$apply('show = true');
+          expect(log).toEqual(['parent created', 'child created', 'grand child created']);
+          log = [];
+          $rootScope.$apply('show = false');
+          expect(log).toEqual(['parent destroyed', 'child destroyed', 'grand child destroyed']);
+        });
+      });
+    });
+
+
+    describe('$afterViewInit', function() {
+
+      it('should call `$afterViewInit`, if provided, after the element has completed linking (i.e. post-link)', function() {
+
+        var log = [];
+
+        function Controller1() { }
+        Controller1.prototype.$afterViewInit = function() { log.push('d1 view init'); };
+
+        function Controller2() { }
+        Controller2.prototype.$afterViewInit = function() { log.push('d2 view init'); };
+
+        angular.module('my', [])
+          .directive('d1', valueFn({
+            controller: Controller1,
+            link: { pre: function(s, e) { log.push('d1 pre: ' + e.text()); }, post: function(s, e) { log.push('d1 post: ' + e.text()); } },
+            template: '<d2></d2>'
+          }))
+          .directive('d2', valueFn({
+            controller: Controller2,
+            link: { pre: function(s, e) { log.push('d2 pre: ' + e.text()); }, post: function(s, e) { log.push('d2 post: ' + e.text()); } },
+            template: 'loaded'
+          }));
+
+        module('my');
+        inject(function($compile, $rootScope) {
+          element = $compile('<d1></d1>')($rootScope);
+          expect(log).toEqual([
+            'd1 pre: loaded',
+            'd2 pre: loaded',
+            'd2 post: loaded',
+            'd2 view init',
+            'd1 post: loaded',
+            'd1 view init'
+          ]);
+        });
+      });
+    });
+
+
+    describe('$onChanges', function() {
+      it('should call `$onChanges`, if provided, when a one-way (`<`) binding is updated', function() {
+        var log = [];
+        function TestController() { }
+        TestController.prototype.$onChanges = function(change) { log.push(change); };
+
+        angular.module('my', [])
+          .component('c1', {
+            controller: TestController,
+            bindings: { 'prop1': '<', 'prop2': '<' }
+          });
+
+        module('my');
+        inject(function($compile, $rootScope) {
+          // Setup a watch to indicate some complicated updated logic
+          $rootScope.$watch('val', function(val, oldVal) { $rootScope.val2 = val * 2; });
+
+          // Setup the directive with two bindings
+          element = $compile('<c1 prop1="val" prop2="val2"></c1>')($rootScope);
+
+          // There should be no changes initially
+          expect(log).toEqual([]);
+
+          // Update val to trigger the onChanges
+          $rootScope.$apply('val = 42');
+
+          // Now we should have a single changes entry in the log
+          expect(log).toEqual([
+            {
+              prop1: {previousValue: undefined, currentValue: 42},
+              prop2: {previousValue: undefined, currentValue: 84}
+            }
+          ]);
+
+          // Clear the log
+          log = [];
+
+          // Update val to trigger the onChanges
+          $rootScope.$apply('val = 17');
+
+          // Now we should have a single changes entry in the log
+          expect(log).toEqual([
+            {
+              prop1: {previousValue: 42, currentValue: 17},
+              prop2: {previousValue: 84, currentValue: 34}
+            }
+          ]);
+        });
+      });
+    });
+  });
+
 
   describe('isolated locals', function() {
     var componentScope, regularScope;
@@ -5324,32 +5509,6 @@ describe('$compile', function() {
       });
     });
 
-    it('should call `controller.$onInit`, if provided after all the controllers have been constructed', function() {
-
-      function check() {
-        /*jshint validthis:true */
-        expect(this.element.controller('d1').id).toEqual(1);
-        expect(this.element.controller('d2').id).toEqual(2);
-      }
-
-      function Controller1($element) { this.id = 1; this.element = $element; }
-      Controller1.prototype.$onInit = jasmine.createSpy('$onInit').and.callFake(check);
-
-      function Controller2($element) { this.id = 2; this.element = $element; }
-      Controller2.prototype.$onInit = jasmine.createSpy('$onInit').and.callFake(check);
-
-      angular.module('my', [])
-        .directive('d1', valueFn({ controller: Controller1 }))
-        .directive('d2', valueFn({ controller: Controller2 }));
-
-      module('my');
-      inject(function($compile, $rootScope) {
-        element = $compile('<div d1 d2></div>')($rootScope);
-        expect(Controller1.prototype.$onInit).toHaveBeenCalledOnce();
-        expect(Controller2.prototype.$onInit).toHaveBeenCalledOnce();
-      });
-    });
-
     describe('should not overwrite @-bound property each digest when not present', function() {
       it('when creating new scope', function() {
         module(function($compileProvider) {