knowhow-server

<a href="http://github.com/angular/angular.js/tree/v1.2.9/src/ng/rootScope.js#L86" class="view-source btn btn-action"><i class="icon-zoom-in"> </i> View source</a><a href="http://github.com/angular/angular.js/edit/master/src/ng/rootScope.js" class="improve-docs btn btn-primary"><i class="icon-edit"> </i> Improve this doc</a><h1><code ng:non-bindable="">Scope</code> <div><span class="hint">type in module <code ng:non-bindable="">ng</code> </span> </div> </h1> <div><h2 id="description">Description</h2> <div class="description"><div class="ng-rootscope-scope-page"><p>A root scope can be retrieved using the <a href="api/ng.$rootScope"><code>$rootScope</code></a> key from the <a href="api/AUTO.$injector"><code>$injector</code></a>. Child scopes are created using the <a href="api/ng.$rootScope.Scope#methods_$new"><code>$new()</code></a> method. (Most scopes are created automatically when compiled HTML template is executed.)</p> <p>Here is a simple scope snippet to show how you can interact with the scope. <pre class="prettyprint linenums"> var scope = $rootScope.$new(); scope.salutation = 'Hello'; scope.name = 'World'; expect(scope.greeting).toEqual(undefined); scope.$watch('name', function() { scope.greeting = scope.salutation + ' ' + scope.name + '!'; }); // initialize the watch expect(scope.greeting).toEqual(undefined); scope.name = 'Misko'; // still old value, since watches have not been called yet expect(scope.greeting).toEqual(undefined); scope.$digest(); // fire all the watches expect(scope.greeting).toEqual('Hello Misko!'); </pre> <h3 id="description_inheritance">Inheritance</h3> <p>A scope can inherit from a parent scope, as in this example: <pre class="prettyprint linenums"> var parent = $rootScope; var child = parent.$new(); parent.salutation = "Hello"; child.name = "World"; expect(child.salutation).toEqual('Hello'); child.salutation = "Welcome"; expect(child.salutation).toEqual('Welcome'); expect(parent.salutation).toEqual('Hello'); </pre> </div></div> <h2 id="usage">Usage</h2> <div class="usage"><pre class="prettyprint linenums">Scope([providers][, instanceCache]);</pre> <h4 id="usage_parameters">Parameters</h4><table class="variables-matrix table table-bordered table-striped"><thead><tr><th>Param</th><th>Type</th><th>Details</th></tr></thead><tbody><tr><td>providers <div><em>(optional)</em></div></td><td><a href="" class="label type-hint type-hint-object">Object.<string, function()></a></td><td><div class="ng-rootscope-scope-page"><p>Map of service factory which need to be provided for the current scope. Defaults to <a href="api/ng">ng</a>.</p> </div></td></tr><tr><td>instanceCache <div><em>(optional)</em></div></td><td><a href="" class="label type-hint type-hint-object">Object.<string, *></a></td><td><div class="ng-rootscope-scope-page"><p>Provides pre-instantiated services which should append/override services provided by <code>providers</code>. This is handy when unit-testing and having the need to override a default service.</p> </div></td></tr></tbody></table><h4 id="usage_returns">Returns</h4><table class="variables-matrix"><tr><td><a href="" class="label type-hint type-hint-object">Object</a></td><td><div class="ng-rootscope-scope-page"><p>Newly created scope.</p> </div></td></tr></table></div> <div class="member method"><h2 id="methods">Methods</h2> <ul class="methods"><li><h3 id="methods_$apply">$apply(exp)</h3> <div class="$apply"><div class="ng-rootscope-scope-apply-page"><p><code>$apply()</code> is used to execute an expression in angular from outside of the angular framework. (For example from browser DOM events, setTimeout, XHR or third party libraries). Because we are calling into the angular framework we need to perform proper scope life cycle of <a href="api/ng.$exceptionHandler"><code>exception handling</code></a>, <a href="api/ng.$rootScope.Scope#methods_$digest"><code>executing watches</code></a>.</p> <h5 id="methods_$apply_life-cycle">Life cycle</h5> <h4 id="methods_$apply_pseudo-code-of">Pseudo-Code of <code>$apply()</code></h4> <pre class="prettyprint linenums"> function $apply(expr) { try { return $eval(expr); } catch (e) { $exceptionHandler(e); } finally { $root.$digest(); } } </pre> <p>Scope's <code>$apply()</code> method transitions through the following stages:</p> <ol> <li>The <a href="guide/expression">expression</a> is executed using the <a href="api/ng.$rootScope.Scope#methods_$eval"><code>$eval()</code></a> method.</li> <li>Any exceptions from the execution of the expression are forwarded to the <a href="api/ng.$exceptionHandler"><code>$exceptionHandler</code></a> service.</li> <li>The <a href="api/ng.$rootScope.Scope#methods_$watch"><code>watch</code></a> listeners are fired immediately after the expression was executed using the <a href="api/ng.$rootScope.Scope#methods_$digest"><code>$digest()</code></a> method.</li> </ol> </div><h5 id="methods_$apply_pseudo-code-of_parameters">Parameters</h5><table class="variables-matrix table table-bordered table-striped"><thead><tr><th>Param</th><th>Type</th><th>Details</th></tr></thead><tbody><tr><td>exp <div><em>(optional)</em></div></td><td><a href="" class="label type-hint type-hint-string">string</a><a href="" class="label type-hint type-hint-function">function()</a></td><td><div class="ng-rootscope-scope-apply-page"><p>An angular expression to be executed.</p> <ul> <li><code>string</code>: execute using the rules as defined in <a href="guide/expression">expression</a>.</li> <li><code>function(scope)</code>: execute the function with current <code>scope</code> parameter.</li> </ul> </div></td></tr></tbody></table><h5 id="methods_$apply_pseudo-code-of_returns">Returns</h5><table class="variables-matrix"><tr><td><a href="" class="label type-hint type-hint-object">*</a></td><td><div class="ng-rootscope-scope-apply-page"><p>The result of evaluating the expression.</p> </div></td></tr></table></div> </li> <li><h3 id="methods_$broadcast">$broadcast(name, args)</h3> <div class="$broadcast"><div class="ng-rootscope-scope-broadcast-page"><p>Dispatches an event <code>name</code> downwards to all child scopes (and their children) notifying the registered <a href="api/ng.$rootScope.Scope#methods_$on"><code>ng.$rootScope.Scope#methods_$on</code></a> listeners.</p> <p>The event life cycle starts at the scope on which <code>$broadcast</code> was called. All <a href="api/ng.$rootScope.Scope#methods_$on"><code>listeners</code></a> listening for <code>name</code> 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.</p> <p>Any exception emitted from the <a href="api/ng.$rootScope.Scope#methods_$on"><code>listeners</code></a> will be passed onto the <a href="api/ng.$exceptionHandler"><code>$exceptionHandler</code></a> service.</p> </div><h5 id="methods_$broadcast_parameters">Parameters</h5><table class="variables-matrix table table-bordered table-striped"><thead><tr><th>Param</th><th>Type</th><th>Details</th></tr></thead><tbody><tr><td>name</td><td><a href="" class="label type-hint type-hint-string">string</a></td><td><div class="ng-rootscope-scope-broadcast-page"><p>Event name to broadcast.</p> </div></td></tr><tr><td>args</td><td><a href="" class="label type-hint type-hint-object">...*</a></td><td><div class="ng-rootscope-scope-broadcast-page"><p>Optional set of arguments which will be passed onto the event listeners.</p> </div></td></tr></tbody></table><h5 id="methods_$broadcast_returns">Returns</h5><table class="variables-matrix"><tr><td><a href="" class="label type-hint type-hint-object">Object</a></td><td><div class="ng-rootscope-scope-broadcast-page"><p>Event object, see <a href="api/ng.$rootScope.Scope#methods_$on"><code>ng.$rootScope.Scope#methods_$on</code></a></p> </div></td></tr></table></div> </li> <li><h3 id="methods_$destroy">$destroy()</h3> <div class="$destroy"><div class="ng-rootscope-scope-destroy-page"><p>Removes the current scope (and all of its children) from the parent scope. Removal implies that calls to <a href="api/ng.$rootScope.Scope#methods_$digest"><code>$digest()</code></a> will no longer propagate to the current scope and its children. Removal also implies that the current scope is eligible for garbage collection.</p> <p>The <code>$destroy()</code> is usually used by directives such as <a href="api/ng.directive:ngRepeat"><code>ngRepeat</code></a> for managing the unrolling of the loop.</p> <p>Just before a scope is destroyed, a <code>$destroy</code> event is broadcasted on this scope. Application code can register a <code>$destroy</code> event handler that will give it a chance to perform any necessary cleanup.</p> <p>Note that, in AngularJS, there is also a <code>$destroy</code> jQuery event, which can be used to clean up DOM bindings before an element is removed from the DOM.</p> </div></div> </li> <li><h3 id="methods_$digest">$digest()</h3> <div class="$digest"><div class="ng-rootscope-scope-digest-page"><p>Processes all of the <a href="api/ng.$rootScope.Scope#methods_$watch"><code>watchers</code></a> of the current scope and its children. Because a <a href="api/ng.$rootScope.Scope#methods_$watch"><code>watcher</code></a>'s listener can change the model, the <code>$digest()</code> keeps calling the <a href="api/ng.$rootScope.Scope#methods_$watch"><code>watchers</code></a> until no more listeners are firing. This means that it is possible to get into an infinite loop. This function will throw <code>'Maximum iteration limit exceeded.'</code> if the number of iterations exceeds 10.</p> <p>Usually, you don't call <code>$digest()</code> directly in <a href="api/ng.directive:ngController"><code>controllers</code></a> or in <a href="api/ng.$compileProvider#methods_directive"><code>directives</code></a>. Instead, you should call <a href="api/ng.$rootScope.Scope#methods_$apply"><code>$apply()</code></a> (typically from within a <a href="api/ng.$compileProvider#methods_directive"><code>directives</code></a>), which will force a <code>$digest()</code>.</p> <p>If you want to be notified whenever <code>$digest()</code> is called, you can register a <code>watchExpression</code> function with <a href="api/ng.$rootScope.Scope#methods_$watch"><code>$watch()</code></a> with no <code>listener</code>.</p> <p>In unit tests, you may need to call <code>$digest()</code> to simulate the scope life cycle.</p> <h4 id="methods_$digest_example">Example</h4> <pre class="prettyprint linenums"> var scope = ...; scope.name = 'misko'; scope.counter = 0; expect(scope.counter).toEqual(0); scope.$watch('name', function(newValue, oldValue) { scope.counter = scope.counter + 1; }); expect(scope.counter).toEqual(0); scope.$digest(); // no variable change expect(scope.counter).toEqual(0); scope.name = 'adam'; scope.$digest(); expect(scope.counter).toEqual(1); </pre> </div></div> </li> <li><h3 id="methods_$emit">$emit(name, args)</h3> <div class="$emit"><div class="ng-rootscope-scope-emit-page"><p>Dispatches an event <code>name</code> upwards through the scope hierarchy notifying the registered <a href="api/ng.$rootScope.Scope#methods_$on"><code>ng.$rootScope.Scope#methods_$on</code></a> listeners.</p> <p>The event life cycle starts at the scope on which <code>$emit</code> was called. All <a href="api/ng.$rootScope.Scope#methods_$on"><code>listeners</code></a> listening for <code>name</code> 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.</p> <p>Any exception emitted from the <a href="api/ng.$rootScope.Scope#methods_$on"><code>listeners</code></a> will be passed onto the <a href="api/ng.$exceptionHandler"><code>$exceptionHandler</code></a> service.</p> </div><h5 id="methods_$emit_parameters">Parameters</h5><table class="variables-matrix table table-bordered table-striped"><thead><tr><th>Param</th><th>Type</th><th>Details</th></tr></thead><tbody><tr><td>name</td><td><a href="" class="label type-hint type-hint-string">string</a></td><td><div class="ng-rootscope-scope-emit-page"><p>Event name to emit.</p> </div></td></tr><tr><td>args</td><td><a href="" class="label type-hint type-hint-object">...*</a></td><td><div class="ng-rootscope-scope-emit-page"><p>Optional set of arguments which will be passed onto the event listeners.</p> </div></td></tr></tbody></table><h5 id="methods_$emit_returns">Returns</h5><table class="variables-matrix"><tr><td><a href="" class="label type-hint type-hint-object">Object</a></td><td><div class="ng-rootscope-scope-emit-page"><p>Event object (see <a href="api/ng.$rootScope.Scope#methods_$on"><code>ng.$rootScope.Scope#methods_$on</code></a>).</p> </div></td></tr></table></div> </li> <li><h3 id="methods_$eval">$eval(expression, locals)</h3> <div class="$eval"><div class="ng-rootscope-scope-eval-page"><p>Executes the <code>expression</code> on the current scope and returns the result. Any exceptions in the expression are propagated (uncaught). This is useful when evaluating Angular expressions.</p> <h4 id="methods_$eval_example">Example</h4> <pre class="prettyprint linenums"> var scope = ng.$rootScope.Scope(); scope.a = 1; scope.b = 2; expect(scope.$eval('a+b')).toEqual(3); expect(scope.$eval(function(scope){ return scope.a + scope.b; })).toEqual(3); </pre> </div><h5 id="methods_$eval_example_parameters">Parameters</h5><table class="variables-matrix table table-bordered table-striped"><thead><tr><th>Param</th><th>Type</th><th>Details</th></tr></thead><tbody><tr><td>expression <div><em>(optional)</em></div></td><td><a href="" class="label type-hint type-hint-string">string</a><a href="" class="label type-hint type-hint-function">function()</a></td><td><div class="ng-rootscope-scope-eval-page"><p>An angular expression to be executed.</p> <ul> <li><code>string</code>: execute using the rules as defined in <a href="guide/expression">expression</a>.</li> <li><code>function(scope)</code>: execute the function with the current <code>scope</code> parameter.</li> </ul> </div></td></tr><tr><td>locals <div><em>(optional)</em></div></td><td><a href="" class="label type-hint type-hint-object">object</a></td><td><div class="ng-rootscope-scope-eval-page"><p>Local variables object, useful for overriding values in scope.</p> </div></td></tr></tbody></table><h5 id="methods_$eval_example_returns">Returns</h5><table class="variables-matrix"><tr><td><a href="" class="label type-hint type-hint-object">*</a></td><td><div class="ng-rootscope-scope-eval-page"><p>The result of evaluating the expression.</p> </div></td></tr></table></div> </li> <li><h3 id="methods_$evalasync">$evalAsync(expression)</h3> <div class="$evalasync"><div class="ng-rootscope-scope-evalasync-page"><p>Executes the expression on the current scope at a later point in time.</p> <p>The <code>$evalAsync</code> makes no guarantees as to when the <code>expression</code> will be executed, only that:</p> <ul> <li>it will execute after the function that scheduled the evaluation (preferably before DOM rendering).</li> <li>at least one <a href="api/ng.$rootScope.Scope#methods_$digest"><code>$digest cycle</code></a> will be performed after <code>expression</code> execution.</li> </ul> <p>Any exceptions from the execution of the expression are forwarded to the <a href="api/ng.$exceptionHandler"><code>$exceptionHandler</code></a> service.</p> <p><strong>Note:</strong> if this function is called outside of a <code>$digest</code> cycle, a new <code>$digest</code> cycle will be scheduled. However, it is encouraged to always call code that changes the model from within an <code>$apply</code> call. That includes code evaluated via <code>$evalAsync</code>.</p> </div><h5 id="methods_$evalasync_parameters">Parameters</h5><table class="variables-matrix table table-bordered table-striped"><thead><tr><th>Param</th><th>Type</th><th>Details</th></tr></thead><tbody><tr><td>expression <div><em>(optional)</em></div></td><td><a href="" class="label type-hint type-hint-string">string</a><a href="" class="label type-hint type-hint-function">function()</a></td><td><div class="ng-rootscope-scope-evalasync-page"><p>An angular expression to be executed.</p> <ul> <li><code>string</code>: execute using the rules as defined in <a href="guide/expression">expression</a>.</li> <li><code>function(scope)</code>: execute the function with the current <code>scope</code> parameter.</li> </ul> </div></td></tr></tbody></table></div> </li> <li><h3 id="methods_$new">$new(isolate)</h3> <div class="$new"><div class="ng-rootscope-scope-new-page"><p>Creates a new child <a href="api/ng.$rootScope.Scope"><code>scope</code></a>.</p> <p>The parent scope will propagate the <a href="api/ng.$rootScope.Scope#methods_$digest"><code>$digest()</code></a> and <a href="api/ng.$rootScope.Scope#methods_$digest"><code>$digest()</code></a> events. The scope can be removed from the scope hierarchy using <a href="api/ng.$rootScope.Scope#methods_$destroy"><code>$destroy()</code></a>.</p> <p><a href="api/ng.$rootScope.Scope#methods_$destroy"><code>$destroy()</code></a> must be called on a scope when it is desired for 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.</p> </div><h5 id="methods_$new_parameters">Parameters</h5><table class="variables-matrix table table-bordered table-striped"><thead><tr><th>Param</th><th>Type</th><th>Details</th></tr></thead><tbody><tr><td>isolate</td><td><a href="" class="label type-hint type-hint-boolean">boolean</a></td><td><div class="ng-rootscope-scope-new-page"><p>If true, then the scope does not prototypically inherit from the parent scope. The scope is isolated, as it can not see parent scope properties. When creating widgets, it is useful for the widget to not accidentally read parent state.</p> </div></td></tr></tbody></table><h5 id="methods_$new_returns">Returns</h5><table class="variables-matrix"><tr><td><a href="" class="label type-hint type-hint-object">Object</a></td><td><div class="ng-rootscope-scope-new-page"><p>The newly created child scope.</p> </div></td></tr></table></div> </li> <li><h3 id="methods_$on">$on(name, listener)</h3> <div class="$on"><div class="ng-rootscope-scope-on-page"><p>Listens on events of a given type. See <a href="api/ng.$rootScope.Scope#methods_$emit"><code>$emit</code></a> for discussion of event life cycle.</p> <p>The event listener function format is: <code>function(event, args...)</code>. The <code>event</code> object passed into the listener has the following attributes:</p> <ul> <li><code>targetScope</code> - <code>{Scope}</code>: the scope on which the event was <code>$emit</code>-ed or <code>$broadcast</code>-ed.</li> <li><code>currentScope</code> - <code>{Scope}</code>: the current scope which is handling the event.</li> <li><code>name</code> - <code>{string}</code>: name of the event.</li> <li><code>stopPropagation</code> - <code>{function=}</code>: calling <code>stopPropagation</code> function will cancel further event propagation (available only for events that were <code>$emit</code>-ed).</li> <li><code>preventDefault</code> - <code>{function}</code>: calling <code>preventDefault</code> sets <code>defaultPrevented</code> flag to true.</li> <li><code>defaultPrevented</code> - <code>{boolean}</code>: true if <code>preventDefault</code> was called.</li> </ul> </div><h5 id="methods_$on_parameters">Parameters</h5><table class="variables-matrix table table-bordered table-striped"><thead><tr><th>Param</th><th>Type</th><th>Details</th></tr></thead><tbody><tr><td>name</td><td><a href="" class="label type-hint type-hint-string">string</a></td><td><div class="ng-rootscope-scope-on-page"><p>Event name to listen on.</p> </div></td></tr><tr><td>listener</td><td><a href="" class="label type-hint type-hint-function">function(event, args...</a></td><td><div class="ng-rootscope-scope-on-page"><p>Function to call when the event is emitted.</p> </div></td></tr></tbody></table><h5 id="methods_$on_returns">Returns</h5><table class="variables-matrix"><tr><td><a href="" class="label type-hint type-hint-function">function()</a></td><td><div class="ng-rootscope-scope-on-page"><p>Returns a deregistration function for this listener.</p> </div></td></tr></table></div> </li> <li><h3 id="methods_$watch">$watch(watchExpression, listener, objectEquality)</h3> <div class="$watch"><div class="ng-rootscope-scope-watch-page"><p>Registers a <code>listener</code> callback to be executed whenever the <code>watchExpression</code> changes.</p> <ul> <li>The <code>watchExpression</code> is called on every call to <a href="api/ng.$rootScope.Scope#methods_$digest"><code>$digest()</code></a> and should return the value that will be watched. (Since <a href="api/ng.$rootScope.Scope#methods_$digest"><code>$digest()</code></a> reruns when it detects changes the <code>watchExpression</code> can execute multiple times per <a href="api/ng.$rootScope.Scope#methods_$digest"><code>$digest()</code></a> and should be idempotent.)</li> <li>The <code>listener</code> is called only when the value from the current <code>watchExpression</code> and the previous call to <code>watchExpression</code> are not equal (with the exception of the initial run, see below). The inequality is determined according to <a href="api/angular.equals"><code>angular.equals</code></a> function. To save the value of the object for later comparison, the <a href="api/angular.copy"><code>angular.copy</code></a> function is used. It also means that watching complex options will have adverse memory and performance implications.</li> <li>The watch <code>listener</code> may change the model, which may trigger other <code>listener</code>s to fire. This is achieved by rerunning the watchers until no changes are detected. The rerun iteration limit is 10 to prevent an infinite loop deadlock.</li> </ul> <p>If you want to be notified whenever <a href="api/ng.$rootScope.Scope#methods_$digest"><code>$digest</code></a> is called, you can register a <code>watchExpression</code> function with no <code>listener</code>. (Since <code>watchExpression</code> can execute multiple times per <a href="api/ng.$rootScope.Scope#methods_$digest"><code>$digest</code></a> cycle when a change is detected, be prepared for multiple calls to your listener.)</p> <p>After a watcher is registered with the scope, the <code>listener</code> fn is called asynchronously (via <a href="api/ng.$rootScope.Scope#methods_$evalasync"><code>$evalAsync</code></a>) to initialize the watcher. In rare cases, this is undesirable because the listener is called when the result of <code>watchExpression</code> didn't change. To detect this scenario within the <code>listener</code> fn, you can compare the <code>newVal</code> and <code>oldVal</code>. If these two values are identical (<code>===</code>) then the listener was called due to initialization.</p> <p>The example below contains an illustration of using a function as your $watch listener</p> <h4 id="methods_$watch_example">Example</h4> <pre class="prettyprint linenums"> // let's assume that scope was dependency injected as the $rootScope var scope = $rootScope; scope.name = 'misko'; scope.counter = 0; expect(scope.counter).toEqual(0); scope.$watch('name', function(newValue, oldValue) { scope.counter = scope.counter + 1; }); expect(scope.counter).toEqual(0); scope.$digest(); // no variable change expect(scope.counter).toEqual(0); scope.name = 'adam'; scope.$digest(); expect(scope.counter).toEqual(1); // Using a listener function var food; scope.foodCounter = 0; expect(scope.foodCounter).toEqual(0); scope.$watch( // This is the listener function function() { return food; }, // This is the change handler function(newValue, oldValue) { if ( newValue !== oldValue ) { // Only increment the counter if the value changed scope.foodCounter = scope.foodCounter + 1; } } ); // No digest has been run so the counter will be zero expect(scope.foodCounter).toEqual(0); // Run the digest but since food has not changed count will still be zero scope.$digest(); expect(scope.foodCounter).toEqual(0); // Update food and run digest. Now the counter will increment food = 'cheeseburger'; scope.$digest(); expect(scope.foodCounter).toEqual(1); </pre> </div><h5 id="methods_$watch_example_parameters">Parameters</h5><table class="variables-matrix table table-bordered table-striped"><thead><tr><th>Param</th><th>Type</th><th>Details</th></tr></thead><tbody><tr><td>watchExpression</td><td><a href="" class="label type-hint type-hint-function">function()</a><a href="" class="label type-hint type-hint-string">string</a></td><td><div class="ng-rootscope-scope-watch-page"><p>Expression that is evaluated on each <a href="api/ng.$rootScope.Scope#methods_$digest"><code>$digest</code></a> cycle. A change in the return value triggers a call to the <code>listener</code>.</p> <ul> <li><code>string</code>: Evaluated as <a href="guide/expression">expression</a></li> <li><code>function(scope)</code>: called with current <code>scope</code> as a parameter.</li> </ul> </div></td></tr><tr><td>listener <div><em>(optional)</em></div></td><td><a href="" class="label type-hint type-hint-function">function()</a><a href="" class="label type-hint type-hint-string">string</a></td><td><div class="ng-rootscope-scope-watch-page"><p>Callback called whenever the return value of the <code>watchExpression</code> changes.</p> <ul> <li><code>string</code>: Evaluated as <a href="guide/expression">expression</a></li> <li><code>function(newValue, oldValue, scope)</code>: called with current and previous values as parameters.</li> </ul> </div></td></tr><tr><td>objectEquality <div><em>(optional)</em></div></td><td><a href="" class="label type-hint type-hint-boolean">boolean</a></td><td><div class="ng-rootscope-scope-watch-page"><p>Compare object for equality rather than for reference.</p> </div></td></tr></tbody></table><h5 id="methods_$watch_example_returns">Returns</h5><table class="variables-matrix"><tr><td><a href="" class="label type-hint type-hint-function">function()</a></td><td><div class="ng-rootscope-scope-watch-page"><p>Returns a deregistration function for this listener.</p> </div></td></tr></table></div> </li> <li><h3 id="methods_$watchcollection">$watchCollection(obj, listener)</h3> <div class="$watchcollection"><div class="ng-rootscope-scope-watchcollection-page"><p>Shallow watches the properties of an object and fires whenever any of the properties change (for arrays, this implies watching the array items; for object maps, this implies watching the properties). If a change is detected, the <code>listener</code> callback is fired.</p> <ul> <li>The <code>obj</code> collection is observed via standard $watch operation and is examined on every call to $digest() to see if any items have been added, removed, or moved.</li> <li>The <code>listener</code> is called whenever anything within the <code>obj</code> has changed. Examples include adding, removing, and moving items belonging to an object or array.</li> </ul> <h4 id="methods_$watchcollection_example">Example</h4> <pre class="prettyprint linenums"> $scope.names = ['igor', 'matias', 'misko', 'james']; $scope.dataCount = 4; $scope.$watchCollection('names', function(newNames, oldNames) { $scope.dataCount = newNames.length; }); expect($scope.dataCount).toEqual(4); $scope.$digest(); //still at 4 ... no changes expect($scope.dataCount).toEqual(4); $scope.names.pop(); $scope.$digest(); //now there's been a change expect($scope.dataCount).toEqual(3); </pre> </div><h5 id="methods_$watchcollection_example_parameters">Parameters</h5><table class="variables-matrix table table-bordered table-striped"><thead><tr><th>Param</th><th>Type</th><th>Details</th></tr></thead><tbody><tr><td>obj</td><td><a href="" class="label type-hint type-hint-string">string</a><a href="" class="label type-hint type-hint-function">Function(scope</a></td><td><div class="ng-rootscope-scope-watchcollection-page"><p>Evaluated as <a href="guide/expression">expression</a>. The expression value should evaluate to an object or an array which is observed on each <a href="api/ng.$rootScope.Scope#methods_$digest"><code>$digest</code></a> cycle. Any shallow change within the collection will trigger a call to the <code>listener</code>.</p> </div></td></tr><tr><td>listener</td><td><a href="" class="label type-hint type-hint-function">function(newCollection, oldCollection, scope</a></td><td><div class="ng-rootscope-scope-watchcollection-page"><p>a callback function that is fired with both the <code>newCollection</code> and <code>oldCollection</code> as parameters. The <code>newCollection</code> object is the newly modified data obtained from the <code>obj</code> expression and the <code>oldCollection</code> object is a copy of the former collection data. The <code>scope</code> refers to the current scope.</p> </div></td></tr></tbody></table><h5 id="methods_$watchcollection_example_returns">Returns</h5><table class="variables-matrix"><tr><td><a href="" class="label type-hint type-hint-function">function()</a></td><td><div class="ng-rootscope-scope-watchcollection-page"><p>Returns a de-registration function for this listener. When the de-registration function is executed, the internal watch operation is terminated.</p> </div></td></tr></table></div> </li> </ul> </div> <div class="member property"><h2 id="properties">Properties</h2> <ul class="properties"><li><h3 id="properties_$id">$id</h3> <div class="$id"><h5 id="properties_$id_returns">Returns</h5><table class="variables-matrix"><tr><td><a href="" class="label type-hint type-hint-number">number</a></td><td><div class="ng-rootscope-scope-id-page"><p>Unique scope ID (monotonically increasing alphanumeric sequence) useful for debugging.</p> </div></td></tr></table></div> </li> </ul> </div> <div class="member event"><h2 id="events">Events</h2> <ul class="events"><li><h3 id="events_$destroy">$destroy</h3> <div class="$destroy"><div class="ng-rootscope-scope-destroy-page"><p>Broadcasted when a scope and its children are being destroyed.</p> <p>Note that, in AngularJS, there is also a <code>$destroy</code> jQuery event, which can be used to clean up DOM bindings before an element is removed from the DOM.</p> </div><div class="inline"><h4 id="events_$destroy_type">Type:</h4> <div class="type">broadcast</div> </div> <div class="inline"><h4 id="events_$destroy_target">Target:</h4> <div class="target">scope being destroyed</div> </div> </div> </li> </ul> </div> </div>