feat(ngIf): add directive to remove and recreate DOM elements

This directive is adapted from ui-if in the AngularUI project and provides a complement
to the ngShow/ngHide directives that only change the visibility of the DOM element and
ngSwitch which does change the DOM but is more verbose.

angularFiles.js

@@ -49,6 +49,7 @@ angularFiles = {
  'src/ng/directive/ngController.js',
  'src/ng/directive/ngCsp.js',
  'src/ng/directive/ngEventDirs.js',
+ 'src/ng/directive/ngIf.js',
  'src/ng/directive/ngInclude.js',
  'src/ng/directive/ngInit.js',
  'src/ng/directive/ngNonBindable.js',

src/AngularPublic.js

@@ -82,6 +82,7 @@ function publishExternalAPI(angular){
  ngController: ngControllerDirective,
  ngForm: ngFormDirective,
  ngHide: ngHideDirective,
+ ngIf: ngIfDirective,
  ngInclude: ngIncludeDirective,
  ngInit: ngInitDirective,
  ngNonBindable: ngNonBindableDirective,

src/ng/directive/ngIf.js

@@ -0,0 +1,83 @@
+'use strict';
+
+/**
+ * @ngdoc directive
+ * @name ng.directive:ngIf
+ * @restrict A
+ *
+ * @description
+ * The `ngIf` directive removes and recreates a portion of the DOM tree (HTML)
+ * conditionally based on **"falsy"** and **"truthy"** values, respectively, evaluated within
+ * an {expression}. In other words, if the expression assigned to **ngIf evaluates to a false
+ * value** then **the element is removed from the DOM** and **if true** then **a clone of the
+ * element is reinserted into the DOM**.
+ *
+ * `ngIf` differs from `ngShow` and `ngHide` in that `ngIf` completely removes and recreates the
+ * element in the DOM rather than changing its visibility via the `display` css property. A common
+ * case when this difference is significant is when using css selectors that rely on an element's
+ * position within the DOM (HTML), such as the `:first-child` or `:last-child` pseudo-classes.
+ *
+ * Note that **when an element is removed using ngIf its scope is destroyed** and **a new scope
+ * is created when the element is restored**. The scope created within `ngIf` inherits from 
+ * its parent scope using
+ * {@link https://github.com/angular/angular.js/wiki/The-Nuances-of-Scope-Prototypal-Inheritance prototypal inheritance}.
+ * An important implication of this is if `ngModel` is used within `ngIf` to bind to
+ * a javascript primitive defined in the parent scope. In this case any modifications made to the
+ * variable within the child scope will override (hide) the value in the parent scope.
+ *
+ * Also, `ngIf` recreates elements using their compiled state. An example scenario of this behavior
+ * is if an element's class attribute is directly modified after it's compiled, using something like 
+ * jQuery's `.addClass()` method, and the element is later removed. When `ngIf` recreates the element
+ * the added class will be lost because the original compiled state is used to regenerate the element.
+ *
+ * Additionally, you can provide animations via the ngAnimate attribute to animate the **enter**
+ * and **leave** effects.
+ *
+ * @animations
+ * enter - happens just after the ngIf contents change and a new DOM element is created and injected into the ngIf container
+ * leave - happens just before the ngIf contents are removed from the DOM
+ *
+ * @element ANY
+ * @scope
+ * @param {expression} ngIf If the {@link guide/expression expression} is falsy then
+ * the element is removed from the DOM tree (HTML).
+ *
+ * @example
+ <doc:example>
+ <doc:source>
+ Click me: <input type="checkbox" ng-model="checked" ng-init="checked=true" /><br/>
+ Show when checked: <span ng-if="checked">I'm removed when the checkbox is unchecked</span>
+ </doc:source>
+ </doc:example>
+ */
+var ngIfDirective = ['$animator', function($animator) {
+ return {
+ transclude: 'element',
+ priority: 1000,
+ terminal: true,
+ restrict: 'A',
+ compile: function (element, attr, transclude) {
+ return function ($scope, $element, $attr) {
+ var animate = $animator($scope, $attr);
+ var childElement, childScope;
+ $scope.$watch($attr.ngIf, function ngIfWatchAction(value) {
+ if (childElement) {
+ animate.leave(childElement);
+ childElement = undefined;
+ }
+ if (childScope) {
+ childScope.$destroy();
+ childScope = undefined;
+ }
+ if (toBoolean(value)) {
+ childScope = $scope.$new();
+ transclude(childScope, function (clone) {
+ childElement = clone;
+ animate.enter(clone, $element.parent(), $element);
+ });
+ }
+ });
+ }
+ }
+ }
+}];

test/ng/directive/ngIfSpec.js

@@ -0,0 +1,191 @@
+'use strict';
+
+describe('ngIf', function () {
+ var $scope, $compile, element;
+
+ beforeEach(inject(function ($rootScope, _$compile_) {
+ $scope = $rootScope.$new();
+ $compile = _$compile_;
+ element = $compile('<div></div>')($scope);
+ }));
+
+ afterEach(function () {
+ dealoc(element);
+ });
+
+ function makeIf(expr) {
+ element.append($compile('<div class="my-class" ng-if="' + expr + '"><div>Hi</div></div>')($scope));
+ $scope.$apply();
+ }
+
+ it('should immediately remove element if condition is false', function () {
+ makeIf('false');
+ expect(element.children().length).toBe(0);
+ });
+
+ it('should leave the element if condition is true', function () {
+ makeIf('true');
+ expect(element.children().length).toBe(1);
+ });
+
+ it('should create then remove the element if condition changes', function () {
+ $scope.hello = true;
+ makeIf('hello');
+ expect(element.children().length).toBe(1);
+ $scope.$apply('hello = false');
+ expect(element.children().length).toBe(0);
+ });
+
+ it('should create a new scope', function () {
+ $scope.$apply('value = true');
+ element.append($compile(
+ '<div ng-if="value"><span ng-init="value=false"></span></div>'
+ )($scope));
+ $scope.$apply();
+ expect(element.children('div').length).toBe(1);
+ });
+
+ it('should play nice with other elements beside it', function () {
+ $scope.values = [1, 2, 3, 4];
+ element.append($compile(
+ '<div ng-repeat="i in values"></div>' +
+ '<div ng-if="values.length==4"></div>' +
+ '<div ng-repeat="i in values"></div>'
+ )($scope));
+ $scope.$apply();
+ expect(element.children().length).toBe(9);
+ $scope.$apply('values.splice(0,1)');
+ expect(element.children().length).toBe(6);
+ $scope.$apply('values.push(1)');
+ expect(element.children().length).toBe(9);
+ });
+
+ it('should restore the element to its compiled state', function() {
+ $scope.value = true;
+ makeIf('value');
+ expect(element.children().length).toBe(1);
+ jqLite(element.children()[0]).removeClass('my-class');
+ expect(element.children()[0].className).not.toContain('my-class');
+ $scope.$apply('value = false');
+ expect(element.children().length).toBe(0);
+ $scope.$apply('value = true');
+ expect(element.children().length).toBe(1);
+ expect(element.children()[0].className).toContain('my-class');
+ });
+
+});
+
+describe('ngIf ngAnimate', function () {
+ var vendorPrefix, window;
+ var body, element;
+
+ function html(html) {
+ body.html(html);
+ element = body.children().eq(0);
+ return element;
+ }
+
+ beforeEach(function() {
+ // we need to run animation on attached elements;
+ body = jqLite(document.body);
+ });
+
+ afterEach(function(){
+ dealoc(body);
+ dealoc(element);
+ });
+
+ beforeEach(module(function($animationProvider, $provide) {
+ $provide.value('$window', window = angular.mock.createMockWindow());
+ return function($sniffer, $animator) {
+ vendorPrefix = '-' + $sniffer.vendorPrefix + '-';
+ $animator.enabled(true);
+ };
+ }));
+
+ it('should fire off the enter animation + add and remove the css classes',
+ inject(function($compile, $rootScope, $sniffer) {
+ var $scope = $rootScope.$new();
+ var style = vendorPrefix + 'transition: 1s linear all';
+ element = $compile(html(
+ '<div>' +
+ '<div ng-if="value" style="' + style + '" ng-animate="{enter: \'custom-enter\', leave: \'custom-leave\'}"><div>Hi</div></div>' +
+ '</div>'
+ ))($scope);
+
+ $rootScope.$digest();
+ $scope.$apply('value = true');
+
+
+ expect(element.children().length).toBe(1);
+ var first = element.children()[0];
+
+ if ($sniffer.supportsTransitions) {
+ expect(first.className).toContain('custom-enter-setup');
+ window.setTimeout.expect(1).process();
+ expect(first.className).toContain('custom-enter-start');
+ window.setTimeout.expect(1000).process();
+ } else {
+ expect(window.setTimeout.queue).toEqual([]);
+ }
+
+ expect(first.className).not.toContain('custom-enter-setup');
+ expect(first.className).not.toContain('custom-enter-start');
+ }));
+
+ it('should fire off the leave animation + add and remove the css classes',
+ inject(function ($compile, $rootScope, $sniffer) {
+ var $scope = $rootScope.$new();
+ var style = vendorPrefix + 'transition: 1s linear all';
+ element = $compile(html(
+ '<div>' +
+ '<div ng-if="value" style="' + style + '" ng-animate="{enter: \'custom-enter\', leave: \'custom-leave\'}"><div>Hi</div></div>' +
+ '</div>'
+ ))($scope);
+ $scope.$apply('value = true');
+
+ expect(element.children().length).toBe(1);
+ var first = element.children()[0];
+
+ if ($sniffer.supportsTransitions) {
+ window.setTimeout.expect(1).process();
+ window.setTimeout.expect(1000).process();
+ } else {
+ expect(window.setTimeout.queue).toEqual([]);
+ }
+
+ $scope.$apply('value = false');
+ expect(element.children().length).toBe($sniffer.supportsTransitions ? 1 : 0);
+
+ if ($sniffer.supportsTransitions) {
+ expect(first.className).toContain('custom-leave-setup');
+ window.setTimeout.expect(1).process();
+ expect(first.className).toContain('custom-leave-start');
+ window.setTimeout.expect(1000).process();
+ } else {
+ expect(window.setTimeout.queue).toEqual([]);
+ }
+
+ expect(element.children().length).toBe(0);
+ }));
+
+ it('should catch and use the correct duration for animation',
+ inject(function ($compile, $rootScope, $sniffer) {
+ var $scope = $rootScope.$new();
+ var style = vendorPrefix + 'transition: 0.5s linear all';
+ element = $compile(html(
+ '<div>' +
+ '<div ng-if="value" style="' + style + '" ng-animate="{enter: \'custom-enter\', leave: \'custom-leave\'}"><div>Hi</div></div>' +
+ '</div>'
+ ))($scope);
+ $scope.$apply('value = true');
+
+ if ($sniffer.supportsTransitions) {
+ window.setTimeout.expect(1).process();
+ window.setTimeout.expect(500).process();
+ } else {
+ expect(window.setTimeout.queue).toEqual([]);
+ }
+ }));
+
+});