docs(architecture): add Jade blocks for Dart, and other tweaks (#2990)
This commit is contained in:
Patrice Chalin
Kathy Walrath
parent
5d7221c026
commit
562c629d22
|
|
@ -35,3 +35,4 @@ link-checker-results.txt
|
|||
/dist
|
||||
/public/docs/dart
|
||||
/public/docs/ts/_cache
|
||||
/public/docs/_examples/*/dart
|
||||
|
|
|
|||
|
|
@ -48,115 +48,119 @@ figure
|
|||
## Modules
|
||||
figure
|
||||
img(src="/resources/images/devguide/architecture/module.png" alt="Component" align="left" style="width:240px; margin-left:-40px;margin-right:10px" )
|
||||
:marked
|
||||
Angular apps are modular and Angular has its own modularity system called _Angular modules_ or _NgModules_.
|
||||
|
||||
_Angular modules_ are a big deal.
|
||||
This page introduces modules; the [Angular modules](ngmodule.html) page covers them in depth.
|
||||
|
||||
<br class="l-clear-both"><br>
|
||||
:marked
|
||||
Every Angular app has at least one Angular module class, [the _root module_](appmodule.html "AppModule: the root module"),
|
||||
conventionally named `AppModule`.
|
||||
|
||||
While the _root module_ may be the only module in a small application, most apps have many more
|
||||
_feature modules_, each a cohesive block of code dedicated to an application domain,
|
||||
a workflow, or a closely related set of capabilities.
|
||||
|
||||
An Angular module, whether a _root_ or _feature_, is a class with an `@NgModule` decorator.
|
||||
.l-sub-section
|
||||
block angular-modules
|
||||
:marked
|
||||
Decorators are functions that modify JavaScript classes.
|
||||
Angular has many decorators that attach metadata to classes so that it knows
|
||||
what those classes mean and how they should work.
|
||||
<a href="https://medium.com/google-developers/exploring-es7-decorators-76ecb65fb841#.x5c2ndtx0" target="_blank">
|
||||
Learn more</a> about decorators on the web.
|
||||
:marked
|
||||
`NgModule` is a decorator function that takes a single metadata object whose properties describe the module.
|
||||
The most important properties are:
|
||||
* `declarations` - the _view classes_ that belong to this module.
|
||||
Angular has three kinds of view classes: [components](#components), [directives](#directives), and [pipes](pipes.html).
|
||||
Angular apps are modular and Angular has its own modularity system called _Angular modules_ or _NgModules_.
|
||||
|
||||
* `exports` - the subset of declarations that should be visible and usable in the component [templates](#templates) of other modules.
|
||||
_Angular modules_ are a big deal.
|
||||
This page introduces modules; the [Angular modules](ngmodule.html) page covers them in depth.
|
||||
|
||||
* `imports` - other modules whose exported classes are needed by component templates declared in _this_ module.
|
||||
|
||||
* `providers` - creators of [services](#services) that this module contributes to
|
||||
the global collection of services; they become accessible in all parts of the app.
|
||||
|
||||
* `bootstrap` - the main application view, called the _root component_,
|
||||
that hosts all other app views. Only the _root module_ should set this `bootstrap` property.
|
||||
|
||||
Here's a simple root module:
|
||||
+makeExample('app/mini-app.ts', 'module', 'app/app.module.ts')(format='.')
|
||||
|
||||
.l-sub-section
|
||||
<br class="l-clear-both"><br>
|
||||
:marked
|
||||
The `export` of `AppComponent` is just to show how to export; it isn't actually necessary in this example. A root module has no reason to _export_ anything because other components don't need to _import_ the root module.
|
||||
:marked
|
||||
Launch an application by _bootstrapping_ its root module.
|
||||
During development you're likely to bootstrap the `AppModule` in a `main.ts` file like this one.
|
||||
Every Angular app has at least one Angular module class, [the _root module_](appmodule.html "AppModule: the root module"),
|
||||
conventionally named `AppModule`.
|
||||
|
||||
While the _root module_ may be the only module in a small application, most apps have many more
|
||||
_feature modules_, each a cohesive block of code dedicated to an application domain,
|
||||
a workflow, or a closely related set of capabilities.
|
||||
|
||||
An Angular module, whether a _root_ or _feature_, is a class with an `@NgModule` decorator.
|
||||
.l-sub-section
|
||||
:marked
|
||||
Decorators are functions that modify JavaScript classes.
|
||||
Angular has many decorators that attach metadata to classes so that it knows
|
||||
what those classes mean and how they should work.
|
||||
<a href="https://medium.com/google-developers/exploring-es7-decorators-76ecb65fb841#.x5c2ndtx0" target="_blank">
|
||||
Learn more</a> about decorators on the web.
|
||||
:marked
|
||||
`NgModule` is a decorator function that takes a single metadata object whose properties describe the module.
|
||||
The most important properties are:
|
||||
* `declarations` - the _view classes_ that belong to this module.
|
||||
Angular has three kinds of view classes: [components](#components), [directives](#directives), and [pipes](pipes.html).
|
||||
|
||||
* `exports` - the subset of declarations that should be visible and usable in the component [templates](#templates) of other modules.
|
||||
|
||||
* `imports` - other modules whose exported classes are needed by component templates declared in _this_ module.
|
||||
|
||||
* `providers` - creators of [services](#services) that this module contributes to
|
||||
the global collection of services; they become accessible in all parts of the app.
|
||||
|
||||
* `bootstrap` - the main application view, called the _root component_,
|
||||
that hosts all other app views. Only the _root module_ should set this `bootstrap` property.
|
||||
|
||||
Here's a simple root module:
|
||||
+makeExample('app/mini-app.ts', 'module', 'app/app.module.ts')(format='.')
|
||||
|
||||
.l-sub-section
|
||||
:marked
|
||||
The `export` of `AppComponent` is just to show how to export; it isn't actually necessary in this example. A root module has no reason to _export_ anything because other components don't need to _import_ the root module.
|
||||
:marked
|
||||
Launch an application by _bootstrapping_ its root module.
|
||||
During development you're likely to bootstrap the `AppModule` in a `main.ts` file like this one.
|
||||
|
||||
+makeExample('app/main.ts', '', 'app/main.ts')(format='.')
|
||||
|
||||
:marked
|
||||
### Angular modules vs. JavaScript modules
|
||||
|
||||
The Angular module — a class decorated with `@NgModule` — is a fundamental feature of Angular.
|
||||
|
||||
JavaScript also has its own module system for managing collections of JavaScript objects.
|
||||
It's completely different and unrelated to the Angular module system.
|
||||
|
||||
+makeExample('app/main.ts', '', 'app/main.ts')(format='.')
|
||||
In JavaScript each _file_ is a module and all objects defined in the file belong to that module.
|
||||
The module declares some objects to be public by marking them with the `export` key word.
|
||||
Other JavaScript modules use *import statements* to access public objects from other modules.
|
||||
|
||||
:marked
|
||||
### Angular modules vs. JavaScript modules
|
||||
|
||||
The Angular module — a class decorated with `@NgModule` — is a fundamental feature of Angular.
|
||||
|
||||
JavaScript also has its own module system for managing collections of JavaScript objects.
|
||||
It's completely different and unrelated to the Angular module system.
|
||||
|
||||
In JavaScript each _file_ is a module and all objects defined in the file belong to that module.
|
||||
The module declares some objects to be public by marking them with the `export` key word.
|
||||
Other JavaScript modules use *import statements* to access public objects from other modules.
|
||||
|
||||
+makeExample('app/app.module.ts', 'imports', '')(format='.')
|
||||
+makeExample('app/app.module.ts', 'export', '')(format='.')
|
||||
|
||||
.l-sub-section
|
||||
+makeExample('app/app.module.ts', 'imports', '')(format='.')
|
||||
+makeExample('app/app.module.ts', 'export', '')(format='.')
|
||||
|
||||
.l-sub-section
|
||||
:marked
|
||||
<a href="http://exploringjs.com/es6/ch_modules.html" target="_blank">Learn more about the JavaScript module system on the web.</a>
|
||||
:marked
|
||||
<a href="http://exploringjs.com/es6/ch_modules.html" target="_blank">Learn more about the JavaScript module system on the web.</a>
|
||||
:marked
|
||||
These are two different and _complementary_ module systems. Use them both to write your apps.
|
||||
These are two different and _complementary_ module systems. Use them both to write your apps.
|
||||
|
||||
:marked
|
||||
### Angular libraries
|
||||
|
||||
figure
|
||||
img(src="/resources/images/devguide/architecture/library-module.png" alt="Component" align="left" style="width:240px; margin-left:-40px;margin-right:10px" )
|
||||
|
||||
:marked
|
||||
Angular ships as a collection of JavaScript modules. You can think of them as library modules.
|
||||
|
||||
Each Angular library name begins with the `!{_at_angular}` prefix.
|
||||
|
||||
You install them with the **npm** package manager and import parts of them with JavaScript `import` statements.
|
||||
<br class="l-clear-both"><br>
|
||||
:marked
|
||||
For example, import Angular's `Component` decorator from the `@angular/core` library like this:
|
||||
+makeExample('app/app.component.ts', 'import', '')(format='.')
|
||||
:marked
|
||||
You also import Angular _modules_ from Angular _libraries_ using JavaScript import statements:
|
||||
+makeExample('app/mini-app.ts', 'import-browser-module', '')(format='.')
|
||||
:marked
|
||||
In the example of the simple root module above, the application module needs material from within that `BrowserModule`. To access that material, add it to the `@NgModule` metadata `imports` like this.
|
||||
+makeExample('app/mini-app.ts', 'ngmodule-imports', '')(format='.')
|
||||
:marked
|
||||
In this way you're using both the Angular and JavaScript module systems _together_.
|
||||
|
||||
It's easy to confuse the two systems because they share the common vocabulary of "imports" and "exports".
|
||||
Hang in there. The confusion yields to clarity with time and experience.
|
||||
|
||||
.l-sub-section
|
||||
block angular-libraries
|
||||
:marked
|
||||
Learn more from the [Angular modules](ngmodule.html) page.
|
||||
Angular ships as a collection of JavaScript modules. You can think of them as library modules.
|
||||
|
||||
Each Angular library name begins with the `!{_at_angular}` prefix.
|
||||
|
||||
You install them with the **npm** package manager and import parts of them with JavaScript `import` statements.
|
||||
<br class="l-clear-both"><br>
|
||||
|
||||
For example, import Angular's `Component` decorator from the `@angular/core` library like this:
|
||||
+makeExample('app/app.component.ts', 'import', '')(format='.')
|
||||
:marked
|
||||
You also import Angular _modules_ from Angular _libraries_ using JavaScript import statements:
|
||||
+makeExample('app/mini-app.ts', 'import-browser-module', '')(format='.')
|
||||
:marked
|
||||
In the example of the simple root module above, the application module needs material from within that `BrowserModule`. To access that material, add it to the `@NgModule` metadata `imports` like this.
|
||||
+makeExample('app/mini-app.ts', 'ngmodule-imports', '')(format='.')
|
||||
:marked
|
||||
In this way you're using both the Angular and JavaScript module systems _together_.
|
||||
|
||||
It's easy to confuse the two systems because they share the common vocabulary of "imports" and "exports".
|
||||
Hang in there. The confusion yields to clarity with time and experience.
|
||||
|
||||
.l-sub-section
|
||||
:marked
|
||||
Learn more from the [Angular modules](ngmodule.html) page.
|
||||
|
||||
.l-hr
|
||||
|
||||
.l-main-section
|
||||
.l-main-section#components
|
||||
:marked
|
||||
<a id="components"></a>
|
||||
## Components
|
||||
|
||||
figure
|
||||
img(src="/resources/images/devguide/architecture/hero-component.png" alt="Component" align="left" style="width:200px; margin-left:-40px;margin-right:10px" )
|
||||
|
||||
|
|
@ -169,7 +173,6 @@ figure
|
|||
* The list of heroes.
|
||||
* The hero editor.
|
||||
|
||||
|
||||
You define a component's application logic—what it does to support the view—inside a class.
|
||||
The class interacts with the view through an API of properties and methods.
|
||||
|
||||
|
|
@ -253,7 +256,7 @@ block ts-decorator
|
|||
Here are a few of the possible `@Component` configuration options:
|
||||
|
||||
:marked
|
||||
- `moduleId`: sets the source of the base address (`module.id`) for module-relative URLs such as the `templateUrl`.
|
||||
<ul if-docs="ts"><li>`moduleId`: sets the source of the base address (`module.id`) for module-relative URLs such as the `templateUrl`.</ul>
|
||||
|
||||
- `selector`: CSS selector that tells Angular to create and insert an instance of this component
|
||||
where it finds a `<hero-list>` tag in *parent* HTML.
|
||||
|
|
@ -262,6 +265,9 @@ block ts-decorator
|
|||
|
||||
- `templateUrl`: module-relative address of this component's HTML template, shown [above](#templates).
|
||||
|
||||
block dart-directives
|
||||
|
||||
:marked
|
||||
- `providers`: !{_array} of **dependency injection providers** for services that the component requires.
|
||||
This is one way to tell Angular that the component's constructor requires a `HeroService`
|
||||
so it can get the list of heroes to display.
|
||||
|
|
@ -305,7 +311,7 @@ figure
|
|||
|
||||
:marked
|
||||
* The `{{hero.name}}` [*interpolation*](displaying-data.html#interpolation)
|
||||
displays the component's `hero.name` property value within the `<li>` tags.
|
||||
displays the component's `hero.name` property value within the `<li>` element.
|
||||
|
||||
* The `[hero]` [*property binding*](template-syntax.html#property-binding) passes the value of `selectedHero` from
|
||||
the parent `HeroListComponent` to the `hero` property of the child `HeroDetailComponent`.
|
||||
|
|
@ -349,12 +355,10 @@ figure
|
|||
Angular templates are *dynamic*. When Angular renders them, it transforms the DOM
|
||||
according to the instructions given by **directives**.
|
||||
|
||||
A directive is a class with directive metadata. In !{_Lang}, apply the `@Directive` !{_decorator}
|
||||
to attach metadata to the class.
|
||||
<br class="l-clear-both">
|
||||
:marked
|
||||
A directive is a class with a `@Directive` !{_decorator}.
|
||||
A component is a *directive-with-a-template*;
|
||||
a `@Component` !{_decorator} is actually a `@Directive` !{_decorator} extended with template-oriented features.
|
||||
<br class="l-clear-both">
|
||||
|
||||
.l-sub-section
|
||||
:marked
|
||||
|
|
@ -377,7 +381,6 @@ figure
|
|||
* [`*ngIf`](displaying-data.html#ngIf) includes the `HeroDetail` component only if a selected hero exists.
|
||||
|
||||
block dart-bool
|
||||
//- N/A
|
||||
|
||||
:marked
|
||||
**Attribute** directives alter the appearance or behavior of an existing element.
|
||||
|
|
@ -491,17 +494,19 @@ figure
|
|||
In brief, you must have previously registered a **provider** of the `HeroService` with the injector.
|
||||
A provider is something that can create or return a service, typically the service class itself.
|
||||
|
||||
You can register providers in modules or in components.
|
||||
|
||||
In general, add providers to the [root module](#module) so that
|
||||
the same instance of a service is available everywhere.
|
||||
block registering-providers
|
||||
:marked
|
||||
You can register providers in modules or in components.
|
||||
|
||||
In general, add providers to the [root module](#module) so that
|
||||
the same instance of a service is available everywhere.
|
||||
|
||||
+makeExample('app/app.module.ts', 'providers', 'app/app.module.ts (module providers)')(format='.')
|
||||
+makeExcerpt('app/app.module.ts (module providers)', 'providers')
|
||||
|
||||
:marked
|
||||
Alternatively, register at a component level in the `providers` property of the `@Component` metadata:
|
||||
|
||||
+makeExample('app/hero-list.component.ts', 'providers', 'app/hero-list.component.ts (component providers)')(format='.')
|
||||
+makeExcerpt('app/hero-list.component.ts (component providers)', 'providers')
|
||||
|
||||
:marked
|
||||
Registering at a component level means you get a new instance of the
|
||||
|
|
|
|||
Loading…
Reference in New Issue