diff --git a/.gitignore b/.gitignore index f347aa50a6..f94e8f4f3b 100644 --- a/.gitignore +++ b/.gitignore @@ -35,3 +35,4 @@ link-checker-results.txt /dist /public/docs/dart /public/docs/ts/_cache +/public/docs/_examples/*/dart diff --git a/public/docs/ts/latest/guide/architecture.jade b/public/docs/ts/latest/guide/architecture.jade index 9a71f006b0..addfce287e 100644 --- a/public/docs/ts/latest/guide/architecture.jade +++ b/public/docs/ts/latest/guide/architecture.jade @@ -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. - -

-: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. - - Learn more 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 +

: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. + + Learn more 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 + Learn more about the JavaScript module system on the web. :marked - Learn more about the JavaScript module system on the web. -: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. -

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

+ + 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 - ## 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`. + - `selector`: CSS selector that tells Angular to create and insert an instance of this component where it finds a `` 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 `
  • ` tags. + displays the component's `hero.name` property value within the `
  • ` 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. -
    -: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. +
    .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