diff options
| author | Peter Bacon Darwin | 2014-02-12 22:47:42 +0000 |
|---|---|---|
| committer | Peter Bacon Darwin | 2014-02-16 19:03:41 +0000 |
| commit | a564160511bf1bbed5a4fe5d2981fae1bb664eca (patch) | |
| tree | 16fe76a5c8a4e75c50db5f15224f1b954060cd38 /docs/content/guide/scope.ngdoc | |
| parent | 06f2ba899fac8ad004bf65dce39a3b05e2387c0f (diff) | |
| download | angular.js-a564160511bf1bbed5a4fe5d2981fae1bb664eca.tar.bz2 | |
docs(bike-shed-migration): fix url-based links refs to AUTO module
Diffstat (limited to 'docs/content/guide/scope.ngdoc')
| -rw-r--r-- | docs/content/guide/scope.ngdoc | 62 |
1 files changed, 31 insertions, 31 deletions
diff --git a/docs/content/guide/scope.ngdoc b/docs/content/guide/scope.ngdoc index da194977..f13350fa 100644 --- a/docs/content/guide/scope.ngdoc +++ b/docs/content/guide/scope.ngdoc @@ -4,17 +4,17 @@ # What are Scopes? -{@link api/ng.$rootScope.Scope scope} is an object that refers to the application +{@link ng.$rootScope.Scope scope} is an object that refers to the application model. It is an execution context for {@link expression expressions}. Scopes are arranged in hierarchical structure which mimic the DOM structure of the application. Scopes can watch {@link guide/expression expressions} and propagate events. ## Scope characteristics - - Scopes provide APIs ({@link api/ng.$rootScope.Scope#methods_$watch $watch}) to observe + - Scopes provide APIs ({@link ng.$rootScope.Scope#methods_$watch $watch}) to observe model mutations. - - Scopes provide APIs ({@link api/ng.$rootScope.Scope#methods_$apply $apply}) to + - Scopes provide APIs ({@link ng.$rootScope.Scope#methods_$apply $apply}) to propagate any model changes through the system into the view from outside of the "Angular realm" (controllers, services, Angular event handlers). @@ -32,8 +32,8 @@ watch {@link guide/expression expressions} and propagate events. ## Scope as Data-Model Scope is the glue between application controller and the view. During the template {@link compiler -linking} phase the {@link api/ng.$compileProvider#methods_directive directives} set up -{@link api/ng.$rootScope.Scope#methods_$watch `$watch`} expressions on the scope. The +linking} phase the {@link ng.$compileProvider#methods_directive directives} set up +{@link ng.$rootScope.Scope#methods_$watch `$watch`} expressions on the scope. The `$watch` allows the directives to be notified of property changes, which allows the directive to render the updated value to the DOM. @@ -106,7 +106,7 @@ to test the behavior without being distracted by the rendering details. ## Scope Hierarchies -Each Angular application has exactly one {@link api/ng.$rootScope root scope}, but +Each Angular application has exactly one {@link ng.$rootScope root scope}, but may have several child scopes. The application can have multiple scopes, because some {@link guide/directive directives} create @@ -169,7 +169,7 @@ where the `department` property is defined. Scopes are attached to the DOM as `$scope` data property, and can be retrieved for debugging purposes. (It is unlikely that one would need to retrieve scopes in this way inside the application.) The location where the root scope is attached to the DOM is defined by the location -of {@link api/ng.directive:ngApp `ng-app`} directive. Typically +of {@link ng.directive:ngApp `ng-app`} directive. Typically `ng-app` is placed on the `<html>` element, but it can be placed on other elements as well, if, for example, only a portion of the view needs to be controlled by Angular. @@ -248,8 +248,8 @@ the `$digest` phase. This delay is desirable, since it coalesces multiple model 1. **Creation** - The {@link api/ng.$rootScope root scope} is created during the application - bootstrap by the {@link api/AUTO.$injector $injector}. During template + The {@link ng.$rootScope root scope} is created during the application + bootstrap by the {@link auto.$injector $injector}. During template linking, some directives create new child scopes. 2. **Watcher registration** @@ -263,12 +263,12 @@ the `$digest` phase. This delay is desirable, since it coalesces multiple model For mutations to be properly observed, you should make them only within the {@link api/ng.$rootScope.Scope#methods_$apply scope.$apply()}. (Angular APIs do this implicitly, so no extra `$apply` call is needed when doing synchronous work in controllers, - or asynchronous work with {@link api/ng.$http $http}, {@link api/ng.$timeout $timeout} - or {@link api/ng.$interval $interval} services. + or asynchronous work with {@link ng.$http $http}, {@link ng.$timeout $timeout} + or {@link ng.$interval $interval} services. 4. **Mutation observation** - At the end `$apply`, Angular performs a {@link api/ng.$rootScope.Scope#methods_$digest + At the end `$apply`, Angular performs a {@link ng.$rootScope.Scope#methods_$digest $digest} cycle on the root scope, which then propagates throughout all child scopes. During the `$digest` cycle, all `$watch`ed expressions or functions are checked for model mutation and if a mutation is detected, the `$watch` listener is called. @@ -276,7 +276,7 @@ the `$digest` phase. This delay is desirable, since it coalesces multiple model 5. **Scope destruction** When child scopes are no longer needed, it is the responsibility of the child scope creator - to destroy them via {@link api/ng.$rootScope.Scope#methods_$destroy scope.$destroy()} + to destroy them via {@link ng.$rootScope.Scope#methods_$destroy scope.$destroy()} API. This will stop propagation of `$digest` calls into the child scope and allow for memory used by the child scope models to be reclaimed by the garbage collector. @@ -287,12 +287,12 @@ During the compilation phase, the {@link compiler compiler} matches {@link api/ng.$compileProvider#methods_directive directives} against the DOM template. The directives usually fall into one of two categories: - - Observing {@link api/ng.$compileProvider#methods_directive directives}, such as + - Observing {@link ng.$compileProvider#methods_directive directives}, such as double-curly expressions `{{expression}}`, register listeners using the {@link api/ng.$rootScope.Scope#methods_$watch $watch()} method. This type of directive needs to be notified whenever the expression changes so that it can update the view. - - Listener directives, such as {@link api/ng.directive:ngClick + - Listener directives, such as {@link ng.directive:ngClick ng-click}, register a listener with the DOM. When the DOM listener fires, the directive executes the associated expression and updates the view using the {@link api/ng.$rootScope.Scope#methods_$apply $apply()} method. @@ -304,7 +304,7 @@ correctly. ### Directives that Create Scopes -In most cases, {@link api/ng.$compileProvider#methods_directive directives} and scopes interact +In most cases, {@link ng.$compileProvider#methods_directive directives} and scopes interact but do not create new instances of scope. However, some directives, such as {@link api/ng.directive:ngController ng-controller} and {@link api/ng.directive:ngRepeat ng-repeat}, create new child scopes @@ -322,10 +322,10 @@ Scopes and controllers interact with each other in the following situations: - Controllers define methods (behavior) that can mutate the model (properties on the scope). - - Controllers may register {@link api/ng.$rootScope.Scope#methods_$watch watches} on + - Controllers may register {@link ng.$rootScope.Scope#methods_$watch watches} on the model. These watches execute immediately after the controller behavior executes. -See the {@link api/ng.directive:ngController ng-controller} for more +See the {@link ng.directive:ngController ng-controller} for more information. @@ -360,23 +360,23 @@ implementing custom event callbacks, or when working with third-party library ca api/ng.$rootScope.Scope#methods_$apply $apply}`(stimulusFn)`. Where `stimulusFn` is the work you wish to do in Angular execution context. 2. Angular executes the `stimulusFn()`, which typically modifies application state. - 3. Angular enters the {@link api/ng.$rootScope.Scope#methods_$digest $digest} loop. The + 3. Angular enters the {@link ng.$rootScope.Scope#methods_$digest $digest} loop. The loop is made up of two smaller loops which process {@link api/ng.$rootScope.Scope#methods_$evalAsync $evalAsync} queue and the {@link api/ng.$rootScope.Scope#methods_$watch $watch} list. The {@link api/ng.$rootScope.Scope#methods_$digest $digest} loop keeps iterating until the model - stabilizes, which means that the {@link api/ng.$rootScope.Scope#methods_$evalAsync - $evalAsync} queue is empty and the {@link api/ng.$rootScope.Scope#methods_$watch + stabilizes, which means that the {@link ng.$rootScope.Scope#methods_$evalAsync + $evalAsync} queue is empty and the {@link ng.$rootScope.Scope#methods_$watch $watch} list does not detect any changes. - 4. The {@link api/ng.$rootScope.Scope#methods_$evalAsync $evalAsync} queue is used to + 4. The {@link ng.$rootScope.Scope#methods_$evalAsync $evalAsync} queue is used to schedule work which needs to occur outside of current stack frame, but before the browser's view render. This is usually done with `setTimeout(0)`, but the `setTimeout(0)` approach suffers from slowness and may cause view flickering since the browser renders the view after each event. - 5. The {@link api/ng.$rootScope.Scope#methods_$watch $watch} list is a set of expressions + 5. The {@link ng.$rootScope.Scope#methods_$watch $watch} list is a set of expressions which may have changed since last iteration. If a change is detected then the `$watch` function is called which typically updates the DOM with the new value. - 6. Once the Angular {@link api/ng.$rootScope.Scope#methods_$digest $digest} loop finishes + 6. Once the Angular {@link ng.$rootScope.Scope#methods_$digest $digest} loop finishes the execution leaves the Angular and JavaScript context. This is followed by the browser re-rendering the DOM to reflect any changes. @@ -385,22 +385,22 @@ Here is the explanation of how the `Hello world` example achieves the data-bindi user enters text into the text field. 1. During the compilation phase: - 1. the {@link api/ng.directive:ngModel ng-model} and {@link + 1. the {@link ng.directive:ngModel ng-model} and {@link api/ng.directive:input input} {@link guide/directive directive} set up a `keydown` listener on the `<input>` control. - 2. the {@link api/ng.$interpolate {{name}} } interpolation - sets up a {@link api/ng.$rootScope.Scope#methods_$watch $watch} to be notified of + 2. the {@link ng.$interpolate {{name}} } interpolation + sets up a {@link ng.$rootScope.Scope#methods_$watch $watch} to be notified of `name` changes. 2. During the runtime phase: 1. Pressing an '`X`' key causes the browser to emit a `keydown` event on the input control. - 2. The {@link api/ng.directive:input input} directive + 2. The {@link ng.directive:input input} directive captures the change to the input's value and calls {@link api/ng.$rootScope.Scope#methods_$apply $apply}`("name = 'X';")` to update the application model inside the Angular execution context. 3. Angular applies the `name = 'X';` to the model. - 4. The {@link api/ng.$rootScope.Scope#methods_$digest $digest} loop begins - 5. The {@link api/ng.$rootScope.Scope#methods_$watch $watch} list detects a change - on the `name` property and notifies the {@link api/ng.$interpolate + 4. The {@link ng.$rootScope.Scope#methods_$digest $digest} loop begins + 5. The {@link ng.$rootScope.Scope#methods_$watch $watch} list detects a change + on the `name` property and notifies the {@link ng.$interpolate {{name}} } interpolation, which in turn updates the DOM. 6. Angular exits the execution context, which in turn exits the `keydown` event and with it the JavaScript execution context. |