+
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.
diff --git a/docs/content/guide/concepts.ngdoc b/docs/content/guide/concepts.ngdoc
index bbf12b32..d0c2beca 100644
--- a/docs/content/guide/concepts.ngdoc
+++ b/docs/content/guide/concepts.ngdoc
@@ -2,450 +2,383 @@
@name Conceptual Overview
@description
-# Overview
+There are some concepts within Angular that you should understand before creating your first application.
+This section touches all important parts of Angular really quickly using a simple example.
+However, it won't explain all details.
+For a more in-depth explanation, have a look at the {@link tutorial/ tutorial}.
-This document gives a quick overview of the main angular components and how they work together.
-These are:
+| Concept | Description |
+|------------------|------------------------------------------|
+|{@link concepts#template Template} | HTML with additional markup |
+|{@link concepts#directive Directives} | extend HTML with custom attributes and elements |
+|{@link concepts#model Model} | the data that is shown to the user and with which the user interacts |
+|{@link concepts#scope Scope} | context where the model is stored so that directives and expressions can access it |
+|{@link concepts#expression Expressions} | access variables and functions from the scope |
+|{@link concepts#compiler Compiler} | parses the template and instantiates directives and expressions |
+|{@link concepts#filter Filter} | formats the value of an expression for display to the user |
+|{@link concepts#view View} | what the user sees (the DOM) |
+|{@link concepts#databinding Data Binding} | sync data between the model and the view |
+|{@link concepts#controller Controller} | the business logic behind views |
+|{@link concepts#di Dependency Injection} | Creates and wires objects / functions |
+|{@link concepts#injector Injector} | dependency injection container |
+|{@link concepts#module Module} | configures the Injector |
+|{@link concepts#service Service} | reusable business logic independent of views |
- * {@link concepts#startup startup} - bring up hello world
- * {@link concepts#runtime runtime} - overview of angular runtime
- * {@link concepts#scope scope} - the glue between the view and the controller
- * {@link concepts#controller controller} - application behavior
- * {@link concepts#model model} - your application data
- * {@link concepts#view view} - what the user sees
- * {@link concepts#directives directives} - extend HTML vocabulary
- * {@link concepts#filters filters} - format the data in user locale
- * {@link concepts#injector injector} - assembles your application
- * {@link concepts#module module} - configures the injector
- * {@link concepts#angular_namespace `$`} - angular namespace
-
-
+This looks like normal HTML, with some new markup. In Angular, a file like this is called a
+
- Hello {{name}}!
-
-
-
- -
-
- {{name}} -
+**Custom directives to access the DOM**: In Angular, the only place where an application touches the DOM is
+ within directives. This is good as artifacts that access the DOM are hard to test.
+ If you need to access the DOM directly you should write a custom directive for this. The
+ {@link directive directives guide} explains how to do this.
-
+The second kind of new markup are the double curly braces `{{ expression | filter }}`:
+When the compiler encounters this markup, it will replace it with the evaluated value of the markup.
+An "{@link expression expression}" in a template is a JavaScript-like code snippet that allows
+to read and write variables. Note that those variables are not global variables.
+Just like variables in a JavaScript function live in a scope,
+Angular provides a "{@link scope scope}" for the variables accessible to expressions.
+The values that are stored in variables on the scope are referred to as the "model"
+in the rest of the documentation.
+Applied to the example above, the markup directs Angular to "take the data we got from the input widgets
+and multiply them together".
+
+The example above also contains a "{@link dev_guide.templates.filters filter}".
+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
+into an output that looks like money.
+
+The important thing in the example is that angular provides _live_ bindings:
+Whenever the input values change, the value of the expressions are automatically
+recalculated and the DOM is updated with their values.
+The concept behind this is "{@link databinding two-way data binding}".
-
-# Controller
+# Adding UI logic: Controllers
-
+Let's add some more logic to the example to
+allow to enter and calculate the costs in different currencies and also pay the invoice.
-A controller is the code behind the view. Its job is to construct the model and publish it to the
-view along with callback methods. The view is a projection of the scope onto the template (the
-HTML). The scope is the glue which marshals the model to the view and forwards the events to the
-controller.
+
- Hello {{name}}!
-
-
- 
-
-The model is the data which is merged with the template to produce the view. To be able to
-render the model into the view, the model has to be able to be referenced from the scope. Unlike many
-other frameworks Angular makes no restrictions or requirements on the model. There are no classes
-to inherit from or special accessor methods for accessing or changing the model. The model can be
-primitive, object hash, or a full object Type. In short the model is a plain JavaScript object.
-
-
-
-# View
-
-
-
-The view is what the user sees. The view begins its life as a template, is merged with the
-model and finally rendered into the browser DOM. Angular takes a very different approach to
-rendering the view compared to most other templating systems.
-
- * **Others** - Most templating systems begin as an HTML string with special templating markup.
- Often the template markup breaks the HTML syntax which means that the template can not be
- edited by an HTML editor. The template string is then parsed by the template engine, and
- merged with the data. The result of the merge is an HTML string. The HTML string is then
- written to the browser using the `.innerHTML`, which causes the browser to render the HTML.
- When the model changes the whole process needs to be repeated. The granularity of the template
- is the granularity of the DOM updates. The key here is that the templating system manipulates
- strings.
- * **Angular** - Angular is different, since its templating system works on DOM objects not on
- strings. The template is still written in an HTML string, but it is HTML (not HTML with
- template sprinkled in.) The browser parses the HTML into the DOM, and the DOM becomes the input to
- the template engine known as the {@link api/ng.$compile compiler}. The compiler
- looks for {@link guide/directive directives} which in turn set up {@link
- api/ng.$rootScope.Scope#methods_$watch watches} on the model. The result is a
- continuously updating view which does not need template model re-merging. Your model becomes
- the single source-of-truth for your view.
-
-
-
-
-
-
- -
-
list={{list}} -
-
-
- - {{item}} - -
Edit Me
- model = {{content}}
-
- Number formatting: {{ 1234567890 | number }}
- array filtering - {{ list | filter:predicate | json }} -
- - array filtering - {{ list | filter:predicate | json }} -
-
-The {@link api/AUTO.$injector injector} is a service locator. There is a single
-{@link api/AUTO.$injector injector} per Angular {@link
-api/ng.directive:ngApp application}. The {@link
-api/AUTO.$injector injector} provides a way to look up an object instance by its
-name. The injector keeps an internal cache of all objects so that repeated calls to get the same
-object name result in the same instance. If the object does not exist, then the {@link
-api/AUTO.$injector injector} asks the instance factory to create a new instance.
-
-A {@link api/angular.Module module} is a way to configure the injector's instance factory, known
-as a {@link api/AUTO.$provide provider}.
-
-
- // Create a module
- var myModule = angular.module('myModule', [])
-
- // Configure the injector
- myModule.factory('serviceA', function() {
- return {
- // instead of {}, put your object creation here
- };
- });
-
- // create an injector and configure it from 'myModule'
- var $injector = angular.injector(['myModule']);
-
- // retrieve an object from the injector by name
- var serviceA = $injector.get('serviceA');
-
- // always true because of instance cache
- $injector.get('serviceA') === $injector.get('serviceA');
-
-
-
-But the real magic of the {@link api/AUTO.$injector injector} is that it can be
-used to {@link api/AUTO.$injector#methods_invoke call} methods and {@link
-api/AUTO.$injector#methods_instantiate instantiate} types. This subtle feature is what
-allows the methods and types to ask for their dependencies instead of having to look for them.
-
-
- // You write functions such as this one.
- function doSomething(serviceA, serviceB) {
- // do something here.
- }
-
- // Angular provides the injector for your application
- var $injector = ...;
-
- ///////////////////////////////////////////////
- // the old-school way of getting dependencies.
- var serviceA = $injector.get('serviceA');
- var serviceB = $injector.get('serviceB');
-
- // now call the function
- doSomething(serviceA, serviceB);
-
- ///////////////////////////////////////////////
- // the cool way of getting dependencies.
- // the $injector will supply the arguments to the function automatically
- $injector.invoke(doSomething); // This is how the framework calls your functions
-
-
-Notice that the only thing you needed to write was the function, and list the dependencies in the
-function arguments. When angular calls the function, it will use the {@link
-api/AUTO.$injector#methods_invoke call} which will automatically fill the function
-arguments.
-
-Examine the `ClockCtrl` below, and notice how it lists the dependencies in the constructor. When the
-{@link api/ng.directive:ngController ng-controller} instantiates
-the controller it automatically provides the dependencies. There is no need to create
-dependencies, look for dependencies, or even get a reference to the injector.
-
-
- Current time is: {{ time.now }}
-
-
+ Invoice:
+
+ Quantity:
+
+
+ Costs:
+
+
+
+ Total:
+
+ {{invoice.total(c) | currency:c}}
+
+
+
+ 
+
+# View independent business logic: Services
+
+Right now, the `InvoiceController` contains all logic of our example. When the application grows it
+is a good practise to move view independent logic from the controller into a so called
+"{@link dev_guide.services service}", so it can be reused by other parts
+of the application as well. Later on, we could also change that service to load the exchange rates
+from the web, e.g. by calling the Yahoo Finance API, without changing the controller.
+
+Let's refactor our example and move the currency conversion into a service in another file:
+
+
+ Invoice:
+
+
+ Quantity:
+
+
+ Costs:
+
+
+
+ Total:
+
+ {{invoice.total(c) | currency:c}}
+
+
+
+ 
+
+What changed?
+We moved the `convertCurrency` function and the definition of the existing currencies
+into the new file `finance.js`. But how does the controller
+get a hold of the now separated function?
+
+This is where "{@link di Dependency Injection}" comes into play.
+Dependency Injection (DI) is a software design pattern that
+deals with how objects and functions get created and how they get a hold of their dependencies.
+Everything within Angular (directives, filters, controllers,
+services, ...) is created and wired using dependency injection. Within Angular,
+the DI container is called the "{@link di injector}".
+
+To use DI, there needs to be a place where all the things that should work together are registered.
+In Angular, this is the purpose of the so called "{@link module modules}".
+When Angular starts, it will use the configuration of the module with the name defined by the `ng-app` directive,
+including the configuration of all modules that this module depends on.
+
+In the example above:
+The template contains the directive `ng-app="invoice"`. This tells Angular
+to use the `invoice` module as the main module for the application.
+The code snippet `angular.module('invoice', ['finance'])` specifies that the `invoice` module depends on the
+`finance` module. By this, Angular uses the `InvoiceController` as well as the `currencyConverter` service.
+
+Now that Angular knows of all the parts of the application, it needs to create them.
+In the previous section we saw that controllers are created using a factory function.
+For services there are multiple ways to define their factory
+(see the {@link dev_guide.services service guide}).
+In the example above, we are using a function that returns the `currencyConverter` function as the factory
+for the service.
+
+Back to the initial question: How does the `InvoiceController` get a reference to the `currencyConverter` function?
+In Angular, this is done by simply defining arguments on the constructor function. With this, the injector
+is able to create the objects in the right order and pass the previously created objects into the
+factories of the objects that depend on them.
+In our example, the `InvoiceController` has an argument named `currencyConverter`. By this, Angular knows about the
+dependency between the controller and the service and calls the controller with the service instance as argument.
+
+The last thing that changed in the example between the previous section and this section is that we
+now pass an array to the `module.controller` function, instead of a plain function. The array first
+contains the names of the service dependencies that the controller needs. The last entry
+in the array is the controller constructor function.
+Angular uses this array syntax to define the dependencies so that the DI also works after minifying
+the code, which will most probably rename the argument name of the controller constructor function
+to something shorter like `a`.
+
+# Accessing the backend
+
+Let's finish our example by fetching the exchange rates from the Yahoo Finance API.
+The following example shows how this is done with Angular:
+
+
+ Invoice:
+
+
+ Quantity:
+
+
+ Costs:
+
+
+
+ Total:
+
+ {{invoice.total(c) | currency:c}}
+
+
+
+ 
-
-
-## Related Topics
-
-* {@link dev_guide.mvc About MVC in Angular}
-* {@link dev_guide.mvc.understanding_controller Understanding the Controller Component}
-* {@link dev_guide.mvc.understanding_view Understanding the View Component}
diff --git a/docs/content/guide/dev_guide.mvc.understanding_view.ngdoc b/docs/content/guide/dev_guide.mvc.understanding_view.ngdoc
deleted file mode 100644
index 2827cf67..00000000
--- a/docs/content/guide/dev_guide.mvc.understanding_view.ngdoc
+++ /dev/null
@@ -1,22 +0,0 @@
-@ngdoc overview
-@name Developer Guide: About MVC in Angular: Understanding the View Component
-@description
-
-In Angular, the view is the DOM loaded and rendered in the browser, after Angular has transformed
-the DOM based on information in the template, controller and model.
-
-
-
-In the Angular implementation of MVC, the view has knowledge of both the model and the controller.
-The view knows about the model where two-way data-binding occurs. The view has knowledge of the
-controller through Angular directives, such as {@link api/ng.directive:ngController
-ngController} and {@link api/ngRoute.directive:ngView ngView}, and through bindings of this form:
-`{{someControllerFunction()}}`. In these ways, the view can call functions in an associated
-controller function.
-
-
-## Related Topics
-
-* {@link dev_guide.mvc About MVC in Angular}
-* {@link dev_guide.mvc.understanding_model Understanding the Model Component}
-* {@link dev_guide.mvc.understanding_controller Understanding the Controller Component}
diff --git a/docs/content/guide/dev_guide.templates.css-styling.ngdoc b/docs/content/guide/dev_guide.templates.css-styling.ngdoc
index 46ae6e96..38962fd2 100644
--- a/docs/content/guide/dev_guide.templates.css-styling.ngdoc
+++ b/docs/content/guide/dev_guide.templates.css-styling.ngdoc
@@ -13,7 +13,7 @@ Angular sets these CSS classes. It is up to your application to provide useful s
* `ng-binding`
- **Usage:** angular applies this class to any element that is attached to a data binding, via `ng-bind` or
- {{}} curly braces, for example. (see {@link guide/dev_guide.templates.databinding databinding} guide)
+ {{}} curly braces, for example. (see {@link guide/databinding databinding} guide)
* `ng-invalid`, `ng-valid`
- **Usage:** angular applies this class to an input widget element if that element's input does
@@ -27,5 +27,5 @@ Angular sets these CSS classes. It is up to your application to provide useful s
## Related Topics
-* {@link dev_guide.templates Angular Templates}
+* {@link templates Angular Templates}
* {@link forms Angular Forms}
diff --git a/docs/content/guide/di.ngdoc b/docs/content/guide/di.ngdoc
index 0b8cb263..f694ea12 100644
--- a/docs/content/guide/di.ngdoc
+++ b/docs/content/guide/di.ngdoc
@@ -47,6 +47,8 @@ is simply handed the `greeter` at runtime.
This is desirable, but it puts the responsibility of getting hold of the dependency on the
code that constructs `SomeClass`.
+