docs(bootstrap): rewritten bootstrap guide

mhevery · mhevery · commit 6933fb7924cd · 2012-06-02T16:02:05.000-07:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1758,7 +1758,7 @@ with the `$route` service
 [angular.bootstrap]: http://docs-next.angularjs.org/api/angular.bootstrap
 [$anchorScroll]: http://docs-next.angularjs.org/api/angular.module.ng.$anchorScroll
 [$cacheFactory]: http://docs-next.angularjs.org/api/angular.module.ng.$cacheFactory
-[bootstrapping]: http://docs-next.angularjs.org/guide/dev_guide.bootstrap
+[bootstrapping]: http://docs-next.angularjs.org/guide/bootstrap
 [angular.copy]: http://docs-next.angularjs.org/api/angular.copy
 [ng:app]: http://docs-next.angularjs.org/api/angular.directive.ng-app
 [$compile]: http://docs-next.angularjs.org/api/angular.module.ng.$compile
diff --git a/docs/content/cookbook/helloworld.ngdoc b/docs/content/cookbook/helloworld.ngdoc
@@ -28,7 +28,7 @@
 
 Take a look through the source and note:
 
-* The script tag that {@link guide/dev_guide.bootstrap bootstraps} the angular environment.
+* The script tag that {@link guide/bootstrap bootstraps} the angular environment.
 * The text {@link api/angular.module.ng.$compileProvider.directive.input input widget} which is
   bound to the greeting name text.
 * No need for listener registration and event firing on change events.
