diff --git a/aio/content/guide/ajs-quick-reference.md b/aio/content/guide/ajs-quick-reference.md index c8dfb3ac10..a3466ca12b 100644 --- a/aio/content/guide/ajs-quick-reference.md +++ b/aio/content/guide/ajs-quick-reference.md @@ -190,7 +190,7 @@ The following are some of the key AngularJS built-in directives and their equiva The application startup process is called **bootstrapping**. - Although you can bootstrap an AngularJS app in code, + Although you can bootstrap an AngularJS application in code, many applications bootstrap declaratively with the `ng-app` directive, giving it the name of the application's module (`movieHunter`). @@ -207,7 +207,7 @@ The following are some of the key AngularJS built-in directives and their equiva Angular doesn't have a bootstrap directive. - To launch the app in code, explicitly bootstrap the application's root module (`AppModule`) + To launch the application in code, explicitly bootstrap the application's root module (`AppModule`) in `main.ts` and the application's root component (`AppComponent`) in `app.module.ts`. @@ -691,9 +691,9 @@ The following are some of the key AngularJS built-in directives and their equiva In this example, if `favoriteHero` is not set, the `ngSwitch` value is `null` and `*ngSwitchDefault` displays, "Please enter ...". - If `favoriteHero` is set, the app checks the movie hero by calling a component method. - If that method returns `true`, the app selects `*ngSwitchCase="true"` and displays: "Excellent choice!" - If that methods returns `false`, the app selects `*ngSwitchCase="false"` and displays: "No movie, sorry!" + If `favoriteHero` is set, the application checks the movie hero by calling a component method. + If that method returns `true`, the application selects `*ngSwitchCase="true"` and displays: "Excellent choice!" + If that methods returns `false`, the application selects `*ngSwitchCase="false"` and displays: "No movie, sorry!" The (*) before `ngSwitchCase` and `ngSwitchDefault` is required in this example. diff --git a/aio/content/guide/deprecations.md b/aio/content/guide/deprecations.md index e493fb3953..3bba0a4f0b 100644 --- a/aio/content/guide/deprecations.md +++ b/aio/content/guide/deprecations.md @@ -3,7 +3,7 @@ Angular strives to balance innovation and stability. Sometimes, APIs and features become obsolete and need to be removed or replaced so that Angular can stay current with new best practices, changing dependencies, or changes in the (web) platform itself. -To make these transitions as easy as possible, we deprecate APIs and features for a period of time before removing them. This gives you time to update your apps to the latest APIs and best practices. +To make these transitions as easy as possible, we deprecate APIs and features for a period of time before removing them. This gives you time to update your applications to the latest APIs and best practices. This guide contains a summary of all Angular APIs and features that are currently deprecated. @@ -20,7 +20,7 @@ For step-by-step instructions on how to update to the latest Angular release, us ## Index -To help you future-proof your apps, the following table lists all deprecated APIs and features, organized by the release in which they are candidates for removal. Each item is linked to the section later in this guide that describes the deprecation reason and replacement options. +To help you future-proof your projects, the following table lists all deprecated APIs and features, organized by the release in which they are candidates for removal. Each item is linked to the section later in this guide that describes the deprecation reason and replacement options. `) rather than behind it as was the case previously. +* Embedded views (such as ones created by `*ngFor`) are now inserted in front of anchor DOM comment node (for example, ``) rather than behind it as was the case previously. In most cases this does not have any impact on rendered DOM. In some cases (such as animations delaying the removal of an embedded view) any new embedded views will be inserted after the embedded view being animated away. This difference only last while the animation is active, and might alter the visual appearance of the animation. diff --git a/aio/content/guide/releases.md b/aio/content/guide/releases.md index 7dbb210a14..2850251fd2 100644 --- a/aio/content/guide/releases.md +++ b/aio/content/guide/releases.md @@ -4,7 +4,7 @@ We recognize that you need stability from the Angular framework. Stability ensur We also share with you the desire for Angular to keep evolving. We strive to ensure that the foundation on top of which you are building is continuously improving and enabling you to stay up-to-date with the rest of the web ecosystem and your user needs. -This document contains the practices that we follow to provide you with a leading-edge app development platform, balanced with stability. We strive to ensure that future changes are always introduced in a predictable way. We want everyone who depends on Angular to know when and how new features are added, and to be well-prepared when obsolete ones are removed. +This document contains the practices that we follow to provide you with a leading-edge application development platform, balanced with stability. We strive to ensure that future changes are always introduced in a predictable way. We want everyone who depends on Angular to know when and how new features are added, and to be well-prepared when obsolete ones are removed.
@@ -26,7 +26,7 @@ The version number is incremented based on the level of change included in the r * **Major releases** contain significant new features, some but minimal developer assistance is expected during the update. When updating to a new major release, you may need to run update scripts, refactor code, run additional tests, and learn new APIs. -* **Minor releases** contain new smaller features. Minor releases are fully backward-compatible; no developer assistance is expected during update, but you can optionally modify your apps and libraries to begin using new APIs, features, and capabilities that were added in the release. We update peer dependencies in minor versions by expanding the supported versions, but we do not require projects to update these dependencies. +* **Minor releases** contain new smaller features. Minor releases are fully backward-compatible; no developer assistance is expected during update, but you can optionally modify your applications and libraries to begin using new APIs, features, and capabilities that were added in the release. We update peer dependencies in minor versions by expanding the supported versions, but we do not require projects to update these dependencies. * **Patch releases** are low risk, bug fix releases. No developer assistance is expected during update. @@ -131,7 +131,7 @@ To make these transitions as easy as possible, we make these commitments to you: * We work hard to minimize the number of breaking changes and to provide migration tools when possible. -* We follow the deprecation policy described here, so you have time to update your apps to the latest APIs and best practices. +* We follow the deprecation policy described here, so you have time to update your applications to the latest APIs and best practices. To help ensure that you have sufficient time and a clear path to update, this is our deprecation policy: @@ -141,7 +141,7 @@ To help ensure that you have sufficient time and a clear path to update, this is * **Deprecation period:** When an API or a feature is deprecated, it will still be present in the next two major releases. After that, deprecated APIs and features will be candidates for removal. A deprecation can be announced in any release, but the removal of a deprecated API or feature will happen only in major release. Until a deprecated API or feature is removed, it will be maintained according to the LTS support policy, meaning that only critical and security issues will be fixed. -* **npm dependencies:** We only make npm dependency updates that require changes to your apps in a major release. +* **npm dependencies:** We only make npm dependency updates that require changes to your applications in a major release. In minor releases, we update peer dependencies by expanding the supported versions, but we do not require projects to update these dependencies until a future major version. This means that during minor Angular releases, npm dependency updates within Angular applications and libraries are optional. diff --git a/aio/content/guide/roadmap.md b/aio/content/guide/roadmap.md index 9688980665..18572a2e62 100644 --- a/aio/content/guide/roadmap.md +++ b/aio/content/guide/roadmap.md @@ -1,6 +1,6 @@ # Angular Roadmap -Angular receives a large number of feature requests, both from inside Google and from the broader open-source community. At the same time, our list of projects contains plenty of maintenance tasks, code refactorings, potential performance improvements, and so on. We bring together representatives from developer relations, product management, and engineering to prioritize this list. As new projects come into the queue, we regularly position them based on relative priority to other projects. As work gets done, projects will move up in the queue. +Angular receives a large number of feature requests, both from inside Google and from the broader open-source community. At the same time, our list of projects contains plenty of maintenance tasks, code refactorings, and potential performance improvements. We bring together representatives from developer relations, product management, and engineering to prioritize this list. As new projects come into the queue, we regularly position them based on relative priority to other projects. As work gets done, projects will move up in the queue. The projects below are not associated with a particular Angular version. We'll release them on completion, and they will be part of a specific version based on our release schedule, following semantic versioning. For example, features are released in the next minor after they are complete, or the next major if they include breaking changes. diff --git a/aio/content/guide/upgrade-performance.md b/aio/content/guide/upgrade-performance.md index bb538ff91b..3585b513a3 100644 --- a/aio/content/guide/upgrade-performance.md +++ b/aio/content/guide/upgrade-performance.md @@ -11,9 +11,9 @@ This guide describes some of the built-in tools for efficiently migrating Angula the Angular platform, one piece at a time. It is very similar to [Upgrading from AngularJS](guide/upgrade) with the exception that this one uses the {@link downgradeModule downgradeModule()} helper function instead of the {@link UpgradeModule -UpgradeModule} class. This affects how the app is bootstrapped and how change detection is +UpgradeModule} class. This affects how the application is bootstrapped and how change detection is propagated between the two frameworks. It allows you to upgrade incrementally while improving the -speed of your hybrid apps and leveraging the latest of Angular in AngularJS apps early in the +speed of your hybrid applications and leveraging the latest of Angular in AngularJS applications early in the process of upgrading. @@ -28,8 +28,8 @@ same regardless of how you upgrade, refer to the [Preparation](guide/upgrade#pre ## Upgrading with `ngUpgrade` -With the `ngUpgrade` library in Angular you can upgrade an existing AngularJS app incrementally by -building a hybrid app where you can run both frameworks side-by-side. In these hybrid apps you can +With the `ngUpgrade` library in Angular you can upgrade an existing AngularJS application incrementally by +building a hybrid app where you can run both frameworks side-by-side. In these hybrid applications you can mix and match AngularJS and Angular components and services and have them interoperate seamlessly. That means you don't have to do the upgrade work all at once as there is a natural coexistence between the two frameworks during the transition period. @@ -46,7 +46,7 @@ upgrade/static} utilities remain the same. For more information, see the
The [Change Detection](guide/upgrade#change-detection) section of - [Upgrading from AngularJS](guide/upgrade) only applies to apps that use `UpgradeModule`. Though + [Upgrading from AngularJS](guide/upgrade) only applies to applications that use `UpgradeModule`. Though you handle change detection differently with `downgradeModule()`, which is the focus of this guide, reading the [Change Detection](guide/upgrade#change-detection) section provides helpful context for what follows. @@ -65,14 +65,14 @@ the Angular part and vice versa. This is convenient as it ensures that neither f important change. Most of the time, though, these extra change detection runs are unnecessary. `downgradeModule()`, on the other side, avoids explicitly triggering change detection unless it -knows the other part of the app is interested in the changes. For example, if a downgraded component -defines an `@Input()`, chances are that the app needs to be aware when that value changes. Thus, +knows the other part of the application is interested in the changes. For example, if a downgraded component +defines an `@Input()`, chances are that the application needs to be aware when that value changes. Thus, `downgradeComponent()` automatically triggers change detection on that component. In most cases, though, the changes made locally in a particular component are of no interest to the -rest of the app. For example, if the user clicks a button that submits a form, the component usually +rest of the application. For example, if the user clicks a button that submits a form, the component usually handles the result of this action. That being said, there _are_ cases where you want to propagate -changes to some other part of the app that may be controlled by the other framework. In such cases, +changes to some other part of the application that may be controlled by the other framework. In such cases, you are responsible for notifying the interested parties by manually triggering change detection. If you want a particular piece of code to trigger change detection in the AngularJS part of the app, @@ -81,14 +81,14 @@ you need to wrap it in triggering change detection in Angular you would use {@link NgZone#run ngZone.run()}. In many cases, a few extra change detection runs may not matter much. However, on larger or -change-detection-heavy apps they can have a noticeable impact. By giving you more fine-grained +change-detection-heavy applications they can have a noticeable impact. By giving you more fine-grained control over the change detection propagation, `downgradeModule()` allows you to achieve better -performance for your hybrid apps. +performance for your hybrid applications. ## Using `downgradeModule()` -Both AngularJS and Angular have their own concept of modules to help organize an app into cohesive +Both AngularJS and Angular have their own concept of modules to help organize an application into cohesive blocks of functionality. Their details are quite different in architecture and implementation. In AngularJS, you create a @@ -97,10 +97,10 @@ module by specifying its name and dependencies with assets using its various methods. In Angular, you create a class adorned with an {@link NgModule NgModule} decorator that describes assets in metadata. -In a hybrid app you run both frameworks at the same time. This means that you need at least one +In a hybrid application you run both frameworks at the same time. This means that you need at least one module each from both AngularJS and Angular. -For the most part, you specify the modules in the same way you would for a regular app. Then, you +For the most part, you specify the modules in the same way you would for a regular application. Then, you use the `upgrade/static` helpers to let the two frameworks know about assets they can use from each other. This is known as "upgrading" and "downgrading". @@ -109,16 +109,16 @@ other. This is known as "upgrading" and "downgrading". Definitions: - _Upgrading_: The act of making an AngularJS asset, such as a component or service, available to - the Angular part of the app. + the Angular part of the application. - _Downgrading_: The act of making an Angular asset, such as a component or service, available to - the AngularJS part of the app. + the AngularJS part of the application.
An important part of inter-linking dependencies is linking the two main modules together. This is where `downgradeModule()` comes in. Use it to create an AngularJS module—one that you can use as a dependency in your main AngularJS module—that will bootstrap your main Angular module and -kick off the Angular part of the hybrid app. In a sense, it "downgrades" an Angular module to an +kick off the Angular part of the hybrid application. In a sense, it "downgrades" an Angular module to an AngularJS module. There are a few things to note, though: @@ -126,7 +126,7 @@ There are a few things to note, though: 1. You don't pass the Angular module directly to `downgradeModule()`. All `downgradeModule()` needs is a "recipe", for example, a factory function, to create an instance for your module. -2. The Angular module is not instantiated until the app actually needs it. +2. The Angular module is not instantiated until the application actually needs it. The following is an example of how you can use `downgradeModule()` to link the two modules. @@ -156,11 +156,11 @@ of the Angular module. `downgradeModule()` accepts two types of factory function When you pass an `NgModuleFactory`, `downgradeModule()` uses it to instantiate the module using {@link platformBrowser platformBrowser}'s {@link PlatformRef#bootstrapModuleFactory bootstrapModuleFactory()}, which is compatible with ahead-of-time (AOT) compilation. AOT compilation -helps make your apps load faster. For more about AOT and how to create an `NgModuleFactory`, see the +helps make your applications load faster. For more about AOT and how to create an `NgModuleFactory`, see the [Ahead-of-Time Compilation](guide/aot-compiler) guide. Alternatively, you can pass a plain function, which is expected to return a promise resolving to an -{@link NgModuleRef NgModuleRef} (i.e. an instance of your Angular module). The function is called +{@link NgModuleRef NgModuleRef} (that is, an instance of your Angular module). The function is called with an array of extra {@link StaticProvider Providers} that are expected to be available on the returned `NgModuleRef`'s {@link Injector Injector}. For example, if you are using {@link platformBrowser platformBrowser} or {@link platformBrowserDynamic platformBrowserDynamic}, you can @@ -192,9 +192,9 @@ until later. `downgradeModule()` is again less aggressive. It will only instanti when it is required for the first time; that is, as soon as it needs to create a downgraded component. -You could go a step further and not even download the code for the Angular part of the app to the +You could go a step further and not even download the code for the Angular part of the application to the user's browser until it is needed. This is especially useful when you use Angular on parts of the -hybrid app that are not necessary for the initial rendering or that the user doesn't reach. +hybrid application that are not necessary for the initial rendering or that the user doesn't reach. A few examples are: @@ -203,23 +203,23 @@ A few examples are: - You use Angular for features that are only visible to specific types of users; for example, logged-in users, administrators, or VIP members. You don't need to load Angular until a user is authenticated. -- You use Angular for a feature that is not critical for the initial rendering of the app and you +- You use Angular for a feature that is not critical for the initial rendering of the application and you can afford a small delay in favor of better initial load performance. ### Bootstrapping with `downgradeModule()` As you might have guessed, you don't need to change anything in the way you bootstrap your existing -AngularJS app. Unlike `UpgradeModule`—which requires some extra steps— +AngularJS application. Unlike `UpgradeModule`—which requires some extra steps— `downgradeModule()` is able to take care of bootstrapping the Angular module, as long as you provide the recipe. In order to start using any `upgrade/static` APIs, you still need to load the Angular framework as -you would in a normal Angular app. You can see how this can be done with SystemJS by following the +you would in a normal Angular application. You can see how this can be done with SystemJS by following the instructions in the [Upgrade Setup](guide/upgrade-setup "Setup for Upgrading from AngularJS") guide, selectively copying code from the [QuickStart github repository](https://github.com/angular/quickstart). -You also need to install the `@angular/upgrade` package via `npm install @angular/upgrade --save` +You also need to install the `@angular/upgrade` package using `npm install @angular/upgrade --save` and add a mapping for the `@angular/upgrade/static` package: @@ -251,7 +251,7 @@ declaration on its `NgModule` decorator.
You do not add a `bootstrap` declaration to the `NgModule` decorator since AngularJS owns the root - template of the app and `ngUpgrade` bootstraps the necessary components. + template of the application and `ngUpgrade` bootstraps the necessary components.
@@ -278,7 +278,7 @@ The existing AngularJS code works as before _and_ you are ready to start adding ### Using Components and Injectables The differences between `downgradeModule()` and `UpgradeModule` end here. The rest of the -`upgrade/static` APIs and concepts work in the exact same way for both types of hybrid apps. +`upgrade/static` APIs and concepts work in the exact same way for both types of hybrid applications. See [Upgrading from AngularJS](guide/upgrade) to learn about: - [Using Angular Components from AngularJS Code](guide/upgrade#using-angular-components-from-angularjs-code).
@@ -296,7 +296,7 @@ See [Upgrading from AngularJS](guide/upgrade) to learn about: While it is possible to downgrade injectables, downgraded injectables will not be available until the Angular module that provides them is instantiated. In order to be safe, you need to ensure - that the downgraded injectables are not used anywhere _outside_ the part of the app where it is + that the downgraded injectables are not used anywhere _outside_ the part of the application where it is guaranteed that their module has been instantiated. For example, it is _OK_ to use a downgraded service in an upgraded component that is only used @@ -309,8 +309,8 @@ See [Upgrading from AngularJS](guide/upgrade) to learn about: ## Using ahead-of-time compilation with hybrid apps -You can take advantage of ahead-of-time (AOT) compilation in hybrid apps just like in any other -Angular app. The setup for a hybrid app is mostly the same as described in the +You can take advantage of ahead-of-time (AOT) compilation in hybrid applications just like in any other +Angular application. The setup for a hybrid application is mostly the same as described in the [Ahead-of-Time Compilation](guide/aot-compiler) guide save for differences in `index.html` and `main-aot.ts`. @@ -331,17 +331,17 @@ angular.module('mainAngularJsModule', [ ]); -And that is all you need to do to get the full benefit of AOT for hybrid Angular apps. +And that is all you need to do to get the full benefit of AOT for hybrid Angular applications. ## Conclusion This page covered how to use the {@link upgrade/static upgrade/static} package to incrementally -upgrade existing AngularJS apps at your own pace and without impeding further development of the app +upgrade existing AngularJS applications at your own pace and without impeding further development of the app for the duration of the upgrade process. Specifically, this guide showed how you can achieve better performance and greater flexibility in -your hybrid apps by using {@link downgradeModule downgradeModule()} instead of {@link UpgradeModule +your hybrid applications by using {@link downgradeModule downgradeModule()} instead of {@link UpgradeModule UpgradeModule}. To summarize, the key differentiating factors of `downgradeModule()` are: @@ -350,9 +350,9 @@ To summarize, the key differentiating factors of `downgradeModule()` are: loading time. In some cases this may waive the cost of running a second framework altogether. 2. It improves performance by avoiding unnecessary change detection runs while giving the developer greater ability to customize. -3. It does not require you to change how you bootstrap your AngularJS app. +3. It does not require you to change how you bootstrap your AngularJS application. -Using `downgradeModule()` is a good option for hybrid apps when you want to keep the AngularJS and +Using `downgradeModule()` is a good option for hybrid applications when you want to keep the AngularJS and Angular parts less coupled. You can still mix and match components and services from both frameworks, but you might need to manually propagate change detection. In return, `downgradeModule()` offers more control and better performance. diff --git a/aio/content/guide/upgrade-setup.md b/aio/content/guide/upgrade-setup.md index fcc87ece4f..98efc74047 100644 --- a/aio/content/guide/upgrade-setup.md +++ b/aio/content/guide/upgrade-setup.md @@ -204,10 +204,10 @@ Focus on the following three TypeScript (`.ts`) files in the **`/src`** folder. All guides and cookbooks have _at least these core files_. Each file has a distinct purpose and evolves independently as the application grows. -Files outside `src/` concern building, deploying, and testing your app. +Files outside `src/` concern building, deploying, and testing your application. They include configuration files and external dependencies. -Files inside `src/` "belong" to your app. +Files inside `src/` "belong" to your application. Add new Typescript, HTML and CSS files inside the `src/` directory, most of them inside `src/app`, unless told to do otherwise. @@ -299,10 +299,10 @@ The following are all in `src/` ## Appendix: Develop locally with IE -If you develop Angular locally with `ng serve`, a `websocket` connection is set up automatically between browser and local dev server, so when your code changes, the browser can automatically refresh. +If you develop Angular locally with `ng serve`, a `websocket` connection is set up automatically between browser and local development server, so when your code changes, the browser can automatically refresh. In Windows, by default, one application can only have 6 websocket connections, MSDN WebSocket Settings. -So when IE is refreshed (manually or automatically by `ng serve`), sometimes the websocket does not close properly. When websocket connections exceed the limitations, a `SecurityError` will be thrown. This error will not affect the Angular application, you can just restart IE to clear this error, or modify the windows registry to update the limitations. +So when IE is refreshed (manually or automatically by `ng serve`), sometimes the websocket does not close properly. When websocket connections exceed the limitations, a `SecurityError` will be thrown. This error will not affect the Angular application, you can restart IE to clear this error, or modify the windows registry to update the limitations. ## Appendix: Test using `fakeAsync()/waitForAsync()` diff --git a/aio/content/guide/upgrade.md b/aio/content/guide/upgrade.md index 64801c086b..45976e6302 100644 --- a/aio/content/guide/upgrade.md +++ b/aio/content/guide/upgrade.md @@ -3,7 +3,7 @@ _Angular_ is the name for the Angular of today and tomorrow.
_AngularJS_ is the name for all 1.x versions of Angular. -AngularJS apps are great. +AngularJS applications are great. Always consider the business case before moving to Angular. An important part of that case is the time and effort to get there. This guide describes the built-in tools for efficiently migrating AngularJS projects over to the @@ -30,7 +30,7 @@ make incremental upgrading seamless. There are many ways to structure AngularJS applications. When you begin to upgrade these applications to Angular, some will turn out to be much more easy to work with than others. There are a few key techniques -and patterns that you can apply to future proof apps even before you +and patterns that you can apply to future proof applications even before you begin the migration. {@a follow-the-angular-styleguide} @@ -46,8 +46,8 @@ importantly - how **not** to write and organize AngularJS code. Angular is a reimagined version of the best parts of AngularJS. In that sense, its goals are the same as the AngularJS Style Guide's: To preserve the good parts of AngularJS, and to avoid the bad parts. There's a lot -more to Angular than just that of course, but this does mean that -*following the style guide helps make your AngularJS app more closely +more to Angular than that of course, but this does mean that +*following the style guide helps make your AngularJS application more closely aligned with Angular*. There are a few rules in particular that will make it much easier to do @@ -284,7 +284,7 @@ owned by AngularJS, Angular treats it as if it didn't exist, and vice versa. So normally a hybrid application begins life as an AngularJS application, -and it is AngularJS that processes the root template, e.g. the index.html. +and it is AngularJS that processes the root template, for example, the index.html. Angular then steps into the picture when an Angular component is used somewhere in an AngularJS template. That component's template will then be managed by Angular, and it may contain any number of Angular components and @@ -404,7 +404,7 @@ be used to bootstrap the AngularJS application. Pure AngularJS applications can be automatically bootstrapped by using an `ng-app` -directive somewhere on the HTML page. But for hybrid applications, you manually bootstrap via the +directive somewhere on the HTML page. But for hybrid applications, you manually bootstrap using the `UpgradeModule`. Therefore, it is a good preliminary step to switch AngularJS applications to use the manual JavaScript [`angular.bootstrap`](https://docs.angularjs.org/api/ng/function/angular.bootstrap) method even before switching them to hybrid mode. @@ -424,7 +424,7 @@ will result in the same thing: To begin converting your AngularJS application to a hybrid, you need to load the Angular framework. You can see how this can be done with SystemJS by following the instructions in [Setup for Upgrading to AngularJS](guide/upgrade-setup) for selectively copying code from the [QuickStart github repository](https://github.com/angular/quickstart). -You also need to install the `@angular/upgrade` package via `npm install @angular/upgrade --save` +You also need to install the `@angular/upgrade` package using `npm install @angular/upgrade --save` and add a mapping for the `@angular/upgrade/static` package: @@ -435,12 +435,12 @@ Next, create an `app.module.ts` file and add the following `NgModule` class: -This bare minimum `NgModule` imports `BrowserModule`, the module every Angular browser-based app must have. +This bare minimum `NgModule` imports `BrowserModule`, the module every Angular browser-based application must have. It also imports `UpgradeModule` from `@angular/upgrade/static`, which exports providers that will be used for upgrading and downgrading services and components. In the constructor of the `AppModule`, use dependency injection to get a hold of the `UpgradeModule` instance, -and use it to bootstrap the AngularJS app in the `AppModule.ngDoBootstrap` method. +and use it to bootstrap the AngularJS application in the `AppModule.ngDoBootstrap` method. The `upgrade.bootstrap` method takes the exact same arguments as [angular.bootstrap](https://docs.angularjs.org/api/ng/function/angular.bootstrap):
@@ -467,7 +467,7 @@ code. One of the more common patterns for doing that is to use an Angular compon in an AngularJS context. This could be a completely new component or one that was previously AngularJS but has been rewritten for Angular. -Say you have a simple Angular component that shows information about a hero: +Say you have an Angular component that shows information about a hero: @@ -482,7 +482,7 @@ using the `downgradeComponent()` method. The result is an AngularJS
By default, Angular change detection will also run on the component for every -AngularJS `$digest` cycle. If you wish to only have change detection run when +AngularJS `$digest` cycle. If you want to only have change detection run when the inputs change, you can set `propagateDigest` to `false` when calling `downgradeComponent()`. @@ -590,7 +590,7 @@ The safest bet for ensuring compatibility is using the [component API](https://docs.angularjs.org/api/ng/type/angular.Module) introduced in AngularJS 1.5. -A simple example of an upgradable component is one that just has a template +An example of an upgradable component is one that just has a template and a controller: @@ -791,7 +791,7 @@ compilation can pick it up.
**Note:** The 'heroes' string inside the factory refers to the AngularJS `HeroesService`. -It is common in AngularJS apps to choose a service name for the token, for example "heroes", +It is common in AngularJS applications to choose a service name for the token, for example "heroes", and append the "Service" suffix to create the class name.
@@ -860,7 +860,7 @@ In most environments where both Angular and AngularJS are used to render the app Overall application performance is affected in cases where the user stays on Angular-rendered pages because the AngularJS framework and application are still loaded and running, even if they are never accessed. -You can take steps to mitigate both bundle size and performance issues. By isolating your AngularJS app to a separate bundle, you can take advantage of [lazy loading](guide/glossary#lazy-loading) to load, bootstrap, and render the AngularJS application only when needed. This strategy reduces your initial bundle size, defers any potential impact from loading both frameworks until absolutely necessary, and keeps your application running as efficiently as possible. +You can take steps to mitigate both bundle size and performance issues. By isolating your AngularJS application to a separate bundle, you can take advantage of [lazy loading](guide/glossary#lazy-loading) to load, bootstrap, and render the AngularJS application only when needed. This strategy reduces your initial bundle size, defers any potential impact from loading both frameworks until absolutely necessary, and keeps your application running as efficiently as possible. The steps below show you how to do the following: @@ -871,19 +871,19 @@ The steps below show you how to do the following: ### Create a service to lazy load AngularJS -As of Angular version 8, lazy loading code can be accomplished simply by using the dynamic import syntax `import('...')`. In your application, you create a new service that uses dynamic imports to lazy load AngularJS. +As of Angular version 8, lazy loading code can be accomplished by using the dynamic import syntax `import('...')`. In your application, you create a new service that uses dynamic imports to lazy load AngularJS. -The service uses the `import()` method to load your bundled AngularJS application lazily. This decreases the initial bundle size of your application as you're not loading code your user doesn't need yet. You also need to provide a way to _bootstrap_ the application manually after it has been loaded. AngularJS provides a way to manually bootstrap an application using the [angular.bootstrap()](https://docs.angularjs.org/api/ng/function/angular.bootstrap) method with a provided HTML element. Your AngularJS app should also expose a `bootstrap` method that bootstraps the AngularJS app. +The service uses the `import()` method to load your bundled AngularJS application lazily. This decreases the initial bundle size of your application as you're not loading code your user doesn't need yet. You also need to provide a way to _bootstrap_ the application manually after it has been loaded. AngularJS provides a way to manually bootstrap an application using the [angular.bootstrap()](https://docs.angularjs.org/api/ng/function/angular.bootstrap) method with a provided HTML element. Your AngularJS application should also expose a `bootstrap` method that bootstraps the AngularJS app. To ensure any necessary teardown is triggered in the AngularJS app, such as removal of global listeners, you also implement a method to call the `$rootScope.destroy()` method. -Your AngularJS application is configured with only the routes it needs to render content. The remaining routes in your application are handled by the Angular Router. The exposed `bootstrap` method is called in your Angular app to bootstrap the AngularJS application after the bundle is loaded. +Your AngularJS application is configured with only the routes it needs to render content. The remaining routes in your application are handled by the Angular Router. The exposed `bootstrap` method is called in your Angular application to bootstrap the AngularJS application after the bundle is loaded.
@@ -893,7 +893,7 @@ Your AngularJS application is configured with only the routes it needs to render ### Create a component to render AngularJS content -In your Angular application, you need a component as a placeholder for your AngularJS content. This component uses the service you create to load and bootstrap your AngularJS app after the component is initialized. +In your Angular application, you need a component as a placeholder for your AngularJS content. This component uses the service you create to load and bootstrap your AngularJS application after the component is initialized. @@ -914,7 +914,7 @@ The following code adds a route object to your routing configuration using the ` -When your application matches a route that needs AngularJS, the AngularJS app is loaded and bootstrapped, the AngularJS routes match the necessary URL to render their content, and your application continues to run with both AngularJS and Angular frameworks. +When your application matches a route that needs AngularJS, the AngularJS application is loaded and bootstrapped, the AngularJS routes match the necessary URL to render their content, and your application continues to run with both AngularJS and Angular frameworks. ## Using the Unified Angular Location Service @@ -999,7 +999,7 @@ And that's all you need do to get the full benefit of AOT for Angular apps! ## PhoneCat Upgrade Tutorial In this section, you'll learn to prepare and upgrade an application with `ngUpgrade`. -The example app is [Angular PhoneCat](https://github.com/angular/angular-phonecat) +The example application is [Angular PhoneCat](https://github.com/angular/angular-phonecat) from [the original AngularJS tutorial](https://docs.angularjs.org/tutorial), which is where many of us began our Angular adventures. Now you'll see how to bring that application to the brave new world of Angular. @@ -1220,7 +1220,7 @@ Keep this process running in the background, watching and recompiling as you mak Next, convert your current JavaScript files into TypeScript. Since TypeScript is a super-set of ECMAScript 2015, which in turn is a super-set -of ECMAScript 5, you can simply switch the file extensions from `.js` to `.ts` +of ECMAScript 5, you can switch the file extensions from `.js` to `.ts` and everything will work just like it did before. As the TypeScript compiler runs, it emits the corresponding `.js` file for every `.ts` file and the compiled JavaScript is what actually gets executed. If you start @@ -1230,7 +1230,7 @@ application in your browser. Now that you have TypeScript though, you can start benefiting from some of its features. There's a lot of value the language can provide to AngularJS applications. -For one thing, TypeScript is a superset of ES2015. Any app that has previously +For one thing, TypeScript is a superset of ES2015. Any application that has previously been written in ES5 - like the PhoneCat example has - can with TypeScript start incorporating all of the JavaScript features that are new to ES2015. These include things like `let`s and `const`s, arrow functions, default function @@ -1348,7 +1348,7 @@ Once these are done, run: npm install -Soon you can load Angular dependencies into the application via `index.html`, +Soon you can load Angular dependencies into the application using `index.html`, but first you need to do some directory path adjustments. You'll need to load files from `node_modules` and the project root instead of from the `/app` directory as you've been doing to this point. @@ -1369,8 +1369,8 @@ cause relative URLs to be resolved back to the `/app` directory: -Now you can load Angular via SystemJS. You'll add the Angular polyfills and the -SystemJS config to the end of the `` section, and then you'll use `System.import` +Now you can load Angular using SystemJS. You'll add the Angular polyfills and the +SystemJS configuration to the end of the `` section, and then you'll use `System.import` to load the actual application: @@ -1382,7 +1382,7 @@ to the `systemjs.config.js` file installed during [upgrade setup](guide/upgrade- Point the browser to the project root when loading things through SystemJS, instead of using the `` URL. -Install the `upgrade` package via `npm install @angular/upgrade --save` +Install the `upgrade` package using `npm install @angular/upgrade --save` and add a mapping for the `@angular/upgrade/static` package. @@ -1411,7 +1411,7 @@ you can start converting the individual pieces to Angular. The application is currently bootstrapped using the AngularJS `ng-app` directive attached to the `` element of the host page. This will no longer work in the hybrid -app. Switch to the [ngUpgrade bootstrap](#bootstrapping-hybrid-applications) method +application. Switch to the [ngUpgrade bootstrap](#bootstrapping-hybrid-applications) method instead. First, remove the `ng-app` attribute from `index.html`. @@ -1442,12 +1442,12 @@ exciting! You're not running any actual Angular components yet. That's next. `@types/angular` is declared as a UMD module, and due to the way UMD typings work, once you have an ES6 `import` statement in a file all UMD typed modules must also be -imported via `import` statements instead of being globally available. +imported using `import` statements instead of being globally available. AngularJS is currently loaded by a script tag in `index.html`, which means that the whole app has access to it as a global and uses the same instance of the `angular` variable. If you used `import * as angular from 'angular'` instead, you'd also have to -load every file in the AngularJS app to use ES2015 modules in order to ensure AngularJS was being +load every file in the AngularJS application to use ES2015 modules in order to ensure AngularJS was being loaded correctly. This is a considerable effort and it often isn't worth it, especially since you are in the @@ -1624,7 +1624,7 @@ which was injected into `PhoneDetails` when it was still an AngularJS controller You intend to inject it into the new `PhoneDetailsComponent`. Unfortunately, AngularJS dependencies are not automatically available to Angular components. -You must upgrade this service via a [factory provider](guide/upgrade#making-angularjs-dependencies-injectable-to-angular) +You must upgrade this service using a [factory provider](guide/upgrade#making-angularjs-dependencies-injectable-to-angular) to make `$routeParams` an Angular injectable. Do that in a new file called `ajs-upgraded-providers.ts` and import it in `app.module.ts`: @@ -1708,7 +1708,7 @@ as well: These files need to be copied together with the polyfills. The files the application needs at runtime, like the `.json` phone lists and images, also need to be copied. -Install `fs-extra` via `npm install fs-extra --save-dev` for better file copying, and change +Install `fs-extra` using `npm install fs-extra --save-dev` for better file copying, and change `copy-dist-files.js` to the following: @@ -1729,13 +1729,13 @@ Like all routers, it needs a place in the UI to display routed views. For Angular that's the `` and it belongs in a *root component* at the top of the applications component tree. -You don't yet have such a root component, because the app is still managed as an AngularJS app. +You don't yet have such a root component, because the application is still managed as an AngularJS app. Create a new `app.component.ts` file with the following `AppComponent` class: -It has a simple template that only includes the ``. +It has a template that only includes the ``. This component just renders the contents of the active route and nothing else. The selector tells Angular to plug this root component into the `` @@ -1765,7 +1765,7 @@ instead of the default "push state" strategy. Now update the `AppModule` to import this `AppRoutingModule` and also the declare the root `AppComponent` as the bootstrap component. -That tells Angular that it should bootstrap the app with the _root_ `AppComponent` and +That tells Angular that it should bootstrap the application with the _root_ `AppComponent` and insert its view into the host web page. You must also remove the bootstrap of the AngularJS module from `ngDoBootstrap()` in `app.module.ts` @@ -1868,7 +1868,7 @@ break during the upgrade. E2E tests are especially useful for this purpose. The PhoneCat project has both E2E Protractor tests and some Karma unit tests in it. Of these two, E2E tests can be dealt with much more easily: By definition, E2E tests access the application from the *outside* by interacting with -the various UI elements the app puts on the screen. E2E tests aren't really that +the various UI elements the application puts on the screen. E2E tests aren't really that concerned with the internal structure of the application components. That also means that, although you modify the project quite a bit during the upgrade, the E2E test suite should keep passing with just minor modifications. You @@ -1878,7 +1878,7 @@ During TypeScript conversion, there is nothing to do to keep E2E tests working. But when you change the bootstrap to that of a Hybrid app, you must make a few changes. -Update the `protractor-conf.js` to sync with hybrid apps: +Update the `protractor-conf.js` to sync with hybrid applications: ng12Hybrid: true @@ -1991,7 +1991,7 @@ For PhoneCat you need to make the following changes in order to make things work When the bootstrap method is switched from that of `UpgradeModule` to pure Angular, AngularJS ceases to exist on the page completely. At this point, you need to tell Protractor that it should not be looking for -an AngularJS app anymore, but instead it should find *Angular apps* from +an AngularJS application anymore, but instead it should find *Angular apps* from the page. Replace the `ng12Hybrid` previously added with the following in `protractor-conf.js`: