diff options
| author | Igor Minar | 2011-06-15 22:31:40 -0700 | 
|---|---|---|
| committer | Igor Minar | 2011-06-15 22:31:40 -0700 | 
| commit | b842642b574a2b95c53b791308ed1bf8ff9d304d (patch) | |
| tree | fb26431c5372be74de2105df77e94dea4f198489 /docs/content/guide | |
| parent | d428c9910e66246c2af46602499acaeaf187d75b (diff) | |
| download | angular.js-b842642b574a2b95c53b791308ed1bf8ff9d304d.tar.bz2 | |
docs - stripping extra new lines
Diffstat (limited to 'docs/content/guide')
48 files changed, 2 insertions, 795 deletions
| diff --git a/docs/content/guide/dev_guide.bootstrap.auto_bootstrap.ngdoc b/docs/content/guide/dev_guide.bootstrap.auto_bootstrap.ngdoc index 1c5e3e26..0b03e19c 100644 --- a/docs/content/guide/dev_guide.bootstrap.auto_bootstrap.ngdoc +++ b/docs/content/guide/dev_guide.bootstrap.auto_bootstrap.ngdoc @@ -3,30 +3,23 @@  @name Developer Guide: Initializing Angular: Automatic Initiialization  @description -  Angular initializes automatically when you load the angular script into your page, specifying  angular's `ng:autobind` attribute with no arguments: -          <script src="angular.js" ng:autobind> -  From a high-level view, this is what happens during angular's automatic initialization process: -  1. The browser loads the page, and then runs the angular script. -      The `ng:autobind` attribute tells angular to compile and manage the whole HTML document. The  compilation phase is initiated in the page's `onLoad()` handler. Angular doesn't begin processing  the page until after the page load is complete. -  2. Angular finds the root of the HTML document and creates the global variable `angular` in the  global namespace. Everything that angular subsequently creates is bound to fields in this global  object. -  3. Angular walks the DOM looking for angular widgets, directives, and markup (such as `ng:init` or  `ng:repeat`). As angular encounters these, it creates child scopes as necessary and attaches them  to the DOM, registers listeners on those scopes, associates any controller functions with their @@ -34,39 +27,29 @@ data and their part of the view, and ultimately constructs a runnable applicatio  app features two-way data-binding and a nice separation between data, presentation, and business  logic. -  4. For the duration of the application session (while the page is loaded), angular monitors the  state of the application, and updates the view and the data model whenever the state of either one  changes. -  For details on how the compiler works, see {@link dev_guide.compiler Angular HTML Compiler}. - -  ## Initialization Options -  The reason why `ng:autobind` exists is because angular should not assume that the entire HTML  document should be processed just because the `angular.js` script is included. In order to compile  only a part of the document, specify the ID of the element you want to use for angular's root  element as the value of the `ng:autobind` attribute: -          ng:autobind="angularContent" - -  ## Auto-bootstrap with `#autobind` -  In some rare cases you can't define the `ng:` prefix before the script tag's attribute  (for  example,  in some CMS systems). In those situations it is possible to auto-bootstrap angular by  appending `#autobind` to the `<script src=...>` URL, like in this snippet: -  <pre>    <!doctype html>    <html> @@ -82,19 +65,15 @@ appending `#autobind` to the `<script src=...>` URL, like in this snippet:    </html>  </pre> -  As with `ng:autobind`, you can specify an element id that should be exclusively targeted for  compilation as the value of the `#autobind`, for example: `#autobind=angularContent`. -  ## Filename Restrictions for Auto-bootstrap -  In order for us to find the auto-bootstrap from a script attribute or URL fragment, the value of  the `script` `src` attribute that loads the angular script must match one of these naming  conventions: -  - `angular.js`  - `angular-min.js`  - `angular-x.x.x.js` @@ -103,28 +82,20 @@ conventions:  - `angular-x.x.x-xxxxxxxx.min.js` (dev snapshot)  - `angular-bootstrap.js` (used for development of angular) -  Optionally, any of the filename formats above can be prepended with a relative or absolute URL that  ends with `/`. -  ## Global Angular Object -  The angular script creates a single global variable `angular` in the global namespace. All angular  APIs are bound to fields of this global object. - -  ## Related Topics -  * {@link dev_guide.bootstrap Initializing Angular}  * {@link dev_guide.bootstrap.manual_bootstrap Manual Initialization} -  ## Related API -  {@link api/angular.compile Compiler API} diff --git a/docs/content/guide/dev_guide.bootstrap.manual_bootstrap.ngdoc b/docs/content/guide/dev_guide.bootstrap.manual_bootstrap.ngdoc index 2cce7b31..99535954 100644 --- a/docs/content/guide/dev_guide.bootstrap.manual_bootstrap.ngdoc +++ b/docs/content/guide/dev_guide.bootstrap.manual_bootstrap.ngdoc @@ -3,17 +3,14 @@  @name  Developer Guide: Initializing Angular: Manual Initialization  @description -  Letting angular handle the initialization process (bootstrapping) is a handy way to start using  angular, but advanced users who want more control over the initialization process can choose to use  the manual bootstrapping method instead. -  The best way to get started with manual bootstrapping is to look at the what happens when you use  {@link api/angular.directive.ng:autobind ng:autobind}, by showing each step of the process  explicitly. -  <pre>  <!doctype html>  <html xmlns:ng="http://angularjs.org"> @@ -32,27 +29,20 @@ Hello {{'World'}}!  </html>  </pre> -  This is the sequence that your code should follow if you bootstrap angular on your own: -  1. After the page is loaded, find the root of the HTML template, which is typically the root of  the document.  2. Run angular's {@link dev_guide.compiler Angular HTML compiler}, which converts a template into  an executable, bi-directionally bound application. - -  ## Related Topics -  * {@link dev_guide.bootstrap Initializing Angular}  * {@link dev_guide.bootstrap.auto_bootstrap Automatic Initialization}  * {@link dev_guide.compiler Angular HTML compiler} -  ## Related API -  {@link api/angular.compile Compiler API} diff --git a/docs/content/guide/dev_guide.bootstrap.ngdoc b/docs/content/guide/dev_guide.bootstrap.ngdoc index 49bb3a77..248491ae 100644 --- a/docs/content/guide/dev_guide.bootstrap.ngdoc +++ b/docs/content/guide/dev_guide.bootstrap.ngdoc @@ -3,20 +3,16 @@  @name Developer Guide: Initializing Angular  @description -  Initializing angular consists of loading the `angular.js` script in your page, and specifying how  angular should process and manage the page. To initialize angular you do the following: -  * Specify the angular namespace in the `<html>` page  * Choose which flavor of angular script to load (debug or production)  * Specify whether or not angular should process and manage the page automatically (`ng:autobind`) -  The simplest way to initialize angular is to load the angular script and tell angular to compile  and manage the whole page. You do this as follows: -  <pre>  <!doctype html>  <html xmlns:ng="http://angularjs.org"> @@ -30,57 +26,40 @@ and manage the whole page. You do this as follows:  </pre> - -  ## Specifying the Angular Namespace -          <html xmlns:ng="http://angularjs.org"> -  You need to declare the angular namespace declaration in the following cases: -  * For all types of browser if you are using XHTML.  * For Internet Explorer older than version 9 (because older versions of IE do not render widgets  properly for either HTML or XHTML). - -  ## Creating Your Own Namespaces -  When you are ready to define your own {@link dev_guide.compiler.widgets widgets}, you must create  your own namespace in addition to specifying the angular namespace. You use your own namespace to  form the fully qualified name for widgets that you create. -  For example, you could map the alias `my` to your domain, and create a widget called `my:widget`.  To create your own namespace, simply add another `xmlns` tag to your page, create an alias, and set  it to your unique domain: -          <html xmlns:ng="http://angularjs.org" xmlns:my="http://mydomain.com"> - -  ## Loading the Angular Bootstrap Script -  The angular bootstrap script comes in two flavors; a debug script, and a production script: -  * angular-[version].js - This is a human-readable file, suitable for development and debugging.  * angular-[version].min.js - This is a compressed and obfuscated file, suitable for use in  production. - -  ## Related Topics -  * {@link dev_guide.bootstrap.auto_bootstrap Automatic Initialization}  * {@link dev_guide.bootstrap.manual_bootstrap Manual Initialization} diff --git a/docs/content/guide/dev_guide.compiler.directives.creating_directives.ngdoc b/docs/content/guide/dev_guide.compiler.directives.creating_directives.ngdoc index 570de384..c70efd51 100644 --- a/docs/content/guide/dev_guide.compiler.directives.creating_directives.ngdoc +++ b/docs/content/guide/dev_guide.compiler.directives.creating_directives.ngdoc @@ -3,12 +3,10 @@  @name Developer Guide: Angular HTML Compiler: Directives: Creating Custom Angular Directives  @description -  The following code snippet shows how to define a custom directive. You define a new directive by  extending the {@link dev_guide.compiler Angular HTML compiler}. The code snippet below is a  simplified definition of the built-in {@link api/angular.directive.ng:bind ng:bind} directive: -  <pre>  angular.directive('ng:bind', function(expression, compiledElement) {      var compiler = this; @@ -21,29 +19,21 @@ angular.directive('ng:bind', function(expression, compiledElement) {  });  </pre> -  # Additional Compiler Methods for Custom Directives -  The angular compiler exposes methods that you may need to use when writing your own widgets and  directives.  For example, the `descend()` method lets you control whether the compiler ignores or  processes child elements of the element it is compiling.  For information on this and other  compiler methods, see the {@link api/angular.compile Compiler API doc}. - -  ## Related Docs -  * {@link dev_guide.compiler.directives Understanding Angular Directives}  * {@link dev_guide.compiler.directives_widgets Comparing Directives and Widgets}  * {@link dev_guide.compiler Angular HTML Compiler} - -  ## Related API -  * {@link api/angular.directive Angular Directive API}. diff --git a/docs/content/guide/dev_guide.compiler.directives.ngdoc b/docs/content/guide/dev_guide.compiler.directives.ngdoc index f853d5e8..0f99e46b 100644 --- a/docs/content/guide/dev_guide.compiler.directives.ngdoc +++ b/docs/content/guide/dev_guide.compiler.directives.ngdoc @@ -3,39 +3,30 @@  @name Developer Guide: Angular HTML Compiler: Understanding Angular Directives  @description -  An angular directive is a custom HTML attribute that angular knows how to process.  You add them to  a template element like any other attribute.  Angular directives all have a `ng:` prefix.  In the  following example, the angular directive (`ng:controller`) is  a div tag: -          <div ng:controller> -  You use angular directives to modify DOM element properties. The element you modify can be an  existing HTML element type or a custom DOM element type that you created. You can use any number of  directives per element. -  You add angular directives to a standard HTML tag as in the following example, in which we have  added the {@link api/angular.directive.ng:click ng:click} directive to a button tag: -          <button name="button1" ng:click="foo()">Click This</button> -  In the example above, `name` is the standard HTML attribute, and `ng:click` is the angular  directive. The `ng:click` directive lets you implement custom behavior in an associated controller  function. -  In the next example, we add the {@link api/angular.directive.ng:bind ng:bind} directive to a  `<span>` tag: -          <span ng:bind="1+2"></span> -  The `ng:bind` directive tells angular to set up {@link dev_guide.templates.databinding data  binding} between the data model and the view for the specified expression.  When the angular {@link  dev_guide.compiler compiler} encounters an `ng:bind` directive in a template, it passes the @@ -44,18 +35,13 @@ the expression in the model, the view is updated to display the span text with t  expression value. - -  ## Related Topics -  * {@link dev_guide.compiler Angular HTML Compiler}  * {@link dev_guide.compiler.directives.creating_directives Creating Angular Directives}  * {@link dev_guide.compiler.directives_widgets Comparing Directives and Widgets} -  ## Related API: -  * {@link api/angular.directive Directive API}  * {@link api/angular.widget Widget API} diff --git a/docs/content/guide/dev_guide.compiler.directives_widgets.ngdoc b/docs/content/guide/dev_guide.compiler.directives_widgets.ngdoc index 53da202c..ca6c54df 100644 --- a/docs/content/guide/dev_guide.compiler.directives_widgets.ngdoc +++ b/docs/content/guide/dev_guide.compiler.directives_widgets.ngdoc @@ -3,18 +3,15 @@  @name Developer Guide: Angular HTML Compiler: Comparing Directives and Attribute Widgets  @description -  Although directives and {@link dev_guide.compiler.widgets attribute widgets} appear the same in a  template (`ng:init` is a directive, `ng:repeat` is an attribute widget), there is a difference in  the order in which they are evaluated.  The user of existing directives or widgets cannot determine  the order of evaluation. The evaluation order is the responsibility of the developer creating  custom directives and widgets. -  For example, consider this piece of HTML, which uses the `ng:repeat`, `ng:init`, and `ng:bind`  widget and directives: -  <pre>  <ul ng:init="people=['mike', 'mary']">  <li ng:repeat="person in people" @@ -24,36 +21,28 @@ widget and directives:  </ul>  </pre> -  Notice that the order of execution matters here. Because we want to run the `ng:init="a=a+1` and  `ng:bind="person"` once for each `person in people`, we need to execute {@link  api/angular.widget.@ng:repeat ng:repeat} to make copies of the `<li>` element before we run the  {@link api/angular.directive.ng:init ng:init}, and {@link api/angular.directive.ng:bind ng:bind}  for each of the `<li>`copies. -  If you implemented `ng:repeat` as a directive, there would be no guarantee that the attributes  `ng:repeat`, `ng:init`, and `ng:bind` would be evaluated in the order they are declared, because  the order of element attributes in HTML is not significant to the browser. -  So, when creating a custom HTML attribute, you will have to consider whether a directive or a  widget is more appropriate. When the order of execution doesn't matter, directives are the right  choice. In a situation where the order matters and one attribute should be processed with a higher  priority than others, use a widget for the attribute that must be processed first. - -  ## Related Topics -  * {@link dev_guide.compiler.directives Understanding Angular Directives}  * {@link dev_guide.compiler.widgets Understanding Angular Widgets} -  ## Related API: -  * {@link api/angular.directive Directive API}  * {@link api/angular.widget Widget API} diff --git a/docs/content/guide/dev_guide.compiler.extending_compiler.ngdoc b/docs/content/guide/dev_guide.compiler.extending_compiler.ngdoc index ea0a063c..ff507630 100644 --- a/docs/content/guide/dev_guide.compiler.extending_compiler.ngdoc +++ b/docs/content/guide/dev_guide.compiler.extending_compiler.ngdoc @@ -65,17 +65,13 @@ return function(linkElement){  Note: For more about widgets, see {@link dev_guide.compiler.widgets Understanding Angular Widgets}  and the {@link api/angular.widget widget API reference page}. -  # Compilation process for `<my:greeter>` -  Here are the steps that the compiler takes in processing the page that contains the widget  definition above: -  ## Compile Phase -  1. Recursively traverse the DOM depth-first.  2. Find the angular.widget definition.  3. Find and execute the widget's compileElement function, which includes the following steps: @@ -86,10 +82,8 @@ template (i.e. any repeating elements)).     2. Extract the salutation and name HTML attributes as angular expressions.  4. Return the aggregate link function, which includes just one link function in this example. -  ## Link Phase -  1. Execute the aggregate link function, which includes the following steps:     1. Create a <span> element set to the salutation class     2. Create a <span> element set to the name class. @@ -99,17 +93,12 @@ compileElement, because that's the template.)  corresponding spans. - -  ## Related Topics -  * {@link dev_guide.compiler Angular HTML Compiler}  * {@link dev_guide.compiler.understanding_compiler Understanding How the Compiler Works}  * {@link dev_guide.compiler.testing_dom_element Testing a New DOM Element} -  ## Related API -  * {@link api/angular.compile angular.compile()} diff --git a/docs/content/guide/dev_guide.compiler.markup.ngdoc b/docs/content/guide/dev_guide.compiler.markup.ngdoc index 64a3940b..a6f43586 100644 --- a/docs/content/guide/dev_guide.compiler.markup.ngdoc +++ b/docs/content/guide/dev_guide.compiler.markup.ngdoc @@ -3,59 +3,46 @@  @name Developer Guide: Angular HTML Compiler: Understanding Angular Markup  @description -  Markup in angular is a feature that you can use in templates to transform the content of DOM  elements prior to the compile phase (in which elements are compiled and link functions are  returned.  See the {@link dev_guide.compiler compiler docs} for details on how the compiler  works.)  The ability to make pre-compile changes to DOM elements lets you create shorthand for  {@link api/angular.widget widget} and {@link api/angular.directive directive} declarations. -  Angular provides one built-in markup feature: the double curly-braces used to declare binding  points (between the model and view) for angular expressions.  You can also create your own custom  markup. -  # Using Double Curly-brace Markup (`{{ }}`) -  The double curly-brace (`{{ }}`) markup translates an enclosed expression into an {@link  api/angular.directive.ng:bind ng:bind} directive: -  <pre>  {{expression}}  </pre> -  is transformed to: -  <pre>  <span ng:bind="expression"></span>  </pre> -  Markup is useful for the simple reason that `{{1+2}}` is easier to write and understand than `<span  ng:bind="1+2"></span>`. After markup shorthand is expanded into the DOM elements it represents, the  expanded elements are then {@link dev_guide.compiler compiled} normally. - -  # Creating Custom Markup -  Let's say you want to define markup that transforms `---` into a horizontal rule (`<hr/>`): -  <pre>  header  ---  footer  </pre> -  should translate to:  <pre>  header @@ -63,10 +50,8 @@ header  footer  </pre> -  Here is how you could extend the angular compiler to create the "---" markup: -  <pre>  angular.markup('---', function(text, textNode, parentElement) {      var compiler = this; @@ -83,20 +68,16 @@ angular.markup('---', function(text, textNode, parentElement) {  });  </pre> -  Unlike the way the compiler processes {@link api/angular.widget widgets} and {@link  api/angular.directive directives} (matching the name of the handler function to a DOM element or  attribute name), the compiler calls every markup handler for every text node, giving the handler a  chance to transform the text. The markup handler needs to find all the matches in the text. -  ## Attribute Markup -  Attribute markup extends the angular compiler in a very similar way to markup, except that it  allows you to modify the state of attribute text rather then the content of a node. -  <pre>  angular.attrMarkup('extraClass', function(attrValue, attrName, element){   if (attrName == 'additional-class') { @@ -106,15 +87,10 @@ angular.attrMarkup('extraClass', function(attrValue, attrName, element){  </pre> - -  ## Related Topics -  * {@link dev_guide.compiler Angular HTML Compiler} -  ## Related API -  * {@link api/angular.compile Compiler API Reference} diff --git a/docs/content/guide/dev_guide.compiler.ngdoc b/docs/content/guide/dev_guide.compiler.ngdoc index 08c40a56..86581fb5 100644 --- a/docs/content/guide/dev_guide.compiler.ngdoc +++ b/docs/content/guide/dev_guide.compiler.ngdoc @@ -3,24 +3,18 @@  @name Developer Guide: Angular HTML Compiler  @description -  The core of angular is its HTML compiler.  The compiler processes angular directives, widgets, and  markup to transform a static HTML page into a dynamic web application. -  The default HTML transformations that the angular compiler provides are useful for building generic  apps, but you can also extend the compiler to create a domain-specific language for building  specific types of web applications. -  All compilation takes place in the web browser; no server is involved. - -  ## Related Topics -  * {@link dev_guide.compiler.understanding_compiler Understanding How the Compiler Works}  * {@link dev_guide.compiler.extending_compiler Extending the Angular Compiler}  * {@link dev_guide.compiler.testing_dom_element Testing a New DOM Element} @@ -28,8 +22,6 @@ All compilation takes place in the web browser; no server is involved.  * {@link dev_guide.compiler.directives Understanding Angular Directives}  * {@link dev_guide.compiler.markup Understanding Angular Markup} -  ## Related API -  * {@link api/angular.compile Angular Compiler API} diff --git a/docs/content/guide/dev_guide.compiler.testing_dom_element.ngdoc b/docs/content/guide/dev_guide.compiler.testing_dom_element.ngdoc index bd290f0d..9b559c17 100644 --- a/docs/content/guide/dev_guide.compiler.testing_dom_element.ngdoc +++ b/docs/content/guide/dev_guide.compiler.testing_dom_element.ngdoc @@ -4,22 +4,15 @@  @description - -  "Testing, testing, come in, over?" - -  ## Related Topics -  * {@link dev_guide.compiler Angular HTML Compiler}  * {@link dev_guide.compiler.understanding_compiler Understanding How the Compiler Works}  * {@link dev_guide.compiler.extending_compiler Extending the Angular Compiler} -  ## Related API -  * {@link api/angular.compile angular.compile()} diff --git a/docs/content/guide/dev_guide.compiler.understanding_compiler.ngdoc b/docs/content/guide/dev_guide.compiler.understanding_compiler.ngdoc index 714ef9c0..7e86e206 100644 --- a/docs/content/guide/dev_guide.compiler.understanding_compiler.ngdoc +++ b/docs/content/guide/dev_guide.compiler.understanding_compiler.ngdoc @@ -3,7 +3,6 @@  @name Developer Guide: Angular HTML Compiler: Understanding How the Compiler Works  @description -  Every {@link api/angular.widget widget}, {@link api/angular.directive directive} and {@link  dev_guide.compiler.markup markup} is defined with a compile function, which the angular compiler  executes on each widget or directive it encounters. The compile function optionally returns a link @@ -11,10 +10,8 @@ function.  This compilation process happens automatically when the page is loade  `ng:autobind` in the script tag from which you load the angular script file.  (See {@link  dev_guide.bootstrap Initializing Angular}.) -  The compile and link functions are related as follows: -  * **compile function** — Registers a listener for the widget, directive, or markup expression. The  compiler calls this function exactly once.  * **link function** — Sets up the listener registered by the compile function. This function can be @@ -22,20 +19,16 @@ called multiple times, once per cloned DOM element. For example, in the case of  api/angular.widget.@ng:repeat repeater widget} used in a list element (`<li ng:repeat="[item in  dataset]"`), the link function gets called to set up a listener on each element in the list. -  Note that angular's built-in widgets, directives, and markup have predefined compile and link  functions that you don't need to modify. When you create your own widgets, directives, or markup,  you must write compile and link functions for them. Refer to the {@link api/angular.compile  Compiler API} for details. -  When the angular compiler compiles a page, it proceeds through 3 phases: Compile, Create Root  Scope, and Link: -  1. Compile Phase -     1. Recursively traverse the DOM, depth-first.     2. Look for a matching compile function of type widget, then markup, then directive.     3. If a compile function is found then execute it. @@ -43,46 +36,34 @@ Scope, and Link:  function with all link functions returned previously by step 3.     5. Repeat steps 3 and 4 for all compile functions found. -  The result of the compilation phase is an aggregate link function, which comprises all of the  individual link functions. -  2. Create Root Scope Phase -  * Inject all services into the root scope. -  3. Link Phase -     1. Execute the aggregate link function with the root scope. The aggregate link function calls  all of the individual link functions that were generated in the compile phase.     2. If there are any clones of the DOM caused by repeating elements, call the link function  multiple times, one for each repeating item. -  Note that while the compile function is executed exactly once, the link function can be executed  multiple times, for example, once for each iteration in a repeater. -  The angular compiler exposes methods that you will need to make use of when writing your own  widgets and directives.  For information on these methods, see the {@link api/angular.compile  Compiler API doc}. - -  ## Related Topics -  * {@link dev_guide.compiler Angular HTML Compiler}  * {@link dev_guide.compiler.extending_compiler Extending the Angular Compiler}  * {@link dev_guide.compiler.testing_dom_element Testing a New DOM Element} -  ## Related API -  * {@link api/angular.compile angular.compile()} diff --git a/docs/content/guide/dev_guide.compiler.widgets.creating_widgets.ngdoc b/docs/content/guide/dev_guide.compiler.widgets.creating_widgets.ngdoc index 62edd04f..906e0127 100644 --- a/docs/content/guide/dev_guide.compiler.widgets.creating_widgets.ngdoc +++ b/docs/content/guide/dev_guide.compiler.widgets.creating_widgets.ngdoc @@ -3,24 +3,19 @@  @name Developer Guide: Angular HTML Compiler: Widgets: Creating Custom Widgets  @description -  When you create your own widgets, you must set up your own namespace for them.  (See  dev_guide.bootstrap Initializing Angular} for information about namespaces in angular.) -  Let's say we would like to create a new element type in the namespace `my` that can watch an  expression and `alert()` the user with each new value: -  <pre>  // An element widget  <my:watch exp="name"/>  </pre> -  You can implement `my:watch` like this: -  <pre>  angular.widget('my:watch', function(compileElement) {   var compiler = this; @@ -35,15 +30,11 @@ angular.widget('my:watch', function(compileElement) {  </pre> - -  # Creating a Custom Attribute Widget -  Let's implement the same widget as in the example in Defining an Element Widget, but this time as  an attribute that can be added to any existing DOM element: -  <pre>  // An attribute widget (my-watch) in a div tag  <div my-watch="name">text</div> @@ -62,11 +53,8 @@ angular.widget('@my:watch', function(expression, compileElement) {  </pre> - -  # Live Example of a Custom Element Widget -  <doc:example>  <doc:source>  <script> @@ -88,29 +76,21 @@ angular.widget('my:time', function(compileElement){  </doc:example> - -  # Additional Compiler Methods for Custom Widgets -  The angular compiler exposes methods that you may need to use of when writing your own widgets and  directives.  For example, the `descend()` method lets you control whether the compiler ignores or  processes child elements of the element it is compiling.  For information on this and other  compiler methods, see the {@link api/angular.compile Compiler API doc}. - -  ## Related Topics -  * {@link dev_guide.compiler Angular HTML Compiler}  * {@link dev_guide.compiler.directives Angular Directives}  * {@link dev_guide.compiler.widgets Angular Widgets}  * {@link dev_guide.compiler.directives.creating_directives Creating Custom Directives} -  ## Related API -  * {@link api/angular.compile Compiler API} diff --git a/docs/content/guide/dev_guide.compiler.widgets.ngdoc b/docs/content/guide/dev_guide.compiler.widgets.ngdoc index dbe082a6..1c5fbca3 100644 --- a/docs/content/guide/dev_guide.compiler.widgets.ngdoc +++ b/docs/content/guide/dev_guide.compiler.widgets.ngdoc @@ -3,24 +3,19 @@  @name Developer Guide: Angular HTML Compiler: Understanding Angular Widgets  @description -  Widgets are DOM elements that the browser doesn't already understand. Angular provides some  built-in widgets (such as {@link api/angular.widget.@ng:repeat ng:repeat}), and you can create your  own custom widgets. -  Widgets are intended to manipulate the DOM tree by adding new elements (unlike {@link  dev_guide.compiler.directives angular directives}, which are intended to modify only element  properties). -  Widgets come in two types: -  * Element Widget — A custom DOM element.  An example of a custom element is shown in {@link  dev_guide.compiler.widgets.creating_widgets Creating Custom Widgets}. -  * Attribute Widget — A custom attribute on an existing DOM element.  An attribute widget is similar  to an angular directive, with the main difference being that an attribute widget will always be  processed before any directives that are specified on the same element.  Only one attribute widget @@ -29,19 +24,13 @@ dev_guide.compiler.widgets.creating_widgets Creating Custom Widgets}. - - -  ## Related Topics -  * {@link dev_guide.compiler Angular HTML Compiler}  * {@link dev_guide.compiler.directives Angular Directives}  * {@link dev_guide.compiler.widgets.creating_widgets Creating Custom Widgets}  * {@link dev_guide.compiler.directives.creating_directives Creating Custom Directives} -  ## Related API -  * {@link api/angular.compile Compiler API} diff --git a/docs/content/guide/dev_guide.di.ngdoc b/docs/content/guide/dev_guide.di.ngdoc index a2352cc3..67e12a9b 100644 --- a/docs/content/guide/dev_guide.di.ngdoc +++ b/docs/content/guide/dev_guide.di.ngdoc @@ -3,41 +3,31 @@  @name Developer Guide: About Dependency Injection (DI)  @description -  Dependency Injection (DI) is an object-oriented software design pattern that supports the  decoupling and dependency management of application components. -  The idea behind DI is to decouple each component from all of the other components that it depends  on to do its particular job. The way this is done in DI is by moving the responsibility for  managing dependencies out of each individual component and into a provider component. The provider  (or injector) component manages the life cycles and dependencies for all of the other components in  an application. -  Angular has a built-in dependency management subsystem that helps to make your applications easier  to develop, understand, and test. -  For more information on DI in general, see {@link http://en.wikipedia.org/wiki/Dependency_injection  Dependency Injection} at Wikipedia, and {@link http://martinfowler.com/articles/injection.html  Inversion of Control} by Martin Fowler, or read about DI in your favorite software design pattern  book. - -  ## Related Topics -  * {@link dev_guide.di.understanding_di Understanding DI in Angular}  * {@link dev_guide.services Angular Services} - -  ## Related API -  * {@link api/angular.service Service API}  * {@link api/angular.injector Angular Injector API} diff --git a/docs/content/guide/dev_guide.di.understanding_di.ngdoc b/docs/content/guide/dev_guide.di.understanding_di.ngdoc index 1b131eaf..ff2551f1 100644 --- a/docs/content/guide/dev_guide.di.understanding_di.ngdoc +++ b/docs/content/guide/dev_guide.di.understanding_di.ngdoc @@ -4,21 +4,16 @@  @description - -  While DI is widely used in statically typed languages such as Java or C++, it has not been widely  used in JavaScript. Angular brings the benefits of DI into JavaScript apps. -  In angular, DI is implemented as a subsystem that manages dependencies between services,  controllers, widgets, and filters. The most important of these are {@link api/angular.service  services}. -  Services are objects that handle common tasks in web applications. Angular provides several{@link  api/angular.service built-in services}, and you can create your own custom services. -  The main job of angular's DI subsystem is to provide services to angular components that depend on  them. The way the DI subsystem provides services is as follows: all services are registered with  angular's {@link api/angular.service service API}, and all components that depend on services @@ -27,13 +22,10 @@ manages the creation of service objects and the provision of those objects to th  need them, at the time they need them. The following illustration steps through the sequence of  events: -  <img src="img/guide/di_sequence_final.png"> -  In the illustration above, the dependency injection sequence proceeds as follows: -  1. Service factory functions are registered with angular's service factory repository.  2. `ng:autobind` triggers angular's bootstrap sequence, during which angular compiles the template,  creates the root scope, and creates the dependency injector. @@ -45,22 +37,17 @@ factory function from the service factory repository to construct it.  6. DI provides the instance of $xhr service to the PhoneListCtrl controller constructor - -  ## How Scope Relates to DI -  The {@link api/angular.injector injector} is responsible for resolving the service dependencies in  the application. It gets created and configured with the creation of a root scope. The injector  caches instances of services, with the services cache bound to the root scope. -  Different root scopes have different instances of the injector. While typical angular applications  will only have one root scope (and hence the services will act like application singletons), in  tests it is important to not share singletons across test invocations for isolation reasons. We  achieve the necessary isolation by having each test create its own separate root scope. -  <pre>  // create a root scope  var rootScope = angular.scope(); @@ -68,50 +55,40 @@ var rootScope = angular.scope();  var myService = rootScope.$service('myService');  </pre> -  ## Inferring dependencies from the signature of the factory function or constructor -  **EXPERIMENTAL FEATURE**: This is an experimental feature. See the important note at the end of  this section for drawbacks. -  We resort to `$inject` and our own annotation because there is no way in JavaScript to get a list  of arguments. Or is there? It turns out that calling `.toString()` on a function returns the  function declaration along with the argument names as shown below: -  <pre>  function myFn(a,b){}  expect(myFn.toString()).toEqual('function myFn(a,b){}');  </pre> -  This means that angular can infer the function names after all and use that information to generate  the `$inject` annotation automatically. Therefore the following two function definitions are  equivalent: -  <pre>  // given a user defined service  angular.service('serviceA', ...); -  // inject '$window', 'serviceA', curry 'name';  function fnA($window, serviceA, name){};  fnA.$inject = ['$window', 'serviceA']; -  // inject '$window', 'serviceA', curry 'name';  function fnB($window, serviceA_, name){};  // implies: fnB.$inject = ['$window', 'serviceA'];  </pre> -  If angular does not find a `$inject` annotation on the function, then it calls the `.toString()`  method and tries to infer what should be injected using the following rules: -  * Any argument starting with `$` is an angular service and will be added to the `$inject` property  array  * Any argument ending with `_` will be added to the `$inject` property array (angular strips the @@ -119,7 +96,6 @@ array  * All arguments following an argument which has neither `$` nor `_` , must not have `$` nor `_`  (these are free arguments for {@link http://en.wikipedia.org/wiki/Currying currying}) -  **IMPORTANT**  Minifiers/obfuscators change the names of function arguments and will therefore break the `$inject`  inference. For this reason, either explicitly declare the `$inject` or do not use @@ -127,15 +103,10 @@ minifiers/obfuscators. In the future, we may provide a pre-processor which will  code and insert the `$inject` into the source code so that it can be minified/obfuscated. - -  ## Related Topics -  * {@link dev_guide.services Angular Services} -  ## Related API -  * {@link api/angular.service Services API} diff --git a/docs/content/guide/dev_guide.di.using_di_controllers.ngdoc b/docs/content/guide/dev_guide.di.using_di_controllers.ngdoc index ea1cb965..bd51c391 100644 --- a/docs/content/guide/dev_guide.di.using_di_controllers.ngdoc +++ b/docs/content/guide/dev_guide.di.using_di_controllers.ngdoc @@ -3,11 +3,9 @@  @name Developer Guide: DI: Using DI in Controllers  @description -  The most common place to use dependency injection in angular applications is in {@link  dev_guide.mvc.understanding_controller controllers}. Here is a simple example: -  <pre>  function MyController($route){   // configure the route service @@ -16,14 +14,12 @@ function MyController($route){  MyController.$inject = ['$route'];  </pre> -  In this example, the `MyController` constructor function takes one argument, the {@link  api/angular.service.$route $route} service. Angular is then responsible for supplying the instance  of `$route` to the controller when the constructor is instantiated. There are two ways to cause  controller instantiation – by configuring routes with the `$route` service, or by referencing the  controller from the HTML template, as follows: -  <pre>  <!doctype html>  <html xmlns:ng="http://angularjs.org" ng:controller="MyController"> @@ -34,33 +30,25 @@ controller from the HTML template, as follows:  </html>  </pre> -  When angular is instantiating your controller, it needs to know what services, if any, should be  injected (passed in as arguments) into the controller. Since there is no reflection in JavaScript,  we have to supply this information to angular in the form of an additional property on the  controller constructor function called `$inject`. Think of it as annotations for JavaScript. -  <pre>  MyController.$inject = ['$route'];  </pre> -  The information in `$inject` is then used by the {@link api/angular.injector injector} to call the  function with the correct arguments. - -  ## Related Topics -  * {@link dev_guide.di About Dependency Injection}  * {@link dev_guide.di.understanding_di Understanding Dependency Injection in Angular}  * {@link dev_guide.services Angular Services} -  ## Related API -  * {@link api/angular.injector Angular Injector API} diff --git a/docs/content/guide/dev_guide.expressions.ngdoc b/docs/content/guide/dev_guide.expressions.ngdoc index 6cf42720..177a5e87 100644 --- a/docs/content/guide/dev_guide.expressions.ngdoc +++ b/docs/content/guide/dev_guide.expressions.ngdoc @@ -3,31 +3,24 @@  @name Developer Guide: Understanding Angular Expressions  @description -  Expressions are {@link dev_guide.templates.databinding bindings} that you write in HTML and embed  in templates in order to create views in angular. Angular expressions are similar but not  equivalent to JavaScript expressions. -  For example, these are all valid expressions in angular: -  * `1+2={{1+2}}`  * `3*10|currency`  * `Hello {{name}}!`  * `Hello {{'World'}}!` - -  ## Angular Expressions vs. JS Expressions -  It might be tempting to think of angular view expressions as JavaScript expressions, but that is  not entirely correct. Angular does not use a simple JavaScript eval of the expression text. You can  think of angular expressions as JavaScript expressions with these differences: -  * **Attribute Evaluation:** evaluation of all attributes are against the current scope, not to the  global window as in JavaScript.  * **Forgiving:** expression evaluation is forgiving to undefined and null, unlike in JavaScript. @@ -38,12 +31,10 @@ conditionals, loops, or throw.  human-readable format.  * **The $:** angular reserves this prefix to differentiate its API names from others. -  If, on the other hand, you do want to run arbitrary JavaScript code, you should make it a  controller method and call that. If you want to `eval()` an angular expression from JavaScript, use  the `Scope:$eval()` method. -  ## Example  <doc:example>  <doc:source> @@ -56,10 +47,8 @@ the `Scope:$eval()` method.  </doc:scenario>  </doc:example> -  You can try evaluating different expressions here: -  <doc:example>  <doc:source>   <div ng:init="exprs=[]" class="expressions"> @@ -85,18 +74,14 @@ You can try evaluating different expressions here:  </doc:example> - -  # Attribute Evaluation -  Evaluation of all attributes takes place against the current scope. Unlike JavaScript, where names  default to global window properties, angular expressions have to use `$window` to refer to the  global object. For example, if you want to call `alert()`, which is defined on `window`, an  expression must use `$window.alert()`. This is done intentionally to prevent accidental access to  the global state (a common source of subtle bugs). -  <doc:example>  <doc:source>   <div class="example2" ng:init="$window = $service('$window')"> @@ -121,67 +106,50 @@ the global state (a common source of subtle bugs).  </doc:scenario>  </doc:example> -  ## Forgiving -  Expression evaluation is forgiving to undefined and null. In JavaScript, evaluating `a.b.c` throws  an exception if `a` is not an object. While this makes sense for a general purpose language, the  expression evaluations are primarily used for data binding, which often look like this: -          {{a.b.c}} -  It makes more sense to show nothing than to throw an exception if `a` is undefined (perhaps we are  waiting for the server response, and it will become defined soon). If expression evaluation wasn't  forgiving we'd have to write bindings that clutter the code, for example: `{{((a||{}).b||{}).c}}` -  Similarly, invoking a function `a.b.c()` on undefined or null simply returns undefined. -  Assignments work the same way in reverse: -         a.b.c = 10 -  ...creates the intermediary objects even if a is undefined. - -  ## No Control Flow Statements -  You cannot write a control flow statement in an expression. The reason behind this is core to the  angular philosophy that application logic should be in controllers, not in the view. If you need a  conditional (including ternary operators), loop, or to throw from a view expression, delegate to a  JavaScript method instead. - -  ## Type Augmentation -  Built-in types have methods like `[].push()`, but the richness of these methods is limited.  Consider the example below, which allows you to do a simple search over a canned set of contacts.  The example would be much more complicated if we did not have the `Array:$filter()`. There is no  built-in method on `Array` called {@link api/angular.Array.filter $filter} and angular doesn't add  it to `Array.prototype` because that could collide with other JavaScript frameworks. -  For this reason the scope expression evaluator augments the built-in types to make them act like  they have extra methods. The actual method for `$filter()` is `angular.Array.filter()`. You can  call it from JavaScript. -  Extensions: You can further extend the expression vocabulary by adding new methods to  `angular.Array` or `angular.String`, etc. -  <doc:example>  <doc:source>   <div ng:init="friends = [ @@ -206,48 +174,36 @@ Extensions: You can further extend the expression vocabulary by adding new metho      input('searchText').enter('a');      expect(tr.count()).toBe(2); -   });  </doc:scenario>  </doc:example> -  ## Filters -  When presenting data to the user, you might need to convert the data from its raw format to a  user-friendly format. For example, you might have a data object that needs to be formatted  according to the locale before displaying it to the user. You can pass expressions through a chain  of filters like this: -         name | uppercase -  The expression evaluator simply passes the value of name to angular.filter.uppercase. -  Chain filters using this syntax: -         value | filter1 | filter2 -  You can also pass colon-delimited arguments to filters, for example, to display the number 123 with  2 decimal points: -         123 | number:2 -  # The $ -  You might be wondering, what is the significance of the $ prefix? It is simply a prefix that  angular uses, to differentiate its API names from others. If angular didn't use $, then evaluating  `a.length()` would return undefined because neither a nor angular define such a property. -  Consider that in a future version of angular we might choose to add a length method, in which case  the behavior of the expression would change. Worse yet, you the developer could create a length  property and then we would have a collision. This problem exists because angular augments existing @@ -255,16 +211,11 @@ objects with additional behavior. By prefixing its additions with $ we are reser  so that angular developers and developers who use angular can develop in harmony without collisions. - -  ## Related Topics -  * {@link dev_guide.compiler.markup Understanding Angular Markup}  * {@link dev_guide.templates.filters Understanding Angular Filters} -  ## Related API -  * {@link api/angular.compile Angular Compiler API} diff --git a/docs/content/guide/dev_guide.introduction.ngdoc b/docs/content/guide/dev_guide.introduction.ngdoc index 0a41cc9b..b4cf3bd7 100644 --- a/docs/content/guide/dev_guide.introduction.ngdoc +++ b/docs/content/guide/dev_guide.introduction.ngdoc @@ -3,30 +3,24 @@  @name Developer Guide: Introduction  @description -  Angular is pure client-side technology, written entirely in JavaScript. It works with the  long-established technologies of the web (HTML, CSS, and JavaScript) to make the development of web  apps easier and faster than ever before. -  One important way that angular simplifies web development is by increasing the level of abstraction  between the developer and most low-level web app development tasks. Angular automatically takes  care of many of these tasks, including: -  * DOM Manipulation  * Setting Up Listeners and Notifiers  * Input Validation -  Because angular handles much of the work involved in these tasks, developers can concentrate more  on application logic and less on repetitive, error-prone, lower-level coding. -  At the same time that angular simplifies the development of web apps, it brings relatively  sophisticated techniques to the client-side, including: -  * Separation of data, application logic, and presentation components  * Data Binding between data and presentation components  * Services (common web app operations, implemented as substitutable objects) @@ -34,18 +28,14 @@ sophisticated techniques to the client-side, including:  * An extensible HTML compiler (written entirely in JavaScript)  * Ease of Testing -  These techniques have been for the most part absent from the client-side for far too long. -  ## Single-page / Round-trip Applications -  You can use angular to develop both single-page and round-trip apps, but angular is designed  primarily for developing single-page apps. Angular supports browser history, forward and back  buttons, and bookmarking in single-page apps. -  You normally wouldn't want to load angular with every page change, as would be the case with using  angular in a round-trip app. However, it would make sense to do so if you were adding a subset of  angular's features (for example, templates to leverage angular's data-binding feature) to an diff --git a/docs/content/guide/dev_guide.mvc.ngdoc b/docs/content/guide/dev_guide.mvc.ngdoc index 93ad63f5..d6d14061 100644 --- a/docs/content/guide/dev_guide.mvc.ngdoc +++ b/docs/content/guide/dev_guide.mvc.ngdoc @@ -3,31 +3,23 @@  @name Developer Guide: About MVC in Angular  @description -  While Model-View-Controller (MVC) has acquired different shades of meaning over the years since it  first appeared, angular incorporates the basic principles behind the original {@link  http://en.wikipedia.org/wiki/Model–view–controller MVC} software design pattern into its way of  building client-side web applications. -  The MVC pattern greatly summarized: -  * Separate applications into distinct presentation, data, and logic components  * Encourage loose coupling between these components -  Along with {@link dev_guide.services services} and {@link dev_guide.di dependency injection}, MVC  makes angular applications better structured, easier to maintain and more testable. -  The following topics explain how angular incorporates the MVC pattern into the angular way of  developing web applications: -  * {@link dev_guide.mvc.understanding_model Understanding the Model Component}  * {@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_controller.ngdoc b/docs/content/guide/dev_guide.mvc.understanding_controller.ngdoc index e348e70b..15ae3b34 100644 --- a/docs/content/guide/dev_guide.mvc.understanding_controller.ngdoc +++ b/docs/content/guide/dev_guide.mvc.understanding_controller.ngdoc @@ -3,56 +3,43 @@  @name Developer Guide: About MVC in Angular: Understanding the Controller Component  @description -  In angular, a controller is a JavaScript function (type/class) that is used to augment instances of  angular {@link dev_guide.scopes Scope}, excluding the root scope. When you or angular create a new  child scope object via the {@link api/angular.scope.$new scope.$new} API        , there is an  option to pass in a controller as a method argument. This will tell angular to associate the  controller with the new scope and to augment its behavior. -  Use controllers to: -  - Set up the initial state of a scope object.  - Add behavior to the scope object. -  # Setting up the initial state of a scope object -  Typically, when you create an application you need to set up an initial state for an angular scope. -  Angular applies (in the sense of JavaScript's `Function#apply`) the controller constructor function  to a new angular scope object, which sets up an initial scope state. This means that angular never  creates instances of the controller type (by invoking the `new` operator on the controller  constructor). Constructors are always applied to an existing scope object. -  You set up the initial state of a scope by creating model properties. For example: -  function GreetingCtrl() {   this.greeting = 'Hola!';  } -  The `GreetingCtrl` controller creates a `greeting` model which can be referred to in a template. -  When a controller function is applied to an angular scope object, the `this` of the controller  function becomes the scope of the angular scope object, so any assignment to `this` within the  controller function happens on the angular scope object. -  # Adding Behavior to a Scope Object -  Behavior on an angular scope object is in the form of scope method properties available to the  template/view. This behavior interacts with and modifies the application model. -  As discussed in the {@link dev_guide.mvc.understanding_model Model} section of this guide, any  objects (or primitives) assigned to the scope become model properties. Any functions assigned to  the scope, along with any prototype methods of the controller type, become functions available in @@ -63,24 +50,18 @@ the `this` keyword of any controller method is always bound to the scope that th  augments). This is how the second task of adding behavior to the scope is accomplished. - -  # Using Controllers Correctly -  In general, a controller shouldn't try to do too much. It should contain only the business logic  needed for a single view. -  The most common way to keep controllers slim is by encapsulating work that doesn't belong to  controllers into services and then using these services in controllers via dependency injection.  This is discussed in the {@link dev_guide.di Dependency Injection} {@link dev_guide.services  Services} sections of this guide. -  Do not use controllers for: -  - Any kind of DOM manipulation — Controllers should contain only business logic. DOM  manipulation—the presentation logic of an application—is well known for being hard to test.  Putting any presentation logic into controllers significantly affects testability of the business @@ -95,40 +76,29 @@ services} instead.  instances). - -  # Associating Controllers with Angular Scope Objects -  You can associate controllers with scope objects explicitly via the {@link api/angular.scope.$new  scope.$new} api or implicitly via the {@link api/angular.directive.ng:controller ng:controller  directive} or {@link api/angular.service.$route $route service}. - -  ## Controller Constructor and Methods Example -  To illustrate how the controller component works in angular, let's create a little app with the  following components: -  - A {@link dev_guide.templates template} with two buttons and a simple message  - A model consisting of a string named `spice`  - A controller with two functions that set the value of `spice` -  The message in our template contains a binding to the `spice` model, which by default is set to the  string "very". Depending on which button is clicked, the `spice` model is set to `chili` or  `jalapeño`, and the message is automatically updated by data-binding. - -  ## A Spicy Controller Example -  <pre>  <body ng:controller="SpicyCtrl">   <button ng:click="chiliSpicy()">Chili</button> @@ -136,7 +106,6 @@ string "very". Depending on which button is clicked, the `spice` model is set to   <p>The food is {{spice}} spicy!</p>  </body> -  function SpicyCtrl() {   this.spice = 'very';   this.chiliSpicy = function() { @@ -144,16 +113,13 @@ function SpicyCtrl() {   }  } -  SpicyCtrl.prototype.jalapenoSpicy = function() {   this.spice = 'jalapeño';  }  </pre> -  Things to notice in the example above: -  - The `ng:controller` directive is used to (implicitly) create a scope for our template, and the  scope is augmented (managed) by the `SpicyCtrl` controller.  - `SpicyCtrl` is just a plain JavaScript function. As an (optional) naming convention the name @@ -166,14 +132,11 @@ as prototype methods of the controller constructor function (the `jalapenoSpicy`  - Both controller methods are available in the template (for the `body` element and and its  children). -  Controller methods can also take arguments, as demonstrated in the following variation of the  previous example. -  ## Controller Method Arguments Example -  <pre>  <body ng:controller="SpicyCtrl">   <input name="customSpice" value="wasabi"> @@ -182,7 +145,6 @@ previous example.   <p>The food is {{spice}} spicy!</p>  </body> -  function SpicyCtrl() {   this.spice = 'very';   this.spicy = function(spice) { @@ -191,22 +153,17 @@ function SpicyCtrl() {  }  </pre> -  Notice that the `SpicyCtrl` controller now defines just one method called `spicy`, which takes one  argument called `spice`. The template then refers to this controller method and passes in a string  constant `'chili'` in the binding for the first button and a model property `spice` (bound to an  input box) in the second button. - -  ## Controller Inheritance Example -  Controller inheritance in angular is based on {@link api/angular.scope Scope} inheritance. Let's  have a look at an example: -  <pre>  <body ng:controller="MainCtrl">   <p>Good {{timeOfDay}}, {{name}}!</p> @@ -215,29 +172,24 @@ have a look at an example:     <p ng:controller="BabyCtrl">Good {{timeOfDay}}, {{name}}!</p>  </body> -  function MainCtrl() {   this.timeOfDay = 'morning';   this.name = 'Nikki';  } -  function ChildCtrl() {   this.name = 'Mattie';  } -  function BabyCtrl() {   this.timeOfDay = 'evening';   this.name = 'Gingerbreak Baby';  }  </pre> -  Notice how we nested three `ng:controller` directives in our template. This template construct will  result in 4 scopes being created for our view: -  - The root scope  - The `MainCtrl` scope, which contains `timeOfDay` and `name` models  - The `ChildCtrl` scope, which shadows the `name` model from the previous scope and inherits the @@ -245,28 +197,21 @@ result in 4 scopes being created for our view:  - The `BabyCtrl` scope, which shadows both the `timeOfDay` model defined in `MainCtrl` and `name`  model defined in the ChildCtrl -  Inheritance works between controllers in the same way as it does with models. So in our previous  examples, all of the models could be replaced with controller methods that return string values. -  Note: Standard prototypical inheritance between two controllers doesn't work as one might expect,  because as we mentioned earlier, controllers are not instantiated directly by angular, but rather  are applied to the scope object. - -  ## Testing Controllers -  The way to test a controller depends upon how complicated the controller is. -  - If your controller doesn't use DI or scope methods — create the controller with the `new`  operator and test away. For example: -  Controller Function:  <pre>  function myController() { @@ -274,31 +219,25 @@ function myController() {                    {"name":"jalapeno", "spiceiness":"hot hot hot!"},                    {"name":"habanero", "spiceness":"LAVA HOT!!"}]; -     this.spice = "habanero";  }  </pre> -  Controller Test:  <pre>  describe('myController function', function() { -    describe('myController', function(){      var ctrl; -      beforeEach(function() {        ctrl = new myController();      }); -      it('should create "spices" model with 3 spices', function() {        expect(ctrl.spices.length).toBe(3);      }); -      it('should set the default value of spice', function() {        expect(ctrl.spice).toBe('habanero');      }); @@ -306,18 +245,16 @@ describe('myController function', function() {  });  </pre> -  - If your controller does use DI or scope methods — create a root scope, then create the controller  in the root scope with `scope.$new(MyController)`. Test the controller using `$eval`, if necessary.  - If you need to test a nested controller that depends on its parent's state — create a root scope,  create a parent scope, create a child scope, and test the controller using $eval if necessary. - -  ## 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_view Understanding the View Component} + + diff --git a/docs/content/guide/dev_guide.mvc.understanding_model.ngdoc b/docs/content/guide/dev_guide.mvc.understanding_model.ngdoc index 15d8bcb2..4efb03ca 100644 --- a/docs/content/guide/dev_guide.mvc.understanding_model.ngdoc +++ b/docs/content/guide/dev_guide.mvc.understanding_model.ngdoc @@ -3,94 +3,70 @@  @name Developer Guide: About MVC in Angular: Understanding the Model Component  @description -  Depending on the context of the discussion in angular documentation, the term _model_ can refer to  either a single object representing one entity (for example, a model called "phones" with its value  being an array of phones) or the entire data model for the application (all entities). -  In angular, a model is any data that is reachable as a property of an angular {@link  dev_guide.scopes Scope} object. The name of the property is the model identifier and the value is  any JavaScript object (including arrays and primitives). -  The only requirement for a JavaScript object to be a model in angular is that the object must be  referenced by an angular scope as a property of that scope object. This property reference can be  created explicitly or implicitly. -  You can create models by explicitly creating scope properties referencing JavaScript objects in the  following ways: -  * Make a direct property assignment to the scope object in JavaScript code; this most commonly  occurs in controllers: -           function MyCtrl() {               // create property 'foo' on the MyCtrl's scope               // and assign it an initial value 'bar'               this.foo = 'bar';           } -  * Use an {@link dev_guide.expressions angular expression} with an assignment operator in templates: -           <button ng:click="{{foos='ball'}}">Click me</button> -  * Use {@link api/angular.directive.ng:init ng:init directive} in templates (for toy/example apps  only, not recommended for real applications): -           <body ng:init=" foo = 'bar' "> -  Angular creates models implicitly (by creating a scope property and assigning it a suitable value)  when processing the following template constructs: -  * Form input, select, and textarea elements: -           <input name="query" value="fluffy cloud">     The code above creates a model called "query" on the current scope with the value set to "fluffy  cloud". -  * An iterator declaration in {@link api/angular.widget.@ng:repeat ng:repeater}: -           <p ng:repeat="phone in phones"></p> -     The code above creates one child scope for each item in the "phones" array and creates a "phone"  object (model) on each of these scopes with its value set to the value of "phone" in the array. -  In angular, a JavaScript object stops being a model when: -  * No angular scope contains a property that references the object. -  * All angular scopes that contain a property referencing the object become stale and eligible for  garbage collection. -  The following illustration shows a simple data model created implicitly from a simple template: -  <img src="img/guide/about_model_final.png"> - -  ## 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 index b5a3047a..0cb41449 100644 --- a/docs/content/guide/dev_guide.mvc.understanding_view.ngdoc +++ b/docs/content/guide/dev_guide.mvc.understanding_view.ngdoc @@ -3,14 +3,11 @@  @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. -  <img src="img/guide/about_view_final.png"> -  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/angular.directive.ng:controller @@ -19,11 +16,8 @@ ng:controller} and {@link api/angular.widget.ng:view ng:view}, and through bindi  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.overview.ngdoc b/docs/content/guide/dev_guide.overview.ngdoc index 7eb56470..4a817921 100644 --- a/docs/content/guide/dev_guide.overview.ngdoc +++ b/docs/content/guide/dev_guide.overview.ngdoc @@ -3,33 +3,25 @@  @description - -  # What Is Angular? -  The short answer: angular is a new, powerful, client-side technology that makes it much easier for  you to create dynamic web sites and complex web apps, all without leaving the comfort of your HTML  / JavaScript home. -  The long answer: it depends on where you're coming from... -  * If you're a web designer, you might perceive angular to be a sweet {@link dev_guide.templates  templating} system, that doesn't get in your way and provides you with lots of nice built-ins that  make it easier to do what you want to do. -  * If you're a web developer, you might be thrilled that angular functions as an excellent web  framework, one that assists you all the way through the development cycle. -  * If you want to go deeper, you can immerse yourself in angular's extensible  HTML {@link  dev_guide.compiler compiler} that runs in your browser. The angular compiler teaches your browser  new tricks. -  Angular is not just a templating system, but you can create fantastic templates with it. Angular is  not just a web framework, but it features a very nice framework. Angular is not just an extensible  HTML compiler, but the compiler is at the core of Angular. Angular includes all of these @@ -37,22 +29,17 @@ components, along with others. Angular is far greater than the sum of its parts.  better way to develop web applications! - -  ## An Introductory Angular Example -  Let's say that you are a web designer, and you've spent many thous — erm, hundreds of hours  designing web sites. But at this point, the thought of manipulating the DOM, writing listeners and  input validators, all just to implement a simple form?  No. You either don't want to go there in  the first place or you've been there and the thrill is gone. -  So look over the following simple example written using angular.  Note that it features only the  templating aspect of angular, but this should suffice for now to quickly demonstrate how much  easier a web developer's life can if they're using angular: -  <doc:example>  <doc:source>   <b>Invoice:</b> @@ -85,43 +72,32 @@ ng:required/></td>  -->  </doc:example> -  Try out the Live Preview above, and then let's walk through the example and describe what's going  on. -  In the `<html>` tag, we add an attribute to let the browser know about the angular namespace: -          <html xmlns:ng="http://angularjs.org"> -  This ensures angular runs nicely in all major browsers. -  In the `<script>` tag we do two angular setup tasks: -  1. We load `angular.js`.  2. The angular {@link api/angular.directive.ng:autobind ng:autobind} directive tells angular to  {@link dev_guide.compiler compile} and manage the whole HTML document. -      `<script src="http://code.angularjs.org/0.9.15/angular-0.9.15.min.js"               ng:autobind></script>` -  From the `name` attribute of the `<input>` tags, angular automatically sets up two-way data  binding, and we also demonstrate some easy input validation: -          Quantity: <input name="qty" value="1" ng:validate="integer:0" ng:required/>          Cost: <input name="cost" value="199.95" ng:validate="number" ng:required/> -  These input widgets look normal enough, but consider these points: -  * When this page loaded, angular bound the names of the input widgets (`qty` and `cost`) to  variables of the same name. Think of those variables as the "Model" component of the  Model-View-Controller design pattern. @@ -131,13 +107,10 @@ or leave the the input fields blank, the borders turn red color, and the display  These `ng:` directives make it easier to implement field validators than coding them in JavaScript,  no?  Yes. -  And finally, the mysterious `{{ double curly braces }}`: -           Total: {{qty * cost | currency}} -  This notation, `{{ _expression_ }}`, is a bit of built-in angular {@link dev_guide.compiler.markup  markup}, a shortcut for displaying data to the user. The expression within curly braces gets  transformed by the angular compiler into an angular directive ({@link api/angular.directive.ng:bind @@ -145,36 +118,28 @@ ng:bind}). The expression itself can be a combination of both an expression and  dev_guide.templates.filters filter}: `{{ expression | filter }}`. Angular provides filters for  formatting display data. -  In the example above, the expression in double-curly braces directs angular to, "Bind the data we  got from the input widgets to the display, multiply them together, and format the resulting number  into output that looks like money." - -  # The Angular Philosophy -  Angular is built around the belief that declarative code is better than imperative when it comes to  building UIs and wiring software components together, while imperative code is excellent for  expressing business logic. -  Not to put too fine a point on it, but if you wanted to add a new label to your application, you  could do so by simply adding text to the HTML template, saving the code, and refreshing your  browser: -  <pre>  <span class="label">Hello</span>  </pre> -  Or, as in programmatic systems (like {@link http://code.google.com/webtoolkit/ GWT}), you would  have to write the code and then run the code like this: -  <pre>  var label = new Label();  label.setText('Hello'); @@ -182,15 +147,11 @@ label.setClass('label');  parent.addChild(label);  </pre> -  That's one line of markup versus four times as much code. - -  ## More Angular Philosophy -  * It is a very good idea to decouple DOM manipulation from app logic. This dramatically improves  the testability of the code.  * It is a really, _really_ good idea to regard app testing as equal in importance to app writing. @@ -201,11 +162,9 @@ development work to progress in parallel, and allows for reuse of both sides.  building an app: from designing the UI, through writing the business logic, to testing.  * It is always good to make common tasks trivial and difficult tasks possible. -  Now that we're homing in on what angular is, perhaps now would be a good time to list a few things  that angular is not: -  * It's not a Library. You don't just call its functions, although it does provide you with some  utility APIs.  * It's not a DOM Manipulation Library. Angular uses jQuery to manipulate the DOM behind the scenes, @@ -225,14 +184,10 @@ changes to the model are automatically reflected in the view. Any changes by the  are automatically reflected in the model. - -  # Why You Want Angular -  Angular frees you from the following pain: -  * **Registering callbacks:** Registering callbacks clutters your code, making it hard to see the  forest for the trees. Removing common boilerplate code such as callbacks is a good thing. It vastly  reduces the amount of JavaScript coding _you_ have to do, and it makes it easier to see what your @@ -256,15 +211,11 @@ get started developing features quickly. As a bonus, you get full control over t  process in automated tests. - -  # Watch a Presentation About Angular -  Here is an early presentation on angular, but note that substantial development has occurred since  the talk was given in July of 2010. -  <object width="480" height="385">   <param name="movie" value="http://www.youtube.com/v/elvcgVSynRg&hl=en_US&fs=1"></param>   <param name="allowFullScreen" value="true"></param> @@ -274,7 +225,6 @@ the talk was given in July of 2010.          allowfullscreen="true" width="480" height="385"></embed>  </object> -  {@link  https://docs.google.com/present/edit?id=0Abz6S2TvsDWSZDQ0OWdjaF8yNTRnODczazdmZg&hl=en&authkey=CO-b7oID diff --git a/docs/content/guide/dev_guide.scopes.controlling_scopes.ngdoc b/docs/content/guide/dev_guide.scopes.controlling_scopes.ngdoc index ca63cbc3..cdbad444 100644 --- a/docs/content/guide/dev_guide.scopes.controlling_scopes.ngdoc +++ b/docs/content/guide/dev_guide.scopes.controlling_scopes.ngdoc @@ -3,48 +3,37 @@  @name Developer Guide: Scopes: Applying Controllers to Scopes  @description -  When a controller function is applied to a scope, the scope is augmented with the behavior defined  in the controller. The end result is that the scope behaves as if it were the controller: -  <pre>  var scope = angular.scope();  scope.salutation = 'Hello';  scope.name = 'World'; -  expect(scope.greeting).toEqual(undefined); -  scope.$watch('name', function(){  this.greeting = this.salutation + ' ' + this.name + '!';  }); -  expect(scope.greeting).toEqual('Hello World!');  scope.name = 'Misko';  // scope.$eval() will propagate the change to listeners  expect(scope.greeting).toEqual('Hello World!'); -  scope.$eval();  expect(scope.greeting).toEqual('Hello Misko!');  </pre> - -  ## Related Topics -  * {@link dev_guide.scopes Angular Scope Objects}  * {@link dev_guide.scopes.understanding_scopes Understanding Angular Scopes}  * {@link dev_guide.scopes.working_scopes Working With Angular Scopes}  * {@link dev_guide.scopes.updating_scopes Updating Angular Scopes} -  ## Related API -  * {@link api/angular.scope Angular Scope API} diff --git a/docs/content/guide/dev_guide.scopes.ngdoc b/docs/content/guide/dev_guide.scopes.ngdoc index 730ac348..e9706e2f 100644 --- a/docs/content/guide/dev_guide.scopes.ngdoc +++ b/docs/content/guide/dev_guide.scopes.ngdoc @@ -4,48 +4,35 @@  @description - -  An angular scope is a JavaScript type defined by angular. Instances of this type are objects that  serve as the context within which all model and controller methods live and get evaluated. -  Angular links scope objects to specific points in a compiled (processed) template. This linkage  provides the contexts in which angular creates data-bindings between the model and the view. You  can think of angular scope objects as the medium through which the model, view, and controller  communicate. -  In addition to providing the context in which data is evaluated, angular scope objects watch for  model changes. The scope objects also notify all components interested in any model changes (for  example, functions registered through {@link api/angular.scope.$watch $watch}, bindings created by  {@link api/angular.directive.ng:bind ng:bind}, or HTML input elements). -  Angular scope objects are responsible for: -  * Gluing the model, controller and view template together.  * Providing the mechanism to watch for model changes ({@link api/angular.scope.$watch}).  * Notifying interested components when the model changes ({@link api/angular.scope.$eval}).  * Providing the context in which all controller functions and angular expressions are evaluated. - -  ## Related Topics -  * {@link dev_guide.scopes.understanding_scopes Understanding Scopes}  * {@link dev_guide.scopes.working_scopes Working With Scopes}  * {@link dev_guide.scopes.controlling_scopes Applying Controllers to Scopes}  * {@link dev_guide.scopes.updating_scopes Updating Scopes} -  ## Related API -  * {@link api/angular.scope Angular Scope API} - - diff --git a/docs/content/guide/dev_guide.scopes.understanding_scopes.ngdoc b/docs/content/guide/dev_guide.scopes.understanding_scopes.ngdoc index 073c919e..704c9241 100644 --- a/docs/content/guide/dev_guide.scopes.understanding_scopes.ngdoc +++ b/docs/content/guide/dev_guide.scopes.understanding_scopes.ngdoc @@ -3,7 +3,6 @@  @name Developer Guide: Scopes: Understanding Scopes  @description -  Angular automatically creates a root scope during initialization, and attaches it to the page's  root DOM element (usually `<html>`). The root scope object, along with any of its child scope  objects, serves as the infrastructure on which your data model is built. The data model (JavaScript @@ -11,20 +10,16 @@ objects, arrays, or primitives) is attached to angular scope properties. Angular  values to the DOM where bindings are specified in the template. Angular attaches any controller  functions you have created to their respective scope objects. -  <img src="img/guide/simple_scope_final.png"> -  Angular scopes can be nested, so a child scope has a parent scope upstream in the DOM.  When you  display an angular expression in the view, angular walks the DOM tree looking in the closest  attached scope object for the specified data. If it doesn't find the data in the closest attached  scope, it looks further up the scope hierarchy until it finds the data. -  A child scope object inherits properties from its parents. For example, in the following snippet of  code, observe how the value of `name` changes, based on the HTML element it is displayed in: -  <doc:example>  <doc:source>   <ul ng:init="name='Hank'; names=['Igor', 'Misko', 'Gail', 'Kai']"> @@ -41,7 +36,6 @@ code, observe how the value of `name` changes, based on the HTML element it is d       expect(using('.doc-example-live').repeater('li').row(1)).         toEqual(['Misko']); -       expect(using('.doc-example-live').repeater('li').row(2)).         toEqual(['Gail']);       expect(using('.doc-example-live').repeater('li').row(3)). @@ -52,32 +46,24 @@ code, observe how the value of `name` changes, based on the HTML element it is d  </doc:scenario>  </doc:example> -  The angular {@link api/angular.widget.@ng:repeat ng:repeat} directive creates a new scope for each  element that it repeats (in this example the elements are list items). In the `<ul>` element, we  initialized `name` to "Hank", and we created an array called `names` to use as the data source for  the list items. In each `<li>` element, `name` is overridden. Outside of the `<li>` repeater, the  original value of `name` is displayed. -  The following illustration shows the DOM and angular scopes for the example above: -  <img src="img/guide/dom_scope_final.png"> - -  ## Related Topics -  * {@link dev_guide.scopes Angular Scope Objects}  * {@link dev_guide.scopes.working_scopes Working With Scopes}  * {@link dev_guide.scopes.controlling_scopes Applying Controllers to Scopes}  * {@link dev_guide.scopes.updating_scopes Updating Scopes} -  ## Related API -  * {@link api/angular.scope Angular Scope API} diff --git a/docs/content/guide/dev_guide.scopes.updating_scopes.ngdoc b/docs/content/guide/dev_guide.scopes.updating_scopes.ngdoc index ff6734cc..2d5f1725 100644 --- a/docs/content/guide/dev_guide.scopes.updating_scopes.ngdoc +++ b/docs/content/guide/dev_guide.scopes.updating_scopes.ngdoc @@ -3,19 +3,16 @@  @name Developer Guide: Scopes: Updating Scope Properties  @description -  You can update a scope by calling its {@link api/angular.scope.$eval $eval()} method, but usually  you do not have to do this explicitly. In most cases, angular intercepts all external events (such  as user interactions, XHRs, and timers) and calls the `$eval()` method on the scope object for you  at the right time. The only time you might need to call `$eval()` explicitly is when you create  your own custom widget or service. -  The reason it is unnecessary to call `$eval()` from within your controller functions when you use  built-in angular widgets and services is because a change in the data model triggers a call to the  `$eval()` method on the scope object where the data model changed. -  When a user inputs data, angularized widgets copy the data to the appropriate scope and then call  the `$eval()` method on the root scope to update the view. It works this way because scopes are  inherited, and a child scope `$eval()` overrides its parent's `$eval()` method. Updating the whole @@ -23,25 +20,19 @@ page requires a call to `$eval()` on the root scope as `$root.$eval()`. Similarl  to fetch data from a server is made and the response comes back, the data is written into the model  and then `$eval()` is called to push updates through to the view and any other dependents. -  A widget that creates scopes (such as {@link api/angular.widget.@ng:repeat ng:repeat}) is  responsible for forwarding `$eval()` calls from the parent to those child scopes. That way, calling  `$eval()` on the root scope will update the whole page. This creates a spreadsheet-like behavior  for your app; the bound views update immediately as the user enters data. - -  ## Related Documents -  * {@link dev_guide.scopes Angular Scope Objects}  * {@link dev_guide.scopes.understanding_scopes Understanding Angular Scope Objects}  * {@link dev_guide.scopes.working_scopes Working With Angular Scopes}  * {@link dev_guide.scopes.controlling_scopes Applying Controllers to Scopes} -  ## Related API -  * {@link api/angular.scope Angular Scope API} diff --git a/docs/content/guide/dev_guide.scopes.working_scopes.ngdoc b/docs/content/guide/dev_guide.scopes.working_scopes.ngdoc index ab507e16..8e4503a5 100644 --- a/docs/content/guide/dev_guide.scopes.working_scopes.ngdoc +++ b/docs/content/guide/dev_guide.scopes.working_scopes.ngdoc @@ -3,27 +3,22 @@  @name Developer Guide: Scopes: Working With Angular Scopes  @description -  When you use {@link api/angular.directive.ng:autobind ng:autobind} to bootstrap your application,  angular creates the root scope automatically for you. If you need more control over the  bootstrapping process, or if you need to create a root scope for a test, you can do so using the  {@link api/angular.scope angular.scope()} API. -  Here is a simple code snippet that demonstrates how to create a scope object, assign model  properties to it, and register listeners to watch for changes to the model properties: -  <pre>  var scope = angular.scope();  scope.salutation = 'Hello';  scope.name = 'World'; -  // Verify that greeting is undefined  expect(scope.greeting).toEqual(undefined); -  // Set up the watcher...  scope.$watch('name', function(){  // when 'name' changes, set 'greeting'... @@ -31,35 +26,27 @@ this.greeting = this.salutation + ' ' + this.name + '!';  }  ); -  // verify that 'greeting' was set...  expect(scope.greeting).toEqual('Hello World!'); -  // 'name' changed!  scope.name = 'Misko'; -  // scope.$eval() will propagate the change to listeners  expect(scope.greeting).toEqual('Hello World!'); -  scope.$eval();  // verify that '$eval' propagated the change  expect(scope.greeting).toEqual('Hello Misko!');  </pre> -  ## Related Topics -  * {@link dev_guide.scopes Angular Scope Objects}  * {@link dev_guide.scopes.understanding_scopes Understanding Scopes}  * {@link dev_guide.scopes.controlling_scopes Applying Controllers to Scopes}  * {@link dev_guide.scopes.updating_scopes Updating Scopes} -  ## Related API -  * {@link api/angular.scope Angular Scope API} diff --git a/docs/content/guide/dev_guide.services.creating_services.ngdoc b/docs/content/guide/dev_guide.services.creating_services.ngdoc index d36c9d67..b75e75a3 100644 --- a/docs/content/guide/dev_guide.services.creating_services.ngdoc +++ b/docs/content/guide/dev_guide.services.creating_services.ngdoc @@ -3,15 +3,12 @@  @name Developer Guide: Angular Services: Creating Angular Services  @description -  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  that angular's DI will use to create the service object when it is needed. -  The `angular.service` method accepts three parameters: -  - `{string} name` - Name of the service.  - `{function()} factory` - Factory function (called just once by DI).  - `{Object} config` -  Configuration object with the following properties: @@ -22,23 +19,19 @@ array. Defaults to `[]`.  instantiated when angular boots. If false, the service will be lazily instantiated when it is first  requested during instantiation of a dependant. Defaults to `false`. -  The `this` of the factory function is bound to the root scope of the angular application. -  All angular services participate in {@link dev_guide.di dependency injection (DI)} by registering  themselves with angular's DI system (injector) under a `name` (id) as well as by declaring  dependencies which need to be provided for the factory function of the registered service. The  ability to swap dependencies for mocks/stubs/dummies in tests allows for services to be highly  testable. -  Following is an example of a very simple service. This service depends on the `$window` service  (which is passed as a parameter to the factory function) and is just a function. The service simply  stores all notifications; after the third one, the service displays all of the notifications by  window alert. -  <pre>      angular.service('notify', function(win) {        var msgs = []; @@ -53,19 +46,14 @@ window alert.  </pre> - -  ## Related Topics -  * {@link dev_guide.services.understanding_services Understanding Angular Services}  * {@link dev_guide.services.registering_services Registering Angular Services}  * {@link dev_guide.services.managing_dependencies Managing Service Dependencies}  * {@link dev_guide.services.injecting_controllers Injecting Services Into Controllers }  * {@link dev_guide.services.testing_services Testing Angular Services} -  ## Related API -  * {@link api/angular.service 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 75630b32..0046dd7f 100644 --- a/docs/content/guide/dev_guide.services.injecting_controllers.ngdoc +++ b/docs/content/guide/dev_guide.services.injecting_controllers.ngdoc @@ -3,11 +3,9 @@  @name Developer Guide: Angular Services: Injecting Services Into Controllers  @description -  Using services as dependencies for controllers is very similar to using services as dependencies  for another service. -  Since JavaScript is a dynamic language, DI can't figure out which services to inject by static  types (like in static typed languages). Therefore, you must specify the service name by using the  `$inject` property, which is an array containing strings with names of services to be injected. @@ -16,7 +14,6 @@ IDs matters: the order of the services in the array will be used when calling th  with injected parameters. The names of parameters in factory function don't matter, but by  convention they match the service IDs. -  <pre>  function myController($loc, $log) {  this.firstMethod = function() { @@ -32,7 +29,6 @@ this.secondMethod = function() {  myController.$inject = ['$location', '$log'];  </pre> -  <doc:example>  <doc:source>  <script type="text/javascript"> @@ -47,18 +43,15 @@ angular.service('notify', function(win) {    };  }, {$inject: ['$window']}); -  function myController(notifyService) {    this.callNotify = function(msg) {      notifyService(msg);    };  } -  myController.$inject = ['notify'];  </script> -  <div ng:controller="myController">  <p>Let's try this simple notify service, injected into the controller...</p>  <input ng:init="message='test'" type="text" name="message" /> @@ -73,19 +66,14 @@ it('should test service', function(){  </doc:example> - -  ## Related Topics -  {@link dev_guide.services.understanding_services Understanding Angular Services}  {@link dev_guide.services.creating_services Creating Angular Services}  {@link dev_guide.services.registering_services Registering Angular Services}  {@link dev_guide.services.managing_dependencies Managing Service Dependencies}  {@link dev_guide.services.testing_services Testing Angular Services} -  ## Related API -  {@link api/angular.service 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 5adbefae..5f45b001 100644 --- a/docs/content/guide/dev_guide.services.managing_dependencies.ngdoc +++ b/docs/content/guide/dev_guide.services.managing_dependencies.ngdoc @@ -3,20 +3,16 @@  @name Developer Guide: Angular Services: Managing Service Dependencies  @description -  Angular allows services to declare other services as dependencies needed for construction of their  instances. -  To declare dependencies, you specify them in the factory function signature and via the `$inject`  property, as an array of string identifiers. Optionally the `$inject` property declaration can be  dropped (see "Inferring `$inject`" but note that that is currently an experimental feature). -  Here is an example of two services that depend on each other, as well as on other services that are  provided by angular's web framework: -  <pre>  /**  * batchLog service allows for messages to be queued in memory and flushed @@ -27,7 +23,6 @@ provided by angular's web framework:  angular.service('batchLog', function($defer, $log) {  var messageQueue = []; -  function log() {   if (messageQueue.length) {     $log('batchLog messages: ', messageQueue); @@ -36,14 +31,12 @@ function log() {   $defer(log, 50000);   } -  return function(message) {   messageQueue.push(message);  }  }, {$inject: ['$defer', '$log']);  // note how we declared dependency on built-in $defer and $log services above -  /**  * routeTemplateMonitor monitors each $route change and logs the current  * template via the batchLog service. @@ -55,10 +48,8 @@ $route.onChange(function() {  }, {$inject: ['$route', 'batchLog'], $eager: true});  </pre> -  Things to notice in this example: -  * The `batchLog` service depends on the built-in {@link api/angular.service.$defer $defer} and  {@link api/angular.service.$log $log} services, and allows messages to be logged into the  `console.log` in batches. @@ -77,20 +68,15 @@ this array with IDs and their order that the injector uses to determine which se  order to inject. - -  ## Related Topics -  * {@link dev_guide.services.understanding_services Understanding Angular Services}  * {@link dev_guide.services.creating_services Creating Angular Services}  * {@link dev_guide.services.registering_services Registering Services}  * {@link dev_guide.services.injecting_controllers Injecting Services Into Controllers }  * {@link dev_guide.services.testing_services Testing Angular Services} -  ## Related API -  * {@link api/angular.service Angular Service API}  * {@link api/angular.injector Angular Injector API} diff --git a/docs/content/guide/dev_guide.services.ngdoc b/docs/content/guide/dev_guide.services.ngdoc index 57449edc..01f747f7 100644 --- a/docs/content/guide/dev_guide.services.ngdoc +++ b/docs/content/guide/dev_guide.services.ngdoc @@ -3,18 +3,14 @@  @name Developer Guide: Angular Services  @description -  Services are a feature that angular brings to client-side web apps from the server side, where  services have been commonly used for a long time.  Services in angular apps are substitutable  objects that are wired together using {@link dev_guide.di dependency injection (DI)}. Services are  most often used with {@link dev_guide.di dependency injection}, also a key feature of angular apps. - -  ## Related Topics -  * {@link dev_guide.services.understanding_services Understanding Angular Services}  * {@link dev_guide.services.creating_services Creating Angular Services}  * {@link dev_guide.services.registering_services Registering Angular Services} @@ -22,8 +18,6 @@ most often used with {@link dev_guide.di dependency injection}, also a key featu  * {@link dev_guide.services.injecting_controllers Injecting Services Into Conrollers}  * {@link dev_guide.services.testing_services Testing Angular Services} -  ## Related API -  * {@link api/angular.service Angular Service API} diff --git a/docs/content/guide/dev_guide.services.registering_services.ngdoc b/docs/content/guide/dev_guide.services.registering_services.ngdoc index ea182944..cc50d678 100644 --- a/docs/content/guide/dev_guide.services.registering_services.ngdoc +++ b/docs/content/guide/dev_guide.services.registering_services.ngdoc @@ -3,12 +3,10 @@  @name Developer Guide: Angular Services: Registering Angular Services  @description -  To register a service, register a factory function that creates the service with angular's  Injector. The Injector is exposed as {@link api/angular.scope.$service scope.$service}. The  following pseudo-code shows a simple service registration: -  <pre>  angular.service('service id', function() {    var shinyNewServiceInstance; @@ -17,27 +15,21 @@ angular.service('service id', function() {  });  </pre> -  Note that you are not registering a service instance, but rather a factory function that will  create this instance when called. -  # Instantiating Angular Services -  A service can be instantiated eagerly or lazily. By default angular instantiates services lazily,  which means that a service will be created only when it is needed for instantiation of a service or  an application component that depends on it. In other words, angular won't instantiate lazy  services unless they are requested directly or indirectly by the application. -  Eager services on the other hand, are instantiated right after the injector itself is created,  which happens when the angular {@link dev_guide.bootstrap application initializes}. -  To override the default, you can request that a service is eagerly instantiated as follows: -  <pre>  angular.service('service id', function() {    var shinyNewServiceInstance; @@ -46,12 +38,10 @@ angular.service('service id', function() {  }, {$eager: true});  </pre> -  While it is tempting to declare services as eager, only in few cases it is actually useful. If you  are unsure whether to make a service eager, it likely doesn't need to be. To be more specific, a  service should be declared as eager only if it fits one of these scenarios: -  * Nothing in your application declares this service as its dependency, and this service affects the  state or configuration of the application (e.g. a service that configures `$route` or `$resource`  services) @@ -60,7 +50,6 @@ because the service passively observes the application and it is optional for ot  components to depend on it.  An example of this scenario is a service that monitors and logs  application memory usage. -  Lastly, it is important to realize that all angular services are applicaiton singletons. This means  that there is only one instance of a given service per injector. Since angular is lethally allergic  to the global state, it is possible to create multiple injectors, each with its own instance of a @@ -68,19 +57,14 @@ given service, but that is rarely needed, except in tests where this property is  important. - -  ## Related Topics -  * {@link dev_guide.services.understanding_services Understanding Angular Services}  * {@link dev_guide.services.creating_services Creating Angular Services}  * {@link dev_guide.services.managing_dependencies Managing Service Dependencies}  * {@link dev_guide.services.injecting_controllers Injecting Services Into Controllers }  * {@link dev_guide.services.testing_services Testing Angular Services} -  ## Related API -  * {@link api/angular.service 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 65e1ab6d..bc860364 100644 --- a/docs/content/guide/dev_guide.services.testing_services.ngdoc +++ b/docs/content/guide/dev_guide.services.testing_services.ngdoc @@ -3,29 +3,24 @@  @name Developer Guide: Angular Services: Testing Angular Services  @description -  Following is a unit test for the service in the example in {@link  dev_guide.services.registering_services Registering Angular Services}. The unit test example uses  Jasmine spy (mock) instead of a real browser alert. -  <pre>  var mock, notify; -  beforeEach(function() {  mock = {alert: jasmine.createSpy()};  notify = angular.service('notify')(mock);  }); -  it('should not alert first two notifications', function() {  notify('one');  notify('two');  expect(mock.alert).not.toHaveBeenCalled();  }); -  it('should alert all after third notification', function() {  notify('one');  notify('two'); @@ -33,7 +28,6 @@ notify('three');  expect(mock.alert).toHaveBeenCalledWith("one\ntwo\nthree");  }); -  it('should clear messages after alert', function() {  notify('one');  notify('two'); @@ -47,24 +41,16 @@ expect(mock.alert.mostRecentCall.args).toEqual(["more\ntwo\nthird"]);  </pre> - -  ## Related Topics -  * {@link dev_guide.services.understanding_services Understanding Angular Services}  * {@link dev_guide.services.creating_services Creating Angular Services}  * {@link dev_guide.services.registering_services Registering Angular Services}  * {@link dev_guide.services.managing_dependencies Managing Service Dependencies}  * {@link dev_guide.services.injecting_controllers Injecting Services Into Conrollers} -  ## Related API -  * {@link api/angular.service 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 f7afc981..05fafcf6 100644 --- a/docs/content/guide/dev_guide.services.understanding_services.ngdoc +++ b/docs/content/guide/dev_guide.services.understanding_services.ngdoc @@ -3,46 +3,36 @@  @name Developer Guide: Angular Services: Understanding Angular Services  @description -  Angular services are singletons that carry out specific tasks common to web apps, such as the  {@link api/angular.service.$xhr $xhr service} that provides low level access to the browser's  `XMLHttpRequest` object. -  To use an angular service, you identify it as a dependency for the dependent (a controller, or  another service) that depends on the service.  Angular's dependency injection subsystem takes care  of the rest. The angular injector subsystem is in charge of service instantiation, resolution of  dependencies, and provision of dependencies to factory functions as requested. -  Angular injects dependencies using "constructor" injection (the service is passed in via a factory  function). Because JavaScript is a dynamically typed language, angular's dependency injection  subsystem cannot use static types to identify service dependencies. For this reason a dependent  must explicitly define its dependencies by using the `$inject` property.  For example: -          myController.$inject = ['$location']; -  The angular web framework provides a set of services for common operations. Like other core angular  variables and identifiers, the built-in services always start with `$` (such as `$xhr` mentioned  above). You can also create your own custom services. - -  ## Related Topics -  * {@link dev_guide.di About Angular Dependency Injection}  * {@link dev_guide.services.creating_services Creating Angular Services}  * {@link dev_guide.services.registering_services Registering Angular Services}  * {@link dev_guide.services.managing_dependencies Managing Service Dependencies}  * {@link dev_guide.services.testing_services Testing Angular Services} -  ## Related API -  * {@link api/angular.service Angular Service API}  * {@link api/angular.injector Injector API} diff --git a/docs/content/guide/dev_guide.templates.css.ngdoc b/docs/content/guide/dev_guide.templates.css.ngdoc index 90021b98..e1e54814 100644 --- a/docs/content/guide/dev_guide.templates.css.ngdoc +++ b/docs/content/guide/dev_guide.templates.css.ngdoc @@ -4,66 +4,48 @@  @description - -  Angular includes built-in CSS classes, which in turn have predefined CSS styles. -  # Built-in CSS classes -  * `ng-exception` -  **Usage:** angular applies this class to a DOM element if that element contains an Expression that  threw an exception when evaluated. -  **Styling:** The built-in styling of the ng-exception class displays an error message surrounded  by a solid red border, for example: -   <div class="ng-exception">Error message</div> -  You can try to evaluate malformed expressions in {@link dev_guide.expressions expressions} to see  the `ng-exception` class' styling. -  * `ng-validation-error` -  **Usage:** angular applies this class to an input widget element if that element's input does not  pass validation. Note that you set the validation criteria on the input widget element using the  Ng:validate or Ng:required directives. -  **Styling:** The built-in styling of the ng-validation-error class turns the border of the input  box red and includes a hovering UI element that includes more details of the validation error. You  can see an example in {@link api/angular.widget.@ng:validate ng:validate example}. -  ## Overriding Styles for Angular CSS Classes -  To override the styles for angular's built-in CSS classes, you can do any of the following: -  * Download the source code, edit angular.css, and host the source on your own server.  * Create a local CSS file, overriding any styles that you'd like, and link to it from your HTML file  as you normally would: -  <pre>  <link href="yourfile.css" rel="stylesheet" type="text/css">  </pre> - -  ## Related Topics -  * {@link dev_guide.templates Angular Templates}  * {@link dev_guide.templates.css Working With CSS in Angular}  * {@link dev_guide.templates.formatters Angular Formatters} diff --git a/docs/content/guide/dev_guide.templates.databinding.ngdoc b/docs/content/guide/dev_guide.templates.databinding.ngdoc index 1459095e..3bd0ea8f 100644 --- a/docs/content/guide/dev_guide.templates.databinding.ngdoc +++ b/docs/content/guide/dev_guide.templates.databinding.ngdoc @@ -3,16 +3,13 @@  @name Developer Guide: Templates: Data Binding in Angular  @description -  Data-binding in angular web apps is the automatic syncing of data between the model and view  components.  The way that angular implements data-binding lets you treat the model as the  single-source-of-truth in your application.  The view is a projection of the model at all times.  When the model changes, the view reflects the change, and vice versa. -  ## Data Binding in Classical Template Systems -  <img class="right" src="img/One_Way_Data_Binding.png"/>  Most templating systems bind data in only one direction: they merge template and model components  together into a view, as illustrated in the diagram. After the merge occurs, changes to the model @@ -20,10 +17,8 @@ or related sections of the view are NOT automatically reflected in the view. Wor  that the user makes to the view are not reflected in the model. This means that the developer has  to write code that constantly syncs the view with the model and the model with the view. -  ## Data Binding in Angular Templates -  <img class="right" src="img/Two_Way_Data_Binding.png"/>  The way angular templates works is different, as illustrated in the diagram. They are different  because first the template (which is the uncompiled HTML along with any additional markup or @@ -33,16 +28,12 @@ the model are propagated to the view. This makes the model always the single-sou  the application state, greatly simplifying the programing model for the developer. You can think of  the view as simply an instant projection of your model. -  Because the view is just a projection of the model, the controller is completely separated from the  view and unaware of it. This makes testing a snap because it is easy to test your controller in  isolation without the view and the related DOM/browser dependency. - -  ## Related Topics -  * {@link dev_guide.scopes Angular Scopes}  * {@link dev_guide.templates Angular Templates} diff --git a/docs/content/guide/dev_guide.templates.filters.creating_filters.ngdoc b/docs/content/guide/dev_guide.templates.filters.creating_filters.ngdoc index ca7fa2f2..ebb7d923 100644 --- a/docs/content/guide/dev_guide.templates.filters.creating_filters.ngdoc +++ b/docs/content/guide/dev_guide.templates.filters.creating_filters.ngdoc @@ -3,25 +3,20 @@  @name Developer Guide: Templates: Filters: Creating Angular Filters  @description -  Writing your own filter is very easy: just define a JavaScript function on the `angular.filter`  object.  The framework passes in the input value as the first argument to your function. Any filter  arguments are passed in as additional function arguments. -  You can use these variables in the function: -  * `this` — The current scope.  * `this.$element` — The DOM element containing the binding. The `$element` variable allows the  filter to manipulate the DOM. -  The following sample filter reverses a text string. In addition, it conditionally makes the  text upper-case and assigns color. -  <doc:example>  <doc:source>  <script type="text/javascript"> @@ -42,7 +37,6 @@ text upper-case and assigns color.   });  </script> -  <input name="text" type="text" value="hello" /><br>  No filter: {{text}}<br>  Reverse: {{text|reverse}}<br> @@ -59,16 +53,11 @@ expect(binding('text|reverse')).toEqual('CBA');  </doc:example> - -  ## Related Topics -  * {@link dev_guide.templates.filters Understanding Angular Filters}  * {@link dev_guide.compiler Angular HTML Compiler} -  ## Related API -  * {@link api/angular.filter Angular Filter API} diff --git a/docs/content/guide/dev_guide.templates.filters.ngdoc b/docs/content/guide/dev_guide.templates.filters.ngdoc index fc0f8f84..e233678b 100644 --- a/docs/content/guide/dev_guide.templates.filters.ngdoc +++ b/docs/content/guide/dev_guide.templates.filters.ngdoc @@ -3,36 +3,26 @@  @name Developer Guide: Templates: Understanding Angular Filters  @description -  Angular filters format data for display to the user. In addition to formatting data, filters can  also modify the DOM. This allows filters to handle tasks such as conditionally applying CSS styles  to filtered output. -  For example, you might have a data object that needs to be formatted according to the locale before  displaying it to the user. You can pass expressions through a chain of filters like this: -          name | uppercase -  The expression evaluator simply passes the value of name to `angular.filter.uppercase()`. -  In addition to formatting data, filters can also modify the DOM. This allows filters to handle  tasks such as conditionally applying CSS styles to filtered output. - -  ## Related Topics -  * {@link dev_guide.templates.filters.using_filters Using Angular Filters}  * {@link dev_guide.templates.filters.creating_filters Creating Angular Filters} -  ## Related API -  * {@link api/angular.filter Angular Filter API} diff --git a/docs/content/guide/dev_guide.templates.filters.using_filters.ngdoc b/docs/content/guide/dev_guide.templates.filters.using_filters.ngdoc index 05da5e7d..41f32ac0 100644 --- a/docs/content/guide/dev_guide.templates.filters.using_filters.ngdoc +++ b/docs/content/guide/dev_guide.templates.filters.using_filters.ngdoc @@ -3,35 +3,26 @@  @name Developer Guide: Templates: Filters: Using Angular Filters  @description -  Filters can be part of any {@link api/angular.scope} evaluation but are typically used to format  expressions in bindings in your templates: -          {{ expression | filter }} -  Filters typically transform the data to a new data type, formatting the data in the process.  Filters can also be chained, and can take optional arguments. -  You can chain filters using this syntax: -          {{ expression | filter1 | filter2 }} -  You can also pass colon-delimited arguments to filters, for example, to display the number 123 with  2 decimal points: -          123 | number:2 -  Here are some examples that show values before and after applying different filters to an  expression in a binding: -  * No filter: `{{1234.5678}}` => `1234.5678`  * Number filter: `{{1234.5678|number}}` => `1,234.57`. Notice the "," and rounding to two  significant digits. @@ -40,16 +31,11 @@ arguments, separated by colons in a binding. For example, the "number" filter ta  argument that specifies how many digits to display to the right of the decimal point. - -  ## Related Topics -  * {@link dev_guide.templates.filters Understanding Angular Filters}  * {@link dev_guide.templates.filters.creating_filters Creating Angular Filters} -  ## Related API -  * {@link api/angular.filter Angular Filter API} diff --git a/docs/content/guide/dev_guide.templates.formatters.creating_formatters.ngdoc b/docs/content/guide/dev_guide.templates.formatters.creating_formatters.ngdoc index 08504bbc..2ecd8f19 100644 --- a/docs/content/guide/dev_guide.templates.formatters.creating_formatters.ngdoc +++ b/docs/content/guide/dev_guide.templates.formatters.creating_formatters.ngdoc @@ -3,19 +3,16 @@  @name Developer Guide: Templates: Angular Formatters: Creating Angular Formatters  @description -  To create your own formatter, you can simply register a pair of JavaScript functions with  `angular.formatter`. One of your functions is used to parse text from the input widget into the  data storage format; the other function is used to format stored data into user-readable text. -  The following example demonstrates a "reverse" formatter. Data is stored in uppercase and in  reverse, but it is displayed in lower case and non-reversed. When a user edits the data model via  the input widget, the input is automatically parsed into the internal data storage format, and when  the data changes in the model, it is automatically formatted to the user-readable form for display  in the view. -  <pre>  function reverse(text) {  var reversed = []; @@ -25,7 +22,6 @@ reversed.unshift(text.charAt(i));  return reversed.join('');  } -  angular.formatter('reverse', {  parse: function(value){  return reverse(value||'').toUpperCase(); @@ -36,7 +32,6 @@ return reverse(value||'').toLowerCase();  });  </pre> -  <doc:example>  <doc:source>  <script type="text/javascript"> @@ -48,7 +43,6 @@ for (var i = 0; i < text.length; i++) {  return reversed.join('');  } -  angular.formatter('reverse', {  parse: function(value){    return reverse(value||'').toUpperCase(); @@ -59,5 +53,3 @@ format: function(value){  });  </script> - - diff --git a/docs/content/guide/dev_guide.templates.formatters.ngdoc b/docs/content/guide/dev_guide.templates.formatters.ngdoc index 4dd8f22b..82a14fb4 100644 --- a/docs/content/guide/dev_guide.templates.formatters.ngdoc +++ b/docs/content/guide/dev_guide.templates.formatters.ngdoc @@ -3,24 +3,18 @@  @name Developer Guide: Templates: Angular Formatters  @description -  In angular, formatters are responsible for translating user-readable text entered in an {@link  api/angular.widget.HTML input widget} to a JavaScript object in the data model that the application  can manipulate. -  You can use formatters in a template, and also in JavaScript.  Angular provides built-in  formatters, and of course you can create your own formatters. -  ## Related Topics -  * {@link dev_guide.templates.formatters.using_formatters Using Angular Formatters}  * {@link dev_guide.templates.formatters.creating_formatters Creating Angular Formatters} -  ## Related API -  * {@link api/angular.formatter Angular Formatter API} diff --git a/docs/content/guide/dev_guide.templates.formatters.using_formatters.ngdoc b/docs/content/guide/dev_guide.templates.formatters.using_formatters.ngdoc index 8e160317..bf983cd5 100644 --- a/docs/content/guide/dev_guide.templates.formatters.using_formatters.ngdoc +++ b/docs/content/guide/dev_guide.templates.formatters.using_formatters.ngdoc @@ -3,10 +3,7 @@  @name Developer Guide: Templates: Angular Formatters: Using Angular Formatters  @description -  The following snippet shows how to use a formatter in a template. The formatter below is  `ng:format="reverse"`, added as an attribute to an `<input>` tag. -  <pre> - diff --git a/docs/content/guide/dev_guide.templates.ngdoc b/docs/content/guide/dev_guide.templates.ngdoc index 59fed0fc..ca0ca99a 100644 --- a/docs/content/guide/dev_guide.templates.ngdoc +++ b/docs/content/guide/dev_guide.templates.ngdoc @@ -3,17 +3,14 @@  @name Developer Guide: Understanding Angular Templates  @description -  An angular template is the declarative specification that, along with information from the model  and controller, becomes the rendered view that a user sees in the browser. It is the static DOM,  containing HTML, CSS, and angular-specific elements and angular-specific element attributes.  The  angular elements and attributes direct angular to add behavior and transform the template DOM into  the dynamic view DOM. -  These are the types of angular elements and element attributes you can use in a template: -  * {@link dev_guide.compiler.directives Directive} — An attribute that augments an existing DOM  element.  * {@link dev_guide.compiler.widgets Widget} — A custom DOM element. An example of a built-in widget @@ -25,16 +22,13 @@ curly brace notation `{{ }}` to bind expressions to elements is built-in angular  * {@link dev_guide.templates.formatters Formatter} — Lets you format the input object into a user  readable view. -  Note:  In addition to declaring the elements above in templates, you can also access these elements  in JavaScript code. -  The following code snippet shows a simple angular template made up of standard HTML tags along with  angular {@link dev_guide.compiler.directives directives}, {@link dev_guide.compiler.markup markup},  and {@link dev_guide.expressions expressions}: -  <pre>  <html>   <!-- Body tag augmented with ng:controller directive  --> @@ -49,7 +43,6 @@ and {@link dev_guide.expressions expressions}:  </html>  </pre> -  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 @@ -59,17 +52,12 @@ example of this technique is shown in the {@link tutorial/ angular tutorial}, in  eight. - -  ## Related Topics -  * {@link dev_guide.templates.filters Angular Filters}  * {@link dev_guide.templates.formatters Angular Formatters}  * {@link dev_guide.templates.validators Angular Validators} -  ## Related API -  * {@link api/index API Reference} diff --git a/docs/content/guide/dev_guide.templates.validators.creating_validators.ngdoc b/docs/content/guide/dev_guide.templates.validators.creating_validators.ngdoc index 661ce744..835b0b51 100644 --- a/docs/content/guide/dev_guide.templates.validators.creating_validators.ngdoc +++ b/docs/content/guide/dev_guide.templates.validators.creating_validators.ngdoc @@ -4,17 +4,13 @@  @description - -  To create a custom validator, you simply add your validator code as a method onto the  `angular.validator` object and provide input(s) for the validator function. Each input provided is  treated as an argument to the validator function.  Any additional inputs should be separated by  commas. -  The following bit of pseudo-code shows how to set up a custom validator: -  <pre>  angular.validator('your_validator', function(input [,additional params]) {          [your validation code]; @@ -26,22 +22,17 @@ angular.validator('your_validator', function(input [,additional params]) {  }  </pre> -  Note that this validator returns "true" when the user's input is incorrect, as in "Yes, it's true,  there was a problem with that input". If you prefer to provide more information when a validator  detects a problem with input, you can specify an error message in the validator that angular will  display when the user hovers over the input widget. -  To specify an error message, replace "`return true;`" with an error string, for example: -       return "Must be a value between 1 and 5!"; -  Following is a sample UPS Tracking Number validator: -  <doc:example>  <doc:source>  <script> @@ -60,7 +51,6 @@ expect(element('input[name=trackNo]').attr('class')).     not().toMatch(/ng-validation-error/);  }); -  it('should not validate in correct UPS tracking number', function() {  input('trackNo').enter('foo');  expect(element('input[name=trackNo]').attr('class')). @@ -69,32 +59,24 @@ expect(element('input[name=trackNo]').attr('class')).  </doc:scenario>  </doc:example> -  In this sample validator, we specify a regular expression against which to test the user's input.  Note that when the user's input matches `regexp`, the function returns "false" (""); otherwise it  returns the specified error message ("true"). -  Note: you can also access the current angular scope and DOM element objects in your validator  functions as follows: -  * `this` ===  The current angular scope.  * `this.$element` ===  The DOM element that contains the binding. This allows the filter to  manipulate the DOM in addition to transforming the input. - -  ## Related Topics -  * {@link dev_guide.templates Angular Templates}  * {@link dev_guide.templates.filters Angular Filters}  * {@link dev_guide.templates.formatters Angular Formatters} -  ## Related API -  * {@link api/angular.validator API Validator Reference} diff --git a/docs/content/guide/dev_guide.templates.validators.ngdoc b/docs/content/guide/dev_guide.templates.validators.ngdoc index 4976b8de..76df92b5 100644 --- a/docs/content/guide/dev_guide.templates.validators.ngdoc +++ b/docs/content/guide/dev_guide.templates.validators.ngdoc @@ -3,11 +3,9 @@  @name Developer Guide: Templates: Understanding Angular Validators  @description -  Angular validators are attributes that test the validity of different types of user input. Angular  provides a set of built-in input validators: -  * {@link api/angular.validator.phone phone number}  * {@link api/angular.validator.number number}  * {@link api/angular.validator.integer integer} @@ -18,35 +16,26 @@ provides a set of built-in input validators:  * {@link api/angular.validator.url URLs}  * {@link api/angular.validator.asynchronous asynchronous} -  You can also create your own custom validators. -  # Using Angular Validators -  You can use angular validators in HTML template bindings, and in JavaScript: -  * Validators in HTML Template Bindings -  <pre>  <input ng:validator="validator_type:parameters" [...]>  </pre> -  * Validators in JavaScript -  <pre>  angular.validator.[validator_type](parameters)  </pre> -  The following example shows how to use the built-in angular integer validator: -  <doc:example>  <doc:source>   Change me: <input type="text" name="number" ng:validate="integer" value="123"> @@ -64,19 +53,15 @@ The following example shows how to use the built-in angular integer validator:  </doc:scenario>  </doc:example> -  # Creating an Angular Validator -  To create a custom validator, you simply add your validator code as a method onto the  `angular.validator` object and provide input(s) for the validator function. Each input provided is  treated as an argument to the validator function.  Any additional inputs should be separated by  commas. -  The following bit of pseudo-code shows how to set up a custom validator: -  <pre>  angular.validator('your_validator', function(input [,additional params]) {          [your validation code]; @@ -88,22 +73,17 @@ angular.validator('your_validator', function(input [,additional params]) {  }  </pre> -  Note that this validator returns "true" when the user's input is incorrect, as in "Yes, it's true,  there was a problem with that input". If you prefer to provide more information when a validator  detects a problem with input, you can specify an error message in the validator that angular will  display when the user hovers over the input widget. -  To specify an error message, replace "`return true;`" with an error string, for example: -        return "Must be a value between 1 and 5!"; -  Following is a sample UPS Tracking Number validator: -  <doc:example>  <doc:source>  <script> @@ -122,7 +102,6 @@ it('should validate correct UPS tracking number', function() {      not().toMatch(/ng-validation-error/);  }); -  it('should not validate in correct UPS tracking number', function() {   input('trackNo').enter('foo');   expect(element('input[name=trackNo]').attr('class')). @@ -131,30 +110,22 @@ it('should not validate in correct UPS tracking number', function() {  </doc:scenario>  </doc:example> -  In this sample validator, we specify a regular expression against which to test the user's input.  Note that when the user's input matches `regexp`, the function returns "false" (""); otherwise it  returns the specified error message ("true"). -  Note: you can also access the current angular scope and DOM element objects in your validator  functions as follows: -  * `this` ===  The current angular scope.  * `this.$element` ===  The DOM element that contains the binding. This allows the filter to  manipulate the DOM in addition to transforming the input. - -  ## Related Topics -  * {@link dev_guide.templates Angular Templates} -  ## Related API -  * {@link api/angular.validator Validator API} diff --git a/docs/content/guide/dev_guide.unit-testing.ngdoc b/docs/content/guide/dev_guide.unit-testing.ngdoc index d26a904e..e068e26d 100644 --- a/docs/content/guide/dev_guide.unit-testing.ngdoc +++ b/docs/content/guide/dev_guide.unit-testing.ngdoc @@ -3,7 +3,6 @@  @name Developer Guide: Unit Testing  @description -  JavaScript is a dynamically typed language which comes with great power of expression, but it also  come with almost no-help from the compiler. For this reason we feel very strongly that any code  written in JavaScript needs to come with a strong set of tests. We have built many features into @@ -27,7 +26,6 @@ DOM in the right way. Angular is written with testability in mind, but it still  do the right thing. We tried to make the right thing easy, but angular is not magic, which means if  you don't follow these, you may very well end up with an untestable application. -  ## Dependency Inject  There are several ways in which you can get a hold of a dependency:  1. You could create it using the `new` operator. @@ -36,18 +34,14 @@ There are several ways in which you can get a hold of a dependency:  the registry? Must likely by looking it up in a well know place. See #2)  4. You could expect that the it be handed to you. -  Out of the list above only the last of is testable. Lets look at why: -  ### Using the `new` operator -  While there is nothing wrong with the `new` operator fundamentally the issue is that calling a new  on a constructor permanently binds the call site to the type. For example lets say that we are  trying to instantiate an `XHR` so that we can get some data from the server. -  <pre>  function MyClass(){    this.doWork = function(){ @@ -59,13 +53,11 @@ function MyClass(){  }  </pre> -  The issue becomes, that in tests, we would very much like to instantiate a `MockXHR` which would  allow us to return fake data and simulate network failures. By calling `new XHR()` we are  permanently bound to the actual one, and there is no good way to replace it. Yes there is monkey  patching, that is a bad idea for many reasons, which is outside the scope of this document. -  The class above is hard to test since we have to resort to monkey patching:  <pre>  var oldXHR = XHR; @@ -77,12 +69,9 @@ XHR = oldXHR; // if you forget this bad things will happen  </pre> - -  ### Global look-up:  Another way to approach the problem is look for the service in a well known location. -  <pre>  function MyClass(){    this.doWork = function(){ @@ -95,7 +84,6 @@ function MyClass(){  }  </pre> -  While no new instance of dependency is being created, it is fundamentally the same as `new`, in  that there is no good way to intercept the call to `global.xhr` for testing purposes, other then  through monkey patching. The basic issue for testing is that global variable needs to be mutated in @@ -103,7 +91,6 @@ order to replace it with call to a mock method. For further explanation why this  http://misko.hevery.com/code-reviewers-guide/flaw-brittle-global-state-singletons/ Brittle Global  State & Singletons} -  The class above is hard to test since we have to change global state:  <pre>  var oldXHR = glabal.xhr; @@ -115,15 +102,11 @@ global.xhr = oldXHR; // if you forget this bad things will happen  </pre> - -  ### Service Registry: -  It may seem as that this can be solved by having a registry for all of the services, and then  having the tests replace the services as needed. -  <pre>  function MyClass() {    var serviceRegistry = ????; @@ -137,13 +120,11 @@ function MyClass() {  }  </pre> -  However, where dose the serviceRegistry come from? if it is:  * `new`-ed up, the the test has no chance to reset the services for testing  *  global look-up, then the service returned is global as well (but resetting is easier, since  there is only one global variable to be reset). -  The class above is hard to test since we have to change global state:  <pre>  var oldServiceLocator = glabal.serviceLocator; @@ -155,12 +136,9 @@ glabal.serviceLocator = oldServiceLocator; // if you forget this bad things will  </pre> - -  ### Passing in Dependencies:  Lastly the dependency can be passed in. -  <pre>  function MyClass(xhr) {    this.doWork = function(){ @@ -227,11 +205,9 @@ function PasswordController(){  }  </pre> -  The code above is problematic from testability, since it requires your test to have the right kind  of DOM present when the code executes. The test would look like this: -  <pre>  var input = $('<input type="text"/>');  var span = $('<span>'); @@ -246,11 +222,9 @@ expect(span.text()).toEqual('weak');  $('body').html('');  </pre> -  In angular the controllers are strictly separated from the DOM manipulation logic which results in  a much easier testability story as can be seen in this example: -  <pre>  function PasswordCntrl(){    this.password = ''; @@ -267,10 +241,8 @@ function PasswordCntrl(){  }  </pre> -  and the tests is straight forward -  <pre>  var pc = new PasswordController();  pc.password('abc'); @@ -278,37 +250,29 @@ pc.grade();  expect(span.strength).toEqual('weak');  </pre> -  Notice that the test is not only much shorter but it is easier to follow what is going on. We say  that such a test tells a story, rather then asserting random bits which don't seem to be related. - -  ## Filters  {@link api/angular.filter Filters} are functions which transform the data into user readable  format. They are important because they remove the formatting responsibility from the application  logic, further simplifying the application logic. -  <pre>  angular.filter('length', function(text){    return (''+(text||'')).length;  }); -  var length = angular.filter('length');  expect(length(null)).toEqual(0);  expect(length('abc')).toEqual(3);  </pre> -  ## Directives  Directives in angular are responsible for updating the DOM when the state of the model changes. - -  ## Mocks  oue  ## Global State Isolation diff --git a/docs/content/guide/index.ngdoc b/docs/content/guide/index.ngdoc index 1a986c51..c40bb1be 100644 --- a/docs/content/guide/index.ngdoc +++ b/docs/content/guide/index.ngdoc @@ -3,78 +3,59 @@  @name Developer Guide  @description -  Welcome to the angular Developer Guide.  If you are here to learn the details of how to use angular  to develop web apps, you've come to the right place. -  If you are completely or relatively unfamiliar with angular, you may want to check out one or both  of the following documents before returning here to the Developer Guide: -  * {@link misc/started Getting Started}  * {@link tutorial/index Angular Tutorial} -  <hr> -  ## {@link dev_guide.overview Overview of Angular} -  ## {@link dev_guide.bootstrap Initializing Angular} -  * {@link dev_guide.bootstrap.auto_bootstrap Understanding Automatic Initialization}  * {@link dev_guide.bootstrap.manual_bootstrap Understanding Manual Initialization} -  ## {@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}  * {@link dev_guide.mvc.understanding_view Understanding the View Component} -  ## {@link dev_guide.scopes Angular Scope Objects} -  * {@link dev_guide.scopes.understanding_scopes Understanding Angular Scope Objects}  * {@link dev_guide.scopes.working_scopes Working With Angular Scopes}  * {@link dev_guide.scopes.controlling_scopes Applying Controllers to Scopes}  * {@link dev_guide.scopes.updating_scopes Updating Scope Properties} -  ## {@link dev_guide.compiler Angular HTML Compiler} -  * {@link dev_guide.compiler.directives Understanding Angular Directives}  * {@link dev_guide.compiler.widgets Understanding Angular Widgets}  * {@link dev_guide.compiler.directives_widgets Comparing Directives and Widgets}  * {@link dev_guide.compiler.markup Understanding Angular Markup} -  ## {@link dev_guide.templates Angular Templates} -  * {@link dev_guide.templates.filters Understanding Angular Filters}  * {@link dev_guide.templates.formatters Understanding Angular Formatters}  * {@link dev_guide.templates.validators Understanding Angular Validators} -  ## {@link dev_guide.services Angular Services} -  * {@link dev_guide.services.understanding_services Understanding Angular Services}  * {@link dev_guide.services.creating_services Creating Angular Services}  * {@link dev_guide.services.registering_services Registering Angular Services}  * {@link dev_guide.services.managing_dependencies Managing Service Dependencies}  * {@link dev_guide.services.testing_services Testing Angular Services} -  ## {@link dev_guide.di About Dependency Injection} -  * {@link dev_guide.di.understanding_di Understanding DI in Angular}  * {@link dev_guide.di.using_di_controllers Using DI in Controllers} | 
