feat(ngAsDirective): new as directive to publish component controllers into current scope

angularFiles.js

@@ -74,6 +74,7 @@ var angularFiles = {
     'src/ng/directive/ngNonBindable.js',
     'src/ng/directive/ngOptions.js',
     'src/ng/directive/ngPluralize.js',
+    'src/ng/directive/ngRef.js',
     'src/ng/directive/ngRepeat.js',
     'src/ng/directive/ngShowHide.js',
     'src/ng/directive/ngStyle.js',

src/AngularPublic.js

@@ -28,6 +28,7 @@
   ngInitDirective,
   ngNonBindableDirective,
   ngPluralizeDirective,
+  ngRefDirective,
   ngRepeatDirective,
   ngShowDirective,
   ngStyleDirective,
@@ -194,6 +195,7 @@ function publishExternalAPI(angular) {
             ngInit: ngInitDirective,
             ngNonBindable: ngNonBindableDirective,
             ngPluralize: ngPluralizeDirective,
+            ngRef: ngRefDirective,
             ngRepeat: ngRepeatDirective,
             ngShow: ngShowDirective,
             ngStyle: ngStyleDirective,

src/ng/directive/ngRef.js

@@ -0,0 +1,209 @@
+'use strict';
+
+/**
+ * @ngdoc directive
+ * @name ngRef
+ * @restrict A
+ *
+ * @description
+ * The `ngRef` attribute tells AngularJS to assign the element component controller
+ * to the given property in the current scope.
+ *
+ * If the component is destroyed `null` is assigned to the property.
+ *
+ *
+ * @element ANY
+ * @param {string} ngRef property name - this must be a valid AngularJS expression identifier
+ *
+ *
+ * @example
+ * ### Simple toggle
+ * This example shows how the controller of the component toggle
+ * is reused in the template through the scope to use its logic.
+ * <example name="ng-ref-component" module="myApp">
+ *   <file name="index.html">
+ *     <my-toggle ng-ref="myToggle"></my-toggle>
+ *     <button ng-click="myToggle.toggle()">Toggle</button>
+ *     <div ng-show="myToggle.isOpen()">
+ *       You are using a component in the same template to show it.
+ *     </div>
+ *   </file>
+ *   <file name="index.js">
+ *     angular.module('myApp', []);
+ *   </file>
+ *   <file name="toggle.js">
+ *     function ToggleController() {
+ *       var opened = false;
+ *       this.isOpen = function() { return opened; };
+ *       this.toggle = function() { opened = !opened; };
+ *     }
+ *
+ *     angular.module('myApp').component('myToggle', {
+ *       controller: ToggleController
+ *     });
+ *   </file>
+ *   <file name="protractor.js" type="protractor">
+ *      it('should publish the toggle into the scope', function() {
+ *        var toggle = element(by.buttonText('Toggle'));
+ *        expect(toggle.evaluate('myToggle.isOpen()')).toEqual(false);
+ *        toggle.click();
+ *        expect(toggle.evaluate('myToggle.isOpen()')).toEqual(true);
+ *      });
+ *   </file>
+ * </example>
+ *
+ * @example
+ * ### ngRef inside scopes
+ * This example shows how new scopes limits
+ * <example name="ng-ref-scopes" module="myApp">
+ *   <file name="index.html">
+ *     <h3>Outer Toggle</h3>
+ *     <my-toggle ng-ref="outerToggle">Outer Toggle</my-toggle>
+ *     <div>outerToggle.isOpen(): {{outerToggle.isOpen() | json}}</div>
+ *
+ *     <h3>ngRepeat toggle</h3>
+ *     <ul>
+ *     <li ng-repeat="i in [1,2,3]">
+ *        <my-toggle ng-ref="ngRepeatToggle">ngRepeat Toggle {{i}}</my-toggle>
+ *        <div>ngRepeatToggle.isOpen(): {{ngRepeatToggle.isOpen() | json}}</div>
+ *        <div>outerToggle.isOpen(): {{outerToggle.isOpen() | json}}</div>
+ *     </li>
+ *     </ul>
+ *     <div>ngRepeat.isOpen(): {{ngRepeatToggle.isOpen() | json}}</div>
+ *
+ *     <h3>ngIf toggle</h3>
+ *     <div ng-if="true">
+ *        <my-toggle ng-ref="ngIfToggle">ngIf Toggle</my-toggle>
+ *        <div>ngIfToggle.isOpen(): {{ngIfToggle.isOpen() | json}}</div>
+ *        <div>outerToggle.isOpen(): {{outerToggle.isOpen() | json}}</div>
+ *     </div>
+ *     <div>ngIf.isOpen(): {{ngIf.isOpen() | json}}</div>
+ *   </file>
+ *   <file name="index.js">
+ *     angular.module('myApp', []);
+ *   </file>
+ *   <file name="toggle.js">
+ *     function ToggleController() {
+ *       var opened = false;
+ *       this.isOpen = function() { return opened; };
+ *       this.toggle = function() { opened = !opened; };
+ *     }
+ *
+ *     angular.module('myApp').component('myToggle', {
+ *       template: '<button ng-click="$ctrl.toggle()" ng-transclude></button>',
+ *       transclude: true,
+ *       controller: ToggleController
+ *     });
+ *   </file>
+ *   <file name="protractor.js" type="protractor">
+ *      var OuterToggle = function() {
+ *        this.toggle = function() {
+ *          element(by.buttonText('Outer Toggle')).click();
+ *        };
+ *        this.isOpen = function() {
+ *          return element.all(by.binding('outerToggle.isOpen()')).first().getText();
+ *        };
+ *      };
+ *      var NgRepeatToggle = function(i) {
+ *        var parent = element.all(by.repeater('i in [1,2,3]')).get(i - 1);
+ *        this.toggle = function() {
+ *          element(by.buttonText('ngRepeat Toggle ' + i)).click();
+ *        };
+ *        this.isOpen = function() {
+ *          return parent.element(by.binding('ngRepeatToggle.isOpen() | json')).getText();
+ *        };
+ *        this.isOuterOpen = function() {
+ *          return parent.element(by.binding('outerToggle.isOpen() | json')).getText();
+ *        };
+ *      };
+ *      var NgRepeatToggles = function() {
+ *        var toggles = [1,2,3].map(function(i) { return new NgRepeatToggle(i); });
+ *        this.forEach = function(fn) {
+ *          toggles.forEach(fn);
+ *        };
+ *        this.isOuterOpen = function(i) {
+ *          return toggles[i - 1].isOuterOpen();
+ *        };
+ *      };
+ *      var NgIfToggle = function() {
+ *        var parent = element(by.css('[ng-if]'));
+ *        this.toggle = function() {
+ *          element(by.buttonText('ngIf Toggle')).click();
+ *        };
+ *        this.isOpen = function() {
+ *          return by.binding('ngIfToggle.isOpen() | json').getText();
+ *        };
+ *        this.isOuterOpen = function() {
+ *          return parent.element(by.binding('outerToggle.isOpen() | json')).getText();
+ *        };
+ *      };
+ *
+ *      it('should toggle the outer toggle', function() {
+ *        var outerToggle = new OuterToggle();
+ *        expect(outerToggle.isOpen()).toEqual('outerToggle.isOpen(): false');
+ *        outerToggle.toggle();
+ *        expect(outerToggle.isOpen()).toEqual('outerToggle.isOpen(): true');
+ *      });
+ *
+ *      it('should toggle all outer toggles', function() {
+ *        var outerToggle = new OuterToggle();
+ *        var repeatToggles = new NgRepeatToggles();
+ *        var ifToggle = new NgIfToggle();
+ *        expect(outerToggle.isOpen()).toEqual('outerToggle.isOpen(): false');
+ *        expect(repeatToggles.isOuterOpen(1)).toEqual('outerToggle.isOpen(): false');
+ *        expect(repeatToggles.isOuterOpen(2)).toEqual('outerToggle.isOpen(): false');
+ *        expect(repeatToggles.isOuterOpen(3)).toEqual('outerToggle.isOpen(): false');
+ *        expect(ifToggle.isOuterOpen()).toEqual('outerToggle.isOpen(): false');
+ *        outerToggle.toggle();
+ *        expect(outerToggle.isOpen()).toEqual('outerToggle.isOpen(): true');
+ *        expect(repeatToggles.isOuterOpen(1)).toEqual('outerToggle.isOpen(): true');
+ *        expect(repeatToggles.isOuterOpen(2)).toEqual('outerToggle.isOpen(): true');
+ *        expect(repeatToggles.isOuterOpen(3)).toEqual('outerToggle.isOpen(): true');
+ *        expect(ifToggle.isOuterOpen()).toEqual('outerToggle.isOpen(): true');
+ *      });
+ *
+ *      it('should toggle each repeat iteration separately', function() {
+ *        var repeatToggles = new NgRepeatToggles();
+ *
+ *        repeatToggles.forEach(function(repeatToggle) {
+ *          expect(repeatToggle.isOpen()).toEqual('ngRepeatToggle.isOpen(): false');
+ *          expect(repeatToggle.isOuterOpen()).toEqual('outerToggle.isOpen(): false');
+ *          repeatToggle.toggle();
+ *          expect(repeatToggle.isOpen()).toEqual('ngRepeatToggle.isOpen(): true');
+ *          expect(repeatToggle.isOuterOpen()).toEqual('outerToggle.isOpen(): false');
+ *        });
+ *      });
+ *   </file>
+ * </example>
+ *
+ */
+var ngRefDirective = ['$parse',function($parse) {
+  return {
+    priority: -1,
+    restrict: 'A',
+    compile: function(tElement, tAttrs) {
+      // gets the expected controller name, converts <data-some-thing> into "someThing"
+      var controllerName = directiveNormalize(nodeName_(tElement));
+
+      // get the expression for value binding
+      var getter = $parse(tAttrs.ngRef);
+      var setter = getter.assign;
+
+      return function(scope, element) {
+        // gets the controller of the current component or the current DOM element
+        var controller = element.data('$' + controllerName + 'Controller');
+        var value = controller || element[0];
+        setter(scope, value);
+
+        // when the element is removed, remove it (nullify it)
+        element.on('$destroy', function() {
+          // only remove it if value has not changed,
+          // carefully because animations (and other procedures) may duplicate elements
+          if (getter(scope) === value) {
+            setter(scope,  null);
+          }
+        });
+      };
+    }
+  };
+}];