cargdev/angular
1
0
Fork 0
Code Issues 8 Pull Requests Actions Packages Projects Releases Wiki Activity

docs(aio): add NgModule docs (#20306)

Browse Source 
PR Close #20306
This commit is contained in:
Kapunahele Wong
2017-07-04 10:58:20 -04:00
committed by Alex Eagle
parent e64b1e99c2
commit 53f91189a1
217 changed files with 3881 additions and 2460 deletions
Download Patch File Download Diff File Expand all files Collapse all files

264
aio/content/guide/bootstrapping.md
View File

@ -1,169 +1,181 @@
# Bootstrapping
An Angular Module (NgModule) class describes how the application parts fit together.
Every application has at least one Angular Module, the _root_ module
that you [bootstrap](#main) to launch the application.
You can call the class anything you want. The conventional name is `AppModule`.
#### Prerequisites
The [**Angular CLI**](https://cli.angular.io/) produces a new project with the following minimal `AppModule`.
You evolve this module as your application grows.
A basic understanding of the following:
* [JavaScript Modules vs. NgModules](guide/ngmodule-vs-jsmodule).
<code-example path="cli-quickstart/src/app/app.module.ts" title="src/app/app.module.ts" linenums="false">
</code-example>
<hr />
An NgModule describes how the application parts fit together.
Every application has at least one Angular module, the _root_ module
that you bootstrap to launch the application.
By convention, it is usually called `AppModule`.
After the `import` statements, you come to a class adorned with the
**`@NgModule`** [_decorator_](guide/glossary#decorator '"Decorator" explained').
If you use the CLI to generate an app, the default `AppModule` is as follows:
```javascript
/* JavaScript imports */
import { BrowserModule } from '@angular/platform-browser';
import { NgModule } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { HttpModule } from '@angular/http';
import { AppComponent } from './app.component';
/* the AppModule class with the @NgModule decorator */
@NgModule({
declarations: [
AppComponent
],
imports: [
BrowserModule,
FormsModule,
HttpModule
],
providers: [],
bootstrap: [AppComponent]
})
export class AppModule { }
```
After the import statements is a class with the
**`@NgModule`** [decorator](guide/glossary#decorator '"Decorator" explained').
The `@NgModule` decorator identifies `AppModule` as an `NgModule` class.
`@NgModule` takes a _metadata_ object that tells Angular how to compile and launch the application.
`@NgModule` takes a metadata object that tells Angular how to compile and launch the application.
The `@NgModule` properties for the minimal `AppModule` generated by the CLI are as follows:
* **_declarations_**&mdash;this application's lone component.
* **_imports_**&mdash;import `BrowserModule` to have browser specific services such as DOM rendering, sanitization, and location.
* **_providers_**&mdash;the service providers.
* **_bootstrap_**&mdash;the _root_ component that Angular creates and inserts
into the `index.html` host web page.
* **[_declarations_](#declarations)** &mdash; declares the application components. At the moment, there is only the `AppComponent`.
* **[_imports_](#imports)** &mdash; the `BrowserModule`, which this and every application must import in order to run the app in a browser.
* **[_providers_](#providers)** &mdash; there are none to start but you are likely to add some soon.
* **[_bootstrap_](#bootstrap-array)** &mdash; the _root_ `AppComponent` that Angular creates and inserts into the `index.html` host web page.
The [Angular Modules (NgModules)](guide/ngmodule) guide dives deeply into the details of `@NgModule`.
All you need to know at the moment is a few basics about these four properties.
The default CLI application only has one component, `AppComponent`, so it
is in both the `declarations` and the `bootstrap` arrays.
{@a declarations}
## The `declarations` array
### The _declarations_ array
The module's `declarations` array tells Angular which components belong to that module.
As you create more components, add them to `declarations`.
You tell Angular which components belong to the `AppModule` by listing it in the module's `declarations` array.
As you create more components, you'll add them to `declarations`.
You must declare every component in exactly one `NgModule` class.
If you use a component without declaring it, Angular returns an
error message.
You must declare _every_ component in an Angular Module class.
If you use a component without declaring it, you'll see a clear error message in the browser console.
The `declarations` array only takes declarables. Declarables
are components, [directives](guide/attribute-directives) and [pipes](guide/pipes).
All of a module's declarables must be in the `declarations` array.
Declarables must belong to exactly one module. The compiler emits
an error if you try to declare the same class in more than one module.
You'll learn to create two other kinds of classes &mdash;
[directives](guide/attribute-directives) and [pipes](guide/pipes) &mdash;
that you must also add to the `declarations` array.
These declared classes are visible within the module but invisible
to components in a different module unless they are exported from
this module and the other module imports this one.
An example of what goes into a declarations array follows:
```javascript
declarations: [
YourComponent,
YourPipe,
YourDirective
],
```
A declarable can only belong to one module, so only declare it in
one `@NgModule`. When you need it elsewhere,
import the module that has the declarable you need in it.
**Only `@NgModule` references** go in the `imports` array.
### Using directives with `@NgModule`
Use the `declarations` array for directives.
To use a directive, component, or pipe in a module, you must do a few things:
1. Export it from the file where you wrote it.
2. Import it into the appropriate module.
3. Declare it in the `@NgModule` `declarations` array.
Those three steps look like the following. In the file where you create your directive, export it.
The following example, named `ItemDirective` is the default directive structure that the CLI generates in its own file, `item.directive.ts`:
<code-example path="bootstrapping/src/app/item.directive.ts" region="directive" title="src/app/item.directive.ts" linenums="false">
</code-example>
The key point here is that you have to export it so you can import it elsewhere. Next, import it
into the NgModule, in this example `app.module.ts`, with a JavaScript import statement:
<code-example path="bootstrapping/src/app/app.module.ts" region="directive-import" title="src/app/app.module.ts" linenums="false">
</code-example>
And in the same file, add it to the `@NgModule` `declarations` array:
<code-example path="bootstrapping/src/app/app.module.ts" region="declarations" title="src/app/app.module.ts" linenums="false">
</code-example>
Now you could use your `ItemDirective` in a component. This example uses `AppModule`, but you'd do it the same way for a feature module. For more about directives, see [Attribute Directives](guide/attribute-directives) and [Structural Directives](guide/structural-directives). You'd also use the same technique for [pipes](guide/pipes) and components.
Remember, components, directives, and pipes belong to one module only. You only need to declare them once in your app because you share them by importing the necessary modules. This saves you time and helps keep your app lean.
<div class="alert is-important">
**Only _declarables_** &mdash; _components_, _directives_ and _pipes_ &mdash; belong in the `declarations` array.
Do not put any other kind of class in `declarations`. Do _not_ declare `NgModule` classes. Do _not_ declare service classes. Do _not_ declare model classes.
</div>
{@a imports}
### The _imports_ array
## The `imports` array
Angular Modules are a way to consolidate features that belong together into discrete units.
Many features of Angular itself are organized as Angular Modules.
HTTP services are in the `HttpClientModule`. The router is in the `RouterModule`.
Eventually you may create your own modules.
The module's `imports` array appears exclusively in the `@NgModule` metadata object.
It tells Angular about other NgModules that this particular module needs to function properly.
Add a module to the `imports` array when the application requires its features.
_This_ application, like most applications, executes in a browser.
Every application that executes in a browser needs the `BrowserModule` from `@angular/platform-browser`.
So every such application includes the `BrowserModule` in its _root_ `AppModule`'s `imports` array.
Other guide pages will tell you when you need to add additional modules to this array.
<div class="alert is-important">
**Only `@NgModule` classes** go in the `imports` array. Do not put any other kind of class in `imports`.
</div>
<div class="l-sub-section">
The `import` statements at the top of the file and the NgModule's `imports` array
are unrelated and have completely different jobs.
The _JavaScript_ `import` statements give you access to symbols _exported_ by other files
so you can reference them within _this_ file.
You add `import` statements to almost every application file.
They have nothing to do with Angular and Angular knows nothing about them.
The _module's_ `imports` array appears _exclusively_ in the `@NgModule` metadata object.
It tells Angular about specific _other_ Angular Modules&mdash;all of them classes decorated
with `@NgModule`&mdash;that the application needs to function properly.
</div>
{@a providers}
### The _providers_ array
Angular apps rely on [_dependency injection (DI)_](guide/dependency-injection)
to deliver services to various parts of the application.
Before DI can inject a service, it must create that service with the help of a _provider_.
You can tell DI about a service's _provider_ in a number of ways.
Among the most popular ways is to register the service in the root `ngModule.providers` array, which will make that service available _everywhere_.
For example, a data service provided in the `AppModule`s _providers_ can be injected into any
component anywhere in the application.
This list of modules are those that export components, directives, or pipes
that the component templates in this module reference. In this case, the component is
`AppComponent`, which references components, directives, or pipes in `BrowserModule`,
`FormsModule`, or `HttpModule`.
A component template can reference another component, directive,
or pipe when the referenced class is declared in this module or
the class was imported from another module.
You don't have any services to provide yet.
But you will create some before long and you may chose to provide many of them here.
{@a bootstrap-array}
### The _bootstrap_ array
## The `providers` array
You launch the application by [_bootstrapping_](#main) the root `AppModule`.
Among other things, the _bootstrapping_ process creates the component(s) listed in the `bootstrap` array
The providers array is where you list the services the app needs. When
you list services here, they are available app-wide. You can scope
them when using feature modules and lazy loading. For more information, see
[Providers](guide/providers).
## The `bootstrap` array
The application launches by bootstrapping the root `AppModule`, which is
also referred to as an `entryComponent`.
Among other things, the bootstrapping process creates the component(s) listed in the `bootstrap` array
and inserts each one into the browser DOM.
Each bootstrapped component is the base of its own tree of components.
Inserting a bootstrapped component usually triggers a cascade of component creations that fill out that tree.
Inserting a bootstrapped component usually triggers a cascade of
component creations that fill out that tree.
While you can put more than one component tree on a host web page, that's not typical.
Most applications have only one component tree and they bootstrap a single _root_ component.
While you can put more than one component tree on a host web page,
most applications have only one component tree and bootstrap a single root component.
You can call the one _root_ component anything you want but most developers call it `AppComponent`.
This one root component is usually called `AppComponent` and is in the
root module's `bootstrap` array.
Which brings us to the _bootstrapping_ process itself.
{@a main}
## Bootstrap in _main.ts_
While there are many ways to bootstrap an application, most applications do so in the `src/main.ts` that is generated by the Angular CLI.
<code-example path="cli-quickstart/src/main.ts" title="src/main.ts" linenums="false">
</code-example>
This code creates a browser platform for dynamic compilation and
bootstraps the `AppModule` described above.
The _bootstrapping_ process sets up the execution environment,
digs the _root_ `AppComponent` out of the module's `bootstrap` array,
creates an instance of the component and inserts it within the element tag identified by the component's `selector`.
The `AppComponent` selector &mdash; here and in most documentation samples &mdash; is `app-root`
so Angular looks for a `<app-root>` tag in the `index.html` like this one ...
<code-example title="src/index.html (body)" linenums="false">
&lt;body>
&lt;app-root>&lt;/app-root>
&lt;/body>
</code-example>
... and displays the `AppComponent` there.
The `main.ts` file is very stable. Once you've set it up, you may never change it again.
## More about Angular Modules
Your initial app has only a single module, the _root_ module.
As your app grows, you'll consider subdividing it into multiple "feature" modules,
some of which can be loaded later ("lazy loaded") if and when the user chooses
to visit those features.
For more on NgModules you're likely to see frequently in apps,
see [Frequently Used Modules](#).
When you're ready to explore these possibilities, visit the [Angular Modules](guide/ngmodule) guide.