380 lines
29 KiB
HTML
Executable file
380 lines
29 KiB
HTML
Executable file
<a href="http://github.com/angular/angular.js/tree/v1.2.0rc1/src/ng/rootScope.js#L75" 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#$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>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="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="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="$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#$digest"><code>executing watches</code></a>.</p>
|
|
<h5>Life cycle</h5>
|
|
<h4>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#$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#$watch"><code>watch</code></a> listeners are fired immediately after the expression
|
|
was executed using the <a href="api/ng.$rootScope.Scope#$digest"><code>$digest()</code></a> method.</li>
|
|
</ol>
|
|
</div><h5 id="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="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="$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#$on"><code>ng.$rootScope.Scope#$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#$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#$on"><code>listeners</code></a> will be passed
|
|
onto the <a href="api/ng.$exceptionHandler"><code>$exceptionHandler</code></a> service.</p>
|
|
</div><h5 id="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="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#$on"><code>ng.$rootScope.Scope#$on</code></a></p>
|
|
</div></td></tr></table></div>
|
|
</li>
|
|
<li><h3 id="$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#$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 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="$digest">$digest()</h3>
|
|
<div class="$digest"><div class="ng-rootscope-scope-digest-page"><p>Processes all of the <a href="api/ng.$rootScope.Scope#$watch"><code>watchers</code></a> of the current scope and its children.
|
|
Because a <a href="api/ng.$rootScope.Scope#$watch"><code>watcher</code></a>'s listener can change the model, the
|
|
<code>$digest()</code> keeps calling the <a href="api/ng.$rootScope.Scope#$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#directive"><code>directives</code></a>.
|
|
Instead a call to <a href="api/ng.$rootScope.Scope#$apply"><code>$apply()</code></a> (typically from within a
|
|
<a href="api/ng.$compileProvider#directive"><code>directives</code></a>) 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#$watch"><code>$watch()</code></a>
|
|
with no <code>listener</code>.</p>
|
|
<p>You may have a need to call <code>$digest()</code> from within unit-tests, to simulate the scope
|
|
life-cycle.</p>
|
|
<h4>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="$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#$on"><code>ng.$rootScope.Scope#$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#$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#$on"><code>listeners</code></a> will be passed
|
|
onto the <a href="api/ng.$exceptionHandler"><code>$exceptionHandler</code></a> service.</p>
|
|
</div><h5 id="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="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#$on"><code>ng.$rootScope.Scope#$on</code></a></p>
|
|
</div></td></tr></table></div>
|
|
</li>
|
|
<li><h3 id="$eval">$eval(expression)</h3>
|
|
<div class="$eval"><div class="ng-rootscope-scope-eval-page"><p>Executes the <code>expression</code> on the current scope returning the result. Any exceptions in the
|
|
expression are propagated (uncaught). This is useful when evaluating Angular expressions.</p>
|
|
<h4>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="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></tbody></table><h5 id="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="$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 schedule the evaluation is done running (preferably before DOM rendering).</li>
|
|
<li>at least one <a href="api/ng.$rootScope.Scope#$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 <code>$digest</code> cycle, a new $digest cycle will be scheduled.
|
|
It is however encouraged to always call code that changes the model from withing an <code>$apply</code> call.
|
|
That includes code evaluated via <code>$evalAsync</code>.</p>
|
|
</div><h5 id="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="$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#$digest"><code>$digest()</code></a> and
|
|
<a href="api/ng.$rootScope.Scope#$digest"><code>$digest()</code></a> events. The scope can be removed from the scope
|
|
hierarchy using <a href="api/ng.$rootScope.Scope#$destroy"><code>$destroy()</code></a>.</p>
|
|
<p><a href="api/ng.$rootScope.Scope#$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="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="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="$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#$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="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="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="$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#$digest"><code>$digest()</code></a> and
|
|
should return the value which will be watched. (Since <a href="api/ng.$rootScope.Scope#$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#$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#$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#$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#$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>
|
|
<h4>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);
|
|
</pre>
|
|
</div><h5 id="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#$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="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="$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 new items
|
|
into the object or array, removing and moving items around.</li>
|
|
</ul>
|
|
<h4>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="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#$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="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
|
|
then 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="$id">$id</h3>
|
|
<div class="$id"><h5 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="$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="Type.">Type:</h4>
|
|
<div class="type-">broadcast</div>
|
|
</div>
|
|
<div class="inline"><h4 id="Target.">Target:</h4>
|
|
<div class="target-">scope being destroyed</div>
|
|
</div>
|
|
</div>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
</div>
|