From 3c1d528a1cfe997dbff754b36cb6d777c91a6f21 Mon Sep 17 00:00:00 2001 From: rexebin Date: Sat, 26 Nov 2016 21:44:27 +0000 Subject: [PATCH] merge --- .../ts/_cache/guide/learning-angular.jade | 88 ++--- public/docs/ts/_cache/guide/setup.jade | 360 +++++++++--------- public/docs/ts/latest/guide/appmodule.jade | 276 +++++++------- .../ts/latest/guide/learning-angular.jade | 86 ++--- .../latest/guide/setup-systemjs-anatomy.jade | 308 +++++++-------- public/docs/ts/latest/guide/setup.jade | 360 +++++++++--------- 6 files changed, 739 insertions(+), 739 deletions(-) diff --git a/public/docs/ts/_cache/guide/learning-angular.jade b/public/docs/ts/_cache/guide/learning-angular.jade index f0963c3ac6..135adf1254 100644 --- a/public/docs/ts/_cache/guide/learning-angular.jade +++ b/public/docs/ts/_cache/guide/learning-angular.jade @@ -1,44 +1,44 @@ -block includes - include ../_util-fns - -figure - img(src="/resources/images/devguide/intro/people.png" width="200px" height="152px" alt="Us" align="left" style="margin-left:-40px;margin-right:10px" ) -:marked - Everyone learns differently. - You don't have to read the documentation straight through. Most pages stand on their own. - Those new to Angular may wish to follow this popular learning path. -
- -:marked - 1. [Setup](setup.html "Setup locally withe Quickstart seed") for local Angular development, if you haven't already done so. - - 1. Take the [*Tour of Heroes* tutorial](../tutorial "Tour of Heroes"). - - The *Tour of Heroes* takes you step-by-step from [setup](setup.html) - to a full-featured example that demonstrates the essential characteristics of a professional application: - a sensible project structure, data binding, master/detail, services, dependency injection, navigation, and remote data access. - - 1. Read the [Architecture](architecture.html) overview for the big picture. -

  • - [The Root Module](appmodule.html) introduces the `NgModule` class that tells Angular how to compile and run your application. -

    • - - 1. [Displaying Data](displaying-data.html) shows how data binding puts component property values on screen. - - 1. [User Input](user-input.html) explains how to respond to user-initiated DOM events. - - 1. [Forms](forms.html) covers data entry and validation within the UI. - - 1. [Dependency Injection](dependency-injection.html) is the way to build large, maintainable applications - from small, single-purpose parts. - - 1. [Template Syntax](template-syntax.html) is a comprehensive study of Angular template HTML. - - After reading the above sections, feel free to skip around among the other pages on this site. - -.l-sub-section - :marked - ### Next Step - - Try the [tutorial](../tutorial "Tour of Heroes") if you're ready to start coding or - visit the [Architecture](architecture.html "Basic Concepts") guide if you prefer to learn the basic concepts first. +block includes + include ../_util-fns + +figure + img(src="/resources/images/devguide/intro/people.png" width="200px" height="152px" alt="Us" align="left" style="margin-left:-40px;margin-right:10px" ) +:marked + Everyone learns differently. + You don't have to read the documentation straight through. Most pages stand on their own. + Those new to Angular may wish to follow this popular learning path. +
    + +:marked + 1. [Setup](setup.html "Setup locally withe Quickstart seed") for local Angular development, if you haven't already done so. + + 1. Take the [*Tour of Heroes* tutorial](../tutorial "Tour of Heroes"). + + The *Tour of Heroes* takes you step-by-step from [setup](setup.html) + to a full-featured example that demonstrates the essential characteristics of a professional application: + a sensible project structure, data binding, master/detail, services, dependency injection, navigation, and remote data access. + + 1. Read the [Architecture](architecture.html) overview for the big picture. +

  • + [The Root Module](appmodule.html) introduces the `NgModule` class that tells Angular how to compile and run your application. +

    • + + 1. [Displaying Data](displaying-data.html) shows how data binding puts component property values on screen. + + 1. [User Input](user-input.html) explains how to respond to user-initiated DOM events. + + 1. [Forms](forms.html) covers data entry and validation within the UI. + + 1. [Dependency Injection](dependency-injection.html) is the way to build large, maintainable applications + from small, single-purpose parts. + + 1. [Template Syntax](template-syntax.html) is a comprehensive study of Angular template HTML. + + After reading the above sections, feel free to skip around among the other pages on this site. + +.l-sub-section + :marked + ### Next Step + + Try the [tutorial](../tutorial "Tour of Heroes") if you're ready to start coding or + visit the [Architecture](architecture.html "Basic Concepts") guide if you prefer to learn the basic concepts first. diff --git a/public/docs/ts/_cache/guide/setup.jade b/public/docs/ts/_cache/guide/setup.jade index e883eacc86..a98c37c704 100644 --- a/public/docs/ts/_cache/guide/setup.jade +++ b/public/docs/ts/_cache/guide/setup.jade @@ -1,180 +1,180 @@ -block includes - include ../_util-fns - - var _prereq = 'node and npm'; - - var _playground = 'playground'; - - var _Install = 'Install'; - //- npm commands - - var _install = 'install'; - - var _start = 'start'; - -a#develop-locally -:marked - ## Setup a local development environment - - - The QuickStart live-coding example is an Angular _playground_. - It's not where you'd develop a real application. - You [should develop locally](#why-locally "Why develop locally") on your own machine ... and that's also how we think you should learn Angular. - - - Setting up a new project on your machine is quick and easy with the **QuickStart seed**, - maintained [on github](!{_qsRepo} "Install the github QuickStart repo"). - - Make sure you have [!{_prereq} installed](#install-prerequisites "What if you don't have !{_prereq}?"). - Then ... - 1. Create a project folder (you can call it `quickstart` and rename it later). - 1. [Clone](#clone "Clone it from github") or [download](#download "download it from github") the **QuickStart seed** into your project folder. - 1. !{_Install} [!{_npm}](#install-prerequisites "What if you don't have !{_prereq}?") packages. - 1. Run `!{_npm} !{_start}` to launch the sample application. - -a#clone -:marked - ### Clone - - Perform the _clone-to-launch_ steps with these terminal commands. - -code-example(language="sh" class="code-shell"). - git clone !{_qsRepo}.git quickstart - cd quickstart - !{_npm} !{_install} - !{_npm} !{_start} - -a#download -:marked - ### Download - Download the QuickStart seed - and unzip it into your project folder. Then perform the remaining steps with these terminal commands. - -code-example(language="sh" class="code-shell"). - cd quickstart - !{_npm} !{_install} - !{_npm} !{_start} - -.l-main-section#seed -:marked - ## What's in the QuickStart seed? - -block qs-seed - :marked - The **QuickStart seed** contains the same application as the QuickStart playground - and even has its own _playground_ - that accomodates development of richer examples in a live coding environment. - - But it's true purpose is to provide a solid foundation for _local_ development. - Consequently, there are _many more files_ in the project folder on your machine, - most of which you can [learn about later](setup-systemjs-anatomy.html "Setup Anatomy"). - -block core-files - :marked - Focus on the following three TypeScript (`.ts`) files in the **`/app`** folder. - - .filetree - .file app - .children - .file app.component.ts - .file app.module.ts - .file main.ts - - +makeTabs(` - setup/ts/app/app.component.ts, - setup/ts/app/app.module.ts, - setup/ts/app/main.ts - `, '', ` - app/app.component.ts, - app/app.module.ts, - app/main.ts - `)(format='.') - -:marked - All guides and cookbooks have _at least these core files_. Each file has a distinct purpose and evolves independently as the application grows. - -style td, th {vertical-align: top} -table(width="100%") - col(width="20%") - col(width="80%") - tr - th File - th Purpose - tr - td app.component.ts - td - :marked - Defines the same `AppComponent` as the one in the QuickStart !{_playground}. - It is the **root** component of what will become a tree of nested components - as the application evolves. - tr(if-docs="ts") - td app.module.ts - td - :marked - Defines `AppModule`, the [root module](appmodule.html "AppModule: the root module") that tells Angular how to assemble the application. - Right now it declares only the `AppComponent`. - Soon there will be more components to declare. - tr - td main.ts - td - :marked - Compiles the application with the [JiT compiler](../glossary.html#jit) - and [bootstraps](appmodule.html#main "bootstrap the application") the application to run in the browser. - That's a reasonable choice for the development of most projects and - it's the only viable choice for a sample running in a _live-coding_ environment like Plunker. - You'll learn about alternative compiling and deployment options later in the documentation. - -.l-sub-section - :marked - ### Next Step - - If you're new to Angular, we recommend staying on the [learning path](learning-angular.html). - -br -br - -a#install-prerequisites -.l-main-section -:marked - ## Appendix: !{_prereq} -block install-tooling - :marked - Node.js and npm are essential to modern web development with Angular and other platforms. - Node powers client development and build tools. - The _npm_ package manager, itself a _node_ application, installs JavaScript libraries. - - - Get them now if they're not already installed on your machine. - - **Verify that you are running node `v4.x.x` or higher and npm `3.x.x` or higher** - by running the commands `node -v` and `npm -v` in a terminal/console window. - Older versions produce errors. - - We recommend [nvm](https://github.com/creationix/nvm) for managing multiple versions of node and npm. - You may need [nvm](https://github.com/creationix/nvm) if you already have projects running on your machine that - use other versions of node and npm. - -+ifDocsFor('ts') - a#why-locally - .l-main-section - :marked - ## Appendix: Why develop locally - - Live coding in the browser is a great way to explore Angular. - - Links on almost every documentation page open completed samples in the browser. - You can play with the sample code, share your changes with friends, and download and run the code on your own machine. - - The [QuickStart](../quickstart.html "Angular QuickStart Playground") shows just the `AppComponent` file. - It creates the equivalent of `app.module.ts` and `main.ts` internally _for the playground only_. - so the reader can discover Angular without distraction. - The other samples are based on the QuickStart seed. - - As much fun as this is ... - * you can't ship your app in plunker - * you aren't always online when writing code - * transpiling TypeScript in the browser is slow - * the type support, refactoring, and code completion only work in your local IDE - - Use the live coding environment as a _playground_, - a place to try the documentation samples and experiment on your own. - It's the perfect place to reproduce a bug when you want to - file a documentation issue or - file an issue with Angular itself. - - For real development, we strongly recommend [developing locally](#develop-locally). +block includes + include ../_util-fns + - var _prereq = 'node and npm'; + - var _playground = 'playground'; + - var _Install = 'Install'; + //- npm commands + - var _install = 'install'; + - var _start = 'start'; + +a#develop-locally +:marked + ## Setup a local development environment + + + The QuickStart live-coding example is an Angular _playground_. + It's not where you'd develop a real application. + You [should develop locally](#why-locally "Why develop locally") on your own machine ... and that's also how we think you should learn Angular. + + + Setting up a new project on your machine is quick and easy with the **QuickStart seed**, + maintained [on github](!{_qsRepo} "Install the github QuickStart repo"). + + Make sure you have [!{_prereq} installed](#install-prerequisites "What if you don't have !{_prereq}?"). + Then ... + 1. Create a project folder (you can call it `quickstart` and rename it later). + 1. [Clone](#clone "Clone it from github") or [download](#download "download it from github") the **QuickStart seed** into your project folder. + 1. !{_Install} [!{_npm}](#install-prerequisites "What if you don't have !{_prereq}?") packages. + 1. Run `!{_npm} !{_start}` to launch the sample application. + +a#clone +:marked + ### Clone + + Perform the _clone-to-launch_ steps with these terminal commands. + +code-example(language="sh" class="code-shell"). + git clone !{_qsRepo}.git quickstart + cd quickstart + !{_npm} !{_install} + !{_npm} !{_start} + +a#download +:marked + ### Download + Download the QuickStart seed + and unzip it into your project folder. Then perform the remaining steps with these terminal commands. + +code-example(language="sh" class="code-shell"). + cd quickstart + !{_npm} !{_install} + !{_npm} !{_start} + +.l-main-section#seed +:marked + ## What's in the QuickStart seed? + +block qs-seed + :marked + The **QuickStart seed** contains the same application as the QuickStart playground + and even has its own _playground_ + that accomodates development of richer examples in a live coding environment. + + But it's true purpose is to provide a solid foundation for _local_ development. + Consequently, there are _many more files_ in the project folder on your machine, + most of which you can [learn about later](setup-systemjs-anatomy.html "Setup Anatomy"). + +block core-files + :marked + Focus on the following three TypeScript (`.ts`) files in the **`/app`** folder. + + .filetree + .file app + .children + .file app.component.ts + .file app.module.ts + .file main.ts + + +makeTabs(` + setup/ts/app/app.component.ts, + setup/ts/app/app.module.ts, + setup/ts/app/main.ts + `, '', ` + app/app.component.ts, + app/app.module.ts, + app/main.ts + `)(format='.') + +:marked + All guides and cookbooks have _at least these core files_. Each file has a distinct purpose and evolves independently as the application grows. + +style td, th {vertical-align: top} +table(width="100%") + col(width="20%") + col(width="80%") + tr + th File + th Purpose + tr + td app.component.ts + td + :marked + Defines the same `AppComponent` as the one in the QuickStart !{_playground}. + It is the **root** component of what will become a tree of nested components + as the application evolves. + tr(if-docs="ts") + td app.module.ts + td + :marked + Defines `AppModule`, the [root module](appmodule.html "AppModule: the root module") that tells Angular how to assemble the application. + Right now it declares only the `AppComponent`. + Soon there will be more components to declare. + tr + td main.ts + td + :marked + Compiles the application with the [JiT compiler](../glossary.html#jit) + and [bootstraps](appmodule.html#main "bootstrap the application") the application to run in the browser. + That's a reasonable choice for the development of most projects and + it's the only viable choice for a sample running in a _live-coding_ environment like Plunker. + You'll learn about alternative compiling and deployment options later in the documentation. + +.l-sub-section + :marked + ### Next Step + + If you're new to Angular, we recommend staying on the [learning path](learning-angular.html). + +br +br + +a#install-prerequisites +.l-main-section +:marked + ## Appendix: !{_prereq} +block install-tooling + :marked + Node.js and npm are essential to modern web development with Angular and other platforms. + Node powers client development and build tools. + The _npm_ package manager, itself a _node_ application, installs JavaScript libraries. + + + Get them now if they're not already installed on your machine. + + **Verify that you are running node `v4.x.x` or higher and npm `3.x.x` or higher** + by running the commands `node -v` and `npm -v` in a terminal/console window. + Older versions produce errors. + + We recommend [nvm](https://github.com/creationix/nvm) for managing multiple versions of node and npm. + You may need [nvm](https://github.com/creationix/nvm) if you already have projects running on your machine that + use other versions of node and npm. + ++ifDocsFor('ts') + a#why-locally + .l-main-section + :marked + ## Appendix: Why develop locally + + Live coding in the browser is a great way to explore Angular. + + Links on almost every documentation page open completed samples in the browser. + You can play with the sample code, share your changes with friends, and download and run the code on your own machine. + + The [QuickStart](../quickstart.html "Angular QuickStart Playground") shows just the `AppComponent` file. + It creates the equivalent of `app.module.ts` and `main.ts` internally _for the playground only_. + so the reader can discover Angular without distraction. + The other samples are based on the QuickStart seed. + + As much fun as this is ... + * you can't ship your app in plunker + * you aren't always online when writing code + * transpiling TypeScript in the browser is slow + * the type support, refactoring, and code completion only work in your local IDE + + Use the live coding environment as a _playground_, + a place to try the documentation samples and experiment on your own. + It's the perfect place to reproduce a bug when you want to + file a documentation issue or + file an issue with Angular itself. + + For real development, we strongly recommend [developing locally](#develop-locally). diff --git a/public/docs/ts/latest/guide/appmodule.jade b/public/docs/ts/latest/guide/appmodule.jade index 8c5ed25973..5e5eee9834 100644 --- a/public/docs/ts/latest/guide/appmodule.jade +++ b/public/docs/ts/latest/guide/appmodule.jade @@ -1,138 +1,138 @@ -include ../_util-fns - -:marked - An Angular module 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 it anything you want. The conventional name is `AppModule`. - - The [setup](setup.html) instructions produce a new project with the following minimal `AppModule`. - You'll evolve this module as your application grows. - -+makeExample('setup/ts/app/app.module.ts','', 'app/app.module.ts')(format='.') - -:marked - After the `import` statements, you come to a class adorned with the - **`@NgModule`** [_decorator_](glossary.html#decorator '"Decorator" explained'). - - The `@NgModule` decorator identifies `AppModule` as an Angular module class (also called an `NgModule` class). - `@NgModule` takes a _metadata_ object that tells Angular how to compile and launch the application. - - * **_imports_** — the `BrowserModule` that this and every application needs to run in a browser. - * **_declarations_** — the application's lone component, which is also ... - * **_bootstrap_** — the _root_ component that Angular creates and inserts into the `index.html` host web page. - - The [Angular Modules (NgModules)](ngmodule.html) guide dives deeply into the details of Angular modules. - All you need to know at the moment is a few basics about these three properties. - -a#imports -:marked - ### 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 `HttpModule`. The router is in the `RouterModule`. - Eventually you may create a feature module. - - 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 and cookbook pages will tell you when you need to add additional modules to this array. - -.alert.is-important - :marked - **Only `NgModule` classes** go in the `imports` array. Don't put any other kind of class in `imports`. - -.l-sub-section - :marked - Don't confuse the `import` statements at the top of the file with the Angular module's `imports` array. - They have different jobs. - - The _JavaScript_ `import` statements give you access to symbols _exported_ by other files - so you can reference them within _this_ file. - They have nothing to do with Angular and Angular knows nothing about them. - - The _module's_ `imports` array tells Angular about specific Angular modules — classes decorated with `@NgModule` — - that the application needs to function properly. -a#declarations -:marked - ### The _declarations_ array - - You must declare _every_ component in one (and _only one_) `NgModule` class. - 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'll learn to create two other kinds of classes — - [directives](attribute-directives.html) and [pipes](pipes.html) — - that you must also add to the `declarations` array. - -.alert.is-important - :marked - **Only _declarables_** — _components_, _directives_ and _pipes_ — belong in the `declarations` array.   - Don't put any other kind of class in `declarations`; _not_ `NgModule` classes, _not_ service classes, _not_ model classes. - -a#bootstrap-array -:marked - ### The _bootstrap_ 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 - 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. - - 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. - - You can call the one _root_ component anything you want but most developers call it `AppComponent`. - - Which brings us to the _bootstrapping_ process itself. - -a#main -l-main-section -:marked - ## Bootstrap in _main.ts_ - - There are many ways to bootstrap an application. - The variations depend upon how you want to compile the application and where you want to run it. - - In the beginning, you will compile the application dynamically with the _Just-in-Time (JiT)_ compiler - and you'll run it in a browser. You can learn about other options later. - - The recommended place to bootstrap a JiT-compiled browser application is in a separate file - in the `app` folder named `app/main.ts` -+makeExample('setup/ts/app/main.ts','','app/main.ts')(format='.') -:marked - This code creates a browser platform for dynamic (JiT) compilation and - bootstrap's 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 — here and in most documentation samples — is `my-app` - so Angular looks for a `` tag in the `index.html` like this one ... -+makeExample('setup/ts/index.html','my-app')(format='.') -:marked - ... and displays the `AppComponent` there. - - This file is very stable. Once you've set it up, you may never change it again. - -a#quickstart-appmodule -l-main-section -:marked - ## QuickStart's _AppModule_ - Every Angular application must have a root `NgModule`, even the [QuickStart](../quickstart.html). - You didn't see it but it was there. - - A script in the `index.html` generated a hidden `AppModule` and bootstrapped it for you - so you could focus on the `AppComponent` and discover the _essential Angular_ more quickly. - - If you're feeling adventurous, add your own `AppModule` and `main.ts` to the - live code in the _QuickStart_ plunker. - - Remove the following `