diff --git a/docs/content/guide/bootstrap.ngdoc b/docs/content/guide/bootstrap.ngdoc
@@ -0,0 +1,108 @@
+@ngdoc overview
+@name Developer Guide: Bootstrap
+@description
+
+# Overview
+
+This page explains the Angular initialization process and how you can manually initialize Angular
+if necessary.
+
+
+# Angular `<script>` Tag
+
+This example shows the recommended path for integrating Angular with what we call automatic
+initialization.
+
+
+<pre>
+<!doctype html>
+<html xmlns:ng="http://angularjs.org" ng-app>
+  <body>
+    ...
+    <script src="angular.js">
+  </body>
+</html>
+</pre>
+
+  * Place the `script` tag at the buttom of the page. Placing script tags at the end of the page
+    impreves app load time becouse the HTML loading is not blocked by loading of the `angular.js`
+    script. You can get the latest bits from {@link http://code.angularjs.org}. Please don't link
+    your production code to this URL, as it will expose a security hole on your site. For
+    experimental development linking to our site is fine.
+    * Choose: `angular-[version].js` for a human-readable file, suitable for development and
+      debugging.
+    * Choose: `angular-[version].min.js` for a compressed and obfuscated file, suitable for use in
+      production.
+  * Place `ng-app` to the root of your application, typically on the `<html>` tag if you want
+    anugular to auto-bootstrap your application.
+
+        <html ng-app>
+
+  * If you chose to use the old style directive syntax `ng:` then include xml-namespace in `html`
+    to make IE happy. (This is here for historical resons, and we no longer recomend use of
+    `ng:`.)
+    
+        <html xmlns:ng="http://angularjs.org">
+  
+  
+
+# Automatic Initialization
+
+Angular initializes automatically upon `DOMContentLoaded` event, at which point angular looks for
+the {@link api/angular.module.ng.$compileProvider.directive.ng:app `ng-app`} directive which
+designates your application root. If {@link
+api/angular.module.ng.$compileProvider.directive.ng:app `ng-app`} directive is found then Angular
+will:
+
+  * load the {@link guide/module module} associated with the directive.
+  * create the application {@link api/angular.module.AUTO.$injector injector}
+  * compile the DOM treating the {@link api/angular.module.ng.$compileProvider.directive.ng:app
+    `ng-app`} directive as the root of the compilation. This allows you to tell it to treat only a
+    portion of the DOM as an Angular application.
+
+    
+<pre>
+<!doctype html>
+<html ng-app="optionalModuleName">
+  <body>
+    I can add: {{ 1+2 }}.
+    <script src="angular.js"></script>
+  </body>
+</html>
+</pre>
+
+
+
+# Manual Initialization
+
+
+If you need to have more control over the initialization process, you can use a manual
+bootstrapping method instead. Examples of when you'd need to do this include using script loaders
+or the need to perform an operation before the Angular compiles a page.
+
+
+Here is an example of manually initializing Angular. The example is equivalent to using the {@link
+api/angular.module.ng.$compileProvider.directive.ng:app ng:app} directive.
+
+<pre>
+<!doctype html>
+<html xmlns:ng="http://angularjs.org">
+  <body>
+    Hello {{'World'}}!
+    <script src="http://code.angularjs.org/angular.js"></script>
+    <script>
+       angular.element(document).ready(function() {
+         angular.bootstrap(document);
+       });
+    </script>
+  </body>
+</html>
+</pre>
+
+This sequence that your code should follow:
+
+  1. After the page and all of the code is loaded, find the root of the HTML template, which is
+  typically the root of the document.
+
+  2. Call {@link api/angular.bootstrap} to {@link compiler compile} the template into an
+  executable, bi-directionally bound application.
diff --git a/docs/content/guide/dev_guide.bootstrap.auto_bootstrap.ngdoc b/docs/content/guide/dev_guide.bootstrap.auto_bootstrap.ngdoc
diff --git a/docs/content/guide/dev_guide.bootstrap.manual_bootstrap.ngdoc b/docs/content/guide/dev_guide.bootstrap.manual_bootstrap.ngdoc
diff --git a/docs/content/guide/dev_guide.bootstrap.ngdoc b/docs/content/guide/dev_guide.bootstrap.ngdoc
diff --git a/docs/content/guide/index.ngdoc b/docs/content/guide/index.ngdoc
@@ -15,10 +15,7 @@ of the following documents before returning here to the Developer Guide:
 
 ## {@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 bootstrap Initializing Angular}
 
 ## {@link dev_guide.mvc About MVC in Angular}
 
diff --git a/docs/content/guide/overview.ngdoc b/docs/content/guide/overview.ngdoc
@@ -113,7 +113,7 @@ on.
 
 In the `<html>` tag, we specify that it is an angular
 application with the `ng-app` directive. The `ng-app' will cause the angular to {@link
-dev_guide.bootstrap auto initialize} your application.
+bootstrap auto initialize} your application.
 
     <html ng-app>
 
diff --git a/docs/content/misc/started.ngdoc b/docs/content/misc/started.ngdoc
@@ -40,7 +40,7 @@ The next line downloads the angular script:
 </pre>
 
 (For details on what happens when angular processes an HTML page,
-see {@link guide/dev_guide.bootstrap Bootstrap}.)
+see {@link guide/bootstrap Bootstrap}.)
 
 Finally, this line in the `<body>` of the page is the template that describes
 how to display our greeting in the UI:
diff --git a/src/Angular.js b/src/Angular.js
@@ -904,7 +904,7 @@ function angularInit(element, bootstrap) {
  * @description
  * Use this function to manually start up angular application.
  *
- * See: {@link guide/dev_guide.bootstrap.manual_bootstrap Bootstrap}
+ * See: {@link guide/bootstrap Bootstrap}
  *
  * @param {Element} element DOM element which is the root of angular application.
  * @param {Array<String|Function>=} modules an array of module declarations. See: {@link angular.module modules}

Original file line number	Diff line number	Diff line change
`@@ -904,7 +904,7 @@ function angularInit(element, bootstrap) {`
`904`	`904`	`* @description`
`905`	`905`	`* Use this function to manually start up angular application.`
`906`	`906`	`*`
`907`		`- * See: {@link guide/dev_guide.bootstrap.manual_bootstrap Bootstrap}`
	`907`	`+ * See: {@link guide/bootstrap Bootstrap}`
`908`	`908`	`*`
`909`	`909`	`* @param {Element} element DOM element which is the root of angular application.`
`910`	`910`	`* @param {Array<String\|Function>=} modules an array of module declarations. See: {@link angular.module modules}`