From 9cb57772a4030925318475fe93bc19e2916b37bf Mon Sep 17 00:00:00 2001 From: Igor Minar Date: Wed, 17 Nov 2010 21:23:23 -0800 Subject: fix docs for angular.directive and ng:autobind --- src/Angular.js | 223 ++++++++++++++++++++++++++++++++------------------------- 1 file changed, 126 insertions(+), 97 deletions(-) (limited to 'src') diff --git a/src/Angular.js b/src/Angular.js index 6a22b027..32187927 100644 --- a/src/Angular.js +++ b/src/Angular.js @@ -97,20 +97,18 @@ var _undefined = undefined, * @ngdoc overview * @name angular.directive * @namespace Namespace for all directives. + * * @description - * A directive is an XML attribute that you can use in an existing HTML - * element type or in a DOM element type that you create using - * `angular.widget`, to modify that element's properties. You can use - * any number of directives per element. + * A directive is an HTML attribute that you can use in an existing HTML element type or in a + * DOM element type that you create as {@link angular.widget}, to modify that element's + * properties. You can use any number of directives per element. * - * For example, you can add the ng:bind directive as an attribute of an - * HTML span element, as in ``. - * How does this work? The compiler passes the attribute value `1+2` - * to the ng:bind extension, which in turn tells the Scope to watch - * that expression and report changes. On any change it sets the span - * text to the expression value. + * For example, you can add the ng:bind directive as an attribute of an HTML span element, as in + * ``. How does this work? The compiler passes the attribute value + * `1+2` to the ng:bind extension, which in turn tells the {@link angular.scope} to watch that + * expression and report changes. On any change it sets the span text to the expression value. * - * Here's how to define ng:bind: + * Here's how to define {@link angular.directive.ng:bind ng:bind}: * 
         angular.directive('ng:bind', function(expression, compiledElement) {
           var compiler = this;
@@ -123,36 +121,31 @@ var _undefined        = undefined,
         });
      *
* - * ## Directive vs. Attribute Widget - * Both attribute widgets and directives can compile a DOM element - * attribute. So why have two different ways to do the same thing? - * The answer is that order matters, but you have no control over - * the order in which attributes are read. To solve this we - * apply attribute widget before the directive. + * # Directive vs. Attribute Widget + * Both [attribute widgets](#!angular.widget) and directives can compile a DOM element + * attribute. So why have two different ways to do the same thing? The answer is that order + * matters, but we have no control over the order in which attributes are read. To solve this + * we apply attribute widget before the directive. * - * For example, consider this piece of HTML, which uses the - * directives `ng:repeat`, `ng:init`, and `ng:bind`: + * For example, consider this piece of HTML, which uses the directives `ng:repeat`, `ng:init`, + * and `ng:bind`: * 
         
      *
