From b3d8bea11c5695c5b3a0b995c7dcd8f4fbb2b2ab Mon Sep 17 00:00:00 2001 From: Kathy Walrath Date: Wed, 4 Mar 2015 16:21:24 -0800 Subject: [PATCH] Copyedit of JS quick start --- public/docs/dart/latest/quickstart.jade | 10 +- public/docs/js/latest/quickstart.jade | 157 +++++++++++++----------- 2 files changed, 86 insertions(+), 81 deletions(-) diff --git a/public/docs/dart/latest/quickstart.jade b/public/docs/dart/latest/quickstart.jade index 50b56e6f77..08a0633261 100644 --- a/public/docs/dart/latest/quickstart.jade +++ b/public/docs/dart/latest/quickstart.jade @@ -52,7 +52,6 @@ p. will be higher than alpha 6. That's fine. // PENDING: Update once 1.9 is on stable channel. - // TODO: Convert the above to a callout. // STEP 2 - Import Angular ########################## @@ -152,16 +151,11 @@ p. of its component controller. The template above binds to a name property through the double-mustache syntax ({{ ... }}). + p. The component controller assigns "Alice" to the name property. When the template renders, "Hello Alice" appears instead of "Hello {{ name }}". - - // [PENDING: Do we really want to use the term "component controller"? - // If so, set it up beforehand. - // In the original text, what does "the backing" mean, and is it - // important that we keep it?] - pre.prettyprint code. class AppComponent { @@ -264,4 +258,4 @@ p. to get the latest version of Angular 2. - // [PENDING: really?] Perhaps point to dartlang.org. + // [PENDING: Perhaps point to dartlang.org.] diff --git a/public/docs/js/latest/quickstart.jade b/public/docs/js/latest/quickstart.jade index d6927a1b72..6d472f8366 100644 --- a/public/docs/js/latest/quickstart.jade +++ b/public/docs/js/latest/quickstart.jade @@ -20,7 +20,7 @@ p. .l-main-section h2#section-add-es6-shim 2. Add the es6-shim - p. Within your project, clone the es6-shim repository: + p Within your project, clone the es6-shim repository: pre.prettyprint code git clone https://github.com/davideast/conscious.git es6-shim @@ -28,7 +28,7 @@ p. p. For the sake of this quickstart we recommend using the es6-shim GitHub repository. - This repository will provides a faster start than building from npm. The es6-shim includes Angular and dependencies to compile ES6 in incompatible browsers. + This repository provides a faster start than building from npm. The es6-shim includes Angular and dependencies to compile ES6 in incompatible browsers. .l-sub-section h3 ES6, AtScript, and the es6-shim @@ -36,19 +36,22 @@ p. h4 AtScript p. Angular is built with AtScript. AtScript is an extension of ES6 (ECMAScript 6), the new specification - of the JavaScript language. This quickstart will be written in AtScript, but it is not required in Angular. + of the JavaScript language. This quickstart features AtScript, but Angular + doesn't require you to write AtScript. h4 ES6 p. - AtScript compiles to ES6. ES6 is not widely supported in all browsers today. + AtScript compiles to ES6, which is not widely supported in all browsers today. The es6-shim repository allows you to use ES6 or AtScript in the browser. h4 es6-shim p. - The es6-shim package includes Angular and dependencies needed to compile - ES6 in the browser, such as Traceur. Traceur is an ES6 compiler that transpiles ES6 to ES5 code. - Think of the es6-shim repository as package rather than a project. + The es6-shim package includes Angular and dependencies + (such as Traceur) needed to compile + ES6 in the browser. Traceur is an ES6 compiler that transpiles ES6 to ES5 code. + Think of the es6-shim repository as a package rather than a project. + // PENDING: "Think of ... as a package" could be clearer. // STEP 2 - Import Angular ########################## @@ -56,20 +59,24 @@ p. h2#section-transpile 2. Import Angular p. - Create two files for this quickstart, an index.html and a - app.es6. Both of these files will be at the root of the project. - The .es6 extension signifies that the file uses ES6 syntax. + Create two files, index.html and + app.es6, both at the root of the project: - pre.prettyprint.linenums - code touch index.html - | touch app.es6 + pre.prettyprint + code. + touch index.html + touch app.es6 - p Inside of app.es6, use the ES6 module syntax you can import the required modules from Angular. + .alert.is-helpful The .es6 extension signifies that the file uses ES6 syntax. + + p Inside of app.es6, import the required modules from Angular: pre.prettyprint.linenums code import {Component, Template, bootstrap} from 'angular2/angular2'; - p The above import statement will import three modules from Angular. These modules load at runtime. + p. + The above import statement uses ES6 module syntax to import three modules from Angular. + These modules load at runtime. // STEP 3 - Create a component ########################## @@ -78,24 +85,23 @@ p. h2#section-angular-create-account 3. Define a component p. - Components structure and represent the UI. This quickstart demonstrates the process of creating a component. - The component will have an HTML tag named app, - <my-app></my-app>. + Components structure and represent the UI. This quickstart demonstrates the process of creating a component + that has an HTML tag named <my-app>. p. - A component consists of two parts; the annotation section + A component consists of two parts, the annotation section and the component controller. pre.prettyprint.linenums code. - // Annotation Section + // Annotation section @Component({ selector: 'my-app' }) @Template({ inline: '<h1>Hello {{ name }}</h1>' }) - // Component Controller + // Component controller class MyAppComponent { constructor() { this.name = 'Alice'; @@ -103,20 +109,20 @@ p. } .l-sub-section - h3 Component Annotations + h3 Component annotations p. A component annotation provides metadata about the component. - An annotation can always identified by its at-sign (@). + An annotation can be identified by its at-sign (@). p. - The @Component annotation defines the HTML tag for the component. - The selector property is a CSS selector which specifies the HTML tag for the component. - + The @Component annotation defines + the HTML tag for the component by specifying the component's CSS selector. p. - The @Template annotation defines the template to apply to the component. - This component uses an inline template, but external templates are - available as well. To use an external template specify a url property - and give it the path to the html file. + The @Template annotation defines the HTML that + represents the component. This component uses an inline template, + but you can also have an external template. To use an external template, + specify a url property + and give it the path to the HTML file. pre.prettyprint.linenums code. @@ -128,11 +134,11 @@ p. }) p. - The component created above has a HTML tag of <my-app></my-app> - and a template of <h1>Hello {{ name }}</h1>. + The annotations above specify an HTML tag of <my-app> + and a template of <h1>Hello {{ name }}</h1>. .l-sub-section - h3 Component Controller + h3 The template and the component controller p. The component controller is the backing of the component's template. A component @@ -151,9 +157,11 @@ p. or functions placed on the component controller. p. - The template above binds to a name property through the {{ }} - syntax.The body of the constructor assigns "Alice" to the name property. When the - template renders, Alice will appear instead of {{ name }}. + The template above binds to a name property through + the double-mustache syntax ({{ ... }}). + The body of the constructor assigns "Alice" to the name property. When the + template renders, "Hello Alice" appears instead of + "Hello {{ name }}". @@ -161,17 +169,18 @@ p. .l-main-section h2#section-transpile 4. Bootstrap - p The last step to load the component on the page. At the bottom of app.es6 call the bootstrap() function. + p. + At the bottom of app.es6, call the bootstrap() function + to load your new component into its page: pre.prettyprint.linenums code bootstrap(MyAppComponent); p. - Angular provides a bootstrap function that renders a - component to the page. The bootstrap function takes a - component as a parameter. Any child components inside of the parent - component will render as well. + The bootstrap() function takes a + component as a parameter, enabling the component + (as well as any child components it contains) to render. // STEP 5 - Declare the HTML ########################## @@ -180,8 +189,9 @@ p. h2#section-angular-create-account 5. Declare the HTML p. - Inside of the index.html, include the es6-shim.js file in the head tag. - Now, declare the app component the body. The es6-shim must load before any application code. + Inside the head tag of index.html, include the es6-shim.js file. + (The es6-shim code must load before any application code.) + Then instantiate the my-app component in the body. pre.prettyprint.linenums code. @@ -202,53 +212,54 @@ p. // STEP 6 - Declare the HTML ########################## .l-main-section - h2#section-load-component-module 5. Load the component + h2#section-load-component-module 6. Load the component p. - The last step is to load the module for the my-app component. - The es6-shim file comes packaged with the System library. We'll - use System to load the component we created above. + The last step is to load the module for the my-app component. + To do this, we'll use the System library, + which is included in es6-shim. .l-sub-section h3 System.js p. - System is a third-party open sourced library. Most browsers today do not support ES6 module loading. System - provides module loading functionality to these browsers. + System is a third-party open-source library that + adds ES6 module loading functionality to browsers. p. - To load the needed modules, System needs to know where to - load the files from. The paths property in System specifies - the location of the files. + Add the following module-loading code to index.html: - p Tell System about three paths: - ol - li Angular: The Angular framework. - li Runtime assertions: Optional assertions for runtime type checking. - li The my-app component created above: The component to display on the page. + pre.prettyprint.linenums + code. + <my-app></my-app> - pre.prettyprint.linenums - code. - <my-app></my-app> + <script> + // Rewrite the paths to load the files + System.paths = { + 'angular2/*':'/es6-shim/angular2/*.js', // Angular + 'rtts_assert/*': '/es6-shim/rtts_assert/*.js', //Runtime assertions + 'app': 'app.es6' // The my-app component + }; - <script> - // Rewrite the paths to load the files - System.paths = { - 'angular2/*':'/es6-shim/angular2/*.js', // Angular - 'rtts_assert/*': '/es6-shim/rtts_assert/*.js', //Runtime assertions - 'app': 'app.es6' // The my-app component - }; + // Kick off the application + System.import('app'); + </script> - // Kick off the application - System.import('app'); - </script> + p. + The System.paths property above specifies + the paths to the following modules: + ul + li The Angular framework + li Optional assertions for runtime type checking + li The component to display on the page -// STEP 6 - Declare the HTML ########################## + +// STEP 6 - Run a local server ########################## .l-main-section - h2#section-load-component-module 5. Run a local server - + h2#section-load-component-module 6. Run a local server + // PENDING: add directions (or at least hints) here // WHAT'S NEXT... ########################## .l-main-section