diff options
| -rw-r--r-- | src/Scope.js | 175 | ||||
| -rw-r--r-- | test/ScopeSpec.js | 353 |
2 files changed, 451 insertions, 77 deletions
diff --git a/src/Scope.js b/src/Scope.js index e978b659..12ac2833 100644 --- a/src/Scope.js +++ b/src/Scope.js @@ -99,6 +99,7 @@ function Scope() { this.$destructor = noop; this['this'] = this.$root = this; this.$$asyncQueue = []; + this.$$listeners = {}; } /** @@ -155,8 +156,8 @@ Scope.prototype = { * the scope and its child scopes to be permanently detached from the parent and thus stop * participating in model change detection and listener notification by invoking. * - * @param {function()=} constructor Constructor function which the scope should behave as. - * @param {curryArguments=} ... Any additional arguments which are curried into the constructor. + * @param {function()=} Class Constructor function which the scope should be applied to the scope. + * @param {...*} curryArguments Any additional arguments which are curried into the constructor. * See {@link guide/dev_guide.di dependency injection}. * @returns {Object} The newly created child scope. * @@ -169,6 +170,7 @@ Scope.prototype = { Child.prototype = this; child = new Child(); child['this'] = child; + child.$$listeners = {}; child.$parent = this; child.$id = nextUid(); child.$$asyncQueue = []; @@ -392,12 +394,15 @@ Scope.prototype = { * scope and its children. Removal also implies that the current scope is eligible for garbage * collection. * + * The destructing scope emits an `$destroy` {@link angular.scope.$emit event}. + * * The `$destroy()` is usually used by directives such as * {@link angular.widget.@ng:repeat ng:repeat} for managing the unrolling of the loop. * */ $destroy: function() { if (this.$root == this) return; // we can't remove the root node; + this.$emit('$destroy'); var parent = this.$parent; if (parent.$$childHead == this) parent.$$childHead = this.$$nextSibling; @@ -413,7 +418,7 @@ Scope.prototype = { * @function * * @description - * Executes the expression on the current scope returning the result. Any exceptions in the + * Executes the `expression` on the current scope returning the result. Any exceptions in the * expression are propagated (uncaught). This is useful when evaluating engular expressions. * * # Example @@ -520,9 +525,173 @@ Scope.prototype = { } finally { this.$root.$digest(); } + }, + + /** + * @workInProgress + * @ngdoc function + * @name angular.scope.$on + * @function + * + * @description + * Listen on events of a given type. See {@link angular.scope.$emit $emit} for discussion of + * event life cycle. + * + * @param {string} name Event name to listen on. + * @param {function(event)} listener Function to call when the event is emitted. + * + * The event listener function format is: `function(event)`. The `event` object passed into the + * listener has the following attributes + * - `targetScope` - {Scope}: the scope on which the event was `$emit`-ed or `$broadcast`-ed. + * - `currentScope` - {Scope}: the current scope which is handling the event. + * - `name` - {string}: Name of the event. + * - `cancel` - {function=}: calling `cancel` function will cancel further event propagation + * (available only for events that were `$emit`-ed). + */ + $on: function(name, listener) { + var namedListeners = this.$$listeners[name]; + if (!namedListeners) { + this.$$listeners[name] = namedListeners = []; + } + namedListeners.push(listener); + }, + + /** + * @workInProgress + * @ngdoc function + * @name angular.scope.$removeListener + * @function + * + * @description + * Remove the on listener registered by {@link angular.scope.$on $on}. + * + * @param {string} name Event name to remove on. + * @param {function} listener Function to remove. + */ + $removeListener: function(name, listener) { + var namedListeners = this.$$listeners[name]; + var i; + if (namedListeners) { + i = namedListeners.indexOf(listener); + namedListeners.splice(i, 1); + } + }, + + /** + * @workInProgress + * @ngdoc function + * @name angular.scope.$emit + * @function + * + * @description + * Dispatches an event `name` upwards through the scope hierarchy notifying the + * registered {@link angular.scope.$on} listeners. + * + * The event life cycle starts at the scope on which `$emit` was called. All + * {@link angular.scope.$on listeners} listening for `name` event on this scope get notified. + * Afterwards, the event traverses upwards toward the root scope and calls all registered + * listeners along the way. The event will stop propagating if one of the listeners cancels it. + * + * Any exception emmited from the {@link angular.scope.$on listeners} will be passed + * onto the {@link angular.service.$exceptionHandler $exceptionHandler} service. + * + * @param {string} name Event name to emit. + * @param {...*} args Optional set of arguments which will be passed onto the event listeners. + */ + $emit: function(name, args) { + var empty = [], + namedListeners, + canceled = false, + scope = this, + event = { + name: name, + targetScope: scope, + cancel: function(){canceled = true;} + }, + listenerArgs = concat([event], arguments, 1), + i, length; + + do { + namedListeners = scope.$$listeners[name] || empty; + event.currentScope = scope; + for (i=0, length=namedListeners.length; i<length; i++) { + try { + namedListeners[i].apply(null, listenerArgs); + if (canceled) return; + } catch (e) { + scope.$service('$exceptionHandler')(e); + } + } + //traverse upwards + scope = scope.$parent; + } while (scope); + }, + + + /** + * @workInProgress + * @ngdoc function + * @name angular.scope.$broadcast + * @function + * + * @description + * Dispatches an event `name` downwards to all child scopes (and their children) notifying the + * registered {@link angular.scope.$on} listeners. + * + * The event life cycle starts at the scope on which `$broadcast` was called. All + * {@link angular.scope.$on listeners} listening for `name` event on this scope get notified. + * Afterwards, the event propagates to all direct and indirect scopes of the current scope and + * calls all registered listeners along the way. The event cannot be canceled. + * + * Any exception emmited from the {@link angular.scope.$on listeners} will be passed + * onto the {@link angular.service.$exceptionHandler $exceptionHandler} service. + * + * @param {string} name Event name to emit. + * @param {...*} args Optional set of arguments which will be passed onto the event listeners. + */ + $broadcast: function(name, args) { + var targetScope = this, + currentScope = targetScope, + nextScope = targetScope, + event = { name: name, + targetScope: targetScope }, + listenerArgs = concat([event], arguments, 1); + + //down while you can, then up and next sibling or up and next sibling until back at root + do { + currentScope = nextScope; + event.currentScope = currentScope; + forEach(currentScope.$$listeners[name], function(listener) { + try { + listener.apply(null, listenerArgs); + } catch(e) { + currentScope.$service('$exceptionHandler')(e); + } + }); + + // down or to the right! + nextScope = currentScope.$$childHead || currentScope.$$nextSibling; + + if (nextScope) { + // found child or sibling + continue; + } + + // we have to restore nextScope and go up! + nextScope = currentScope; + + while (!nextScope.$$nextSibling && (nextScope != targetScope)) { + nextScope = nextScope.$parent; + } + + if (nextScope != targetScope) { + nextScope = nextScope.$$nextSibling; + } + } while (nextScope != targetScope); } }; + function compileToFn(exp, name) { var fn = isString(exp) ? expressionCompile(exp) diff --git a/test/ScopeSpec.js b/test/ScopeSpec.js index efc8c98c..b3bdf935 100644 --- a/test/ScopeSpec.js +++ b/test/ScopeSpec.js @@ -1,9 +1,9 @@ 'use strict'; -describe('Scope', function(){ +describe('Scope', function() { var root, mockHandler; - beforeEach(function(){ + beforeEach(function() { root = createScope(angular.service, { '$exceptionHandler': $exceptionHandlerMockFactory() }); @@ -11,14 +11,14 @@ describe('Scope', function(){ }); - describe('$root', function(){ - it('should point to itself', function(){ + describe('$root', function() { + it('should point to itself', function() { expect(root.$root).toEqual(root); expect(root.hasOwnProperty('$root')).toBeTruthy(); }); - it('should not have $root on children, but should inherit', function(){ + it('should not have $root on children, but should inherit', function() { var child = root.$new(); expect(child.$root).toEqual(root); expect(child.hasOwnProperty('$root')).toBeFalsy(); @@ -27,13 +27,13 @@ describe('Scope', function(){ }); - describe('$parent', function(){ - it('should point to itself in root', function(){ + describe('$parent', function() { + it('should point to itself in root', function() { expect(root.$root).toEqual(root); }); - it('should point to parent', function(){ + it('should point to parent', function() { var child = root.$new(); expect(root.$parent).toEqual(null); expect(child.$parent).toEqual(root); @@ -42,29 +42,29 @@ describe('Scope', function(){ }); - describe('$id', function(){ - it('should have a unique id', function(){ + describe('$id', function() { + it('should have a unique id', function() { expect(root.$id < root.$new().$id).toBeTruthy(); }); }); - describe('this', function(){ - it('should have a \'this\'', function(){ + describe('this', function() { + it('should have a \'this\'', function() { expect(root['this']).toEqual(root); }); }); - describe('$new()', function(){ - it('should create a child scope', function(){ + describe('$new()', function() { + it('should create a child scope', function() { var child = root.$new(); root.a = 123; expect(child.a).toEqual(123); }); - it('should instantiate controller and bind functions', function(){ + it('should instantiate controller and bind functions', function() { function Cntl($browser, name){ this.$browser = $browser; this.callCount = 0; @@ -73,7 +73,7 @@ describe('Scope', function(){ Cntl.$inject = ['$browser']; Cntl.prototype = { - myFn: function(){ + myFn: function() { expect(this).toEqual(cntl); this.callCount++; } @@ -94,15 +94,15 @@ describe('Scope', function(){ }); - describe('$service', function(){ - it('should have it on root', function(){ + describe('$service', function() { + it('should have it on root', function() { expect(root.hasOwnProperty('$service')).toBeTruthy(); }); }); - describe('$watch/$digest', function(){ - it('should watch and fire on simple property change', function(){ + describe('$watch/$digest', function() { + it('should watch and fire on simple property change', function() { var spy = jasmine.createSpy(); root.$watch('name', spy); root.$digest(); @@ -117,7 +117,7 @@ describe('Scope', function(){ }); - it('should watch and fire on expression change', function(){ + it('should watch and fire on expression change', function() { var spy = jasmine.createSpy(); root.$watch('name.first', spy); root.$digest(); @@ -132,8 +132,8 @@ describe('Scope', function(){ expect(spy).wasCalled(); }); - it('should delegate exceptions', function(){ - root.$watch('a', function(){throw new Error('abc');}); + it('should delegate exceptions', function() { + root.$watch('a', function() {throw new Error('abc');}); root.a = 1; root.$digest(); expect(mockHandler.errors[0].message).toEqual('abc'); @@ -141,34 +141,34 @@ describe('Scope', function(){ }); - it('should fire watches in order of addition', function(){ + it('should fire watches in order of addition', function() { // this is not an external guarantee, just our own sanity var log = ''; - root.$watch('a', function(){ log += 'a'; }); - root.$watch('b', function(){ log += 'b'; }); - root.$watch('c', function(){ log += 'c'; }); + root.$watch('a', function() { log += 'a'; }); + root.$watch('b', function() { log += 'b'; }); + root.$watch('c', function() { log += 'c'; }); root.a = root.b = root.c = 1; root.$digest(); expect(log).toEqual('abc'); }); - it('should delegate $digest to children in addition order', function(){ + it('should delegate $digest to children in addition order', function() { // this is not an external guarantee, just our own sanity var log = ''; var childA = root.$new(); var childB = root.$new(); var childC = root.$new(); - childA.$watch('a', function(){ log += 'a'; }); - childB.$watch('b', function(){ log += 'b'; }); - childC.$watch('c', function(){ log += 'c'; }); + childA.$watch('a', function() { log += 'a'; }); + childB.$watch('b', function() { log += 'b'; }); + childC.$watch('c', function() { log += 'c'; }); childA.a = childB.b = childC.c = 1; root.$digest(); expect(log).toEqual('abc'); }); - it('should repeat watch cycle while model changes are identified', function(){ + it('should repeat watch cycle while model changes are identified', function() { var log = ''; root.$watch('c', function(self, v){self.d = v; log+='c'; }); root.$watch('b', function(self, v){self.c = v; log+='b'; }); @@ -183,32 +183,32 @@ describe('Scope', function(){ expect(log).toEqual('abc'); }); - it('should repeat watch cycle from the root elemnt', function(){ + it('should repeat watch cycle from the root elemnt', function() { var log = ''; var child = root.$new(); - root.$watch(function(){ log += 'a'; }); - child.$watch(function(){ log += 'b'; }); + root.$watch(function() { log += 'a'; }); + child.$watch(function() { log += 'b'; }); root.$digest(); expect(log).toEqual('abab'); }); - it('should prevent infinite recursion', function(){ + it('should prevent infinite recursion', function() { root.$watch('a', function(self, v){self.b++;}); root.$watch('b', function(self, v){self.a++;}); root.a = root.b = 0; - expect(function(){ + expect(function() { root.$digest(); }).toThrow('100 $digest() iterations reached. Aborting!'); }); - it('should not fire upon $watch registration on initial $digest', function(){ + it('should not fire upon $watch registration on initial $digest', function() { var log = ''; root.a = 1; - root.$watch('a', function(){ log += 'a'; }); - root.$watch('b', function(){ log += 'b'; }); + root.$watch('a', function() { log += 'a'; }); + root.$watch('b', function() { log += 'b'; }); root.$digest(); log = ''; root.$digest(); @@ -216,12 +216,12 @@ describe('Scope', function(){ }); - it('should watch objects', function(){ + it('should watch objects', function() { var log = ''; root.a = []; root.b = {}; - root.$watch('a', function(){ log +='.';}); - root.$watch('b', function(){ log +='!';}); + root.$watch('a', function() { log +='.';}); + root.$watch('b', function() { log +='!';}); root.$digest(); log = ''; @@ -233,10 +233,10 @@ describe('Scope', function(){ }); - it('should prevent recursion', function(){ + it('should prevent recursion', function() { var callCount = 0; - root.$watch('name', function(){ - expect(function(){ + root.$watch('name', function() { + expect(function() { root.$digest(); }).toThrow('$digest already in progress'); callCount++; @@ -248,56 +248,66 @@ describe('Scope', function(){ }); - describe('$destroy', function(){ + describe('$destroy', function() { var first, middle, last, log; - beforeEach(function(){ + beforeEach(function() { log = ''; first = root.$new(); middle = root.$new(); last = root.$new(); - first.$watch(function(){ log += '1';}); - middle.$watch(function(){ log += '2';}); - last.$watch(function(){ log += '3';}); + first.$watch(function() { log += '1';}); + middle.$watch(function() { log += '2';}); + last.$watch(function() { log += '3';}); root.$digest(); log = ''; }); - it('should ignore remove on root', function(){ + it('should ignore remove on root', function() { root.$destroy(); root.$digest(); expect(log).toEqual('123'); }); - it('should remove first', function(){ + it('should remove first', function() { first.$destroy(); root.$digest(); expect(log).toEqual('23'); }); - it('should remove middle', function(){ + it('should remove middle', function() { middle.$destroy(); root.$digest(); expect(log).toEqual('13'); }); - it('should remove last', function(){ + it('should remove last', function() { last.$destroy(); root.$digest(); expect(log).toEqual('12'); }); + + it('should fire a $destroy event', function() { + var destructedScopes = []; + middle.$on('$destroy', function(event) { + destructedScopes.push(event.currentScope); + }); + middle.$destroy(); + expect(destructedScopes).toEqual([middle]); + }); + }); - describe('$eval', function(){ - it('should eval an expression', function(){ + describe('$eval', function() { + it('should eval an expression', function() { expect(root.$eval('a=1')).toEqual(1); expect(root.a).toEqual(1); @@ -306,24 +316,24 @@ describe('Scope', function(){ }); }); - describe('$evalAsync', function(){ + describe('$evalAsync', function() { - it('should run callback before $watch', function(){ + it('should run callback before $watch', function() { var log = ''; var child = root.$new(); root.$evalAsync(function(scope){ log += 'parent.async;'; }); - root.$watch('value', function(){ log += 'parent.$digest;'; }); + root.$watch('value', function() { log += 'parent.$digest;'; }); child.$evalAsync(function(scope){ log += 'child.async;'; }); - child.$watch('value', function(){ log += 'child.$digest;'; }); + child.$watch('value', function() { log += 'child.$digest;'; }); root.$digest(); expect(log).toEqual('parent.async;parent.$digest;child.async;child.$digest;'); }); - it('should cause a $digest rerun', function(){ + it('should cause a $digest rerun', function() { root.log = ''; root.value = 0; root.$watch('value', 'log = log + ".";'); - root.$watch('init', function(){ + root.$watch('init', function() { root.$evalAsync('value = 123; log = log + "=" '); expect(root.value).toEqual(0); }); @@ -331,7 +341,7 @@ describe('Scope', function(){ expect(root.log).toEqual('.=.'); }); - it('should run async in the same order as added', function(){ + it('should run async in the same order as added', function() { root.log = ''; root.$evalAsync("log = log + 1"); root.$evalAsync("log = log + 2"); @@ -342,8 +352,8 @@ describe('Scope', function(){ }); - describe('$apply', function(){ - it('should apply expression with full lifecycle', function(){ + describe('$apply', function() { + it('should apply expression with full lifecycle', function() { var log = ''; var child = root.$new(); root.$watch('a', function(scope, a){ log += '1'; }); @@ -352,33 +362,33 @@ describe('Scope', function(){ }); - it('should catch exceptions', function(){ + it('should catch exceptions', function() { var log = ''; var child = root.$new(); root.$watch('a', function(scope, a){ log += '1'; }); root.a = 0; - child.$apply(function(){ throw new Error('MyError'); }); + child.$apply(function() { throw new Error('MyError'); }); expect(log).toEqual('1'); expect(mockHandler.errors[0].message).toEqual('MyError'); $logMock.error.logs.shift(); }); - describe('exceptions', function(){ + describe('exceptions', function() { var $exceptionHandler, log; - beforeEach(function(){ + beforeEach(function() { log = ''; $exceptionHandler = jasmine.createSpy('$exceptionHandler'); root.$service = function(name) { return {$exceptionHandler:$exceptionHandler}[name]; }; - root.$watch(function(){ log += '$digest;'; }); + root.$watch(function() { log += '$digest;'; }); root.$digest(); log = ''; }); - it('should execute and return value and update', function(){ + it('should execute and return value and update', function() { root.name = 'abc'; expect(root.$apply(function(scope){ return scope.name; @@ -388,12 +398,207 @@ describe('Scope', function(){ }); - it('should catch exception and update', function(){ + it('should catch exception and update', function() { var error = new Error('MyError'); - root.$apply(function(){ throw error; }); + root.$apply(function() { throw error; }); expect(log).toEqual('$digest;'); expect($exceptionHandler).wasCalledWith(error); }); }); }); + + + describe('events', function() { + + describe('$emit', function() { + var log, child, grandChild, greatGrandChild; + + function logger(event) { + log += event.currentScope.id + '>'; + } + + beforeEach(function() { + log = ''; + child = root.$new(); + grandChild = child.$new(); + greatGrandChild = grandChild.$new(); + + root.id = 0; + child.id = 1; + grandChild.id = 2; + greatGrandChild.id = 3; + + root.$on('myEvent', logger); + child.$on('myEvent', logger); + grandChild.$on('myEvent', logger); + greatGrandChild.$on('myEvent', logger); + }); + + + it('should bubble event up to the root scope', function() { + grandChild.$emit('myEvent'); + expect(log).toEqual('2>1>0>'); + }); + + + it('should dispatch exceptions to the $exceptionHandler', function() { + child.$on('myEvent', function() { throw 'bubbleException'; }); + grandChild.$emit('myEvent'); + expect(log).toEqual('2>1>0>'); + expect(mockHandler.errors).toEqual(['bubbleException']); + }); + + + it('should allow cancelation of event propagation', function() { + child.$on('myEvent', function(event){ event.cancel(); }); + grandChild.$emit('myEvent'); + expect(log).toEqual('2>1>'); + }); + + + it('should remove event listener', function() { + function eventFn(){ + log += 'abc;'; + } + + child.$on('abc', eventFn); + child.$emit('abc'); + expect(log).toEqual('abc;'); + log = ''; + child.$removeListener('abc', eventFn); + child.$emit('abc'); + expect(log).toEqual(''); + }); + + + it('should forward method arguments', function() { + child.$on('abc', function(event, arg1, arg2){ + expect(event.name).toBe('abc'); + expect(arg1).toBe('arg1'); + expect(arg2).toBe('arg2'); + }); + child.$emit('abc', 'arg1', 'arg2'); + }); + + describe('event object', function() { + it('should have methods/properties', function() { + var event; + child.$on('myEvent', function(e){ + expect(e.targetScope).toBe(grandChild); + expect(e.currentScope).toBe(child); + expect(e.name).toBe('myEvent'); + event = e; + }); + grandChild.$emit('myEvent'); + expect(event).toBeDefined(); + }); + }); + }); + + + describe('$broadcast', function() { + describe('event propagation', function() { + var log, child1, child2, child3, grandChild11, grandChild21, grandChild22, + greatGrandChild211; + + function logger(event) { + log += event.currentScope.id + '>'; + } + + beforeEach(function() { + log = ''; + child1 = root.$new(); + child2 = root.$new(); + child3 = root.$new(); + grandChild11 = child1.$new(); + grandChild21 = child2.$new(); + grandChild22 = child2.$new(); + greatGrandChild211 = grandChild21.$new(); + + root.id = 0; + child1.id = 1; + child2.id = 2; + child3.id = 3; + grandChild11.id = 11; + grandChild21.id = 21; + grandChild22.id = 22; + greatGrandChild211.id = 211; + + root.$on('myEvent', logger); + child1.$on('myEvent', logger); + child2.$on('myEvent', logger); + child3.$on('myEvent', logger); + grandChild11.$on('myEvent', logger); + grandChild21.$on('myEvent', logger); + grandChild22.$on('myEvent', logger); + greatGrandChild211.$on('myEvent', logger); + + // R + // / | \ + // 1 2 3 + // / / \ + // 11 21 22 + // | + // 211 + }); + + + it('should broadcast an event from the root scope', function() { + root.$broadcast('myEvent'); + expect(log).toBe('0>1>11>2>21>211>22>3>'); + }); + + + it('should broadcast an event from a child scope', function() { + child2.$broadcast('myEvent'); + expect(log).toBe('2>21>211>22>'); + }); + + + it('should broadcast an event from a leaf scope', function() { + grandChild22.$broadcast('myEvent'); + expect(log).toBe('22>'); + }); + + + it('should not not fire any listeners for other events', function() { + root.$broadcast('fooEvent'); + expect(log).toBe(''); + }); + }); + + + describe('listener', function() { + it('should receive event object', function() { + var scope = angular.scope(), + child = scope.$new(), + event; + + child.$on('fooEvent', function(e) { + event = e; + }); + scope.$broadcast('fooEvent'); + + expect(event.name).toBe('fooEvent'); + expect(event.targetScope).toBe(scope); + expect(event.currentScope).toBe(child); + }); + + + it('should support passing messages as varargs', function() { + var scope = angular.scope(), + child = scope.$new(), + args; + + child.$on('fooEvent', function() { + args = arguments; + }); + scope.$broadcast('fooEvent', 'do', 're', 'me', 'fa'); + + expect(args.length).toBe(5); + expect([].splice.call(args, 1)).toEqual(['do', 're', 'me', 'fa']); + }); + }); + }); + }); }); |