2012-02-24 16:14:44 -08:00
|
|
|
@ngdoc overview
|
2014-02-15 16:09:27 +00:00
|
|
|
@name Bootstrap
|
2014-09-04 16:49:16 +01:00
|
|
|
@sortOrder 350
|
2012-02-24 16:14:44 -08:00
|
|
|
@description
|
|
|
|
|
|
2014-03-03 12:31:51 -08:00
|
|
|
# Bootstrap
|
2012-02-24 16:14:44 -08:00
|
|
|
|
2017-01-24 17:23:54 +00:00
|
|
|
This page explains the AngularJS initialization process and how you can manually initialize AngularJS
|
2012-02-24 16:14:44 -08:00
|
|
|
if necessary.
|
|
|
|
|
|
2014-03-31 06:04:35 -07:00
|
|
|
|
2017-01-24 17:23:54 +00:00
|
|
|
## AngularJS `<script>` Tag
|
2012-02-24 16:14:44 -08:00
|
|
|
|
2017-01-24 17:23:54 +00:00
|
|
|
This example shows the recommended path for integrating AngularJS with what we call automatic
|
2012-02-24 16:14:44 -08:00
|
|
|
initialization.
|
|
|
|
|
|
|
|
|
|
|
2014-02-06 14:02:18 +00:00
|
|
|
```html
|
2012-02-24 16:14:44 -08:00
|
|
|
<!doctype html>
|
|
|
|
|
<html xmlns:ng="http://angularjs.org" ng-app>
|
|
|
|
|
<body>
|
|
|
|
|
...
|
2014-10-21 21:41:26 -07:00
|
|
|
<script src="angular.js"></script>
|
2012-02-24 16:14:44 -08:00
|
|
|
</body>
|
|
|
|
|
</html>
|
2014-02-06 14:02:18 +00:00
|
|
|
```
|
2012-02-24 16:14:44 -08:00
|
|
|
|
2014-03-03 12:31:51 -08:00
|
|
|
1. Place the `script` tag at the bottom of the page. Placing script tags at the end of the page
|
2012-08-09 00:12:54 +10:00
|
|
|
improves app load time because the HTML loading is not blocked by loading of the `angular.js`
|
2014-02-06 13:33:42 +00:00
|
|
|
script. You can get the latest bits from http://code.angularjs.org. Please don't link
|
2012-02-24 16:14:44 -08:00
|
|
|
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.
|
2014-03-03 12:31:51 -08:00
|
|
|
2. Place `ng-app` to the root of your application, typically on the `<html>` tag if you want
|
2017-01-24 17:23:54 +00:00
|
|
|
AngularJS to auto-bootstrap your application.
|
2012-02-24 16:14:44 -08:00
|
|
|
|
|
|
|
|
<html ng-app>
|
|
|
|
|
|
2014-07-11 14:01:24 +02:00
|
|
|
3. If you choose to use the old style directive syntax `ng:` then include xml-namespace in `html`
|
2017-04-12 13:19:53 +02:00
|
|
|
when running the page in the XHTML mode. (This is here for historical reasons, and we no longer
|
|
|
|
|
recommend use of `ng:`.)
|
2012-06-11 23:49:24 -07:00
|
|
|
|
2012-02-24 16:14:44 -08:00
|
|
|
<html xmlns:ng="http://angularjs.org">
|
2012-06-11 23:49:24 -07:00
|
|
|
|
|
|
|
|
|
2012-02-24 16:14:44 -08:00
|
|
|
|
2013-06-12 20:40:07 +01:00
|
|
|
## Automatic Initialization
|
2012-02-24 16:14:44 -08:00
|
|
|
|
2013-11-05 22:16:11 -08:00
|
|
|
<img class="pull-right" style="padding-left: 3em;" src="img/guide/concepts-startup.png">
|
|
|
|
|
|
2017-01-24 17:23:54 +00:00
|
|
|
AngularJS initializes automatically upon `DOMContentLoaded` event or when the `angular.js` script is
|
|
|
|
|
evaluated if at that time `document.readyState` is set to `'complete'`. At this point AngularJS looks
|
2016-02-08 23:24:08 +01:00
|
|
|
for the {@link ng.directive:ngApp `ngApp`} directive which designates your application root.
|
2017-01-24 17:23:54 +00:00
|
|
|
If the {@link ng.directive:ngApp `ngApp`} directive is found then AngularJS will:
|
2012-02-24 16:14:44 -08:00
|
|
|
|
|
|
|
|
* load the {@link guide/module module} associated with the directive.
|
2014-02-12 22:47:42 +00:00
|
|
|
* create the application {@link auto.$injector injector}
|
|
|
|
|
* compile the DOM treating the {@link ng.directive:ngApp
|
2016-02-08 23:24:08 +01:00
|
|
|
`ngApp`} directive as the root of the compilation. This allows you to tell it to treat only a
|
2017-01-24 17:23:54 +00:00
|
|
|
portion of the DOM as an AngularJS application.
|
2012-02-24 16:14:44 -08:00
|
|
|
|
2012-06-11 23:49:24 -07:00
|
|
|
|
2014-02-06 14:02:18 +00:00
|
|
|
```html
|
2012-02-24 16:14:44 -08:00
|
|
|
<!doctype html>
|
|
|
|
|
<html ng-app="optionalModuleName">
|
|
|
|
|
<body>
|
|
|
|
|
I can add: {{ 1+2 }}.
|
|
|
|
|
<script src="angular.js"></script>
|
|
|
|
|
</body>
|
|
|
|
|
</html>
|
2014-02-06 14:02:18 +00:00
|
|
|
```
|
2012-02-24 16:14:44 -08:00
|
|
|
|
2014-10-27 15:49:06 +02:00
|
|
|
As a best practice, consider adding an `ng-strict-di` directive on the same element as
|
2014-10-27 04:26:43 -07:00
|
|
|
`ng-app`:
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
```html
|
|
|
|
|
<!doctype html>
|
|
|
|
|
<html ng-app="optionalModuleName" ng-strict-di>
|
|
|
|
|
<body>
|
|
|
|
|
I can add: {{ 1+2 }}.
|
|
|
|
|
<script src="angular.js"></script>
|
|
|
|
|
</body>
|
|
|
|
|
</html>
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
This will ensure that all services in your application are properly annotated.
|
2014-12-22 17:42:18 +05:30
|
|
|
See the {@link guide/di#using-strict-dependency-injection dependency injection strict mode} docs
|
2014-10-27 04:26:43 -07:00
|
|
|
for more.
|
2012-02-24 16:14:44 -08:00
|
|
|
|
|
|
|
|
|
2013-06-12 20:40:07 +01:00
|
|
|
## Manual Initialization
|
2012-02-24 16:14:44 -08:00
|
|
|
|
|
|
|
|
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
|
2017-01-24 17:23:54 +00:00
|
|
|
or the need to perform an operation before AngularJS compiles a page.
|
2012-02-24 16:14:44 -08:00
|
|
|
|
2017-01-24 17:23:54 +00:00
|
|
|
Here is an example of manually initializing AngularJS:
|
2012-02-24 16:14:44 -08:00
|
|
|
|
2014-02-06 14:02:18 +00:00
|
|
|
```html
|
2012-02-24 16:14:44 -08:00
|
|
|
<!doctype html>
|
2014-03-31 06:04:35 -07:00
|
|
|
<html>
|
|
|
|
|
<body>
|
2014-09-17 13:46:17 -04:00
|
|
|
<div ng-controller="MyController">
|
|
|
|
|
Hello {{greetMe}}!
|
|
|
|
|
</div>
|
2014-06-12 11:05:40 -07:00
|
|
|
<script src="http://code.angularjs.org/snapshot/angular.js"></script>
|
2014-03-31 06:04:35 -07:00
|
|
|
|
|
|
|
|
<script>
|
|
|
|
|
angular.module('myApp', [])
|
|
|
|
|
.controller('MyController', ['$scope', function ($scope) {
|
|
|
|
|
$scope.greetMe = 'World';
|
|
|
|
|
}]);
|
|
|
|
|
|
2016-10-09 23:51:53 +02:00
|
|
|
angular.element(function() {
|
2014-03-31 06:04:35 -07:00
|
|
|
angular.bootstrap(document, ['myApp']);
|
|
|
|
|
});
|
|
|
|
|
</script>
|
|
|
|
|
</body>
|
2012-02-24 16:14:44 -08:00
|
|
|
</html>
|
2014-02-06 14:02:18 +00:00
|
|
|
```
|
2012-02-24 16:14:44 -08:00
|
|
|
|
2014-03-31 06:04:35 -07:00
|
|
|
Note that we provided the name of our application module to be loaded into the injector as the second
|
2014-03-03 12:31:51 -08:00
|
|
|
parameter of the {@link angular.bootstrap} function. Notice that `angular.bootstrap` will not create modules
|
|
|
|
|
on the fly. You must create any custom {@link guide/module modules} before you pass them as a parameter.
|
2013-06-12 20:40:07 +01:00
|
|
|
|
2014-03-31 06:04:35 -07:00
|
|
|
You should call `angular.bootstrap()` *after* you've loaded or defined your modules.
|
|
|
|
|
You cannot add controllers, services, directives, etc after an application bootstraps.
|
|
|
|
|
|
|
|
|
|
<div class="alert alert-warning">
|
|
|
|
|
**Note:** You should not use the ng-app directive when manually bootstrapping your app.
|
|
|
|
|
</div>
|
|
|
|
|
|
2012-07-11 22:27:13 -04:00
|
|
|
This is the sequence that your code should follow:
|
2012-02-24 16:14:44 -08:00
|
|
|
|
2013-06-12 20:40:07 +01:00
|
|
|
1. After the page and all of the code is loaded, find the root element of your AngularJS
|
|
|
|
|
application, which is typically the root of the document.
|
2012-02-24 16:14:44 -08:00
|
|
|
|
2014-02-12 22:47:42 +00:00
|
|
|
2. Call {@link angular.bootstrap} to {@link compiler compile} the element into an
|
2012-02-24 16:14:44 -08:00
|
|
|
executable, bi-directionally bound application.
|
2013-09-15 21:51:50 +01:00
|
|
|
|
2016-02-08 23:24:08 +01:00
|
|
|
## Things to keep in mind
|
|
|
|
|
|
2017-09-10 11:28:33 -04:00
|
|
|
There are a few things to keep in mind regardless of automatic or manual bootstrapping:
|
2016-02-08 23:24:08 +01:00
|
|
|
|
|
|
|
|
- While it's possible to bootstrap more than one AngularJS application per page, we don't actively
|
|
|
|
|
test against this scenario. It's possible that you'll run into problems, especially with complex apps, so
|
|
|
|
|
caution is advised.
|
|
|
|
|
- Do not bootstrap your app on an element with a directive that uses {@link ng.$compile#transclusion transclusion}, such as
|
|
|
|
|
{@link ng.ngIf `ngIf`}, {@link ng.ngInclude `ngInclude`} and {@link ngRoute.ngView `ngView`}.
|
|
|
|
|
Doing this misplaces the app {@link ng.$rootElement `$rootElement`} and the app's {@link auto.$injector injector},
|
|
|
|
|
causing animations to stop working and making the injector inaccessible from outside the app.
|
2014-03-31 06:04:35 -07:00
|
|
|
|
2013-09-15 21:51:50 +01:00
|
|
|
## Deferred Bootstrap
|
|
|
|
|
|
2014-11-01 05:52:17 -07:00
|
|
|
This feature enables tools like [Batarang](https://github.com/angular/angularjs-batarang) and test runners
|
2014-10-27 02:24:07 -07:00
|
|
|
to hook into angular's bootstrap process and sneak in more modules
|
2013-09-15 21:51:50 +01:00
|
|
|
into the DI registry which can replace or augment DI services for
|
|
|
|
|
the purpose of instrumentation or mocking out heavy dependencies.
|
|
|
|
|
|
|
|
|
|
If `window.name` contains prefix `NG_DEFER_BOOTSTRAP!` when
|
2014-02-12 22:47:42 +00:00
|
|
|
{@link angular.bootstrap} is called, the bootstrap process will be paused
|
2013-09-15 21:51:50 +01:00
|
|
|
until `angular.resumeBootstrap()` is called.
|
|
|
|
|
|
|
|
|
|
`angular.resumeBootstrap()` takes an optional array of modules that
|
|
|
|
|
should be added to the original list of modules that the app was
|
2016-10-09 23:51:53 +02:00
|
|
|
about to be bootstrapped with.
|
