kylefang/angular.js
1
0
Fork 0
mirror of https://github.com/zhigang1992/angular.js.git synced 2026-04-26 13:05:35 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs(*): simplify doc urls

Browse Source 
we now have two types of namespaces:

- true namespace: angular.* - used for all global apis
- virtual namespace: ng.*, ngMock.*, ... - used for all DI modules

the virual namespaces have services under the second namespace level (e.g. ng.)
and filters and directives prefixed with filter: and directive: respectively
(e.g. ng.filter:orderBy, ng.directive:ngRepeat)

this simplifies urls and makes them a lot shorter while still avoiding name collisions
This commit is contained in:
Igor Minar
2012-06-11 23:49:24 -07:00
parent fc0b2b5715
commit f16150d5f1
106 changed files with 803 additions and 799 deletions
Download Patch File Download Diff File Expand all files Collapse all files

66
docs/content/guide/scope.ngdoc
View File

@@ -4,32 +4,32 @@
# What are Scopes?
{@link api/angular.module.ng.$rootScope.Scope scope} is an object that refers to the application
{@link api/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/angular.module.ng.$rootScope.Scope#$watch $watch}) to observe
- Scopes provide APIs ({@link api/ng.$rootScope.Scope#$watch $watch}) to observe
model mutations.
- Scopes provide APIs ({@link api/angular.module.ng.$rootScope.Scope#$apply $apply}) to
- Scopes provide APIs ({@link api/ng.$rootScope.Scope#$apply $apply}) to
propagate any model changes through the system into the view from outside of the "Angular
realm" (controllers, services, Angular event handlers).
- Scopes can be nested to isolate application components while providing access to shared model
properties. A scope (prototypically) inherits properties from its parent scope.
- Scopes provide context against which {@link guide/expression expressions} are evaluated. For
- Scopes provide context against which {@link guide/expression expressions} are evaluated. For
example `{{username}}` expression is meaningless, unless it is evaluated against a specific
scope which defines the `username` property.
## Scope as Data-Model
Scope is the glue between application controller and the view. During the template {@link compiler
linking} phase the {@link api/angular.module.ng.$compileProvider.directive directives} set up
{@link api/angular.module.ng.$rootScope.Scope#$watch `$watch`} expressions on the scope. The
linking} phase the {@link api/ng.$compileProvider.directive directives} set up
{@link api/ng.$rootScope.Scope#$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.
@@ -102,7 +102,7 @@ to test the behavior without being distracted by the rendering details.
## Scope Hierarchies
Each Angular application has exactly one {@link api/angular.module.ng.$rootScope root scope}, but
Each Angular application has exactly one {@link api/ng.$rootScope root scope}, but
may have several child scopes.
The application can have multiple scopes, because some {@link guide/directive directives} create
@@ -164,7 +164,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/angular.module.ng.$compileProvider.directive.ngApp `ng-app`} directive. Typically
of {@link api/ng.directive:ngApp `ng-app`} directive. Typically
`ng-app` is placed an 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.
@@ -182,8 +182,8 @@ To examine the scope in the debugger:
## Scope Events Propagation
Scopes can propagate events in similar fashion to DOM events. The event can be {@link
api/angular.module.ng.$rootScope.Scope#$broadcast broadcasted} to the scope children or {@link
api/angular.module.ng.$rootScope.Scope#$emit emitted} to scope parents.
api/ng.$rootScope.Scope#$broadcast broadcasted} to the scope children or {@link
api/ng.$rootScope.Scope#$emit emitted} to scope parents.
<example>
<file name="script.js">
@@ -225,14 +225,14 @@ more events.
When the browser calls into JavaScript the code executes outside they Angular execution context,
which means that Angular is unaware of model modifications. To properly process model
modifications the execution has to enter the Angular execution context using the {@link
api/angular.module.ng.$rootScope.Scope#$apply `$apply`} method. Only model modifications which
api/ng.$rootScope.Scope#$apply `$apply`} method. Only model modifications which
execute inside the `$apply` method will be properly accounted for by Angular. For example if a
directive listens on DOM events, such as {@link
api/angular.module.ng.$compileProvider.directive.ngClick `ng-click`} it must evaluate the
api/ng.directive:ngClick `ng-click`} it must evaluate the
expression inside the `$apply` method.
After evaluating the expression `$apply` method performs a {@link
api/angular.module.ng.$rootScope.Scope#$digest `$digest`}. In $digest phase the scope examines all
api/ng.$rootScope.Scope#$digest `$digest`}. In $digest phase the scope examines all
of the `$watch` expressions and compares them with previous value. This dirty checking, is done
asynchronously. This means that assignment such as `$scope.username="angular"` will not
immediately cause a `$watch` to be notified, instead the `$watch` notification is delayed until
@@ -243,27 +243,27 @@ the `$digest` phase. This delay is desirable, since it coalesces multiple model
1. **Creation**
The {@link api/angular.module.ng.$rootScope root scope} is created during the application
bootstrap by the {@link api/angular.module.AUTO.$injector $injector}. During template
The {@link api/ng.$rootScope root scope} is created during the application
bootstrap by the {@link api/AUTO.$injector $injector}. During template
linking, some directives create new child scopes.
2. **Watcher registration**
During template linking directives register {@link
api/angular.module.ng.$rootScope.Scope#$watch watches} on the scope. This watches will be
api/ng.$rootScope.Scope#$watch watches} on the scope. This watches will be
used to propagate model values to the DOM.
3. **Model mutation**
For mutations to be properly observed, you should make them only within the {@link
api/angular.module.ng.$rootScope.Scope#$apply scope.$apply()}. (Angular apis do this
api/ng.$rootScope.Scope#$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/angular.module.ng.$http $http} or {@link
api/angular.module.ng.$defer $defer} services.
or asynchronous work with {@link api/ng.$http $http} or {@link
api/ng.$defer $defer} services.
4. **Mutation observation**
At the end `$apply`, Angular performs a {@link api/angular.module.ng.$rootScope.Scope#$digest
At the end `$apply`, Angular performs a {@link api/ng.$rootScope.Scope#$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.
@@ -271,7 +271,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/angular.module.ng.$rootScope.Scope#$destroy scope.$destroy()}
to destroy them via {@link api/ng.$rootScope.Scope#$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.
@@ -279,30 +279,30 @@ the `$digest` phase. This delay is desirable, since it coalesces multiple model
### Scopes and Directives
During the compilation phase, the {@link compiler compiler} matches {@link
api/angular.module.ng.$compileProvider.directive directives} against the DOM template. The directives
api/ng.$compileProvider.directive directives} against the DOM template. The directives
usually fall into one of two categories:
- Observing {@link api/angular.module.ng.$compileProvider.directive directives}, such as
- Observing {@link api/ng.$compileProvider.directive directives}, such as
double-curly expressions `{{expression}}`, register listeners using the {@link
api/angular.module.ng.$rootScope.Scope#$watch $watch()} method. This type of directive needs
api/ng.$rootScope.Scope#$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/angular.module.ng.$compileProvider.directive.ngClick
- Listener directives, such as {@link api/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/angular.module.ng.$rootScope.Scope#$apply $apply()} method.
api/ng.$rootScope.Scope#$apply $apply()} method.
When an external event (such as a user action, timer or XHR) is received, the associated {@link
expression expression} must be applied to the scope through the {@link
api/angular.module.ng.$rootScope.Scope#$apply $apply()} method so that all listeners are updated
api/ng.$rootScope.Scope#$apply $apply()} method so that all listeners are updated
correctly.
### Directives that Create Scopes
In most cases, {@link api/angular.module.ng.$compileProvider.directive directives} and scopes interact
In most cases, {@link api/ng.$compileProvider.directive directives} and scopes interact
but do not create new instances of scope. However, some directives, such as {@link
api/angular.module.ng.$compileProvider.directive.ngController ng-controller} and {@link
api/angular.module.ng.$compileProvider.directive.ngRepeat ng-repeat}, create new child scopes
api/ng.directive:ngController ng-controller} and {@link
api/ng.directive:ngRepeat ng-repeat}, create new child scopes
and attach the child scope to the corresponding DOM element. You can retrieve a scope for any DOM
element by using an `angular.element(aDomElement).scope()` method call.
@@ -311,14 +311,14 @@ element by using an `angular.element(aDomElement).scope()` method call.
Scopes and controllers interact with each other in the following situations:
- Controllers use scopes to expose controller methods to templates (see {@link
api/angular.module.ng.$compileProvider.directive.ngController ng-controller}).
api/ng.directive:ngController ng-controller}).
- Controllers define methods (behavior) that can mutate the model (properties on the scope).
- Controllers may register {@link api/angular.module.ng.$rootScope.Scope#$watch watches} on
- Controllers may register {@link api/ng.$rootScope.Scope#$watch watches} on
the model. These watches execute immediately after the controller behavior executes.
See the {@link api/angular.module.ng.$compileProvider.directive.ngController ng-controller} for more
See the {@link api/ng.directive:ngController ng-controller} for more
information.