* - * Notice that the order of execution matters here. We need to - * execute ng:repeat before we run the `ng:init` and `ng:bind` - * on the `
  • ;`. This is because we want to run the - * `ng:init="a=a+1` and `ng:bind="person"` once for each - * person in people. We could not have used directive to - * create this template because attributes are read in an - * unspecified order and there is no way of guaranteeing - * that the repeater attribute would execute first. Using - * the `ng:repeat` attribute directive ensures that we can - * transform the DOM element into a template. - * - * Widgets run before directives. Widgets are expected to - * manipulate the DOM whereas directives are not expected - * to manipulate the DOM, and they run last. + * Notice that the order of execution matters here. We need to execute + * {@link angular.directive.ng:repeat ng:repeat} before we run the + * {@link angular.directive.ng:init ng:init} and `ng:bind` on the `
  • ;`. This is because we + * want to run the `ng:init="a=a+1` and `ng:bind="person"` once for each person in people. We + * could not have used directive to create this template because attributes are read in an + * unspecified order and there is no way of guaranteeing that the repeater attribute would + * execute first. Using the `ng:repeat` attribute directive ensures that we can transform the + * DOM element into a template. * + * Widgets run before directives. Widgets may manipulate the DOM whereas directives are not + * expected to do so, and so they run last. */ angularDirective = extensionMap(angular, 'directive'), @@ -324,8 +317,9 @@ var _undefined = undefined, * # Standard Filters * * The Angular framework provides a standard set of filters for common operations, including: - * {@link angular.filter.currency}, {@link angular.filter.json}, {@link angular.filter.number}, - * and {@link angular.filter.html}. You can also add your own filters. + * {@link angular.filter.currency currency}, {@link angular.filter.json json}, + * {@link angular.filter.number number}, and {@link angular.filter.html html}. You can also add + * your own filters. * * * # Syntax @@ -893,66 +887,103 @@ function toKeyValue(obj) { * @name angular.directive.ng:autobind * @element script * + * @TODO ng:autobind is not a directive!! it should be documented as bootstrap parameter in a + * separate bootstrap section. + * @TODO rename to ng:autobind to ng:autoboot + * * @description - * This section explains how to bootstrap your application to - * the environment using either the - * `angular-x.x.x.js` or `angular-x.x.x.min.js` script. - * - * ## The bootstrap code - * Note that there are two versions of the bootstrap code that you can use: + * This section explains how to bootstrap your application with angular using either the angular + * javascript file. + * + * + * ## The angular distribution + * Note that there are two versions of the angular javascript file that you can use: * - * * `angular-x.x.x.js` - this file is unobfuscated, uncompressed, and thus - * human-readable. Note that despite the name of the file, there is - * no additional functionality built in to help you debug your - * application; it has the prefix debug because you can read - * the source code. - * * `angular-x.x.x.min.js` - this is a compressed and obfuscated version - * of `angular-x.x.x.js`. You might want to use this version if you - * want to load a smaller but functionally equivalent version of the - * code in your application. Note: this minified version was created - * using the Closure Compiler. + * * `angular.js` - the development version - this file is unobfuscated, uncompressed, and thus + * human-readable and useful when developing your angular applications. + * * `angular.min.js` - the production version - this is a minified and obfuscated version of + * `angular.js`. You want to use this version when you want to load a smaller but functionally + * equivalent version of the code in your application. We use the Closure compiler to create this + * file. * * - * ## Auto bind using: ng:autobind - * The simplest way to get an application up and running is by - * inserting a script tag in your HTML file that bootstraps the - * `http://code.angularjs.org/angular-x.x.x.min.js` code and uses the - * special `ng:autobind` attribute, like in this snippet of HTML: + * ## Auto-bootstrap with `ng:autobind` + * The simplest way to get an application up and running is by inserting a script tag in + * your HTML file that bootstraps the `http://code.angularjs.org/angular-x.x.x.min.js` code and uses + * the special `ng:autobind` attribute, like in this snippet of HTML: * * 
         <!doctype html>
     <html xmlns:ng="http://angularjs.org">
      <head>
-      <script type="text/javascript" ng:autobind
-              src="http://code.angularjs.org/angular-0.9.3.min.js"></script>
+      <script type="text/javascript" src="http://code.angularjs.org/angular-0.9.3.min.js"
+              ng:autobind></script>
      </head>
      <body>
        Hello {{'world'}}!
      </body>
     </html>
  *
    - * - * The `ng:autobind` attribute tells to compile and manage - * the whole HTML document. The compilation occurs in the page's - * `onLoad` handler. Note that you don't need to explicitly add an + * + * The `ng:autobind` attribute tells to compile and manage the whole HTML document. The + * compilation occurs in the page's `onLoad` handler. Note that you don't need to explicitly add an * `onLoad` event; auto bind mode takes care of all the magic for you. + * + * + * ## Auto-bootstrap with `#autobind` + * In rare cases when you can't define the `ng` namespace before the script tag (e.g. in some CMS + * systems, etc), it is possible to auto-bootstrap angular by appending `#autobind` to the script + * src URL, like in this snippet: + * + * 
    +    <!doctype html>
