add tests and docs for ngRepeat + ngRef

Author: Narretz

src/ng/directive/ngRef.js

@@ -12,6 +12,11 @@
  *
  * If the element with `ngRef` is destroyed `null` is assigned to the property.
  *
+ * Note that if you want to assign from a child into the parent scope, you must initialize the
+ * target property on the parent scope, otherwise `ngRef` will assign on the child scope.
+ * This commonly happens when assigning elements or components wrapped in {@link ngIf} or
+ * {@link ngRepeat}. See the second example below.
+ *
  *
  * @element ANY
  * @param {string} ngRef property name - A valid AngularJS expression identifier to which the
@@ -56,43 +61,102 @@
  *
  * @example
  * ### ngRef inside scopes
- * This example shows how scopes contain `ngRef` assignments.
+ * This example shows how `ngRef` works with child scopes. The `ngRepeat`-ed `myWrapper` components
+ * are assigned to the scope of `myRoot`, because the `toggles` property has been initialized.
+ * The repeated `myToggle` components are published to the child scopes created by `ngRepeat`.
+ * `ngIf` behaves similarly - the assignment of `myToggle` happens in the `ngIf` child scope,
+ * because the target property has not been initialized on the `myRoot` component controller.
+ *
  * <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>ngRepeatToggle.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>ngIfToggle.isOpen(): {{ngIfToggle.isOpen() | json}}</div>
+ *     <my-root></my-root>
  *   </file>
  *   <file name="index.js">
  *     angular.module('myApp', [])
+ *     .component('myRoot', {
+ *       templateUrl: 'root.html',
+ *       controller: function() {
+ *         this.wrappers = []; // initialize the array so that the wrappers are assigned into the parent scope
+ *       }
+ *     })
  *     .component('myToggle', {
- *       template: '<button ng-click="$ctrl.toggle()" ng-transclude></button>',
+ *       template: '<strong>myToggle</strong><button ng-click="$ctrl.toggle()" ng-transclude></button>',
  *       transclude: true,
  *       controller: function ToggleController() {
  *         var opened = false;
  *         this.isOpen = function() { return opened; };
  *         this.toggle = function() { opened = !opened; };
  *       }
+ *     })
+ *     .component('myWrapper', {
+ *       transclude: true,
+ *       template: '<strong>myWrapper</strong>' +
+ *         '<div>ngRepeatToggle.isOpen(): {{$ctrl.ngRepeatToggle.isOpen() | json}}</div>' +
+ *         '<my-toggle ng-ref="$ctrl.ngRepeatToggle"><ng-transclude></ng-transclude></my-toggle>'
  *     });
  *   </file>
+ *   <file name="root.html">
+ *     <strong>myRoot</strong>
+ *     <my-toggle ng-ref="$ctrl.outerToggle">Outer Toggle</my-toggle>
+ *     <div>outerToggle.isOpen(): {{$ctrl.outerToggle.isOpen() | json}}</div>
+ *     <div><em>wrappers assigned to root</em><br>
+ *     <div ng-repeat="wrapper in $ctrl.wrappers">
+ *       wrapper.ngRepeatToggle.isOpen(): {{wrapper.ngRepeatToggle.isOpen() | json}}
+ *     </div>
+ *
+ *     <ul>
+ *       <li ng-repeat="(index, value) in [1,2,3]">
+ *         <strong>ngRepeat</strong>
+ *         <div>outerToggle.isOpen(): {{$ctrl.outerToggle.isOpen() | json}}</div>
+ *         <my-wrapper ng-ref="$ctrl.wrappers[index]">ngRepeat Toggle {{$index + 1}}</my-wrapper>
+ *       </li>
+ *     </ul>
+ *
+ *     <div>ngIfToggle.isOpen(): {{ngIfToggle.isOpen()}} // This is always undefined because it's
+ *       assigned to the child scope created by ngIf.
+ *     </div>
+ *     <div ng-if="true">
+          <strong>ngIf</strong>
+ *        <my-toggle ng-ref="ngIfToggle">ngIf Toggle</my-toggle>
+ *        <div>ngIfToggle.isOpen(): {{ngIfToggle.isOpen() | json}}</div>
+ *        <div>outerToggle.isOpen(): {{$ctrl.outerToggle.isOpen() | json}}</div>
+ *     </div>
+ *   </file>
+ *   <file name="styles.css">
+ *     ul {
+ *       list-style: none;
+ *       padding-left: 0;
+ *     }
+ *
+ *     li[ng-repeat] {
+ *       background: lightgreen;
+ *       padding: 8px;
+ *       margin: 8px;
+ *     }
+ *
+ *     [ng-if] {
+ *       background: lightgrey;
+ *       padding: 8px;
+ *     }
+ *
+ *     my-root {
+ *       background: lightgoldenrodyellow;
+ *       padding: 8px;
+ *       display: block;
+ *     }
+ *
+ *     my-wrapper {
+ *       background: lightsalmon;
+ *       padding: 8px;
+ *       display: block;
+ *     }
+ *
+ *     my-toggle {
+ *       background: lightblue;
+ *       padding: 8px;
+ *       display: block;
+ *     }
+ *   </file>
  *   <file name="protractor.js" type="protractor">
  *      var OuterToggle = function() {
  *        this.toggle = function() {
@@ -103,7 +167,7 @@
  *        };
  *      };
  *      var NgRepeatToggle = function(i) {
- *        var parent = element.all(by.repeater('i in [1,2,3]')).get(i - 1);
+ *        var parent = element.all(by.repeater('(index, value) in [1,2,3]')).get(i - 1);
  *        this.toggle = function() {
  *          element(by.buttonText('ngRepeat Toggle ' + i)).click();
  *        };

test/ng/directive/ngRefSpec.js

@@ -10,7 +10,6 @@ describe('ngRef', function() {
       $compileProvider.component('myComponent', {
         template: 'foo',
         controller: function() {
-          console.log('ctrl');
           myComponentController = this;
         }
       });
@@ -101,11 +100,11 @@ describe('ngRef', function() {
       expect($rootScope.myComponent).toBe(enteringController);
     }));
 
-    it('should allow bind to a parent controller', function() {
-      $rootScope.$ctrl = {};
+    it('should allow binding to a nested property', function() {
+      $rootScope.obj = {};
 
-      $compile('<my-component ng-ref="$ctrl.myComponent"></my-component>')($rootScope);
-      expect($rootScope.$ctrl.myComponent).toBe(myComponentController);
+      $compile('<my-component ng-ref="obj.myComponent"></my-component>')($rootScope);
+      expect($rootScope.obj.myComponent).toBe(myComponentController);
     });
 
   });
@@ -485,4 +484,34 @@ describe('ngRef', function() {
     });
   });
 
+
+  it('should work with ngRepeat-ed components', function() {
+    var controllers = [];
+
+    module(function($compileProvider) {
+      $compileProvider.component('myComponent', {
+        template: 'foo',
+        controller: function() {
+          controllers.push(this);
+        }
+      });
+    });
+
+
+    inject(function($compile, $rootScope) {
+      $rootScope.elements = [0,1,2,3,4];
+      $rootScope.controllers = []; // Initialize the array because ngRepeat creates a child scope
+
+      var template = '<div><my-component ng-repeat="(key, el) in elements" ng-ref="controllers[key]"></my-component></div>';
+      var element = $compile(template)($rootScope);
+      $rootScope.$apply();
+
+      expect($rootScope.controllers).toEqual(controllers);
+
+      $rootScope.$apply('elements = []');
+
+      expect($rootScope.controllers).toEqual([null, null, null, null, null]);
+    });
+  });
+
 });