From bc752a346026408fce0a456978f771792de3b2b8 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Thu, 11 Aug 2016 10:12:09 -0700 Subject: [PATCH] chore(quickstart/dart): refresh ts _cache Cf. #2088 and #2077. --- public/docs/dart/latest/quickstart.jade | 2 +- public/docs/ts/_cache/quickstart.jade | 636 ++++++++++++++++++++++++ 2 files changed, 637 insertions(+), 1 deletion(-) create mode 100644 public/docs/ts/_cache/quickstart.jade diff --git a/public/docs/dart/latest/quickstart.jade b/public/docs/dart/latest/quickstart.jade index 0150a9a70d..84085d64c7 100644 --- a/public/docs/dart/latest/quickstart.jade +++ b/public/docs/dart/latest/quickstart.jade @@ -1,4 +1,4 @@ -extends ../../ts/latest/quickstart.jade +extends ../../ts/_cache/quickstart.jade block includes include _util-fns diff --git a/public/docs/ts/_cache/quickstart.jade b/public/docs/ts/_cache/quickstart.jade new file mode 100644 index 0000000000..79a258946b --- /dev/null +++ b/public/docs/ts/_cache/quickstart.jade @@ -0,0 +1,636 @@ +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' + - 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 + 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](#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) + +- var step = _stepInit // reinitialize step counter for headers to come +.l-main-section#prereq +h2 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. + +.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)"). + 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 ==> + +- 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) + + ### (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#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: + +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 `app.module.ts`. + ++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. + + 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`. + +.l-main-section +h2#main Step !{step++}: Add #[code #[+adjExPath('main.ts')]] + +block create-main + :marked + Now we need something to tell Angular to load the app module. + 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 `!{_platformBrowserDynamicVsBootStrap}` function + 1. The application !{_moduleVsRootComp}, `!{_AppModuleVsAppComp}`. + + Then we call `!{_pBD_bootstrapModule}` with `AppComponent`. + + ### 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*. + +.l-main-section +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: + ++makeExample('index.html') + +.l-verbose-section + :marked + The `index.html` file defines the web page that hosts the application. + + +ifDocsFor('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#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 + a stylesheet called `styles.css`. + + Create a `styles.css` file in the *#{_indexHtmlDir}* folder and start styling, + perhaps with the minimal styles shown below. + ++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: + 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 app.module.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/app.module.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` + , + ',,,,,,,,', + `app/app.component.ts, + app/app.module.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!** ++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. +: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)!