diff options
Diffstat (limited to 'docs/content/guide')
26 files changed, 161 insertions, 161 deletions
diff --git a/docs/content/guide/animations.ngdoc b/docs/content/guide/animations.ngdoc index a9dd6ac6..0cf08eb7 100644 --- a/docs/content/guide/animations.ngdoc +++ b/docs/content/guide/animations.ngdoc @@ -11,7 +11,7 @@ triggered, will attempt to perform a CSS Transition, CSS Keyframe Animation or a placed on the given directive). Animations can be placed using vanilla CSS by following the naming conventions set in place by AngularJS or with JavaScript code when it's defined as a factory. -Animations are not available unless you include the {@link api/ngAnimate `ngAnimate` module} as a dependency within your application. +Animations are not available unless you include the {@link ngAnimate `ngAnimate` module} as a dependency within your application. Below is a quick example of animations being enabled for `ngShow` and `ngHide`: @@ -55,7 +55,7 @@ Below is a quick example of animations being enabled for `ngShow` and `ngHide`: ## Installation -See the {@link api/ngAnimate API docs for `ngAnimate`} for instructions on installing the module. +See the {@link ngAnimate API docs for `ngAnimate`} for instructions on installing the module. You may also want to setup a separate CSS file for defining CSS-based animations. @@ -253,15 +253,15 @@ The table below explains in detail which animation events are triggered | Directive | Supported Animations | |-------------------------------------------------------------------------------------|------------------------------------------| -| {@link api/ng.directive:ngRepeat#usage_animations ngRepeat} | enter, leave, and move | -| {@link api/ngRoute.directive:ngView#usage_animations ngView} | enter and leave | -| {@link api/ng.directive:ngInclude#usage_animations ngInclude} | enter and leave | -| {@link api/ng.directive:ngSwitch#usage_animations ngSwitch} | enter and leave | -| {@link api/ng.directive:ngIf#usage_animations ngIf} | enter and leave | -| {@link api/ng.directive:ngClass#usage_animations ngClass or {{class}}} | add and remove | -| {@link api/ng.directive:ngShow#usage_animations ngShow & ngHide} | add and remove (the ng-hide class value) | +| {@link ng.directive:ngRepeat#usage_animations ngRepeat} | enter, leave, and move | +| {@link ngRoute.directive:ngView#usage_animations ngView} | enter and leave | +| {@link ng.directive:ngInclude#usage_animations ngInclude} | enter and leave | +| {@link ng.directive:ngSwitch#usage_animations ngSwitch} | enter and leave | +| {@link ng.directive:ngIf#usage_animations ngIf} | enter and leave | +| {@link ng.directive:ngClass#usage_animations ngClass or {{class}}} | add and remove | +| {@link ng.directive:ngShow#usage_animations ngShow & ngHide} | add and remove (the ng-hide class value) | -For a full breakdown of the steps involved during each animation event, refer to the {@link api/ngAnimate.$animate API docs}. +For a full breakdown of the steps involved during each animation event, refer to the {@link ngAnimate.$animate API docs}. ## How do I use animations in my own directives? @@ -284,6 +284,6 @@ myModule.directive('my-directive', ['$animate', function($animate) { ## More about animations -For a full breakdown of each method available on `$animate`, see the {@link api/ngAnimate.$animate API documentation}. +For a full breakdown of each method available on `$animate`, see the {@link ngAnimate.$animate API documentation}. To see a complete demo, see the {@link tutorial/step_12 animation step within the AngularJS phonecat tutorial}. diff --git a/docs/content/guide/bootstrap.ngdoc b/docs/content/guide/bootstrap.ngdoc index d5098a23..7458762f 100644 --- a/docs/content/guide/bootstrap.ngdoc +++ b/docs/content/guide/bootstrap.ngdoc @@ -55,12 +55,12 @@ initialization. Angular initializes automatically upon `DOMContentLoaded` event or when the `angular.js` script is evaluated if at that time `document.readyState` is set to `'complete'`. At this point Angular looks -for the {@link api/ng.directive:ngApp `ng-app`} directive which designates your application root. -If the {@link api/ng.directive:ngApp `ng-app`} directive is found then Angular will: +for the {@link ng.directive:ngApp `ng-app`} directive which designates your application root. +If the {@link ng.directive:ngApp `ng-app`} directive is found then Angular will: * load the {@link guide/module module} associated with the directive. - * create the application {@link api/AUTO.$injector injector} - * compile the DOM treating the {@link api/ng.directive:ngApp + * create the application {@link auto.$injector injector} + * compile the DOM treating the {@link ng.directive:ngApp `ng-app`} directive as the root of the compilation. This allows you to tell it to treat only a portion of the DOM as an Angular application. @@ -103,7 +103,7 @@ Here is an example of manually initializing Angular: ``` Note that we have provided the name of our application module to be loaded into the injector as the second -parameter of the {@link api/angular.bootstrap} function. Notice that `angular.bootstrap` will not create modules +parameter of the {@link angular.bootstrap} function. Notice that `angular.bootstrap` will not create modules on the fly. You must create any custom {@link guide/module modules} before you pass them as a parameter. This is the sequence that your code should follow: @@ -111,7 +111,7 @@ This is the sequence that your code should follow: 1. After the page and all of the code is loaded, find the root element of your AngularJS application, which is typically the root of the document. - 2. Call {@link api/angular.bootstrap} to {@link compiler compile} the element into an + 2. Call {@link angular.bootstrap} to {@link compiler compile} the element into an executable, bi-directionally bound application. ## Deferred Bootstrap @@ -122,7 +122,7 @@ into the DI registry which can replace or augment DI services for the purpose of instrumentation or mocking out heavy dependencies. If `window.name` contains prefix `NG_DEFER_BOOTSTRAP!` when -{@link api/angular.bootstrap} is called, the bootstrap process will be paused +{@link angular.bootstrap} is called, the bootstrap process will be paused until `angular.resumeBootstrap()` is called. `angular.resumeBootstrap()` takes an optional array of modules that diff --git a/docs/content/guide/compiler.ngdoc b/docs/content/guide/compiler.ngdoc index 8defadcf..8a17bef0 100644 --- a/docs/content/guide/compiler.ngdoc +++ b/docs/content/guide/compiler.ngdoc @@ -13,10 +13,10 @@ If you want a deeper look into Angular's compilation process, you're in the righ # Overview -Angular's {@link api/ng.$compile HTML compiler} allows the developer to teach the +Angular's {@link ng.$compile HTML compiler} allows the developer to teach the browser new HTML syntax. The compiler allows you to attach behavior to any HTML element or attribute and even create new HTML elements or attributes with custom behavior. Angular calls these behavior -extensions {@link api/ng.$compileProvider#methods_directive directives}. +extensions {@link ng.$compileProvider#methods_directive directives}. HTML has a lot of constructs for formatting the HTML for static documents in a declarative fashion. For example if something needs to be centered, there is no need to provide instructions to the @@ -48,7 +48,7 @@ process happens in two phases. scope model are reflected in the view, and any user interactions with the view are reflected in the scope model. This makes the scope model the single source of truth. -Some directives such as {@link api/ng.directive:ngRepeat `ng-repeat`} clone DOM elements once +Some directives such as {@link ng.directive:ngRepeat `ng-repeat`} clone DOM elements once for each item in a collection. Having a compile and link phase improves performance since the cloned template only needs to be compiled once, and then linked once for each clone instance. @@ -164,7 +164,7 @@ Angular's `$compile` service. HTML compilation happens in three phases: - 1. {@link api/ng.$compile `$compile`} traverses the DOM and matches directives. + 1. {@link ng.$compile `$compile`} traverses the DOM and matches directives. If the compiler finds that an element matches a directive, then the directive is added to the list of directives that match the DOM element. A single element may match multiple directives. @@ -178,7 +178,7 @@ HTML compilation happens in three phases: 3. `$compile` links the template with the scope by calling the combined linking function from the previous step. This in turn will call the linking function of the individual directives, registering listeners on the elements - and setting up {@link api/ng.$rootScope.Scope#methods_$watch `$watch`s} with the {@link api/ng.$rootScope.Scope `scope`} + and setting up {@link ng.$rootScope.Scope#methods_$watch `$watch`s} with the {@link ng.$rootScope.Scope `scope`} as each directive is configured to do. The result of this is a live binding between the scope and the DOM. So at this point, a change in @@ -240,10 +240,10 @@ Hello {{user}}, you have these actions: When the above example is compiled, the compiler visits every node and looks for directives. -`{{user}}` matches the {@link api/ng.$interpolate interpolation directive} -and `ng-repeat` matches the {@link api/ng.directive:ngRepeat `ngRepeat` directive}. +`{{user}}` matches the {@link ng.$interpolate interpolation directive} +and `ng-repeat` matches the {@link ng.directive:ngRepeat `ngRepeat` directive}. -But {@link api/ng.directive:ngRepeat ngRepeat} has a dilemma. +But {@link ng.directive:ngRepeat ngRepeat} has a dilemma. It needs to be able to clone new `<li>` elements for every `action` in `user.actions`. This initially seems trivial, but it becomes more complicated when you consider that `user.actions` @@ -252,7 +252,7 @@ element for cloning purposes. As new `action`s are inserted, the template `<li>` element needs to be cloned and inserted into `ul`. But cloning the `<li>` element is not enough. It also needs to compile the `<li>` so that its -directives, like `{{action.description}}`, evaluate against the right {@link api/ng.$rootScope.Scope scope}. +directives, like `{{action.description}}`, evaluate against the right {@link ng.$rootScope.Scope scope}. A naive approach to solving this problem would be to simply insert a copy of the `<li>` element and @@ -266,25 +266,25 @@ The solution is to break the compilation process into two phases: the **compile phase** where all of the directives are identified and sorted by priority, and a **linking phase** where any work which "links" a specific instance of the -{@link api/ng.$rootScope.Scope scope} and the specific instance of an `<li>` is performed. +{@link ng.$rootScope.Scope scope} and the specific instance of an `<li>` is performed. <div class="alert alert-warning"> **Note:** *Link* means setting up listeners on the DOM and setting up `$watch` on the Scope to keep the two in sync. </div> -{@link api/ng.directive:ngRepeat `ngRepeat`} works by preventing the compilation process from +{@link ng.directive:ngRepeat `ngRepeat`} works by preventing the compilation process from descending into the `<li>` element so it can make a clone of the original and handle inserting and removing DOM nodes itself. -Instead the {@link api/ng.directive:ngRepeat `ngRepeat`} directive compiles `<li>` separately. +Instead the {@link ng.directive:ngRepeat `ngRepeat`} directive compiles `<li>` separately. The result of the `<li>` element compilation is a linking function which contains all of the directives contained in the `<li>` element, ready to be attached to a specific clone of the `<li>` element. -At runtime the {@link api/ng.directive:ngRepeat `ngRepeat`} watches the expression and as items +At runtime the {@link ng.directive:ngRepeat `ngRepeat`} watches the expression and as items are added to the array it clones the `<li>` element, creates a new -{@link api/ng.$rootScope.Scope scope} for the cloned `<li>` element and calls the link function +{@link ng.$rootScope.Scope scope} for the cloned `<li>` element and calls the link function on the cloned `<li>`. diff --git a/docs/content/guide/concepts.ngdoc b/docs/content/guide/concepts.ngdoc index 7154da39..105af400 100644 --- a/docs/content/guide/concepts.ngdoc +++ b/docs/content/guide/concepts.ngdoc @@ -60,11 +60,11 @@ The loaded, transformed and rendered DOM is then called the <a name="view">"view The first kind of new markup are the so called <a name="directive">"{@link directive directives}"</a>. They apply special behavior to attributes or elements in the HTML. In the example above we use the -{@link api/ng.directive:ngApp `ng-app`} attribute, which is linked to a directive that automatically -initializes our application. Angular also defines a directive for the {@link api/ng.directive:input `input`} +{@link ng.directive:ngApp `ng-app`} attribute, which is linked to a directive that automatically +initializes our application. Angular also defines a directive for the {@link ng.directive:input `input`} element that adds extra behavior to the element. E.g. it is able to automatically validate that the entered text is non empty by evaluating the `required` attribute. -The {@link api/ng.directive:ngModel `ng-model`} directive stores/updates +The {@link ng.directive:ngModel `ng-model`} directive stores/updates the value of the input field into/from a variable and shows the validation state of the input field by adding css classes. In the example we use these css classes to mark an empty input field with a red border. @@ -88,7 +88,7 @@ and multiply them together". The example above also contains a <a name="filter">"{@link filter filter}"</a>. A filter formats the value of an expression for display to the user. -In the example above, the filter {@link api/ng.filter:currency `currency`} formats a number +In the example above, the filter {@link ng.filter:currency `currency`} formats a number into an output that looks like money. The important thing in the example is that angular provides _live_ bindings: @@ -157,7 +157,7 @@ More exactly, the file contains a constructor function that creates the actual c The purpose of controllers is to expose variables and functionality to expressions and directives. Besides the new file that contains the controller code we also added a -{@link api/ng.directive:ngController `ng-controller`} directive to the HTML. +{@link ng.directive:ngController `ng-controller`} directive to the HTML. This directive tells angular that the new `InvoiceController` is responsible for the element with the directive and all of the element's children. The syntax `InvoiceController as invoice` tells Angular to instantiate the controller @@ -165,13 +165,13 @@ and save it in the variable `invoice` in the current scope. We also changed all expressions in the page to read and write variables within that controller instance by prefixing them with `invoice.` . The possible currencies are defined in the controller -and added to the template using {@link api/ng.directive:ngRepeat `ng-repeat`}. +and added to the template using {@link ng.directive:ngRepeat `ng-repeat`}. As the controller contains a `total` function we are also able to bind the result of that function to the DOM using `{{ invoice.total(...) }}`. Again, this binding is live, i.e. the DOM will be automatically updated whenever the result of the function changes. -The button to pay the invoice uses the directive {@link api/ng.directive:ngClick `ngClick`}. This will evaluate the +The button to pay the invoice uses the directive {@link ng.directive:ngClick `ngClick`}. This will evaluate the corresponding expression whenever the button is clicked. In the new JavaScript file we are also creating a {@link concepts#module module} @@ -380,7 +380,7 @@ The following example shows how this is done with Angular: What changed? Our `currencyConverter` service of the `finance` module now uses the -{@link api/ng.$http $http} service, a builtin service provided by Angular +{@link ng.$http $http} service, a builtin service provided by Angular for accessing the backend. It is a wrapper around [`XMLHttpRequest`](https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest) and [JSONP](http://en.wikipedia.org/wiki/JSONP) transports. Details can be found in the api docs of that service. diff --git a/docs/content/guide/controller.ngdoc b/docs/content/guide/controller.ngdoc index 01f5299f..04dcf56c 100644 --- a/docs/content/guide/controller.ngdoc +++ b/docs/content/guide/controller.ngdoc @@ -7,7 +7,7 @@ In Angular, a Controller is a JavaScript **constructor function** that is used to augment the {@link scope Angular Scope}. -When a Controller is attached to the DOM via the {@link api/ng.directive:ngController ng-controller} +When a Controller is attached to the DOM via the {@link ng.directive:ngController ng-controller} directive, Angular will instantiate a new Controller object, using the specified Controller's **constructor function**. A new **child scope** will be available as an injectable parameter to the Controller's constructor function as `$scope`. @@ -88,7 +88,7 @@ expression in the template: As discussed in the {@link concepts Concepts} section of this guide, any objects (or primitives) assigned to the scope become model properties. Any methods assigned to the scope are available in the template/view, and can be invoked via angular expressions -and `ng` event handler directives (e.g. {@link api/ng.directive:ngClick ngClick}). +and `ng` event handler directives (e.g. {@link ng.directive:ngClick ngClick}). # Using Controllers Correctly @@ -117,8 +117,8 @@ services} instead. # Associating Controllers with Angular Scope Objects -You can associate Controllers with scope objects implicitly via the {@link api/ng.directive:ngController ngController -directive} or {@link api/ngRoute.$route $route service}. +You can associate Controllers with scope objects implicitly via the {@link ng.directive:ngController ngController +directive} or {@link ngRoute.$route $route service}. ## Simple Spicy Controller Example @@ -206,7 +206,7 @@ input box) in the second button. ## Scope Inheritance Example It is common to attach Controllers at different levels of the DOM hierarchy. Since the -{@link api/ng.directive:ngController ng-controller} directive creates a new child scope, we get a +{@link ng.directive:ngController ng-controller} directive creates a new child scope, we get a hierarchy of scopes that inherit from each other. The `$scope` that each Controller receives will have access to properties and methods defined by Controllers higher up the hierarchy. See [Understanding Scopes](https://github.com/angular/angular.js/wiki/Understanding-Scopes) for @@ -267,7 +267,7 @@ examples, all of the properties could be replaced with methods that return strin ## Testing Controllers Although there are many ways to test a Controller, one of the best conventions, shown below, -involves injecting the {@link api/ng.$rootScope $rootScope} and {@link api/ng.$controller $controller}: +involves injecting the {@link ng.$rootScope $rootScope} and {@link ng.$controller $controller}: **Controller Definition:** ```js diff --git a/docs/content/guide/dev_guide.e2e-testing.ngdoc b/docs/content/guide/dev_guide.e2e-testing.ngdoc index d72cb9b3..da2dc48a 100644 --- a/docs/content/guide/dev_guide.e2e-testing.ngdoc +++ b/docs/content/guide/dev_guide.e2e-testing.ngdoc @@ -88,19 +88,19 @@ Returns the window.location.search of the currently loaded page in the test fram Returns the window.location.hash (without `#`) of the currently loaded page in the test frame. ## browser().location().url() -Returns the {@link api/ng.$location $location.url()} of the currently loaded page in +Returns the {@link ng.$location $location.url()} of the currently loaded page in the test frame. ## browser().location().path() -Returns the {@link api/ng.$location $location.path()} of the currently loaded page in +Returns the {@link ng.$location $location.path()} of the currently loaded page in the test frame. ## browser().location().search() -Returns the {@link api/ng.$location $location.search()} of the currently loaded page +Returns the {@link ng.$location $location.search()} of the currently loaded page in the test frame. ## browser().location().hash() -Returns the {@link api/ng.$location $location.hash()} of the currently loaded page in +Returns the {@link ng.$location $location.hash()} of the currently loaded page in the test frame. ## expect(future).{matcher} diff --git a/docs/content/guide/dev_guide.services.$location.ngdoc b/docs/content/guide/dev_guide.services.$location.ngdoc index 8f7a596a..57739f9f 100644 --- a/docs/content/guide/dev_guide.services.$location.ngdoc +++ b/docs/content/guide/dev_guide.services.$location.ngdoc @@ -87,7 +87,7 @@ setter methods that allow you to get or change the current URL in the browser. ## $location service configuration To configure the `$location` service, retrieve the -{@link api/ng.$locationProvider $locationProvider} and set the parameters as follows: +{@link ng.$locationProvider $locationProvider} and set the parameters as follows: - **html5Mode(mode)**: {boolean}<br /> @@ -138,7 +138,7 @@ current URL without creating a new browser history record you can call: ``` Note that the setters don't update `window.location` immediately. Instead, the `$location` service is -aware of the {@link api/ng.$rootScope.Scope scope} life-cycle and coalesces multiple `$location` +aware of the {@link ng.$rootScope.Scope scope} life-cycle and coalesces multiple `$location` mutations into one "commit" to the `window.location` object during the scope `$digest` phase. Since multiple changes to the $location's state will be pushed to the browser as a single change, it's enough to call the `replace()` method just once to make the entire "commit" a replace operation @@ -509,11 +509,11 @@ In this examples we use `<base href="/base/index.html" />` The `$location` service allows you to change only the URL; it does not allow you to reload the page. When you need to change the URL and reload the page or navigate to a different page, please -use a lower level API, {@link api/ng.$window $window.location.href}. +use a lower level API, {@link ng.$window $window.location.href}. ## Using $location outside of the scope life-cycle -`$location` knows about Angular's {@link api/ng.$rootScope.Scope scope} life-cycle. When a URL changes in +`$location` knows about Angular's {@link ng.$rootScope.Scope scope} life-cycle. When a URL changes in the browser it updates the `$location` and calls `$apply` so that all $watchers / $observers are notified. When you change the `$location` inside the `$digest` phase everything is ok; `$location` will @@ -635,7 +635,7 @@ then uses the information it obtains to compose hashbang URLs (such as ## Two-way binding to $location The Angular's compiler currently does not support two-way binding for methods (see [issue](https://github.com/angular/angular.js/issues/404)). If you should require two-way binding -to the $location object (using {@link api/ng.directive:input.text +to the $location object (using {@link ng.directive:input.text ngModel} directive on an input field), you will need to specify an extra model property (e.g. `locationPath`) with two watchers which push $location updates in both directions. For example: @@ -661,7 +661,7 @@ function LocationController($scope, $location) { # Related API -* {@link api/ng.$location $location API} +* {@link ng.$location $location API} diff --git a/docs/content/guide/dev_guide.services.creating_services.ngdoc b/docs/content/guide/dev_guide.services.creating_services.ngdoc index c6210cc1..cdcd280b 100644 --- a/docs/content/guide/dev_guide.services.creating_services.ngdoc +++ b/docs/content/guide/dev_guide.services.creating_services.ngdoc @@ -4,8 +4,8 @@ While Angular offers several useful services, for any nontrivial application you'll find it useful to write your own custom services. To do this you begin by registering a service factory function -with a module either via the {@link api/angular.module Module#factory api} or directly -via the {@link api/AUTO.$provide $provide} api inside of module config function. +with a module either via the {@link angular.module Module#factory api} or directly +via the {@link auto.$provide $provide} api inside of module config function. All Angular services participate in {@link di dependency injection (DI)} by registering themselves with Angular's DI system (injector) under a `name` (id) as well as by declaring @@ -17,8 +17,8 @@ testable. # Registering Services To register a service, you must have a module that this service will be part of. Afterwards, you -can register the service with the module either via the {@link api/angular.Module Module api} or -by using the {@link api/AUTO.$provide $provide} service in the module configuration +can register the service with the module either via the {@link angular.Module Module api} or +by using the {@link auto.$provide $provide} service in the module configuration function. The following pseudo-code shows both approaches: Using the angular.Module api: @@ -103,4 +103,4 @@ important. ## Related API -* {@link api/ng Angular Service API} +* {@link ng Angular Service API} diff --git a/docs/content/guide/dev_guide.services.injecting_controllers.ngdoc b/docs/content/guide/dev_guide.services.injecting_controllers.ngdoc index 312342b8..3bbbe6b1 100644 --- a/docs/content/guide/dev_guide.services.injecting_controllers.ngdoc +++ b/docs/content/guide/dev_guide.services.injecting_controllers.ngdoc @@ -118,4 +118,4 @@ dependencies with the `$inject` property. ## Related API -{@link api/ng Angular Service API} +{@link ng Angular Service API} diff --git a/docs/content/guide/dev_guide.services.managing_dependencies.ngdoc b/docs/content/guide/dev_guide.services.managing_dependencies.ngdoc index 726a8bbe..8803eb0d 100644 --- a/docs/content/guide/dev_guide.services.managing_dependencies.ngdoc +++ b/docs/content/guide/dev_guide.services.managing_dependencies.ngdoc @@ -87,10 +87,10 @@ of which depend on other services that are provided by the Angular framework: Things to notice in this example: -* The `batchLog` service depends on the built-in {@link api/ng.$interval $interval} and -{@link api/ng.$log $log} services, and allows messages to be logged into the +* The `batchLog` service depends on the built-in {@link ng.$interval $interval} and +{@link ng.$log $log} services, and allows messages to be logged into the `console.log` in batches. -* The `routeTemplateMonitor` service depends on the built-in {@link api/ngRoute.$route +* The `routeTemplateMonitor` service depends on the built-in {@link ngRoute.$route $route} service as well as our custom `batchLog` service. * Both of our services use the factory function signature and array notation for inject annotations to declare their dependencies. It is important that the order of the string identifiers in the array @@ -109,5 +109,5 @@ that the injector uses to determine which services and in which order to inject. ## Related API -* {@link api/ng Angular Service API} -* {@link api/angular.injector Angular Injector API} +* {@link ./ng Angular Service API} +* {@link angular.injector Angular Injector API} diff --git a/docs/content/guide/dev_guide.services.ngdoc b/docs/content/guide/dev_guide.services.ngdoc index 725e01e3..cb950b96 100644 --- a/docs/content/guide/dev_guide.services.ngdoc +++ b/docs/content/guide/dev_guide.services.ngdoc @@ -17,4 +17,4 @@ objects that are wired together using {@link di dependency injection (DI)}. ## Related API -* {@link api/ng Angular Service API} +* {@link ./ng Angular Service API} diff --git a/docs/content/guide/dev_guide.services.testing_services.ngdoc b/docs/content/guide/dev_guide.services.testing_services.ngdoc index 49f10c5a..e79a483a 100644 --- a/docs/content/guide/dev_guide.services.testing_services.ngdoc +++ b/docs/content/guide/dev_guide.services.testing_services.ngdoc @@ -59,4 +59,4 @@ it('should clear messages after alert', function() { ## Related API -* {@link api/ng Angular Service API} +* {@link ./ng Angular Service API} diff --git a/docs/content/guide/dev_guide.services.understanding_services.ngdoc b/docs/content/guide/dev_guide.services.understanding_services.ngdoc index bb02f541..8ebbed63 100644 --- a/docs/content/guide/dev_guide.services.understanding_services.ngdoc +++ b/docs/content/guide/dev_guide.services.understanding_services.ngdoc @@ -5,7 +5,7 @@ ## What are Angular Services? Angular services are singletons objects or functions that carry out specific tasks common to web apps. -Angular has a number of built in services, such as the {@link api/ng.$http $http service}, which +Angular has a number of built in services, such as the {@link ng.$http $http service}, which provides access to the browser's `XMLHttpRequest` object for making requests to a server. Like other core Angular variables and identifiers, the built-in services always start with `$` (such as `$http` mentioned above). You can also create your own custom services. @@ -49,12 +49,12 @@ dependent on this service gets a reference to the single instance generated by t ## Related Topics -* {@link di About Angular Dependency Injection} -* {@link dev_guide.services.creating_services Creating Angular Services} -* {@link dev_guide.services.managing_dependencies Managing Service Dependencies} -* {@link dev_guide.services.testing_services Testing Angular Services} +* {@link guide/di About Angular Dependency Injection} +* {@link guide/dev_guide.services.creating_services Creating Angular Services} +* {@link guide/dev_guide.services.managing_dependencies Managing Service Dependencies} +* {@link guide/dev_guide.services.testing_services Testing Angular Services} ## Related API -* {@link api/ng Angular Service API} -* {@link api/angular.injector Injector API} +* {@link ./ng Angular Service API} +* {@link angular.injector Injector API} diff --git a/docs/content/guide/dev_guide.templates.css-styling.ngdoc b/docs/content/guide/dev_guide.templates.css-styling.ngdoc index c00aa9f7..3d156790 100644 --- a/docs/content/guide/dev_guide.templates.css-styling.ngdoc +++ b/docs/content/guide/dev_guide.templates.css-styling.ngdoc @@ -8,7 +8,7 @@ Angular sets these CSS classes. It is up to your application to provide useful s # CSS classes used by angular * `ng-scope` - - **Usage:** angular applies this class to any element that where a new {@link api/ng.$rootScope.Scope scope} + - **Usage:** angular applies this class to any element that where a new {@link ng.$rootScope.Scope scope} is defined. (see {@link guide/scope scope} guide for more information about scopes) * `ng-binding` @@ -17,15 +17,15 @@ Angular sets these CSS classes. It is up to your application to provide useful s * `ng-invalid`, `ng-valid` - **Usage:** angular applies this class to an input widget element if that element's input does - not pass validation. (see {@link api/ng.directive:input input} directive) + not pass validation. (see {@link ng.directive:input input} directive) * `ng-pristine`, `ng-dirty` - - **Usage:** angular {@link api/ng.directive:input input} directive applies `ng-pristine` class + - **Usage:** angular {@link ng.directive:input input} directive applies `ng-pristine` class to a new input widget element which did not have user interaction. Once the user interacts with the input widget the class is changed to `ng-dirty`. ## Related Topics -* {@link templates Angular Templates} -* {@link forms Angular Forms} +* {@link guide/templates Angular Templates} +* {@link guide/forms Angular Forms} diff --git a/docs/content/guide/dev_guide.unit-testing.ngdoc b/docs/content/guide/dev_guide.unit-testing.ngdoc index 28779182..6be877e6 100644 --- a/docs/content/guide/dev_guide.unit-testing.ngdoc +++ b/docs/content/guide/dev_guide.unit-testing.ngdoc @@ -261,7 +261,7 @@ Notice that the test is not only much shorter, it is also easier to follow what that such a test tells a story, rather then asserting random bits which don't seem to be related. ## Filters -{@link api/ng.$filterProvider Filters} are functions which transform the data into a user readable +{@link ng.$filterProvider Filters} are functions which transform the data into a user readable format. They are important because they remove the formatting responsibility from the application logic, further simplifying the application logic. diff --git a/docs/content/guide/directive.ngdoc b/docs/content/guide/directive.ngdoc index 39ada01d..95aae48f 100644 --- a/docs/content/guide/directive.ngdoc +++ b/docs/content/guide/directive.ngdoc @@ -7,7 +7,7 @@ <div class="alert alert-warning"> **Note:** this guide is targeted towards developers who are already familiar with AngularJS basics. If you're just getting started, we recommend the {@link tutorial/ tutorial} first. -If you're looking for the **directives API**, we recently moved it to {@link api/ng.$compile `$compile`}. +If you're looking for the **directives API**, we recently moved it to {@link ng.$compile `$compile`}. </div> @@ -18,7 +18,7 @@ how to implement them. ## What are Directives? At a high level, directives are markers on a DOM element (such as an attribute, element -name, or CSS class) that tell AngularJS's **HTML compiler** ({@link api/ng.$compile `$compile`}) to +name, or CSS class) that tell AngularJS's **HTML compiler** ({@link ng.$compile `$compile`}) to attach a specified behavior to that DOM element or even transform the DOM element and its children. Angular comes with a set of these directives built-in, like `ngBind`, `ngModel`, and `ngView`. @@ -120,7 +120,7 @@ Doing so generally makes it easier to determine what directives a given element <div class="alert alert-success"> **Best Practice:** Comment directives were commonly used in places where the DOM API limits the ability to create directives that spanned multiple elements (e.g. inside `<table>` elements). -AngularJS 1.2 introduces {@link api/ng.directive:ngRepeat `ng-repeat-start` and `ng-repeat-end`} +AngularJS 1.2 introduces {@link ng.directive:ngRepeat `ng-repeat-start` and `ng-repeat-end`} as a better solution to this problem. Developers are encouraged to use this over custom comment directives when possible. </div> @@ -129,10 +129,10 @@ directives when possible. ### Text and attribute bindings -During the compilation process the {@link api/ng.$compile compiler} matches text and attributes -using the {@link api/ng.$interpolate $interpolate} service to see if they contain embedded -expressions. These expressions are registered as {@link api/ng.$rootScope.Scope#methods_$watch watches} -and will update as part of normal {@link api/ng.$rootScope.Scope#methods_$digest digest} cycle. An +During the compilation process the {@link ng.$compile compiler} matches text and attributes +using the {@link ng.$interpolate $interpolate} service to see if they contain embedded +expressions. These expressions are registered as {@link ng.$rootScope.Scope#methods_$watch watches} +and will update as part of normal {@link ng.$rootScope.Scope#methods_$digest digest} cycle. An example of interpolation is shown below: ```html @@ -174,7 +174,7 @@ For example, we could fix the example above by instead writing: ## Creating Directives -First let's talk about the {@link api/ng.$compileProvider#methods_directive API for registering directives}. Much like +First let's talk about the {@link ng.$compileProvider#methods_directive API for registering directives}. Much like controllers, directives are registered on modules. To register a directive, you use the `module.directive` API. `module.directive` takes the {@link guide/directive#creating-custom-directives_matching-directives normalized} directive name @@ -183,9 +183,9 @@ options to tell `$compile` how the directive should behave when matched. The factory function is invoked only once when the -{@link api/ng.$compile compiler} matches the directive for the first time. You can perform any +{@link ng.$compile compiler} matches the directive for the first time. You can perform any initialization work here. The function is invoked using -{@link api/AUTO.$injector#methods_invoke $injector.invoke} which makes it injectable just like a +{@link auto.$injector#methods_invoke $injector.invoke} which makes it injectable just like a controller. <div class="alert alert-success"> @@ -324,9 +324,9 @@ Let's change our directive to use `restrict: 'E'`: </example> For more on the -{@link api/ng.$compile#description_comprehensive-directive-api_directive-definition-object `restrict`} +{@link ng.$compile#description_comprehensive-directive-api_directive-definition-object `restrict`} property, see the -{@link api/ng.$compile#description_comprehensive-directive-api_directive-definition-object API docs}. +{@link ng.$compile#description_comprehensive-directive-api_directive-definition-object API docs}. <div class="alert alert-info"> **When should I use an attribute versus an element?** @@ -912,6 +912,6 @@ point for creating your own directives. You might also be interested in an in-depth explanation of the compilation process that's available in the {@link guide/compiler compiler guide}. -The {@link api/ng.$compile `$compile` API} page has a comprehensive list of directive options for +The {@link ng.$compile `$compile` API} page has a comprehensive list of directive options for reference. diff --git a/docs/content/guide/expression.ngdoc b/docs/content/guide/expression.ngdoc index 99cc7514..583fa5fd 100644 --- a/docs/content/guide/expression.ngdoc +++ b/docs/content/guide/expression.ngdoc @@ -3,7 +3,7 @@ @description Expressions are JavaScript-like code snippets that are usually placed in bindings such as `{{ -expression }}`. Expressions are processed by the {@link api/ng.$parse $parse} +expression }}`. Expressions are processed by the {@link ng.$parse $parse} service. Expressions are often post processed using {@link filter filters} to create a more user-friendly format. For example, these are all valid expressions in angular: @@ -30,7 +30,7 @@ You can think of Angular expressions as JavaScript expressions with following di If, on the other hand, you do want to run arbitrary JavaScript code, you should make it a controller method and call the method. If you want to `eval()` an angular expression from -JavaScript, use the {@link api/ng.$rootScope.Scope#methods_$eval `$eval()`} method. +JavaScript, use the {@link ng.$rootScope.Scope#methods_$eval `$eval()`} method. ## Example <doc:example> @@ -87,7 +87,7 @@ You can try evaluating different expressions here: # Property Evaluation Evaluation of all properties takes place against a scope. Unlike JavaScript, where names default -to global window properties, Angular expressions have to use {@link api/ng.$window +to global window properties, Angular expressions have to use {@link ng.$window `$window`} to refer to the global `window` object. For example, if you want to call `alert()`, which is defined on `window`, in an expression you must use `$window.alert()`. This is done intentionally to prevent accidental access to the global state (a common source of subtle bugs). diff --git a/docs/content/guide/filter.ngdoc b/docs/content/guide/filter.ngdoc index d156009a..4bcde01f 100644 --- a/docs/content/guide/filter.ngdoc +++ b/docs/content/guide/filter.ngdoc @@ -5,7 +5,7 @@ A filter formats the value of an expression for display to the user. They can be used in view templates, controllers or services and it is easy to define your own filter. -The underlying API is the {@link api/ng.$filterProvider filterProvider}. +The underlying API is the {@link ng.$filterProvider filterProvider}. ## Using filters in view templates @@ -13,7 +13,7 @@ Filters can be applied to expressions in view templates using the following synt {{ expression | filter }} -E.g. the markup `{{ 12 | currency }}` formats the number 12 as a currency using the {@link api/ng.filter:currency `currency`} +E.g. the markup `{{ 12 | currency }}` formats the number 12 as a currency using the {@link ng.filter:currency `currency`} filter. The resulting value is `$12.00`. Filters can be applied to the result of another filter. This is called "chaining" and uses @@ -26,7 +26,7 @@ Filters may have arguments. The syntax for this is {{ expression | filter:argument1:argument2:... }} E.g. the markup `{{ 1234 | number:2 }}` formats the number 1234 with 2 decimal points using the -{@link api/ng.filter:number `number`} filter. The resulting value is `1,234.00`. +{@link ng.filter:number `number`} filter. The resulting value is `1,234.00`. ## Using filters in controllers and services @@ -36,7 +36,7 @@ to your controller or service. E.g. using the dependency `numberFilter` will inj The injected argument is a function that takes the value to format as first argument and filter parameters starting with the second argument. -The example below uses the filter called {@link api/ng.filter:filter `filter`}. +The example below uses the filter called {@link ng.filter:filter `filter`}. This filter reduces arrays into sub arrays based on conditions. The filter can be applied in the view template with markup like `{{ctrl.array | filter:'a'}}`, which would do a fulltext search for "a". @@ -81,7 +81,7 @@ or the filter expression is changed). ## Creating custom filters Writing your own filter is very easy: just register a new filter factory function with -your module. Internally, this uses the {@link api/ng.$filterProvider `filterProvider`}. +your module. Internally, this uses the {@link ng.$filterProvider `filterProvider`}. This factory function should return a new filter function which takes the input value as the first argument. Any filter arguments are passed in as additional arguments to the filter function. diff --git a/docs/content/guide/forms.ngdoc b/docs/content/guide/forms.ngdoc index 84ee4330..d5f59d18 100644 --- a/docs/content/guide/forms.ngdoc +++ b/docs/content/guide/forms.ngdoc @@ -12,9 +12,9 @@ Server-side validation is still necessary for a secure application. # Simple form -The key directive in understanding two-way data-binding is {@link api/ng.directive:ngModel ngModel}. +The key directive in understanding two-way data-binding is {@link ng.directive:ngModel ngModel}. The `ngModel` directive provides the two-way data-binding by synchronizing the model to the view, as well as view to the model. -In addition it provides an {@link api/ng.directive:ngModel.NgModelController API} for other directives to augment its behavior. +In addition it provides an {@link ng.directive:ngModel.NgModelController API} for other directives to augment its behavior. <doc:example> <doc:source> @@ -113,11 +113,11 @@ This ensures that the user is not distracted with an error until after interacti # Binding to form and control state -A form is an instance of {@link api/ng.directive:form.FormController FormController}. +A form is an instance of {@link ng.directive:form.FormController FormController}. The form instance can optionally be published into the scope using the `name` attribute. -Similarly, an input control that has the {@link api/ng.directive:ngModel ngModel} directive holds an -instance of {@link api/ng.directive:ngModel.NgModelController NgModelController}. +Similarly, an input control that has the {@link ng.directive:ngModel ngModel} directive holds an +instance of {@link ng.directive:ngModel.NgModelController NgModelController}. Such a control instance can be published as a property of the form instance using the `name` attribute on the input control. The name attribute specifies the name of the property on the form instance. @@ -183,19 +183,19 @@ This allows us to extend the above example with these features: # Custom Validation -Angular provides basic implementation for most common html5 {@link api/ng.directive:input input} -types: ({@link api/ng.directive:input.text text}, {@link api/ng.directive:input.number number}, {@link api/ng.directive:input.url url}, {@link api/ng.directive:input.email email}, {@link api/ng.directive:input.radio radio}, {@link api/ng.directive:input.checkbox checkbox}), as well as some directives for validation (`required`, `pattern`, `minlength`, `maxlength`, `min`, `max`). +Angular provides basic implementation for most common html5 {@link ng.directive:input input} +types: ({@link ng.directive:input.text text}, {@link ng.directive:input.number number}, {@link ng.directive:input.url url}, {@link ng.directive:input.email email}, {@link ng.directive:input.radio radio}, {@link ng.directive:input.checkbox checkbox}), as well as some directives for validation (`required`, `pattern`, `minlength`, `maxlength`, `min`, `max`). -Defining your own validator can be done by defining your own directive which adds a custom validation function to the `ngModel` {@link api/ng.directive:ngModel.NgModelController controller}. +Defining your own validator can be done by defining your own directive which adds a custom validation function to the `ngModel` {@link ng.directive:ngModel.NgModelController controller}. To get a hold of the controller the directive specifies a dependency as shown in the example below. The validation can occur in two places: * **Model to View update** - - Whenever the bound model changes, all functions in {@link api/ng.directive:ngModel.NgModelController#properties_$formatters NgModelController#$formatters} array are pipe-lined, so that each of these functions has an opportunity to format the value and change validity state of the form control through {@link api/ng.directive:ngModel.NgModelController#methods_$setValidity NgModelController#$setValidity}. + Whenever the bound model changes, all functions in {@link ng.directive:ngModel.NgModelController#properties_$formatters NgModelController#$formatters} array are pipe-lined, so that each of these functions has an opportunity to format the value and change validity state of the form control through {@link ng.directive:ngModel.NgModelController#methods_$setValidity NgModelController#$setValidity}. * **View to Model update** - - In a similar way, whenever a user interacts with a control it calls {@link api/ng.directive:ngModel.NgModelController#methods_$setViewValue NgModelController#$setViewValue}. -This in turn pipelines all functions in the {@link api/ng.directive:ngModel.NgModelController#properties_$parsers NgModelController#$parsers} array, so that each of these functions has an opportunity to convert the value and change validity state of the form control through {@link api/ng.directive:ngModel.NgModelController#methods_$setValidity NgModelController#$setValidity}. + In a similar way, whenever a user interacts with a control it calls {@link ng.directive:ngModel.NgModelController#methods_$setViewValue NgModelController#$setViewValue}. +This in turn pipelines all functions in the {@link ng.directive:ngModel.NgModelController#properties_$parsers NgModelController#$parsers} array, so that each of these functions has an opportunity to convert the value and change validity state of the form control through {@link ng.directive:ngModel.NgModelController#methods_$setValidity NgModelController#$setValidity}. In the following example we create two directives. @@ -278,7 +278,7 @@ In the following example we create two directives. # Implementing custom form controls (using `ngModel`) -Angular implements all of the basic HTML form controls ({@link api/ng.directive:input input}, {@link api/ng.directive:select select}, {@link api/ng.directive:textarea textarea}), which should be sufficient for most cases. +Angular implements all of the basic HTML form controls ({@link ng.directive:input input}, {@link ng.directive:select select}, {@link ng.directive:textarea textarea}), which should be sufficient for most cases. However, if you need more flexibility, you can write your own form control as a directive. In order for custom control to work with `ngModel` and to achieve two-way data-binding it needs to: diff --git a/docs/content/guide/i18n.ngdoc b/docs/content/guide/i18n.ngdoc index 159958f8..9be65c0a 100644 --- a/docs/content/guide/i18n.ngdoc +++ b/docs/content/guide/i18n.ngdoc @@ -91,7 +91,7 @@ because an extra script needs to be loaded. **Currency symbol "gotcha"** Angular's [currency filter](http://docs.angularjs.org/#!/api/ng.filter:currency) allows -you to use the default currency symbol from the {@link api/ng.$locale locale service}, +you to use the default currency symbol from the {@link ng.$locale locale service}, or you can provide the filter with a custom currency symbol. If your app will be used only in one locale, it is fine to rely on the default currency symbol. However, if you anticipate that viewers in other locales might use your app, you should provide your own currency symbol to make sure the diff --git a/docs/content/guide/index.ngdoc b/docs/content/guide/index.ngdoc index a851e5b6..d975cd0e 100644 --- a/docs/content/guide/index.ngdoc +++ b/docs/content/guide/index.ngdoc @@ -27,7 +27,7 @@ In Angular applications, you move the job of filling page templates with data fr * {@link guide/databinding Data binding} * {@link guide/expression Expressions} * {@link guide/directive Directives} -* {@link api/ngRoute.$route Views and routes (see the example)} +* {@link ngRoute.$route Views and routes (see the example)} * {@link guide/filter Filters} * {@link guide/forms Forms} and [Concepts of AngularJS Forms](http://mrbool.com/the-concepts-of-angularjs-forms/29117) @@ -36,14 +36,14 @@ In Angular applications, you move the job of filling page templates with data fr * **Blog post: **[When to use directives, controllers or services](http://kirkbushell.me/when-to-use-directives-controllers-or-services-in-angular/) * **App wiring:** {@link guide/di Dependency injection} * **Exposing model to templates:** {@link guide/scope Scopes} -* **Communicating with servers:** {@link api/ng.$http $http}, {@link api/ngResource.$resource $resource} +* **Communicating with servers:** {@link ng.$http $http}, {@link ngResource.$resource $resource} ### Other AngularJS Features -* **Animation:** {@link guide/animations Core concepts}, {@link api/ngAnimate ngAnimate API}, and [Animation in AngularJS 1.2](http://www.yearofmoo.com/2013/08/remastered-animation-in-angularjs-1-2.html) -* **Security:** {@link api/ng.$sce Strict Contextual Escaping}, {@link api/ng.directive:ngCsp Content Security Policy}, {@link api/ngSanitize.$sanitize $sanitize}, [video](https://www.youtube.com/watch?v=18ifoT-Id54) -* **Internationalization and Localization:** {@link guide/i18n Angular Guide to i18n and l10n}, {@link api/ng.filter:date date filter}, {@link api/ng.filter:currency currency filter}, [Creating multilingual support](http://www.novanet.no/blog/hallstein-brotan/dates/2013/10/creating-multilingual-support-using-angularjs/) -* **Mobile:** {@link api/ngTouch Touch events} +* **Animation:** {@link guide/animations Core concepts}, {@link ngAnimate ngAnimate API}, and [Animation in AngularJS 1.2](http://www.yearofmoo.com/2013/08/remastered-animation-in-angularjs-1-2.html) +* **Security:** {@link ng.$sce Strict Contextual Escaping}, {@link ng.directive:ngCsp Content Security Policy}, {@link ngSanitize.$sanitize $sanitize}, [video](https://www.youtube.com/watch?v=18ifoT-Id54) +* **Internationalization and Localization:** {@link guide/i18n Angular Guide to i18n and l10n}, {@link ng.filter:date date filter}, {@link ng.filter:currency currency filter}, [Creating multilingual support](http://www.novanet.no/blog/hallstein-brotan/dates/2013/10/creating-multilingual-support-using-angularjs/) +* **Mobile:** {@link ngTouch Touch events} ### Testing diff --git a/docs/content/guide/migration.ngdoc b/docs/content/guide/migration.ngdoc index 92e61f67..2a16c9c7 100644 --- a/docs/content/guide/migration.ngdoc +++ b/docs/content/guide/migration.ngdoc @@ -361,7 +361,7 @@ See [05772e15](https://github.com/angular/angular.js/commit/05772e15fbecfdc63d49 ## $location.search supports multiple keys -{@link api/ng.$location#methods_search `$location.search`} now supports multiple keys with the +{@link ng.$location#methods_search `$location.search`} now supports multiple keys with the same value provided that the values are stored in an array. Before this change: diff --git a/docs/content/guide/module.ngdoc b/docs/content/guide/module.ngdoc index 417d3837..17cadb77 100644 --- a/docs/content/guide/module.ngdoc +++ b/docs/content/guide/module.ngdoc @@ -22,7 +22,7 @@ Ok, I'm in a hurry. How do I get a Hello World module working? Important things to notice: - * {@link api/angular.Module Module} API + * {@link angular.Module Module} API * Notice the reference to the `myApp` module in the `<html ng-app="myApp">`, it is what bootstraps the app using your module. diff --git a/docs/content/guide/providers.ngdoc b/docs/content/guide/providers.ngdoc index f0d33b51..84136563 100644 --- a/docs/content/guide/providers.ngdoc +++ b/docs/content/guide/providers.ngdoc @@ -6,7 +6,7 @@ Each web application you build is composed of objects that collaborate to get stuff done. These objects need to be instantiated and wired together for the app to work. In Angular apps most of -these objects are instantiated and wired together automatically by the {@link api/AUTO.$injector +these objects are instantiated and wired together automatically by the {@link auto.$injector injector service}. The injector creates two types of objects, **services** and **specialized objects**. @@ -34,7 +34,7 @@ In order for the injector to know how to create and wire together all of these o a registry of "recipes". Each recipe has an identifier of the object and the description of how to create this object. -Each recipe belongs to an {@link api/angular.Module Angular module}. An Angular module is a bag +Each recipe belongs to an {@link angular.Module Angular module}. An Angular module is a bag that holds one or more recipes. And since manually keeping track of module dependencies is no fun, a module can contain information about dependencies on other modules as well. 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. diff --git a/docs/content/guide/templates.ngdoc b/docs/content/guide/templates.ngdoc index fdd90b74..bd8bfd89 100644 --- a/docs/content/guide/templates.ngdoc +++ b/docs/content/guide/templates.ngdoc @@ -12,7 +12,7 @@ These are the types of Angular elements and element attributes you can use in a * {@link guide/directive Directive} — An attribute or element that augments an existing DOM element or represents a reusable DOM component - a widget. -* {@link api/ng.$interpolate Markup} — The double +* {@link ng.$interpolate Markup} — The double curly brace notation `{{ }}` to bind expressions to elements is built-in angular markup. * {@link filter Filter} — Formats your data for display to the user. * {@link forms Form controls} — Lets you validate user input. @@ -41,8 +41,8 @@ with {@link expression expressions}: In a simple single-page app, the template consists of HTML, CSS, and angular directives contained in just one HTML file (usually `index.html`). In a more complex app, you can display multiple views within one main page using "partials", which are segments of template located in separate HTML -files. You "include" the partials in the main page using the {@link api/ngRoute.$route -$route} service in conjunction with the {@link api/ngRoute.directive:ngView ngView} directive. An +files. You "include" the partials in the main page using the {@link ngRoute.$route +$route} service in conjunction with the {@link ngRoute.directive:ngView ngView} directive. An example of this technique is shown in the {@link tutorial/ angular tutorial}, in steps seven and eight. @@ -54,4 +54,4 @@ eight. ## Related API -* {@link api/index API Reference} +* {@link ./api API Reference} |