Skip to content
This repository was archived by the owner on Dec 4, 2017. It is now read-only.

docs(architecture): add Jade blocks for Dart, and other tweaks #2990

Merged
merged 1 commit into from
Dec 15, 2016
Merged

docs(architecture): add Jade blocks for Dart, and other tweaks #2990

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,3 +35,4 @@ link-checker-results.txt
/dist
/public/docs/dart
/public/docs/ts/_cache
/public/docs/_examples/*/dart
191 changes: 98 additions & 93 deletions public/docs/ts/latest/guide/architecture.jade
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`.
block angular-modules
:marked
Angular apps are modular and Angular has its own modularity system called _Angular modules_ or _NgModules_.

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.
_Angular modules_ are a big deal.
This page introduces modules; the [Angular modules](ngmodule.html) page covers them in depth.

An Angular module, whether a _root_ or _feature_, is a class with an `@NgModule` decorator.
.l-sub-section
<br class="l-clear-both"><br>
: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).
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.
* `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.
* `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.
* `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.
* `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='.')
Here's a simple root module:
+makeExample('app/mini-app.ts', 'module', 'app/app.module.ts')(format='.')

.l-sub-section
.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
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='.')
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
:marked
### Angular modules vs. JavaScript modules

The Angular module &mdash; a class decorated with `@NgModule` &mdash; is a fundamental feature of Angular.
The Angular module &mdash; a class decorated with `@NgModule` &mdash; 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.
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_.
block angular-libraries
:marked
Angular ships as a collection of JavaScript modules. You can think of them as library modules.

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.
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>

.l-sub-section
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
Learn more from the [Angular modules](ngmodule.html) page.
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" )

Expand All @@ -169,7 +173,6 @@ figure
* The list of heroes.
* The hero editor.


You define a component's application logic&mdash;what it does to support the view&mdash;inside a class.
The class interacts with the view through an API of properties and methods.

Expand Down Expand Up @@ -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.
Expand All @@ -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.
Expand Down Expand Up @@ -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`.
Expand Down Expand Up @@ -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
Expand All @@ -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.
Expand Down Expand Up @@ -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
Expand Down