feat($compile): optionally get controllers from ancestors only

Implement option to strengthen require '^' operator, by adding another '^'.

When a second '^' is used, the controller will only search parent nodes for the
matching controller, and will throw or return null if not found, depending on
whether or not the requirement is optional.

Closes angular#4518

Author: Caitlin Potter

docs/content/guide/directive.ngdoc

@@ -271,7 +271,7 @@ Here's an example directive declared with a Directive Definition Object:
       restrict: 'A',
       scope: false,
       controller: function($scope, $element, $attrs, $transclude, otherInjectables) { ... },
-      require: 'siblingDirectiveName', // or // ['^parentDirectiveName', '?optionalDirectiveName', '?^optionalParent'],
+      require: 'siblingDirectiveName', // or // ['^parentOrSiblingDirectiveName', '?optionalDirectiveName', '?^optionalParentOrSibling'], // or // ['^^parentDirectiveName', '?^^optionalParentDirectiveName'],
       compile: function compile(tElement, tAttrs, transclude) {
         return {
           pre: function preLink(scope, iElement, iAttrs, controller) { ... },
@@ -398,8 +398,10 @@ compiler}. The attributes are:
 
     * (no prefix) - Locate the required controller on the current element.
     * `?` - Attempt to locate the required controller, or return `null` if not found.
-    * `^` - Locate the required controller by searching the element's parents.
-    * `?^` - Attempt to locate the required controller by searching the element's parents, or return `null` if not found.
+    * `^` - Locate the required controller by searching the element and its parents until found.
+		* `^^` - Locate the required controller by searching the element's parents until found.
+    * `?^` - Attempt to locate the required controller by searching the element and its parents, or return `null` if not found.
+		* `?^^` - Attempt to locate the required controller by searching the element's parents, or return `null` if not found.
 
   * `controllerAs` - Creates a controller alias in the directive scope so it
     can be referenced in the directive template. The directive must define a scope for this

src/ng/compile.js

@@ -950,17 +950,20 @@ function $CompileProvider($provide) {
 
 
       function getControllers(require, $element) {
-        var value, retrievalMethod = 'data', optional = false;
+        var value, retrievalMethod = 'data', optional = false, $searchElement = $element;
         if (isString(require)) {
           while((value = require.charAt(0)) == '^' || value == '?') {
             require = require.substr(1);
             if (value == '^') {
+							if (retrievalMethod === 'inheritedData') {
+								$searchElement = $element.parent();
+							}
               retrievalMethod = 'inheritedData';
             }
             optional = optional || value == '?';
           }
 
-          value = $element[retrievalMethod]('$' + require + 'Controller');
+          value = $searchElement[retrievalMethod]('$' + require + 'Controller');
 
           if ($element[0].nodeType == 8 && $element[0].$$controller) { // Transclusion comment node
             value = value || $element[0].$$controller;

test/ng/compileSpec.js

@@ -2282,6 +2282,43 @@ describe('$compile', function() {
     });
 
 
+		it('should get required parent controller', function() {
+			module(function() {
+				directive('nested', function(log) {
+					return {
+						require: '^^?nested',
+						controller: function($scope) {},
+						link: function(scope, element, attrs, controller) {
+							log(!!controller);
+						}
+					};
+				});
+			});
+			inject(function(log, $compile, $rootScope) {
+				element = $compile('<div nested><div nested></div></div>')($rootScope);
+				// Nested div should be post-linked first.
+				expect(log).toEqual('true; false')
+			});
+		});
+
+
+		it('should throw if required parent is not found', function() {
+			module(function() {
+				directive('nested', function() {
+					return {
+						require: '^^nested',
+						controller: function($scope) {},
+						link: function(scope, element, attrs, controller) {}
+					};
+				});
+			});
+			inject(function($compile, $rootScope) {
+				var fn = angular.bind(this, $compile('<div nested></div>'), $rootScope);
+				expect(fn).toThrowMinErr('$compile', 'ctreq', "Controller 'nested', required by directive 'nested', can't be found!");
+			});
+		})
+
+
     it('should support controllerAs', function() {
       module(function() {
         directive('main', function() {