From fe35bc6c313021a7121bda0e0eb7b844616063c3 Mon Sep 17 00:00:00 2001 From: Ward Bell Date: Mon, 8 Aug 2016 17:30:05 -0700 Subject: [PATCH] docs(rc4-to-rc5): New RC4->RC5 migration cookbook. --- public/docs/dart/latest/cookbook/_data.json | 6 + .../docs/dart/latest/cookbook/rc4-to-rc5.jade | 1 + .../docs/dart/latest/cookbook/ts-to-js.jade | 2 +- public/docs/js/latest/cookbook/_data.json | 6 + .../docs/js/latest/cookbook/rc4-to-rc5.jade | 1 + public/docs/ts/latest/cookbook/_data.json | 5 + .../docs/ts/latest/cookbook/rc4-to-rc5.jade | 119 ++++++++++++++++++ public/docs/ts/latest/glossary.jade | 20 +++ 8 files changed, 159 insertions(+), 1 deletion(-) create mode 100644 public/docs/dart/latest/cookbook/rc4-to-rc5.jade create mode 100644 public/docs/js/latest/cookbook/rc4-to-rc5.jade create mode 100644 public/docs/ts/latest/cookbook/rc4-to-rc5.jade diff --git a/public/docs/dart/latest/cookbook/_data.json b/public/docs/dart/latest/cookbook/_data.json index 207dce5e42..c7f07e9834 100644 --- a/public/docs/dart/latest/cookbook/_data.json +++ b/public/docs/dart/latest/cookbook/_data.json @@ -35,6 +35,12 @@ "hide": true }, + "rc4-to-rc5": { + "title": "RC4 to RC5 Migration", + "intro": "Migrate your RC4 app to RC5 in minutes.", + "hide": true + }, + "set-document-title": { "title": "Set the Document Title", "intro": "Setting the document or window title using the Title service." diff --git a/public/docs/dart/latest/cookbook/rc4-to-rc5.jade b/public/docs/dart/latest/cookbook/rc4-to-rc5.jade new file mode 100644 index 0000000000..6778b6af28 --- /dev/null +++ b/public/docs/dart/latest/cookbook/rc4-to-rc5.jade @@ -0,0 +1 @@ +!= partial("../../../_includes/_ts-temp") diff --git a/public/docs/dart/latest/cookbook/ts-to-js.jade b/public/docs/dart/latest/cookbook/ts-to-js.jade index f8df2a84a6..6778b6af28 100644 --- a/public/docs/dart/latest/cookbook/ts-to-js.jade +++ b/public/docs/dart/latest/cookbook/ts-to-js.jade @@ -1 +1 @@ -!= partial("../../../_includes/_ts-temp") \ No newline at end of file +!= partial("../../../_includes/_ts-temp") diff --git a/public/docs/js/latest/cookbook/_data.json b/public/docs/js/latest/cookbook/_data.json index d95e3a6d68..a020c2e148 100644 --- a/public/docs/js/latest/cookbook/_data.json +++ b/public/docs/js/latest/cookbook/_data.json @@ -31,6 +31,12 @@ "intro": "Render dynamic forms with NgFormModel" }, + "rc4-to-rc5": { + "title": "RC4 to RC5 Migration", + "intro": "Migrate your RC4 app to RC5 in minutes.", + "hide": true + }, + "set-document-title": { "title": "Set the Document Title", "intro": "Setting the document or window title using the Title service." diff --git a/public/docs/js/latest/cookbook/rc4-to-rc5.jade b/public/docs/js/latest/cookbook/rc4-to-rc5.jade new file mode 100644 index 0000000000..6778b6af28 --- /dev/null +++ b/public/docs/js/latest/cookbook/rc4-to-rc5.jade @@ -0,0 +1 @@ +!= partial("../../../_includes/_ts-temp") diff --git a/public/docs/ts/latest/cookbook/_data.json b/public/docs/ts/latest/cookbook/_data.json index ecfc0e22d6..aea1b06b7c 100644 --- a/public/docs/ts/latest/cookbook/_data.json +++ b/public/docs/ts/latest/cookbook/_data.json @@ -38,6 +38,11 @@ "intro": "Render dynamic forms with FormGroup" }, + "rc4-to-rc5": { + "title": "RC4 to RC5 Migration", + "intro": "Migrate your RC4 app to RC5 in minutes." + }, + "set-document-title": { "title": "Set the Document Title", "intro": "Setting the document or window title using the Title service." diff --git a/public/docs/ts/latest/cookbook/rc4-to-rc5.jade b/public/docs/ts/latest/cookbook/rc4-to-rc5.jade new file mode 100644 index 0000000000..3933263c07 --- /dev/null +++ b/public/docs/ts/latest/cookbook/rc4-to-rc5.jade @@ -0,0 +1,119 @@ +include ../_util-fns + +:marked + # Angular Modules (NgModules) have landed in Angular RC5! + + _Angular Modules_, also known as _NgModules_, are the powerful new way to organize and bootstrap your Angular application. +.l-sub-section + :marked + Read more in the ["RC5 and NgModules" announcement](https://angularjs.blogspot.com). + + Learn the details of NgModule in the [Angular Module](../guide/ngmodule) chapter. +:marked + The new `@NgModule` decorator gives you module-level components, directives, and pipes without + the need to specify them repeatedly in every component of your application. + + The `@NgModule` metadata give the Angular compiler the context needed so that you can use the same code + regardless of whether you are running Angular in [Ahead of Time](../glossary.html#aot) or [Just in Time](../glossary.html#jit) mode. + + ## How do I use them? + + If you were previously writing an Angular application, your app should continue to work in RC5. + We’ve worked hard to ensure that applications that worked with RC4 continue to work while you migrate. + For this to work, we’re doing 2 things automatically for you: + + * We create an implicit `NgModule` for you as part of the `bootstrap()` command + * We automatically hoist your components, pipes, and directives + + While your application will continue to work today, + it’s important that you update your application to ensure future updates and deprecations don’t negatively affect you. + To make it easier, you can think of the process as having 5 steps. + + 1. **Update to RC5** - Your application should continue to work without modification, but it’s important that you are running the latest version of Angular. + + 2. **Create an _NgModule_** - Create the root `NgModule` that you’ll use to bootstrap your application. + + 3. **Update your bootstrap** - Bootstrap that module instead of your root component + + 4. **Update your 3rd party libraries** - Take advantage of the latest from Forms, Material, Http, and more + + 5. **Cleanup** - Clean up your code. + The deprecated classes, methods and properties will be removed from Angular very soon. + + Prefer to look at code and diffs? + Check out the upgrade in [one commit](https://github.com/StephenFluin/ngmodule-migration/commit/9f9c6ae099346e491fc31d77bf65ed440e1f164c). + + ## 1. Update to RC5 + If you use npm, you should be able to either update your package.json file and run npm install. + Or alternatively you can run the following command: + + ```bash + npm install @angular/{core,common,compiler,angular-cli,platform-browser,platform-browser-dynamic}@2.0.0-rc.5 --save + ``` + + You should also update any libraries you are using + + ```bash + npm install @angular/router@3.0.0-rc.1 + npm install @angular/forms@1.0.0-rc.1 + npm install @angular2-material/{button,card,toolbar,etc}@experimental + ``` + + ## 2. Create an NgModule + Create a new file called app.module.ts. Populate it with your root component as follows: + + ```javascript + import { NgModule } from '@angular/core'; + import { BrowserModule } from '@angular/platform-browser'; + import { AppComponent } from './app.component'; + + @NgModule({ + declarations: [AppComponent], + imports: [BrowserModule], + bootstrap: [AppComponent], + }) + export class AppModule {} + ``` + + + ## 3. Update your bootstrap + Update your `main.ts` file to bootstrap using the Just in Time compiler. + + ```javascript + import { platformBrowserDynamic } from '@angular/platform-browser-dynamic'; + import { AppModule } from './app/app.module'; + + platformBrowserDynamic().bootstrapModule(AppModule); + ``` + + ## 4. Update your 3rd party libraries + Remove any 3rd party libraries from you AppComponent’s providers. + You’ll want to move these to your NgModule’s imports, while updating to use each library’s provided Module(s). + + ```javascript + imports: [ + BrowserModule, + // Router + RouterModule.forRoot(config), + // Forms + FormsModule, + // Material Design + MdSlideToggleModule, + MdButtonModule, + MdToolbarModule, + MdCardModule, + MdInputModule, + ], + ``` + + ## 5. Cleanup + As of RC5, we allow you to leave `directives` and `pipes` in your `@Component` decorators. + In fact, we automatically hoist (add) them to the NgModule that they belong to. + +.alert.is-important + :marked + This behavior is provided temporarily for backward compatibility. It will soon be removed. + + Stay ahead of this deprecation by removing them from your components and placing them into your `NgModule` declarations + as soon as possible. +:marked diff --git a/public/docs/ts/latest/glossary.jade b/public/docs/ts/latest/glossary.jade index 3342e16d0f..bc34cf94e1 100644 --- a/public/docs/ts/latest/glossary.jade +++ b/public/docs/ts/latest/glossary.jade @@ -20,6 +20,17 @@ include _util-fns // #docregion a1 // #enddocregion a1 +a#aot +.l-main-section +:marked + ## Ahead of Time (AOT) Compilation +.l-sub-section + :marked + Angular applications can be compiled by developers at build-time. + By compiling your application using the compiler-cli, `ngc`, you can boostrap directly + to a Module Factory, meaning you don't need to include the Angular compiler in your javascript bundle. + Ahead of Time compiled applications also benefit from decreased load time and increased performance. + .l-main-section :marked @@ -417,7 +428,16 @@ include _util-fns +a#jit .l-main-section +:marked + ## Just in Time (JIT) Compilation +.l-sub-section + :marked + With Angular _Just in Time_ bootstrapping you compile your components and modules in the browser + and launch the application dynamically. This is a good choice during development. + Consider the [Ahead of Time](#aot) mode for production apps. + :marked ## kebab-case