From bc83a75469b7a830b37629b2f36bb785c9b518f5 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Wed, 10 Aug 2016 08:05:15 -0700 Subject: [PATCH 1/2] docs(quickstart): post-RC5 Dart resync - Resync Dart QS prose with TS, post RC5. - Added to-be-shared Jade `var` definitions to `_util-fns.jade`. - Delete cached QS jade file. - Eliminate the stub file `styles.1.css` in favor of a `docregion` in the main `styles.css`. This commit requires a `gulp add-example-boilerplate` after pulling it in. Contributes to #2077. --- public/_includes/_util-fns.jade | 9 + .../quickstart/dart/web/styles_1.css | 14 - .../docs/_examples/quickstart/ts/styles.1.css | 14 - public/docs/_examples/styles.css | 2 + public/docs/dart/latest/_util-fns.jade | 9 + public/docs/dart/latest/quickstart.jade | 35 +- public/docs/ts/_cache/quickstart.jade | 582 ------------------ public/docs/ts/latest/quickstart.jade | 154 ++--- 8 files changed, 120 insertions(+), 699 deletions(-) delete mode 100644 public/docs/_examples/quickstart/dart/web/styles_1.css delete mode 100644 public/docs/_examples/quickstart/ts/styles.1.css delete mode 100644 public/docs/ts/_cache/quickstart.jade diff --git a/public/_includes/_util-fns.jade b/public/_includes/_util-fns.jade index 152fbe4bfd..c36f405145 100644 --- a/public/_includes/_util-fns.jade +++ b/public/_includes/_util-fns.jade @@ -38,6 +38,15 @@ //- Location of sample code - var _liveLink = 'live link'; +//- NgModule related +- var _AppModuleVsAppComp = 'AppModule' +- var _appModuleTsVsAppCompTs = 'app/app.module.ts' +- var _appModuleTsVsMainTs = 'app/app.module.ts' +- var _bootstrapModule = 'bootstrapModule' +- var _moduleVsComp = 'module' +- var _moduleVsRootComp = 'module' +- var _platformBrowserDynamicVsBootStrap = 'platformBrowserDynamic' + //- Other - var _truthy = 'truthy'; - var _falsey = 'falsey'; diff --git a/public/docs/_examples/quickstart/dart/web/styles_1.css b/public/docs/_examples/quickstart/dart/web/styles_1.css deleted file mode 100644 index 27e60d67c0..0000000000 --- a/public/docs/_examples/quickstart/dart/web/styles_1.css +++ /dev/null @@ -1,14 +0,0 @@ -/* #docregion */ -h1 { - color: #369; - font-family: Arial, Helvetica, sans-serif; - font-size: 250%; -} -body { - margin: 2em; -} - -/* -* See https://github.com/angular/angular.io/blob/master/public/docs/_examples/styles.css -* for the full set of master styles used by the documentation samples -*/ diff --git a/public/docs/_examples/quickstart/ts/styles.1.css b/public/docs/_examples/quickstart/ts/styles.1.css deleted file mode 100644 index fbc30e2c9e..0000000000 --- a/public/docs/_examples/quickstart/ts/styles.1.css +++ /dev/null @@ -1,14 +0,0 @@ -/* #docregion */ -h1 { - color: #369; - font-family: Arial, Helvetica, sans-serif; - font-size: 250%; -} -body { - margin: 2em; -} - - /* - * See https://github.com/angular/angular.io/blob/master/public/docs/_examples/styles.css - * for the full set of master styles used by the documentation samples - */ diff --git a/public/docs/_examples/styles.css b/public/docs/_examples/styles.css index 62ddfa5121..002017d4bd 100644 --- a/public/docs/_examples/styles.css +++ b/public/docs/_examples/styles.css @@ -1,3 +1,4 @@ +/* #docregion , quickstart */ /* Master Styles */ h1 { color: #369; @@ -12,6 +13,7 @@ h2, h3 { body { margin: 2em; } +/* #enddocregion quickstart */ body, input[text], button { color: #888; font-family: Cambria, Georgia; diff --git a/public/docs/dart/latest/_util-fns.jade b/public/docs/dart/latest/_util-fns.jade index cc59d49fb5..e4839cc688 100644 --- a/public/docs/dart/latest/_util-fns.jade +++ b/public/docs/dart/latest/_util-fns.jade @@ -20,6 +20,15 @@ include ../../../_includes/_util-fns - var _indexHtmlDir = 'web'; - var _mainDir = 'web'; +//- NgModule related +- var _AppModuleVsAppComp = 'AppComponent' +- var _appModuleTsVsAppCompTs = 'app/app_component.dart' +- var _appModuleTsVsMainTs = 'web/main.dart' +- var _bootstrapModule = 'bootstrap' +- var _moduleVsComp = 'component' +- var _moduleVsRootComp = 'root component' +- var _platformBrowserDynamicVsBootStrap = 'bootstrap' + //- Deprecated mixin liveExampleLink(linkText, exampleUrlPartName) - var text = linkText || 'live example'; diff --git a/public/docs/dart/latest/quickstart.jade b/public/docs/dart/latest/quickstart.jade index 8126efc8dc..0150a9a70d 100644 --- a/public/docs/dart/latest/quickstart.jade +++ b/public/docs/dart/latest/quickstart.jade @@ -1,11 +1,13 @@ -extends ../../ts/_cache/quickstart.jade +extends ../../ts/latest/quickstart.jade block includes include _util-fns - var _Install = 'Get' - var _prereq = 'the Dart SDK' - - var _angular_browser_uri = 'package:angular2/platform/browser.dart' - - var _angular_core_uri = 'package:angular2/core.dart' + - var _angular_browser_uri = 'angular2/platform/browser.dart' + - var _angular_core_uri = 'angular2/core.dart' + - var _stepInit = 3 + - var _quickstartSrcURL='https://github.com/angular-examples/quickstart' block setup-tooling :marked @@ -20,9 +22,6 @@ block setup-tooling [DT]: https://www.dartlang.org/tools/ [pub]: https://www.dartlang.org/tools/pub/ -block download-source - // exclude this section from Dart - block package-and-config-files :marked In the project folder just created, create a file named @@ -59,9 +58,6 @@ block create-main li a #[b folder named #[code web]] li a file named #[code #[+adjExPath('app/main.ts')]] with the following content: -block index-html-commentary-for-ts - //- N/A - block run-app p. We have a few options for running our app. @@ -87,10 +83,10 @@ block build-app in the [proper folders](#wrap-up), and run `pub get`. - .l-verbose-section - h3#section-angular-run-app Building the app (generating JavaScript) - + .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. @@ -98,11 +94,12 @@ block build-app > pub build Loading source assets... - p. + :marked The generated JavaScript appears, along with supporting files, - under a directory named build. + under a directory named `build`. - h4#angular_transformer Using the Angular transformer + #angular_transformer + h4 Using the Angular transformer p. When generating JavaScript for an Angular app, @@ -124,7 +121,7 @@ block build-app Angular transformer wiki page. - #performance.l-sub-section + .l-sub-section#performance h3 Performance, the transformer, and Angular 2 libraries p. When an app imports bootstrap.dart, @@ -136,7 +133,8 @@ block build-app (entry_points in pubspec.yaml) so that they don't use mirrors. - h4#dart_to_js_script_rewriter Using dart_to_js_script_rewriter + #dart_to_js_script_rewriter + h4 Using dart_to_js_script_rewriter :marked To improve the app's performance, convert the @@ -203,6 +201,3 @@ block project-files index.html, pubspec.yaml, styles.css`) - -block what-next-ts-overhead - //- N/A diff --git a/public/docs/ts/_cache/quickstart.jade b/public/docs/ts/_cache/quickstart.jade deleted file mode 100644 index 5de3efe99c..0000000000 --- a/public/docs/ts/_cache/quickstart.jade +++ /dev/null @@ -1,582 +0,0 @@ -block includes - include _util-fns - - var _Install = 'Install' - - var _prereq = 'Node.js' - - var _angular_browser_uri = '@angular/platform-browser-dynamic' - - var _angular_core_uri = '@angular/core' - -:marked - Our QuickStart goal is to build and run a super-simple - Angular 2 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 2 apps - in #{_docsFor == 'ts' ? 'Dart' : 'TypeScript'} and JavaScript. - Just select either of those languages from the combo-box in the banner. - -:marked - # Try it! - - Try the which loads the sample app - - in plunker - - and displays the simple message: - -figure.image-display - img(src='/resources/images/devguide/quickstart/my-first-app.png' alt="Output of QuickStart app") - -:marked - # Build this app! - - - [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](#main): Add main.ts, identifying the root component to Angular - - [Step 4](#index): Add `index.html`, the web page that hosts the application - - [Step 5](#build-and-run): Build and run the app - - [Make some changes to the app](#make-some-changes) - - [Wrap up](#wrap-up) - -.l-main-section -h2#prereq Prerequisite: #{_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. - -block download-source - .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](https://github.com/angular/quickstart/blob/master/README.md) - from github and follow its brief instructions. - -.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. - - 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 ==> - -.l-main-section -h2#create-and-configure Step 1: Create and configure the project - -- var _package_and_config_files = _docsFor == 'dart' ? 'pubspec.yaml' : 'package definition and configuration files' - -:marked - 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) - -h3 (a) Create the project folder - -- var _ = _docsFor == 'dart' ? '_' : '-'; -code-example(language="sh"). - mkdir angular2!{_}quickstart - cd angular2!{_}quickstart - -h3#add-config-files (b) Add #{_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: - 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. - li. - #[b tsconfig.json] is the TypeScript compiler configuration file. - See #[a(href="#{_tsconfigUri}") TypeScript Configuration] for details. - 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]. - - 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 -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): - - code-example(language="sh"). - npm install - - .l-sub-section - :marked - The `typings` folder could not show up after `npm install`. If so, please install them manually. - - code-example(language="sh"). - npm run typings install - - .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` - -:marked - **We're all set.** Let's write some code. - -.l-main-section -h2#root-component Step 2: Our first Angular component -:marked - 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. - 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: - -+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 2 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 "*My First Angular 2 App*". - - >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 `main.ts`. - -.l-main-section -h2#main Step 3: Add #[code #[+adjExPath('main.ts')]] - -block create-main - p. - Now we need something to tell Angular to load the root component. - Create the file #[code #[+adjExPath('app/main.ts')]] with the following content: - -+makeExample('app/main.ts') - -.l-verbose-section - :marked - We import the two things we need to launch the application: - - 1. Angular's browser `bootstrap` function - 1. The application root component, `AppComponent`. - - Then we call `bootstrap` with `AppComponent`. - - ### Bootstrapping is platform-specific - Notice that we import the `bootstrap` 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 component 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* and app component files? - - Both main.ts and the app component files are tiny. - This is just a QuickStart. - We could have merged these two 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 presenting a view. - Mixing concerns creates difficulties down the road. - We might launch the `AppComponent` 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*. - -.l-main-section -h2#index Step 4: Add #[code index.html] -:marked - In the *#{_indexHtmlDir}* folder - create an `index.html` file and paste the following lines into it: - -+makeExample('index.html') - -.l-verbose-section - :marked - The `index.html` file defines the web page that hosts the application. - - block index-html-commentary-for-ts - :marked - The noteworthy sections of HTML are: - - 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(id="my-app") - :marked - When Angular calls the `bootstrap` function in main.ts, it reads the `AppComponent` - metadata, 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 - a stylesheet called `styles.css`. - - Create a `styles.css` file in the *#{_indexHtmlDir}* folder and start styling, perhaps with the minimal - styles shown below. 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). -+makeExcerpt('styles.1.css') - -.l-main-section -h2#build-and-run Step 5: Build and run the app! -block run-app - :marked - Open a terminal window and enter this command: - code-example. - 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 - - In a few moments, a browser tab should open and display - -figure.image-display - img(src='/resources/images/devguide/quickstart/my-first-app.png' alt="Output of QuickStart app") - -:marked - **Great job!** - -block build-app - //- Nothing for ts. - -:marked - ## Make some changes - - Try changing the message to "My SECOND Angular 2 app". -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! - - We close the terminal window when we're done to terminate both the compiler and the server. - -.l-main-section -:marked - # Wrap up - - Our final project folder structure looks like this: -block project-file-structure - .filetree - .file angular2-quickstart - .children - .file app - .children - .file app.component.ts - .file main.ts - .file node_modules ... - .file typings ... - .file index.html - .file package.json - .file styles.css - .file systemjs.config.js - .file tsconfig.json - .file typings.json -:marked - Here are the file contents: - -block project-files - +makeTabs(` - quickstart/ts/app/app.component.ts, - quickstart/ts/app/main.ts, - quickstart/ts/index.html, - quickstart/ts/package.1.json, - quickstart/ts/tsconfig.1.json, - quickstart/ts/typings.1.json, - quickstart/ts/styles.1.css, - quickstart/ts/systemjs.config.1.js` - ,null, - `app/app.component.ts, - app/main.ts, - index.html, - package.json, - tsconfig.json, - typings.json, - styles.css, - systemjs.config.js`) - -.l-main-section -:marked - ## What next? - Our first application doesn't do much. It's basically "Hello, World" for Angular 2. - - 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. - - **We have greater ambitions!** -block what-next-ts-overhead - :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. -:marked - We're about to take the next step and build a small application that - demonstrates the great things we can build with Angular 2. - - Join us on the [Tour of Heroes Tutorial](./tutorial)! diff --git a/public/docs/ts/latest/quickstart.jade b/public/docs/ts/latest/quickstart.jade index 5cdbb93200..08a4e9e781 100644 --- a/public/docs/ts/latest/quickstart.jade +++ b/public/docs/ts/latest/quickstart.jade @@ -4,6 +4,11 @@ block includes - var _prereq = 'Node.js' - var _angular_browser_uri = '@angular/platform-browser-dynamic' - var _angular_core_uri = '@angular/core' + - 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 :marked Our QuickStart goal is to build and run a super-simple @@ -37,15 +42,16 @@ figure.image-display - [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 4](#main): Add main.ts, identifying the root component to Angular - - [Step 5](#index): Add `index.html`, the web page that hosts the application - - [Step 6](#build-and-run): Build and run the app +
  • [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) -.l-main-section -h2#prereq Prerequisite: #{_prereq} +- var step = _stepInit // reinitialize step counter for headers to come +.l-main-section#prereq +h2 Prerequisite: #{_prereq} block setup-tooling :marked @@ -57,14 +63,13 @@ block setup-tooling by running `node -v` and `npm -v` in a terminal/console window. Older versions produce errors. -block download-source - .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](https://github.com/angular/quickstart/blob/master/README.md) - from github and follow its brief instructions. +.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. .l-main-section button(class="verbose off md-primary md-button md-ink-ripple", type="button", onclick="verbose(false)"). @@ -85,18 +90,18 @@ button(class="verbose on md-primary md-button md-ink-ripple", type="button", onc code-example(format="nocode"). Click the glyph on the right to copy code snippets to the clipboard ==> -.l-main-section -h2#create-and-configure Step 1: Create and configure the project - - 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 we: * [(a) Create the project folder](#create-the-project-folder) * [(b) Add #{_package_and_config_files}](#add-config-files) * [(c) #{_Install} packages](#install-packages) -h3 (a) Create the project folder + ### (a) Create the project folder - var _ = _docsFor == 'dart' ? '_' : '-'; code-example(language="sh"). @@ -208,9 +213,10 @@ block install-packages :marked **We're all set.** Let's write some code. -.l-main-section -h2#root-component Step 2: Our first Angular component +.l-main-section#root-component :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: @@ -304,87 +310,91 @@ p. We **export** `AppComponent` so that we can **import** it elsewhere in our application, as we'll see when we create `app.module.ts`. -.l-main-section -h2#ngmodule Step 3: Our own #[code #[+adjExPath('app.module.ts')]] - -block create-ngmodule ++ifDocsFor('ts') + .l-main-section#ngmodule :marked + ## Step 3: Our own `app.module.ts` + 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. - p. - Create the file #[code #[+adjExPath('app/app.module.ts')]] with the following content: -+makeExample('app/app.module.ts')(format='.') + Create the file `app/app.module.ts` with the following content: -.l-verbose-section - :marked - We're passing metadata to the `NgModule` decorator function: + +makeExample('app/app.module.ts')(format='.') - 1. `imports` - the _other_ modules that export material we need in _this_ module. - Almost every application's _root module_ should import the `BrowserModule`. + .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. `declarations` - components and directives that belong to _this_ module. + 1. `bootstrap` - identifies the _root component_ that Angular should _bootstrap_ when it starts the application. - 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. - 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 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. - 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`. + One of the most common ones is `FormsModule`, and soon we'll also see `RouterModule` and `HttpModule`. .l-main-section -h2#main Step 4: Add #[code #[+adjExPath('main.ts')]] +h2#main Step !{step++}: Add #[code #[+adjExPath('main.ts')]] block create-main - p. + :marked Now we need something to tell Angular to load the app module. - Create the file #[code #[+adjExPath('app/main.ts')]] with the following content: + 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 We import the two things we need to launch the application: - 1. Angular's browser `platformBrowserDynamic` function - 1. The application module, `AppModule`. + 1. Angular's browser `!{_platformBrowserDynamicVsBootStrap}` function + 1. The application !{_moduleVsRootComp}, `!{_AppModuleVsAppComp}`. - Then we call `platformBrowserDynamic().bootstrapModule` with `AppComponent`. + Then we call `!{_pBD_bootstrapModule}` with `AppComponent`. ### Bootstrapping is platform-specific - Notice that we import the `platformBrowserDynamic` function from `#{_angular_browser_uri}`, - not `#{_angular_core_uri}`. + + 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 module in a different environment. + 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? + ### Why create separate *main.ts*, app module and app component files? - Both main.ts, app module and the app component files are tiny. + Then main.ts, app module + and the app component files are tiny. This is just a QuickStart. - We could have merged these three files into one and spared ourselves some complexity. + 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. + 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 `AppModule` in multiple environments with different bootstrappers. + 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*. .l-main-section -h2#index Step 5: Add #[code index.html] +h2#index Step !{step++}: Add #[code index.html] :marked In the *#{_indexHtmlDir}* folder create an `index.html` file and paste the following lines into it: @@ -395,7 +405,7 @@ h2#index Step 5: Add #[code index.html] :marked The `index.html` file defines the web page that hosts the application. - block index-html-commentary-for-ts + +ifDocsFor('ts') :marked The noteworthy sections of HTML are: @@ -494,12 +504,13 @@ h2#index Step 5: Add #[code index.html] All other modules are loaded upon request either by an import statement or by Angular itself. - ### *<my-app>* - - a(id="my-app") + #my-app :marked - When Angular calls the `bootstrapModule` function in main.ts, - it reads the `AppModule` metadata, sees that `AppComponent` is the bootstrap component, + ### *<my-app>* + + 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. @@ -508,13 +519,18 @@ h2#index Step 5: Add #[code index.html] Styles aren't essential but they're nice, and `index.html` assumes we have a stylesheet called `styles.css`. - Create a `styles.css` file in the *#{_indexHtmlDir}* folder and start styling, perhaps with the minimal - styles shown below. 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). -+makeExcerpt('styles.1.css') + Create a `styles.css` file in the *#{_indexHtmlDir}* folder and start styling, + perhaps with the minimal styles shown below. -.l-main-section -h2#build-and-run Step 6: Build and run the app! ++makeExcerpt('styles.css (excerpt)', 'quickstart') + +.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). + +.l-main-section#build-and-run +h2 Step !{step++}: Build and run the app! block run-app :marked Open a terminal window and enter this command: @@ -608,7 +624,7 @@ block project-files static file server. That's about all we'd expect to do for a "Hello, World" app. **We have greater ambitions!** -block what-next-ts-overhead ++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. From f4e6f5c679c620114820234a8f96374aba37a474 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Wed, 10 Aug 2016 13:17:31 -0700 Subject: [PATCH 2/2] post-review edits --- public/docs/ts/latest/quickstart.jade | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/public/docs/ts/latest/quickstart.jade b/public/docs/ts/latest/quickstart.jade index 08a4e9e781..79a258946b 100644 --- a/public/docs/ts/latest/quickstart.jade +++ b/public/docs/ts/latest/quickstart.jade @@ -504,10 +504,10 @@ h2#index Step !{step++}: Add #[code index.html] All other modules are loaded upon request either by an import statement or by Angular itself. - #my-app - :marked - ### *<my-app>* + ### *<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,