docs(ngInit): add note on best practices #4366

Closed
wants to merge 1 commit into
from
@@ -6,23 +6,42 @@
* @restrict AC
*
* @description
- * The `ngInit` directive specifies initialization tasks to be executed
- * before the template enters execution mode during bootstrap.
+ * The `ngInit` directive allows you to evaluate an expression in the
+ * current scope.
+ *
+ * <div class="alert alert-error">
+ * The only appropriate use of `ngInit` for aliasing special properties of
+ * {@link api/ng.directive:ngRepeat `ngRepeat`}, as seen in the demo bellow. Besides this case, you
+ * should use {@link guide/dev_guide.mvc.understanding_controller controllers} rather than `ngInit`
+ * to initialize values on a scope.
+ * </div>
*
* @element ANY
* @param {expression} ngInit {@link guide/expression Expression} to eval.
*
* @example
<doc:example>
<doc:source>
- <div ng-init="greeting='Hello'; person='World'">
- {{greeting}} {{person}}!
- </div>
+ <script>
+ function Ctrl($scope) {
+ $scope.list = [['a', 'b'], ['c', 'd']];
+ }
+ </script>
+ <div ng-controller="Ctrl">
+ <div ng-repeat="innerList in list" ng-init="outerIndex = $index">
+ <div ng-repeat="value in innerList" ng-init="innerIndex = $index">
+ <span class="example-init">list[ {{outerIndex}} ][ {{innerIndex}} ] = {{value}};</span>
+ </div>
+ </div>
+ </div>
</doc:source>
<doc:scenario>
- it('should check greeting', function() {
- expect(binding('greeting')).toBe('Hello');
- expect(binding('person')).toBe('World');
+ it('should alias index positions', function() {
+ expect(element('.example-init').text())
+ .toBe('list[ 0 ][ 0 ] = a;' +
+ 'list[ 0 ][ 1 ] = b;' +
+ 'list[ 1 ][ 0 ] = c;' +
+ 'list[ 1 ][ 1 ] = d;');
});
</doc:scenario>
</doc:example>