From 0fa21c49ad6360f4c7e9ca433350a428be3cfd2f Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Fri, 18 Nov 2016 13:23:38 -0800 Subject: [PATCH] docs(Dart): sync with TS version of quickstart (#2828) * update cache * docs(Dart): sync with TS version of quickstart * sync cache with updates from previous commit --- public/docs/dart/latest/quickstart.jade | 163 +++--- public/docs/ts/_cache/quickstart.jade | 698 ++++++++---------------- public/docs/ts/latest/quickstart.jade | 152 +++--- 3 files changed, 386 insertions(+), 627 deletions(-) diff --git a/public/docs/dart/latest/quickstart.jade b/public/docs/dart/latest/quickstart.jade index 1ad1743be2..12b241544b 100644 --- a/public/docs/dart/latest/quickstart.jade +++ b/public/docs/dart/latest/quickstart.jade @@ -41,8 +41,11 @@ block install-packages packages (along with the packages they depend on). code-example(language="sh" class="code-shell"). - > pub get - Resolving dependencies... + pub get + +block create-your-app + :marked + Let's create a folder to hold our application and add a super-simple Angular component. block annotation-fields :marked @@ -57,6 +60,10 @@ block create-main li a #[b folder named #[code web]] li a file named #[code #[+adjExPath('app/main.ts')]] with the following content: +block commentary-on-index-html + :marked + Note the `` tag in the ``, this is *where your app lives!* + block run-app p. We have a few options for running our app. @@ -76,83 +83,85 @@ block run-app Once the app is running, the browser window should show the following: block build-app - .alert.is-important - :marked - If you don't see **My First Angular App**, make sure you've entered all the code correctly, - in the [proper folders](#wrap-up), - and run `pub get`. - - .l-verbose-section#section-angular-run-app - :marked - ### Building the app (generating JavaScript) - - Before deploying the app, we need to generate JavaScript files. - The `pub build` command makes that easy. - - code-example(language="sh" class="code-shell"). - > pub build - Loading source assets... - - :marked - The generated JavaScript appears, along with supporting files, - under a directory named `build`. - - #angular_transformer - h4 Using the Angular transformer - - p. - When generating JavaScript for an Angular app, - be sure to use the Angular transformer. - It analyzes the Dart code, - converting reflection-using code to static code - that Dart's build tools can compile to faster, smaller JavaScript. - The highlighted lines in pubspec.yaml - configure the Angular transformer: - - - var stylePattern = { otl: /(transformers:)|(- angular2:)|(entry_points.*$)/gm }; - +makeExample('quickstart/dart/pubspec.yaml', null, 'pubspec.yaml', stylePattern) - - p. - The entry_points item - identifies the Dart file in our app - that has a main() function. - For more information, see the - Angular - transformer wiki page. - - .l-sub-section#performance - h3 Performance, the transformer, and Angular libraries - p. - When an app imports bootstrap.dart, - it also gets dart:mirrors, - a reflection library that - causes performance problems when compiled to JavaScript. - Don't worry, - the Angular transformer converts the app's entry points - (entry_points in pubspec.yaml) - so that they don't use mirrors. - - #dart_to_js_script_rewriter - h4 Using dart_to_js_script_rewriter - - :marked - To improve the app's performance, convert the - HTML file to directly include the generated JavaScript; - one way to do that is with `dart_to_js_script_rewriter`. - To use the rewriter, specify `dart_to_js_script_rewriter` in both - the `dependencies` and `transformers` sections of the pubspec. - - - var stylePattern = { otl: /(dart_to_js_script_rewriter.*$)|(- dart_to_js_script_rewriter.*$)|(dependencies:)|(transformers:)/gm }; - +makeExample('quickstart/dart/pubspec.yaml', null, 'pubspec.yaml', stylePattern) - + //- Remove details of building from QS for now. (It is too early for these details.) + if false .alert.is-important :marked - The `dart_to_js_script_rewriter` transformer must be - **after** the `angular2` transformer in `pubspec.yaml`. + If you don't see **Hello Angular!**, make sure you've entered all the code correctly, + in the [proper folders](#wrap-up), + and run `pub get`. - :marked - For more information, see the docs for - [dart_to_js_script_rewriter](https://pub.dartlang.org/packages/dart_to_js_script_rewriter). + .l-verbose-section#section-angular-run-app + :marked + ### Building the app (generating JavaScript) + + Before deploying the app, we need to generate JavaScript files. + The `pub build` command makes that easy. + + code-example(language="sh" class="code-shell"). + > pub build + Loading source assets... + + :marked + The generated JavaScript appears, along with supporting files, + under a directory named `build`. + + #angular_transformer + h4 Using the Angular transformer + + p. + When generating JavaScript for an Angular app, + be sure to use the Angular transformer. + It analyzes the Dart code, + converting reflection-using code to static code + that Dart's build tools can compile to faster, smaller JavaScript. + The highlighted lines in pubspec.yaml + configure the Angular transformer: + + - var stylePattern = { otl: /(transformers:)|(- angular2:)|(entry_points.*$)/gm }; + +makeExample('quickstart/dart/pubspec.yaml', null, 'pubspec.yaml', stylePattern) + + p. + The entry_points item + identifies the Dart file in our app + that has a main() function. + For more information, see the + Angular + transformer wiki page. + + .l-sub-section#performance + h3 Performance, the transformer, and Angular libraries + p. + When an app imports bootstrap.dart, + it also gets dart:mirrors, + a reflection library that + causes performance problems when compiled to JavaScript. + Don't worry, + the Angular transformer converts the app's entry points + (entry_points in pubspec.yaml) + so that they don't use mirrors. + + #dart_to_js_script_rewriter + h4 Using dart_to_js_script_rewriter + + :marked + To improve the app's performance, convert the + HTML file to directly include the generated JavaScript; + one way to do that is with `dart_to_js_script_rewriter`. + To use the rewriter, specify `dart_to_js_script_rewriter` in both + the `dependencies` and `transformers` sections of the pubspec. + + - var stylePattern = { otl: /(dart_to_js_script_rewriter.*$)|(- dart_to_js_script_rewriter.*$)|(dependencies:)|(transformers:)/gm }; + +makeExample('quickstart/dart/pubspec.yaml', null, 'pubspec.yaml', stylePattern) + + .alert.is-important + :marked + The `dart_to_js_script_rewriter` transformer must be + **after** the `angular2` transformer in `pubspec.yaml`. + + :marked + For more information, see the docs for + [dart_to_js_script_rewriter](https://pub.dartlang.org/packages/dart_to_js_script_rewriter). block server-watching :marked @@ -160,7 +169,7 @@ block server-watching .alert.is-important :marked - Be sure to terminate the `pub serve` process once you stop working on this app. + Be sure to terminate your local server once you stop working on this app. block project-file-structure .filetree diff --git a/public/docs/ts/_cache/quickstart.jade b/public/docs/ts/_cache/quickstart.jade index 7241016d77..817f34361f 100644 --- a/public/docs/ts/_cache/quickstart.jade +++ b/public/docs/ts/_cache/quickstart.jade @@ -1,7 +1,7 @@ block includes include _util-fns - var _Install = 'Install' - - var _prereq = 'Node.js' + - var _prereq = 'Node.js and npm' - var _angular_browser_uri = '@angular/platform-browser-dynamic' - var _angular_core_uri = '@angular/core' - var _stepInit = 4 // Step # after NgModule step @@ -10,516 +10,289 @@ block includes //- TS/Dart shared step counter - var step = _stepInit -:marked - Our QuickStart goal is to build and run a super-simple - Angular application in #{_Lang}, and - establish a development environment for the remaining documentation samples - that also can be the foundation for real world applications. - -.callout.is-helpful - header Don't want #{_Lang}? - p. - Although we're getting started in #{_Lang}, you can also write Angular apps - in #{_docsFor == 'ts' ? 'Dart' : 'TypeScript'} and JavaScript. - Just select either of those languages from the combo-box in the banner. ++ifDocsFor('ts') + aside.is-right + :marked + The live example link opens the finished application in + Plunker so that you can interact + with the code. You'll find live examples at the start of most sections. :marked - # Try it! - - Try the which loads the sample app - - in plunker - - and displays the simple message: + The QuickStart application has the structure of a real-world Angular application and + displays the simple message: figure.image-display img(src='/resources/images/devguide/quickstart/hello-angular.png' alt="Output of QuickStart app") :marked - # Build this app! + **Try it out**. Here's a link to a . - - [Prerequisite](#prereq): Install #{_prereq} - - [Step 1](#create-and-configure): Create the app’s project folder and - define package dependencies and special project setup - - [Step 2](#root-component): Create the app’s Angular root component -
  • [Step 3](#ngmodule): Create an Angular Module
    • - - [Step !{step++}](#main): Add main.ts, identifying the root component to Angular - - [Step !{step++}](#index): Add `index.html`, the web page that hosts the application - - [Step !{step++}](#build-and-run): Build and run the app - - [Make some changes to the app](#make-some-changes) - - [Wrap up](#wrap-up) ++ifDocsFor('ts') + :marked + You can also + clone the entire QuickStart application from GitHub. + +h1 Build this application! + +:marked + - [Prerequisite](#prereq): Install #{_prereq}. + - [Step 1](#create-and-configure): Create and configure the project. + - [Step 2](#ngmodule): Create your application. +
  • [Step 3](#root-component): Create a component and add it to your application.
    • + - [Step !{step++}](#main): Start up your application. + - [Step !{step++}](#index): Define the web page that hosts the application. + - [Step !{step++}](#build-and-run): Build and run the application. + - [Step !{step++}](#make-changes): Make some live changes. + - [Wrap up and Next Steps](#wrap-up) - var step = _stepInit // reinitialize step counter for headers to come + .l-main-section#prereq -h2 Prerequisite: #{_prereq} +h2 Prerequisite: Install #{_prereq} block setup-tooling :marked - Install **[Node.js® and npm](https://nodejs.org/en/download/)** - if they are not already on your machine. - .l-sub-section - :marked - **Verify that you are running at least node `v4.x.x` and npm `3.x.x`** - by running `node -v` and `npm -v` in a terminal/console window. - Older versions produce errors. + If Node.js and npm aren't already on your machine, install them. Our examples require node **v4.x.x** or higher and + npm **3.x.x** or higher. To check which version you are using, run `node -v` and `npm -v` + in a terminal window. .l-main-section -.callout.is-helpful - header Download the source - :marked - Instead of following each step of these instructions, we can - [download the QuickStart source](!{_quickstartSrcURL}) - from GitHub and follow its brief instructions. +h2#create-and-configure Step 1: Create and configure the project -.l-main-section -button(class="verbose off md-primary md-button md-ink-ripple", type="button", onclick="verbose(false)"). - Hide explanations -button(class="verbose on md-primary md-button md-ink-ripple", type="button", onclick="verbose(true)"). - View explanations -.l-verbose-section - :marked - *Explanations* describe the concepts and reasons behind the instructions. - Explanations have a thin border on the left like *this* block of text. +- var _package_and_config_files = _docsFor == 'dart' ? 'pubspec.yaml' : 'configuration files' - Click *Hide Explanations* to show only the instructions. - Click *View Explanations* to see everything again. - -.l-sub-section - :marked - We'll see many code blocks as we build the QuickStart app. They're all easy to copy and paste: - code-example(format="nocode"). - Click the glyph on the right to copy code snippets to the clipboard ==> - -- var _package_and_config_files = _docsFor == 'dart' ? 'pubspec.yaml' : 'package definition and configuration files' - -.l-main-section#create-and-configure :marked - ## Step 1: Create and configure the project + In this step you will: + * [Create the project folder](#create-the-project-folder) + * [Create #{_package_and_config_files}](#add-config-files) + * [#{_Install} packages](#install-packages) - In this step we: - * [(a) Create the project folder](#create-the-project-folder) - * [(b) Add #{_package_and_config_files}](#add-config-files) - * [(c) #{_Install} packages](#install-packages) - - ### (a) Create the project folder +h3 Create the project folder +:marked + Using a terminal window, create a directory for the project, and change into this + directory. - var _ = _docsFor == 'dart' ? '_' : '-'; code-example(language="sh" class="code-shell"). - mkdir angular2!{_}quickstart - cd angular2!{_}quickstart + mkdir angular!{_}quickstart + cd angular!{_}quickstart -h3#add-config-files (b) Add #{_package_and_config_files} +h3#add-config-files Create #{_package_and_config_files} block package-and-config-files - var _tsconfigUri = 'guide/typescript-configuration.html#tsconfig' - - var _typingsUri = 'guide/typescript-configuration.html#typings' - p Add the following package definition and configuration files to the project folder: + p Our typical Angular project needs several configuration files: ul li. - #[b package.json] lists packages the QuickStart app depends on and - defines some useful scripts. - See #[a(href="guide/npm-packages.html") Npm Package Configuration] for details. + #[b package.json] identifies npm package dependencies for the project. li. - #[b tsconfig.json] is the TypeScript compiler configuration file. - See #[a(href="#{_tsconfigUri}") TypeScript Configuration] for details. + #[b tsconfig.json] defines how the TypeScript compiler generates JavaScript from the project's + files. li. - #[b typings.json] identifies TypeScript definition files. - See #[a(href="#{_typingsUri}") TypeScript Configuration] for details. - li. - #[b systemjs.config.js], the SystemJS configuration file. - See discussion #[a(href="#systemjs") below]. + #[b systemjs.config.js] provides information to a module loader about where to find + application modules, and registers all the necessary packages. It also + contains other packages that will be needed by later documentation examples. + + p. + Create each of these files in your project directory. Populate them by pasting in text from + the tabs in the example box below. a#config-files +makeTabs(` quickstart/ts/package.1.json, quickstart/ts/tsconfig.1.json, - quickstart/ts/typings.1.json, quickstart/ts/systemjs.config.1.js `, '', ` package.json, tsconfig.json, - typings.json, systemjs.config.js `) -h3#install-packages (c) #{_Install} packages + p. + Learn more about these configuration files in the + #[a(href="guide/npm-packages.html") Npm Package Configuration] guide and the + #[a(href="#{_tsconfigUri}") TypeScript Configuration] guide. + A detailed discussion of module loading is beyond the scope of this guide. + + .callout.is-helpful + header SystemJS or Webpack? + p. + Although we use SystemJS for illustrative purposes here, it's only one option for loading + modules. Use the module loader that you prefer. For Webpack and Angular, see + Webpack: an Introduction. Or, learn more about SystemJS configuration in general here. + + + h3#install-packages #{_Install} packages block install-packages :marked - We install the packages listed in `package.json` using `npm`. Enter the - following command in a terminal window (command window in Windows): + Using npm from the command line, install the packages listed in `package.json` with the command: code-example(language="sh" class="code-shell"). npm install - .l-sub-section - :marked - The `typings` folder could not show up after `npm install`. If so, please install them manually. + :marked + Error messages—in red—might appear during the install, and you might see `npm WARN` messages. As long as there are no `npm ERR!` messages at the end, you can assume success. - code-example(language="sh" class="code-shell"). - npm run typings install + :marked + You should now have the following structure: - .alert.is-important - :marked - Scary error messages in red may appear **during** install. - The install typically recovers from these errors and finishes successfully. - .l-verbose-section(class="l-verbose-inherit") - :marked - #### npm errors and warnings - - All is well if there are no console messages starting with `npm ERR!` *at the end* of **npm install**. - There might be a few `npm WARN` messages along the way — and that is perfectly fine. - - We often see an `npm WARN` message after a series of `gyp ERR!` messages. - Ignore them. A package may try to recompile itself using `node-gyp`. - If the recompile fails, the package recovers (typically with a pre-built version) - and everything works. - - Just make sure there are no `npm ERR!` messages at the end of `npm install`. - - .l-verbose-section - :marked - #### Adding the libraries and packages we need with *npm* - Angular application developers rely on the _[npm](https://docs.npmjs.com)_ - package manager to install the libraries and packages their apps require. - The Angular team recommends the starter-set of packages specified in the - `dependencies` and `devDependencies` sections. - See the [npm packages](guide/npm-packages.html) chapter for details. - - #### Helpful scripts - We've included a number of npm scripts in our suggested `package.json` to handle common development tasks: - +makeJson('quickstart/ts/package.1.json',{ paths: 'scripts'}, 'package.json (scripts)')(format=".") - - :marked - We execute most npm scripts in the following way: `npm run` followed by a *script-name*. - Some commands (such as `start`) don't require the `run` keyword. - - Here's what these scripts do: - - * `npm start` - runs the compiler and a server at the same time, both in "watch mode" - - * `npm run tsc` - runs the TypeScript compiler once - - * `npm run tsc:w` - runs the TypeScript compiler in watch mode; - the process keeps running, awaiting changes to TypeScript files and recompiling when it sees them - - * `npm run lite` - runs the lite-server, - a light-weight, static file server with excellent support for Angular apps that use routing - - * `npm run typings` - runs the [*typings* tool](#{_typingsUri}) separately - - * `npm run postinstall` - called by *npm* automatically *after* it successfully completes package installation. - This script installs the [TypeScript definition files](#{_typingsUri}) defined in `typings.json` + .filetree + .file angular-quickstart + .children + .file node_modules ... + .file package.json + .file systemjs.config.js + .file tsconfig.json :marked - **We're all set.** Let's write some code. + You're now ready to write some code! -.l-main-section#root-component +.l-main-section +h2#ngmodule Step 2: Create your application + +block create-your-app + :marked + You compose Angular applications into closely related blocks of functionality with + [NgModules](guide/ngmodule.html). Angular itself is split into separate Angular Modules. This + makes it possible for you to keep payload size small by only importing the parts of Angular + that your application needs. + + Every Angular application has at least one module: the _root module_, named `AppModule` here. :marked - ## Step 2: Our first Angular component - - Let's create a folder to hold our application and add a super-simple Angular component. - **Create #{_an} #{_appDir} subfolder** off the project root directory: -code-example. +code-example.code-shell. mkdir #{_appDir} -a#app-component -p. - #[b Create the component file] - #[code #[+adjExPath('app/app.component.ts')]] (in this newly created directory) with the following content: ++ifDocsFor('ts') + :marked + Create the file `app/app.module.ts` with the following content: + + +makeExample('app/app.module.1.ts')(format='.') + + :marked + This is the entry point to your application. + + Since the QuickStart application is a web application that runs in a browser, your root module + needs to import the + [`BrowserModule`](../latest/api/platform-browser/index/BrowserModule-class.html) + from `@angular/platform-browser` to the `imports` array. + + This is the smallest amount of Angular that is needed for a minimal application to run in the + browser. + + The QuickStart application doesn't do anything else, so you don't need any other modules. In a real + application, you'd likely import [`FormsModule`](../latest/api/forms/index/FormsModule-class.html) + as well as [`RouterModule`](../latest/api/router/index/RouterModule-class.html) and + [`HttpModule`](../latest/api/http/index/HttpModule-class.html). These are introduced in the + [Tour of Heroes Tutorial](./tutorial/). + + .l-main-section + h2#root-component Step 3: Create a component and add it to your application + +:marked + Every Angular application has at least one component: the _root component_, named `AppComponent` + here. + + Components are the basic building blocks of Angular applications. A component controls a portion + of the screen—a *view*—through its associated template. + +#app-component +:marked + **Create the component file** app/app.component.ts with the following content: +makeExample('app/app.component.ts') -.l-verbose-section - :marked - ### AppComponent is the root of the application - - Every Angular app has at least one **root component**, conventionally named `AppComponent`, - that hosts the client user experience. - Components are the basic building blocks of Angular applications. - A component controls a portion of the screen — a *view* — through its associated template. - - This QuickStart has only one, extremely simple component. - But it has the essential structure of every component we'll ever write: - - * One or more [import](#component-import) - statements to reference the things we need. - * A [@Component #{_decorator}](#component-decorator) - that tells Angular what template to use and how to create the component. - * A [component class](#component-class) - that controls the appearance and behavior of a view through its template. - - a#component-import - :marked - ### Import - - Angular apps are modular. They consist of many files each dedicated to a purpose. - Angular itself is modular. It is a collection of library modules - each made up of several, related features that we'll use to build our application. - - When we need something from a module or library, we import it. - Here we import the Angular core so that our component code can have access to - the `@Component` #{_decorator}. - - +makeExcerpt('app/app.component.ts', 'import') - - h3#component-decorator @Component #{_decorator} - +ifDocsFor('ts') - :marked - `Component` is a *decorator function* that takes a *metadata object* as argument. - We apply this function to the component class by prefixing the function with the - **@** symbol and invoking it with a metadata object, just above the class. - :marked - `@Component` is #{_a} *#{_decorator}* that allows us to associate *metadata* with the - component class. - The metadata tells Angular how to create and use this component. - - +makeExcerpt('app/app.component.ts', 'metadata') - - block annotation-fields - :marked - This particular metadata object has two fields, a `selector` and a `template`. - :marked - The **selector** specifies a simple CSS selector for an HTML element that represents the component. - - >The element for this component is named `my-app`. - Angular creates and displays an instance of our `AppComponent` - wherever it encounters a `my-app` element in the host HTML. - - The **template** specifies the component's companion template, - written in an enhanced form of HTML that tells Angular how to render this component's view. - - >Our template is a single line of HTML announcing "Hello Angular!". - - >A more advanced template could contain data bindings to component properties - and might identify other application components which have their own templates. - These templates might identify yet other components. - In this way an Angular application becomes a tree of components. - - :marked - ### Component class - At the bottom of the file is an empty, do-nothing class named `AppComponent`. - +makeExcerpt('app/app.component.ts', 'class') - :marked - When we're ready to build a substantive application, - we can expand this class with properties and application logic. - Our `AppComponent` class is empty because we don't need it to do anything in this QuickStart. - +ifDocsFor('ts') - :marked - We **export** `AppComponent` so that we can **import** it elsewhere in our application, - as we'll see when we create `app.module.ts`. +- var _decorator_function = _docsFor == 'dart' ? 'annotation' : 'decorator function'; +:marked + The QuickStart application has the same essential structure as any other Angular component: + * **An import statement**. Importing gives your component access to + Angular's core [`@Component` !{_decorator_function}](./api/core/index/Component-decorator.html). + * **A @Component #{_decorator}** that associates *metadata* with the + `AppComponent` component class: + + - a *selector* that specifies a simple CSS selector for an HTML element that represents + the component. + - a *template* that tells Angular how to render the component's view. + * **A component class** that controls the appearance and behavior of a view + through its template. Here, you only have the root component, `AppComponent`. Since you don't + need any application logic in the simple QuickStart example, it's empty. +ifDocsFor('ts') - .l-main-section#ngmodule :marked - ## Step 3: Our own `app.module.ts` + You *export* the `AppComponent` class so that you can *import* it into the application that you + just created. - We compose Angular apps into closely related blocks of functionality with [Angular Modules](guide/ngmodule.html). - Every app requires at least one module, the _root module_, that we call `AppModule` by convention. + Edit the file `app/app.module.ts` to import your new `AppComponent` and add it in the + declarations and bootstrap fields in the `NgModule` decorator: - Create the file `app/app.module.ts` with the following content: - - +makeExample('app/app.module.ts')(format='.') - - .l-verbose-section - :marked - We're passing metadata to the `NgModule` decorator function: - - 1. `imports` - the _other_ modules that export material we need in _this_ module. - Almost every application's _root module_ should import the `BrowserModule`. - - 1. `declarations` - components and directives that belong to _this_ module. - - 1. `bootstrap` - identifies the _root component_ that Angular should _bootstrap_ when it starts the application. - - We import our lone `app.component.ts` and add it to both the `declarations` and `bootstrap` arrays. - - ### Angular Modules import other modules - Notice that we also add the `BrowserModule` from `@angular/platform-browser` to the `imports` array. - This is the Angular Module that contains all the needed Angular bits and pieces to run our app in the browser. - - Angular itself is split into separate Angular Modules so we only need to import the ones we really use. - - One of the most common ones is `FormsModule`, and soon we'll also see `RouterModule` and `HttpModule`. + +makeExample('app/app.module.ts') .l-main-section -h2#main Step !{step++}: Add #[code #[+adjExPath('main.ts')]] +h2#main Step !{step++}: Start up your application block create-main :marked - Now we need something to tell Angular to load the app module. + Now you need to tell Angular to start up your application. + Create the file `app/main.ts` with the following content: +makeExample('app/main.ts') + - var _pBD_bootstrapModule = _docsFor == 'dart' ? _bootstrapModule : 'platformBrowserDynamic().bootstrapModule' -.l-verbose-section + +:marked + This code initializes the platform that your application runs in, then uses the platform to + bootstrap your `!{_AppModuleVsAppComp}`. + + ### Why create separate *main.ts*, app module and app component files? + + App bootstrapping is a separate concern from creating a module or + presenting a view. Testing the component is much easier if it doesn't also try to run the entire application. + + +.callout.is-helpful + header Bootstrapping is platform-specific + :marked - We import the two things we need to launch the application: - - 1. Angular's browser `!{_platformBrowserDynamicVsBootStrap}` function - 1. The application !{_moduleVsRootComp}, `!{_AppModuleVsAppComp}`. - - Then we call `!{_pBD_bootstrapModule}` with `!{_AppModuleVsAppComp}`. - - ### Bootstrapping is platform-specific - - Notice that we import the `!{_platformBrowserDynamicVsBootStrap}` function - from `#{_angular_browser_uri}`, not `#{_angular_core_uri}`. - Bootstrapping isn't core because there isn't a single way to bootstrap the app. - True, most applications that run in a browser call the bootstrap function from - this library. - - But it is possible to load a !{_moduleVsComp} in a different environment. - We might load it on a mobile device with [Apache Cordova](https://cordova.apache.org/) or [NativeScript](https://www.nativescript.org/). - We might wish to render the first page of our application on the server - to improve launch performance or facilitate - [SEO](http://www.google.com/webmasters/docs/search-engine-optimization-starter-guide.pdf). - These targets require a different kind of bootstrap function that we'd import from a different library. - - ### Why create separate *main.ts*, app module and app component files? - - Then main.ts, app module - and the app component files are tiny. - This is just a QuickStart. - We could have merged these files into one and spared ourselves some complexity. - - We'd rather demonstrate the proper way to structure an Angular application. - App bootstrapping is a separate concern from creating a module or - presenting a view. - Mixing concerns creates difficulties down the road. - We might launch the `!{_AppModuleVsAppComp}` in multiple environments with different bootstrappers. - Testing the component is much easier if it doesn't also try to run the entire application. - Let's make the small extra effort to do it *the right way*. + Because the QuickStart application runs directly in the browser, `main.ts` imports the + `!{_platformBrowserDynamicVsBootStrap}` function from `#{_angular_browser_uri}`, not + `#{_angular_core_uri}`. On a mobile device, you might load a !{_moduleVsComp} with + [Apache Cordova](https://cordova.apache.org/) or + [NativeScript](https://www.nativescript.org/), using a bootstrap function that's specific + to that platform. .l-main-section -h2#index Step !{step++}: Add #[code index.html] +h2#index Step !{step++}: Define the web page that hosts the application :marked - In the *#{_indexHtmlDir}* folder + In the *#{_indexHtmlDir}* folder, create an `index.html` file and paste the following lines into it: +makeExample('index.html') -.l-verbose-section + +block commentary-on-index-html :marked - The `index.html` file defines the web page that hosts the application. + The noteworthy sections here are: - +ifDocsFor('ts') - :marked - The noteworthy sections of HTML are: + * JavaScript libraries: `core-js` polyfills for older browsers, the `zone.js` and + `reflect-metadata` libraries needed by Angular, and the `SystemJS` library for module loading. + * Configuration file for `SystemJS`, and a script + where you import and run the `app` module which refers to the `main` file that you just + wrote. + * The `` tag in the `` which is *where your app lives!* - 1. The JavaScript [libraries](#libraries) - 2. Configuration file for [SystemJS](#systemjs), and a script - where we import and run the `app` module which refers to the `main` file that we just wrote. - 3. The [``](#my-app) tag in the `` which is *where our app lives!* - - :marked - ### Libraries - We loaded the following scripts - +makeExcerpt('index.html', 'libraries') - :marked - We begin with `core-js`'s ES2015/ES6 shim which monkey patches the global context (window) with essential features of ES2015 (ES6). - Next are the polyfills for Angular2, `zone.js` and `reflect-metadata`. - Then the [SystemJS](#systemjs) library for module loading. - - We'll make different choices as we gain experience and - become more concerned about production qualities such as - load times and memory footprint. - - h3#systemjs SystemJS - :marked - QuickStart uses SystemJS - to load application and library modules. [Earlier](#add-config-files) we - added the `systemjs.config.js` file to the project root. - There are alternatives that work just fine including the well-regarded - [webpack](guide/webpack.html). - SystemJS happens to be a good choice. - But we want to be clear that it was a *choice* and not a *preference*. - - All module loaders require configuration and all loader configuration - becomes complicated rather quickly as soon as the file structure diversifies and - we start thinking about building for production and performance. - - We suggest becoming well-versed in the loader of your choice. - Learn more about SystemJS configuration - here. - - With those cautions in mind, what are we doing in the - QuickStart [`systemjs.config.js` configuration file we added earlier](#config-files)? - First, we create a map to tell SystemJS where to look when we import some module. - Then, we register all our packages to SystemJS: - all the project dependencies and our application package, `app`. - - .l-sub-section - :marked - Our QuickStart doesn't use all of the listed packages - but any substantial application will want many of them - and all of the listed packages are required by at least one of the documentation samples. - - There is no runtime harm in listing packages that we don't need as they will only be loaded when requested. - :marked - The `app` package tells SystemJS what to do when it sees a request for a - module from the `app/` folder. - - Our QuickStart makes such requests when one of its - application TypeScript files has an import statement like this: - +makeExcerpt('app/main.ts', 'import') - :marked - Notice that the module name (after `from`) does not mention a filename extension. - In the configuration we tell SystemJS to default the extension to `js`, a JavaScript file. - - That makes sense because we transpile TypeScript to JavaScript - *before* running the application. - - .l-sub-section - :marked - #### Transpiling in the browser - In the live example on plunker we transpile (AKA compile) to JavaScript in the browser - on the fly. _That's fine for a demo_. - - **Do not transpile in the browser during development or for production**. - - We strongly recommend transpiling (AKA compiling) to JavaScript during a build phase - before running the application for several reasons including: - - * We see compiler warnings and errors that are hidden from us in the browser. - - * Precompilation simplifies the module loading process and - it's much easier to diagnose problems when this is a separate, external step. - - * Precompilation means a faster user experience because the browser doesn't waste time compiling. - - * We iterate development faster because we only recompile changed files. - We notice the difference as soon as the app grows beyond a handful of files. - - * Precompilation fits into a continuous integration process of build, test, deploy. - - :marked - The `System.import` call tells SystemJS to import the `main` file - (`main.js` ... after transpiling `main.ts`, remember?); - `main` is where we tell Angular to launch the application. - We also catch and log launch errors to the console. - - All other modules are loaded upon request - either by an import statement or by Angular itself. - - ### *<my-app>* - - a#my-app - :marked - When Angular calls the `!{_bootstrapModule}` function in main.ts, - it reads the `!{_AppModuleVsAppComp}` metadata, sees that - `AppComponent` is the bootstrap component, - finds the `my-app` selector, locates an element tag named `my-app`, - and renders our application's view between those tags. :marked ### Add some style - Styles aren't essential but they're nice, and `index.html` assumes we have + + Styles aren't essential, but they're nice, and `index.html` assumes that you have a stylesheet called `styles.css`. - Create a `styles.css` file in the *#{_indexHtmlDir}* folder and start styling, + Create a `styles.css` file in the *#{_indexHtmlDir}* folder, and start styling, perhaps with the minimal styles shown below. +makeExcerpt('styles.css (excerpt)', 'quickstart') @@ -527,53 +300,54 @@ h2#index Step !{step++}: Add #[code index.html] .callout.is-helpful :marked For the full set of master styles used by the documentation samples, - see [styles.css](https://github.com/angular/angular.io/blob/master/public/docs/_examples/styles.css). + see [styles.css](https://github.com/angular/angular.io/blob/master/public/docs/_examples/_boilerplate/styles.css). .l-main-section#build-and-run -h2 Step !{step++}: Build and run the app! +h2 Step !{step++}: Build and run the application block run-app :marked Open a terminal window and enter this command: - code-example. + code-example.code-shell. npm start - :marked - That command runs two parallel node processes - 1. The TypeScript compiler in watch mode - 1. A static server called **lite-server** that loads `index.html` in a browser - and refreshes the browser when application files change + aside.is-right + :marked + [Read more](https://github.com/angular/quickstart/blob/master/README.md#npm-scripts) about + other useful npm scripts included in this example's `package.json`. - In a few moments, a browser tab should open and display + :marked + That command runs the following two parallel node processes: + * The TypeScript compiler in watch mode. + * A static file server called _lite-server_ that loads `index.html` in a browser + and refreshes the browser when application files change. + + In a few moments, a browser tab should open and display the following: figure.image-display img(src='/resources/images/devguide/quickstart/hello-angular.png' alt="Output of QuickStart app") -:marked - **Great job!** block build-app //- Nothing for ts. +.l-main-section#make-changes +h2 Step !{step++}: Make some live changes :marked - ## Make some changes + Try changing the message in app/app.component.ts to "Hello Again Angular!". - Try changing the message to "Hello Again Angular!". block server-watching :marked - The TypeScript compiler and `lite-server` are watching. - They should detect the change, recompile the TypeScript into JavaScript, - refresh the browser, and display the revised message. - It's a nifty way to develop an application! + The TypeScript compiler and `lite-server` will detect your change, recompile the TypeScript into JavaScript, + refresh the browser, and display your revised message. - We close the terminal window when we're done to terminate both the compiler and the server. + Close the terminal window when you're done to terminate both the compiler and the server. .l-main-section +h2#wrap-up Wrap up and next steps :marked - # Wrap up - - Our final project folder structure looks like this: + The final project folder structure looks like this: block project-file-structure .filetree - .file angular2-quickstart + .file angular-quickstart .children .file app .children @@ -587,46 +361,22 @@ block project-file-structure .file systemjs.config.js .file tsconfig.json :marked - Here are the file contents: - -block project-files - +makeTabs(` - quickstart/ts/app/app.component.ts, - quickstart/ts/app/app.module.ts, - quickstart/ts/app/main.ts, - quickstart/ts/index.html, - quickstart/ts/package.1.json, - quickstart/ts/tsconfig.1.json, - quickstart/ts/styles.css, - quickstart/ts/systemjs.config.1.js` - , - ',,,,,,, quickstart,', - `app/app.component.ts, - app/app.module.ts, - app/main.ts, - index.html, - package.json, - tsconfig.json, - styles.css (excerpt), - systemjs.config.js`) + To see the file contents, open the . .l-main-section :marked ## What next? - Our first application doesn't do much. It's basically "Hello, World" for Angular. + This first application doesn't do much. It's basically "Hello, World" for Angular. - We kept it simple in our first pass: we wrote a little Angular component, - created a simple `index.html`, and launched with a - static file server. That's about all we'd expect to do for a "Hello, World" app. + You wrote a little Angular component, created a simple `index.html`, and launched with a + static file server. - **We have greater ambitions!** +ifDocsFor('ts') :marked - The good news is that the overhead of setup is (mostly) behind us. - We'll probably only touch the `package.json` to update libraries. - We'll likely open `index.html` only if we need to add a library or some css stylesheets. + You also created the basic application setup that you'll re-use for other + sections in this guide. From here, the changes you'll make in the + `package.json` or `index.html` files are only minor updates to add libraries or some css + stylesheets. You also won't need to revisit module loading again. :marked - We're about to take the next step and build a small application that - demonstrates the great things we can build with Angular. - - Join us on the [Tour of Heroes Tutorial](./tutorial)! + To take the next step and build a small application that demonstrates real features that you can + build with Angular, carry on to the [Tour of Heroes tutorial](./tutorial)! diff --git a/public/docs/ts/latest/quickstart.jade b/public/docs/ts/latest/quickstart.jade index 6a5ee23076..817f34361f 100644 --- a/public/docs/ts/latest/quickstart.jade +++ b/public/docs/ts/latest/quickstart.jade @@ -4,26 +4,18 @@ block includes - var _prereq = 'Node.js and npm' - var _angular_browser_uri = '@angular/platform-browser-dynamic' - var _angular_core_uri = '@angular/core' - - var _stepInit = 3 // Step # after NgModule step + - var _stepInit = 4 // Step # after NgModule step - var _quickstartSrcURL='https://github.com/angular/quickstart/blob/master/README.md' //- TS/Dart shared step counter - var step = _stepInit -.callout.is-helpful - header Don't want #{_Lang}? - p. - Although you're getting started in #{_Lang}, you can also write Angular applications - in JavaScript and #{_docsFor == 'ts' ? 'Dart' : 'TypeScript'}. Use the language selector in the - left nav to switch development languages for this guide. -.l-main-section -h1 Overview - -aside.is-right - :marked - The live example link opens the finished application in - Plunker so that you can interact - with the code. You'll find live examples at the start of most sections. ++ifDocsFor('ts') + aside.is-right + :marked + The live example link opens the finished application in + Plunker so that you can interact + with the code. You'll find live examples at the start of most sections. :marked The QuickStart application has the structure of a real-world Angular application and @@ -35,16 +27,18 @@ figure.image-display :marked **Try it out**. Here's a link to a . - You can also - clone the entire QuickStart application from GitHub. ++ifDocsFor('ts') + :marked + You can also + clone the entire QuickStart application from GitHub. -h2 Build this application! +h1 Build this application! :marked - [Prerequisite](#prereq): Install #{_prereq}. - [Step 1](#create-and-configure): Create and configure the project. -
  • [Step 2](#ngmodule): Create your application. - - [Step !{step++}](#root-component): Create a component and add it to your application. + - [Step 2](#ngmodule): Create your application. +
  • [Step 3](#root-component): Create a component and add it to your application.
    • - [Step !{step++}](#main): Start up your application. - [Step !{step++}](#index): Define the web page that hosts the application. - [Step !{step++}](#build-and-run): Build and run the application. @@ -54,7 +48,7 @@ h2 Build this application! - var step = _stepInit // reinitialize step counter for headers to come .l-main-section#prereq -h1 Prerequisite: Install #{_prereq} +h2 Prerequisite: Install #{_prereq} block setup-tooling :marked @@ -64,7 +58,7 @@ block setup-tooling in a terminal window. .l-main-section -h1#create-and-configure Step 1: Create and configure the project +h2#create-and-configure Step 1: Create and configure the project - var _package_and_config_files = _docsFor == 'dart' ? 'pubspec.yaml' : 'configuration files' @@ -74,7 +68,7 @@ h1#create-and-configure Step 1: Create and configure the project * [Create #{_package_and_config_files}](#add-config-files) * [#{_Install} packages](#install-packages) -h2 Create the project folder +h3 Create the project folder :marked Using a terminal window, create a directory for the project, and change into this directory. @@ -84,7 +78,7 @@ code-example(language="sh" class="code-shell"). mkdir angular!{_}quickstart cd angular!{_}quickstart -h2#add-config-files Create #{_package_and_config_files} +h3#add-config-files Create #{_package_and_config_files} block package-and-config-files - var _tsconfigUri = 'guide/typescript-configuration.html#tsconfig' @@ -130,7 +124,7 @@ block package-and-config-files Webpack: an Introduction. Or, learn more about SystemJS configuration in general here. - h2#install-packages #{_Install} packages + h3#install-packages #{_Install} packages block install-packages :marked Using npm from the command line, install the packages listed in `package.json` with the command: @@ -154,9 +148,11 @@ block install-packages :marked You're now ready to write some code! -+ifDocsFor('ts') - .l-main-section - h1#ngmodule Step 2: Create your application + +.l-main-section +h2#ngmodule Step 2: Create your application + +block create-your-app :marked You compose Angular applications into closely related blocks of functionality with [NgModules](guide/ngmodule.html). Angular itself is split into separate Angular Modules. This @@ -164,12 +160,13 @@ block install-packages that your application needs. Every Angular application has at least one module: the _root module_, named `AppModule` here. +:marked + **Create #{_an} #{_appDir} subfolder** off the project root directory: - **Create #{_an} #{_appDir} subfolder** off the project root directory: - - code-example.code-shell. - mkdir #{_appDir} +code-example.code-shell. + mkdir #{_appDir} ++ifDocsFor('ts') :marked Create the file `app/app.module.ts` with the following content: @@ -192,8 +189,9 @@ block install-packages [`HttpModule`](../latest/api/http/index/HttpModule-class.html). These are introduced in the [Tour of Heroes Tutorial](./tutorial/). -.l-main-section -h1#root-component Step !{step++}: Create a component and add it to your application + .l-main-section + h2#root-component Step 3: Create a component and add it to your application + :marked Every Angular application has at least one component: the _root component_, named `AppComponent` here. @@ -201,38 +199,39 @@ h1#root-component Step !{step++}: Create a component and add it to your applicat Components are the basic building blocks of Angular applications. A component controls a portion of the screen—a *view*—through its associated template. -a#app-component -p. - #[b Create the component file] - #[code #[+adjExPath('app/app.component.ts')]] with the following content: +#app-component +:marked + **Create the component file** app/app.component.ts with the following content: +makeExample('app/app.component.ts') +- var _decorator_function = _docsFor == 'dart' ? 'annotation' : 'decorator function'; :marked The QuickStart application has the same essential structure as any other Angular component: * **An import statement**. Importing gives your component access to - Angular's core [`@Component` decorator function](../latest/api/core/index/Component-decorator.html). + Angular's core [`@Component` !{_decorator_function}](./api/core/index/Component-decorator.html). * **A @Component #{_decorator}** that associates *metadata* with the `AppComponent` component class: - - - a *selector* that specifies a simple CSS selector for an HTML element that represents - the component. - - a *template* that tells Angular how to render the component's view. + + - a *selector* that specifies a simple CSS selector for an HTML element that represents + the component. + - a *template* that tells Angular how to render the component's view. * **A component class** that controls the appearance and behavior of a view through its template. Here, you only have the root component, `AppComponent`. Since you don't need any application logic in the simple QuickStart example, it's empty. ++ifDocsFor('ts') + :marked + You *export* the `AppComponent` class so that you can *import* it into the application that you + just created. - You *export* the `AppComponent` class so that you can *import* it into the application that you - just created. + Edit the file `app/app.module.ts` to import your new `AppComponent` and add it in the + declarations and bootstrap fields in the `NgModule` decorator: - Edit the file `app/app.module.ts` to import your new `AppComponent` and add it in the - declarations and bootstrap fields in the `NgModule` decorator: - -+makeExample('app/app.module.ts', null, title='app/app.module.ts') + +makeExample('app/app.module.ts') .l-main-section -h1#main Step !{step++}: Start up your application +h2#main Step !{step++}: Start up your application block create-main :marked @@ -267,7 +266,7 @@ block create-main to that platform. .l-main-section -h1#index Step !{step++}: Define the web page that hosts the application +h2#index Step !{step++}: Define the web page that hosts the application :marked In the *#{_indexHtmlDir}* folder, create an `index.html` file and paste the following lines into it: @@ -275,20 +274,21 @@ h1#index Step !{step++}: Define the web page that hosts the application +makeExample('index.html') -+ifDocsFor('ts') -:marked - The noteworthy sections here are: +block commentary-on-index-html + :marked + The noteworthy sections here are: - * JavaScript libraries: `core-js` polyfills for older browsers, the `zone.js` and - `reflect-metadata` libraries needed by Angular, and the `SystemJS` library for module loading. - * Configuration file for `SystemJS`, and a script - where you import and run the `app` module which refers to the `main` file that you just - wrote. - * The [``](#my-app) tag in the `` which is *where your app lives!* + * JavaScript libraries: `core-js` polyfills for older browsers, the `zone.js` and + `reflect-metadata` libraries needed by Angular, and the `SystemJS` library for module loading. + * Configuration file for `SystemJS`, and a script + where you import and run the `app` module which refers to the `main` file that you just + wrote. + * The `` tag in the `` which is *where your app lives!* :marked - ## Add some style + ### Add some style + Styles aren't essential, but they're nice, and `index.html` assumes that you have a stylesheet called `styles.css`. @@ -303,24 +303,24 @@ h1#index Step !{step++}: Define the web page that hosts the application see [styles.css](https://github.com/angular/angular.io/blob/master/public/docs/_examples/_boilerplate/styles.css). .l-main-section#build-and-run -h1 Step !{step++}: Build and run the application +h2 Step !{step++}: Build and run the application block run-app :marked Open a terminal window and enter this command: code-example.code-shell. npm start -aside.is-right + aside.is-right + :marked + [Read more](https://github.com/angular/quickstart/blob/master/README.md#npm-scripts) about + other useful npm scripts included in this example's `package.json`. + :marked - [Read more](https://github.com/angular/quickstart/blob/master/README.md#npm-scripts) about - other useful npm scripts included in this example's `package.json`. + That command runs the following two parallel node processes: + * The TypeScript compiler in watch mode. + * A static file server called _lite-server_ that loads `index.html` in a browser + and refreshes the browser when application files change. -:marked - That command runs the following two parallel node processes: - * The TypeScript compiler in watch mode. - * A static file server called _lite-server_ that loads `index.html` in a browser - and refreshes the browser when application files change. - - In a few moments, a browser tab should open and display the following: + In a few moments, a browser tab should open and display the following: figure.image-display img(src='/resources/images/devguide/quickstart/hello-angular.png' alt="Output of QuickStart app") @@ -330,19 +330,19 @@ block build-app //- Nothing for ts. .l-main-section#make-changes -h1 Step !{step++}: Make some live changes +h2 Step !{step++}: Make some live changes :marked - Try changing the message in `app/app.component.ts` to "Hello Again Angular!". + Try changing the message in app/app.component.ts to "Hello Again Angular!". + block server-watching :marked The TypeScript compiler and `lite-server` will detect your change, recompile the TypeScript into JavaScript, refresh the browser, and display your revised message. - Close the terminal window when you're done to terminate both the compiler and the server. .l-main-section -h1#wrap-up Wrap up and next steps +h2#wrap-up Wrap up and next steps :marked The final project folder structure looks like this: block project-file-structure