+    <html>
+     <head>
+      <script type="text/javascript"
+              src="http://code.angularjs.org/angular-0.9.3.min.js#autobind"></script>
+     </head>
+     <body>
+       <div xmlns:ng="http://angularjs.org">
+         Hello {{'world'}}!
+       </div>
+     </body>
+    </html>
+ *
    + * + * In this case it's the `#autobind` URL fragment that tells angular to auto-bootstrap. + * + * + * ## Filename Restrictions for Auto-bootstrap + * In order for us to find the auto-bootstrap script attribute or URL fragment, the value of the + * `script` `src` attribute that loads angular script must match one of these naming + * conventions: + * + * - `angular.js` + * - `angular-min.js` + * - `angular-x.x.x.js` + * - `angular-x.x.x.min.js` + * - `angular-x.x.x-xxxxxxxx.js` (dev snapshot) + * - `angular-x.x.x-xxxxxxxx.min.js` (dev snapshot) + * - `angular-bootstrap.js` (used for development of angular) + * + * Optionally, any of the filename format above can be prepended with relative or absolute URL that + * ends with `/`. + * + * + * ## Manual Bootstrap + * Using auto-bootstrap is a handy way to start using , but advanced users who want more + * control over the initialization process might prefer to use manual bootstrap instead. * - * # Manual Bind - * Using autobind mode is a handy way to start using , but - * advanced users who want more control over the initialization process - * might prefer to use manual bind mode instead. - * - * The best way to get started with manual bind mode is to look at the - * magic behind `ng:autobind` by writing out each step of the autobind - * process explicitly. Note that the following code is equivalent to - * the code in the previous section. + * The best way to get started with manual bootstraping is to look at the magic behind `ng:autobind` + * by writing out each step of the autobind process explicitly. Note that the following code is + * equivalent to the code in the previous section. * * 
         <!doctype html>
     <html xmlns:ng="http://angularjs.org">
      <head>
-      <script type="text/javascript" ng:autobind
-              src="http://code.angularjs.org/angular-0.9.3.min.js"></script>
+      <script type="text/javascript" src="http://code.angularjs.org/angular-0.9.3.min.js"
+              ng:autobind></script>
       <script type="text/javascript">
        (function(window, previousOnLoad){
          window.onload = function(){
@@ -968,39 +999,37 @@ function toKeyValue(obj) {
     </html>
  *
    * - * This is the sequence that your code should follow if you're writing - * your own manual binding code: + * This is the sequence that your code should follow if you're bootstrapping angular on your own: * - * * After the page is loaded, find the root of the HTML template, - * which is typically the root of the document. - * * Run the HTML compiler, which converts the templates into an - * executable, bi-directionally bound application. - * - * #XML Namespace - * *IMPORTANT:* When using you must declare the ng namespace - * using the xmlsn tag. If you don't declare the namespace, - * Internet Explorer does not render widgets properly. + * * After the page is loaded, find the root of the HTML template, which is typically the root of + * the document. + * * Run the HTML compiler, which converts the templates into an executable, bi-directionally bound + * application. + * + * + * ##XML Namespace + * *IMPORTANT:* When using you must declare the ng namespace using the xmlns tag. If you + * don't declare the namespace, Internet Explorer does not render widgets properly. * * 
      * <html xmlns:ng="http://angularjs.org">
  *
    - * - * # Create your own namespace - * If you want to define your own widgets, you must create your own - * namespace and use that namespace to form the fully qualified - * widget name. 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 xmlsn tag to your page, create an - * alias, and set it to your unique domain: + * + * + * ## Create your own namespace + * If you want to define your own widgets, you must create your own namespace and use that namespace + * to form the fully qualified widget name. 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 xmlsn 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">
  *
    - * - * # Global Object - * The script creates a single global variable `angular` - * in the global namespace. All APIs are bound to fields of this - * global object. + * + * + * ## Global Object + * The script creates a single global variable `angular` in the global namespace. All + * APIs are bound to fields of this global object. * */ function angularInit(config){ -- cgit v1.2.3