mirror of
https://github.com/Hopiu/angular.js.git
synced 2026-03-17 07:40:22 +00:00
docs(bootstrap): rewritten bootstrap guide
This commit is contained in:
Misko Hevery
parent
f5afcca99d
commit
6933fb7924
10 changed files with 114 additions and 177 deletions
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
108
docs/content/guide/bootstrap.ngdoc
Normal file
108
docs/content/guide/bootstrap.ngdoc
Normal file
|
|
@ -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.
|
||||
|
|
@ -1,54 +0,0 @@
|
|||
@ngdoc overview
|
||||
@name Developer Guide: Initializing Angular: Automatic Initialization
|
||||
@description
|
||||
|
||||
For Angular to manage the DOM for your application, it needs to compile some or all of an HTML page. Angular does this initialization automatically when you load the angular.js script into your page and insert an `ngApp` directive (attribute) into one of the page's elements. For example, we can tell Angular to initialize the entire document:
|
||||
|
||||
<pre>
|
||||
<!doctype html>
|
||||
<html ng-app>
|
||||
<head>
|
||||
<script src="angular.js"></script>
|
||||
</head>
|
||||
<body>
|
||||
I can add: {{ 1+2 }}.
|
||||
</body>
|
||||
</html>
|
||||
</pre>
|
||||
|
||||
You can also tell Angular to manage only a portion of a page. You would want to do this if you are using some other framework to manage other parts of the page. You do this by placing the `ngApp` directive on one or more container elements in the document. For example:
|
||||
|
||||
<pre>
|
||||
<div ng-app>
|
||||
I can add: {{ 1+2 }}
|
||||
</div>
|
||||
</pre>
|
||||
|
||||
You can also ask `ngApp` to load additional {@link api/angular.module modules} containing services, directives or filers that you'll use on the page.
|
||||
|
||||
<pre>
|
||||
<div ng-app="AwesomeModule">
|
||||
...
|
||||
</div>
|
||||
</pre
|
||||
|
||||
|
||||
From a high-level, here's what Angular does during the initialization process:
|
||||
|
||||
1. The browser loads the page, and then runs the Angular script. Angular then waits for the
|
||||
`DOMContentLoaded` (or 'Load') event to attempt to initialize.
|
||||
|
||||
2. Angular looks for the `ngApp` directive. If found it compilies the DOM element containing `ngApp` and its children.
|
||||
|
||||
3. Angular creates a global variable `angular` and binds all Angular APIs to this object's fields.
|
||||
|
||||
|
||||
## Related Topics
|
||||
|
||||
* {@link dev_guide.compiler Angular HTML Compiler}
|
||||
* {@link dev_guide.bootstrap Initializing Angular}
|
||||
* {@link dev_guide.bootstrap.manual_bootstrap Manual Initialization}
|
||||
|
||||
## Related API
|
||||
|
||||
{@link api/angular.module.ng.$compile Compiler API}
|
||||
|
|
@ -1,49 +0,0 @@
|
|||
@ngdoc overview
|
||||
@name Developer Guide: Initializing Angular: Manual Initialization
|
||||
@description
|
||||
|
||||
In the vast majority of cases you'll want to let Angular handle initialization automatically.
|
||||
If, however, you need to delay Angular from managing the page right after the DOMContentLoaded
|
||||
event fires, you'll need to control this initialization manually.
|
||||
|
||||
To initialize Angular -- after you've done your own special-purpose initialization -- just call
|
||||
the {@link api/angular.bootstrap bootstrap()} function with the HTML container node that you want
|
||||
Angular to manage. In automatic initialization you'd do this by adding the `ngApp` attribute to
|
||||
the same node. Now, you won't use `ngApp` anywhere in your document.
|
||||
|
||||
To show the contrast of manual vs. automatic initialization, this automatic method:
|
||||
|
||||
<pre>
|
||||
<!doctype html>
|
||||
<html ng-app>
|
||||
<head>
|
||||
<script src="http://code.angularjs.org/angular.js"></script>
|
||||
...
|
||||
</pre
|
||||
|
||||
is the same as this manual method:
|
||||
|
||||
<pre>
|
||||
<!doctype html>
|
||||
<html>
|
||||
<head>
|
||||
<script src="http://code.angularjs.org/angular.js"></script>
|
||||
<script>
|
||||
angular.element(document).ready(function() {
|
||||
angular.bootstrap(document);
|
||||
});
|
||||
</script>
|
||||
</head>
|
||||
...
|
||||
</pre>
|
||||
|
||||
|
||||
## 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.module.ng.$compile Compiler API}
|
||||
|
|
@ -1,65 +0,0 @@
|
|||
@ngdoc overview
|
||||
@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 (`ngApp`)
|
||||
|
||||
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 ng-app>
|
||||
<head>
|
||||
...
|
||||
</head>
|
||||
<body>
|
||||
...
|
||||
<script src="angular.js">
|
||||
</body>
|
||||
</pre>
|
||||
|
||||
|
||||
## Specifying the Angular Namespace
|
||||
|
||||
<html xmlns:ng="http://angularjs.org">
|
||||
|
||||
You need to add the Angular namespace declaration if you use `ng:something` style of declaring
|
||||
Angular directives and you write your templates as XHTML. Or when you are targeting Internet
|
||||
Explorer older than version 9 (because older versions of IE do not render namespace
|
||||
properly for either HTML or XHTML). For more info please read {@link ie Internet Explorer
|
||||
Compatibility} doc.
|
||||
|
||||
|
||||
## Creating Your Own Namespaces
|
||||
|
||||
When you are ready to define your own {@link guide/directive
|
||||
directive}, you may chose to create your own namespace in addition to specifying the Angular
|
||||
namespace. You use your own namespace to form the fully qualified name for directives that you
|
||||
create.
|
||||
|
||||
For example, you could map the alias `my` to your domain, and create a directive called `my:directive`.
|
||||
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}
|
||||
|
|
@ -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}
|
||||
|
||||
|
|
|
|||
|
|
@ -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>
|
||||
|
||||
|
|
|
|||
|
|
@ -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:
|
||||
|
|
|
|||
|
|
@ -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}
|
||||
|
|
|
|||
Loading…
Reference in a new issue