diff --git a/aio/content/guide/creating-libraries.md b/aio/content/guide/creating-libraries.md index c5306e1f08..3b3c157d65 100644 --- a/aio/content/guide/creating-libraries.md +++ b/aio/content/guide/creating-libraries.md @@ -2,8 +2,8 @@ This page provides a conceptual overview of how you can create and publish new libraries to extend Angular functionality. -If you find that you need to solve the same problem in more than one app (or want to share your solution with other developers), you have a candidate for a library. -A simple example might be a button that sends users to your company website, that would be included in all apps that your company builds. +If you find that you need to solve the same problem in more than one application (or want to share your solution with other developers), you have a candidate for a library. +A simple example might be a button that sends users to your company website, that would be included in all applications that your company builds. ## Getting started @@ -50,7 +50,7 @@ You can build, test, and lint the project with CLI commands: ng lint my-lib -Notice that the configured builder for the project is different from the default builder for app projects. +Notice that the configured builder for the project is different from the default builder for application projects. This builder, among other things, ensures that the library is always built with the [AOT compiler](guide/aot-compiler). To make library code reusable you must define a public API for it. This "user layer" defines what is available to consumers of your library. A user of your library should be able to access public functionality (such as NgModules, service providers and general utility functions) through a single import path. @@ -89,7 +89,7 @@ Here are some things to consider in migrating application functionality to a lib ## Integrating with the CLI using code-generation schematics -A library typically includes *reusable code* that defines components, services, and other Angular artifacts (pipes, directives, and so on) that you simply import into a project. +A library typically includes *reusable code* that defines components, services, and other Angular artifacts (pipes, directives) that you import into a project. A library is packaged into an npm package for publishing and sharing. This package can also include [schematics](guide/glossary#schematic) that provide instructions for generating or transforming code directly in your project, in the same way that the CLI creates a generic new component with `ng generate component`. A schematic that is packaged with a library can, for example, provide the Angular CLI with the information it needs to generate a component that configures and uses a particular feature, or set of features, defined in that library. @@ -99,13 +99,13 @@ You can create and include the following kinds of schematics: * Include an installation schematic so that `ng add` can add your library to a project. -* Include generation schematics in your library so that `ng generate` can scaffold your defined artifacts (components, services, tests, and so on) in a project. +* Include generation schematics in your library so that `ng generate` can scaffold your defined artifacts (components, services, tests) in a project. * Include an update schematic so that `ng update` can update your library’s dependencies and provide migrations for breaking changes in new releases. What you include in your library depends on your task. -For example, you could define a schematic to create a dropdown that is pre-populated with canned data to show how to add it to an app. -If you want a dropdown that would contain different passed-in values each time, your library could define a schematic to create it with a given configuration. Developers could then use `ng generate` to configure an instance for their own app. +For example, you could define a schematic to create a dropdown that is pre-populated with canned data to show how to add it to an application. +If you want a dropdown that would contain different passed-in values each time, your library could define a schematic to create it with a given configuration. Developers could then use `ng generate` to configure an instance for their own application. Suppose you want to read a configuration file and then generate a form based on that configuration. If that form will need additional customization by the developer who is using your library, it might work best as a schematic. @@ -135,7 +135,6 @@ npm publish - {@a lib-assets} ## Managing assets in a library @@ -166,7 +165,7 @@ A linked library will then have its own set of Angular libraries that it uses fo However, this can cause problems while building or running your application. To get around this problem you can use TypeScript path mapping to tell TypeScript that it should load some modules from a specific location. -List all the peer dependencies that your library uses in the workspace TypeScript configuration file `./tsconfig.json`, and point them at the local copy in the app's `node_modules` folder. +List all the peer dependencies that your library uses in the workspace TypeScript configuration file `./tsconfig.json`, and point them at the local copy in the application's `node_modules` folder. ``` { @@ -187,7 +186,7 @@ This mapping ensures that your library always loads the local copies of the modu ## Using your own library in apps -You don't have to publish your library to the npm package manager in order to use it in your own apps, but you do have to build it first. +You don't have to publish your library to the npm package manager in order to use it in your own applications, but you do have to build it first. To use your own library in an app: @@ -196,14 +195,14 @@ To use your own library in an app: ng build my-lib -* In your apps, import from the library by name: +* In your applications, import from the library by name: ``` import { myExport } from 'my-lib'; ``` ### Building and rebuilding your library -The build step is important if you haven't published your library as an npm package and then installed the package back into your app from npm. +The build step is important if you haven't published your library as an npm package and then installed the package back into your application from npm. For instance, if you clone your git repository and run `npm install`, your editor will show the `my-lib` imports as missing if you haven't yet built your library.
@@ -216,13 +215,13 @@ The Angular CLI uses the `tsconfig` paths to tell the build system where to find
-If you find that changes to your library are not reflected in your app, your app is probably using an old build of the library. +If you find that changes to your library are not reflected in your application, your app is probably using an old build of the library. You can rebuild your library whenever you make changes to it, but this extra step takes time. *Incremental builds* functionality improves the library-development experience. Every time a file is changed a partial build is performed that emits the amended files. -Incremental builds can be run as a background process in your dev environment. To take advantage of this feature add the `--watch` flag to the build command: +Incremental builds can be run as a background process in your development environment. To take advantage of this feature add the `--watch` flag to the build command: ng build my-lib --watch @@ -232,13 +231,13 @@ ng build my-lib --watch The CLI `build` command uses a different builder and invokes a different build tool for libraries than it does for applications. -* The build system for apps, `@angular-devkit/build-angular`, is based on `webpack`, and is included in all new Angular CLI projects. +* The build system for applications, `@angular-devkit/build-angular`, is based on `webpack`, and is included in all new Angular CLI projects. * The build system for libraries is based on `ng-packagr`. It is only added to your dependencies when you add a library using `ng generate library my-lib`. The two build systems support different things, and even where they support the same things, they do those things differently. This means that the TypeScript source can result in different JavaScript code in a built library than it would in a built application. -For this reason, an app that depends on a library should only use TypeScript path mappings that point to the *built library*. +For this reason, an application that depends on a library should only use TypeScript path mappings that point to the *built library*. TypeScript path mappings should *not* point to the library source `.ts` files. diff --git a/aio/content/guide/forms.md b/aio/content/guide/forms.md index 71fe2eb035..4da2ceb83c 100644 --- a/aio/content/guide/forms.md +++ b/aio/content/guide/forms.md @@ -72,7 +72,7 @@ Every hero needs a job. This form helps the agency match the right hero with the The form highlights some design features that make it easier to use. For instance, the two required fields have a green bar on the left to make them easy to spot. These fields have initial values, so the form is valid and the **Submit** button is enabled. As you work with this form, you will learn how to include validation logic, how to customize the presentation with standard CSS, and how to handle error conditions to ensure valid input. -If the user deletes the hero name, for example, the form becomes invalid. The app detects the changed status, and displays a validation error in an attention-grabbing style. +If the user deletes the hero name, for example, the form becomes invalid. The application detects the changed status, and displays a validation error in an attention-grabbing style. In addition, the **Submit** button is disabled, and the "required" bar to the left of the input control changes from green to red.
@@ -138,7 +138,7 @@ template using the `` tag. At this point, the form layout is all plain HTML5, with no bindings or directives. 6. The sample form uses some style classes from [Twitter Bootstrap](https://getbootstrap.com/css/): `container`, `form-group`, `form-control`, and `btn`. - To use these styles, the app's style sheet imports the library. + To use these styles, the application's style sheet imports the library. @@ -148,7 +148,7 @@ template using the `` tag. -If you run the app right now, you see the list of powers in the selection control. The input elements are not yet bound to data values or events, so they are still blank and have no behavior. +If you run the application right now, you see the list of powers in the selection control. The input elements are not yet bound to data values or events, so they are still blank and have no behavior.
Early form with no binding @@ -230,7 +230,7 @@ After these revisions, the form template should look like the following: * Each `` element also has the required `name` property that Angular uses to register the control with the form. -If you run the app now and change every hero model property, the form might display like this: +If you run the application now and change every hero model property, the form might display like this:
ngModel in action @@ -433,7 +433,7 @@ To let form users add a new hero, you will add a **New Hero** button that respon 5. Enter a name and click **New Hero** again. - Now the app displays a _Name is required_ error message, because the input box is no longer pristine. + Now the application displays a _Name is required_ error message, because the input box is no longer pristine. The form remembers that you entered a name before clicking **New Hero**. 6. To restore the pristine state of the form controls, clear all of the flags imperatively by calling the form's `reset()` method after calling the `newHero()` method. diff --git a/aio/content/guide/libraries.md b/aio/content/guide/libraries.md index 539c8949a7..3bdd857f0b 100644 --- a/aio/content/guide/libraries.md +++ b/aio/content/guide/libraries.md @@ -1,17 +1,17 @@ # Overview of Angular libraries Many applications need to solve the same general problems, such as presenting a unified user interface, presenting data, and allowing data entry. -Developers can create general solutions for particular domains that can be adapted for re-use in different apps. +Developers can create general solutions for particular domains that can be adapted for re-use in different applications. Such a solution can be built as Angular *libraries* and these libraries can be published and shared as *npm packages*. -An Angular library is an Angular [project](guide/glossary#project) that differs from an app in that it cannot run on its own. -A library must be imported and used in an app. +An Angular library is an Angular [project](guide/glossary#project) that differs from an application in that it cannot run on its own. +A library must be imported and used in an application. Libraries extend Angular's base functionality. For example, to add [reactive forms](guide/reactive-forms) to an app, add the library package using `ng add @angular/forms`, then import the `ReactiveFormsModule` from the `@angular/forms` library in your application code. Similarly, adding the [service worker](guide/service-worker-intro) library to an Angular application is one of the steps for turning an application into a [Progressive Web App](https://developers.google.com/web/progressive-web-apps/) (PWA). [Angular Material](https://material.angular.io/) is an example of a large, general-purpose library that provides sophisticated, reusable, and adaptable UI components. -Any app developer can use these and other libraries that have been published as npm packages by the Angular team or by third parties. See [Using Published Libraries](guide/using-libraries). +Any application developer can use these and other libraries that have been published as npm packages by the Angular team or by third parties. See [Using Published Libraries](guide/using-libraries). ## Creating libraries @@ -25,13 +25,13 @@ Whether you decide to package functionality as a library is an architectural dec Packaging functionality as a library forces the artifacts in the library to be decoupled from the application's business logic. This can help to avoid various bad practices or architecture mistakes that can make it difficult to decouple and reuse code in the future. -Putting code into a separate library is more complex than simply putting everything in one app. +Putting code into a separate library is more complex than simply putting everything in one application. It requires more of an investment in time and thought for managing, maintaining, and updating the library. -This complexity can pay off, however, when the library is being used in multiple apps. +This complexity can pay off, however, when the library is being used in multiple applications.
-Note that libraries are intended to be used by Angular apps. -To add Angular functionality to non-Angular web apps, you can use [Angular custom elements](guide/elements). +Note that libraries are intended to be used by Angular applications. +To add Angular functionality to non-Angular web applications, you can use [Angular custom elements](guide/elements).
diff --git a/aio/content/guide/router-tutorial-toh.md b/aio/content/guide/router-tutorial-toh.md index 34ecfc5dea..a540951d29 100644 --- a/aio/content/guide/router-tutorial-toh.md +++ b/aio/content/guide/router-tutorial-toh.md @@ -25,7 +25,7 @@ Along the way, it highlights key features of the router such as: * Lazy loading an `NgModule`. * The `CanLoad` guard (check before loading feature module assets). -This guide proceeds as a sequence of milestones as if you were building the app step-by-step, but assumes you are familiar with basic [Angular concepts](guide/architecture). +This guide proceeds as a sequence of milestones as if you were building the application step-by-step, but assumes you are familiar with basic [Angular concepts](guide/architecture). For a general introduction to angular, see the [Getting Started](start). For a more in-depth overview, see the [Tour of Heroes](tutorial) tutorial. ## Prerequisites @@ -52,7 +52,7 @@ The application has three main feature areas: Try it by clicking on this live example link. -The app renders with a row of navigation buttons and the *Heroes* view with its list of heroes. +The application renders with a row of navigation buttons and the *Heroes* view with its list of heroes.
@@ -61,7 +61,7 @@ The app renders with a row of navigation buttons and the *Heroes* view with its -Select one hero and the app takes you to a hero editing screen. +Select one hero and the application takes you to a hero editing screen.
Crisis Center Detail @@ -70,11 +70,11 @@ Select one hero and the app takes you to a hero editing screen. Alter the name. -Click the "Back" button and the app returns to the heroes list which displays the changed hero name. +Click the "Back" button and the application returns to the heroes list which displays the changed hero name. Notice that the name change took effect immediately. -Had you clicked the browser's back button instead of the app's "Back" button, the app would have returned you to the heroes list as well. -Angular app navigation updates the browser history as normal web navigation does. +Had you clicked the browser's back button instead of the application's "Back" button, the app would have returned you to the heroes list as well. +Angular application navigation updates the browser history as normal web navigation does. Now click the *Crisis Center* link for a list of ongoing crises. @@ -119,7 +119,7 @@ The `Admin` and `Login` buttons illustrate other router capabilities covered lat ## Milestone 1: Getting started -Begin with a basic version of the app that navigates between two empty views. +Begin with a basic version of the application that navigates between two empty views.
@@ -221,7 +221,7 @@ The corresponding component template looks like this: ### Define a Wildcard route -You've created two routes in the app so far, one to `/crisis-center` and the other to `/heroes`. +You've created two routes in the application so far, one to `/crisis-center` and the other to `/heroes`. Any other URL causes the router to throw an error and crash the app. Add a wildcard route to intercept invalid URLs and handle them gracefully. @@ -272,8 +272,8 @@ When the application launches, the initial URL in the browser bar is by default: That doesn't match any of the hard-coded routes which means the router falls through to the wildcard route and displays the `PageNotFoundComponent`. The application needs a default route to a valid page. -The default page for this app is the list of heroes. -The app should navigate there as if the user clicked the "Heroes" link or pasted `localhost:4200/heroes` into the address bar. +The default page for this application is the list of heroes. +The application should navigate there as if the user clicked the "Heroes" link or pasted `localhost:4200/heroes` into the address bar. Add a `redirect` route that translates the initial relative URL (`''`) to the desired default path (`/heroes`). @@ -298,7 +298,7 @@ In this app, the router should select the route to the `HeroListComponent` only In this example, the redirect is in a top level route so the *remaining* URL and the *entire* URL are the same thing. The other possible `pathMatch` value is `'prefix'` which tells the router to match the redirect route when the remaining URL begins with the redirect route's prefix path. - This doesn't apply to this sample app because if the `pathMatch` value were `'prefix'`, every URL would match `''`. + This doesn't apply to this sample application because if the `pathMatch` value were `'prefix'`, every URL would match `''`. Try setting it to `'prefix'` and clicking the `Go to sidekicks` button. Since that's a bad URL, you should see the "Page not found" page. @@ -317,7 +317,7 @@ In this app, the router should select the route to the `HeroListComponent` only ### Milestone 1 wrap up -Your sample app can switch between two views when the user clicks a link. +Your sample application can switch between two views when the user clicks a link. Milestone 1 has covered how to do the following: @@ -327,9 +327,9 @@ Milestone 1 has covered how to do the following: * Configure the router module with `RouterModule.forRoot()`. * Set the router to compose HTML5 browser URLs. * Handle invalid routes with a `wildcard` route. -* Navigate to the default route when the app launches with an empty path. +* Navigate to the default route when the application launches with an empty path. -The starter app's structure looks like this: +The starter application's structure looks like this:
@@ -515,7 +515,7 @@ Here are the files in this milestone. ## Milestone 2: *Routing module* -This milestone shows you how to configure a special-purpose module called a *Routing Module*, which holds your app's routing configuration. +This milestone shows you how to configure a special-purpose module called a *Routing Module*, which holds your application's routing configuration. The Routing Module has several characteristics: @@ -530,7 +530,7 @@ The Routing Module has several characteristics: The sample routing application does not include routing by default. When you use the [Angular CLI](cli) to create a project that does use routing, set the `--routing` option for the project or app, and for each NgModule. -When you create or initialize a new project (using the CLI [`ng new`](cli/new) command) or a new app (using the [`ng generate app`](cli/generate) command), specify the `--routing` option. +When you create or initialize a new project (using the CLI [`ng new`](cli/new) command) or a new application (using the [`ng generate app`](cli/generate) command), specify the `--routing` option. This tells the CLI to include the `@angular/router` npm package and create a file named `app-routing.module.ts`. You can then use routing in any NgModule that you add to the project or app. @@ -554,8 +554,7 @@ Create an `AppRouting` module in the `/app` folder to contain the routing config ng generate module app-routing --module app --flat -Import the `CrisisListComponent`, `HeroListComponent`, and `PageNotFoundComponent` symbols -just like you did in the `app.module.ts`. +Import the `CrisisListComponent`, `HeroListComponent`, and `PageNotFoundComponent` symbols like you did in the `app.module.ts`. Then move the `Router` imports and routing configuration, including `RouterModule.forRoot()`, into this routing module. Re-export the Angular `RouterModule` by adding it to the module `exports` array. @@ -583,11 +582,11 @@ The application continues to work just the same, and you can use `AppRoutingModu The routing module, often called the `AppRoutingModule`, replaces the routing configuration in the root or feature module. -The routing module is helpful as your app grows and when the configuration includes specialized guard and resolver services. +The routing module is helpful as your application grows and when the configuration includes specialized guard and resolver services. Some developers skip the routing module when the configuration is minimal and merge the routing configuration directly into the companion module (for example, `AppModule`). -Most apps should implement a routing module for consistency. +Most applications should implement a routing module for consistency. It keeps the code clean when configuration becomes complex. It makes testing the feature module easier. Its existence calls attention to the fact that a module is routed. @@ -599,11 +598,11 @@ It is where developers expect to find and expand routing configuration. This milestone covers the following: -* Organizing the app and routes into feature areas using modules. +* Organizing the application and routes into feature areas using modules. * Navigating imperatively from one component to another. * Passing required and optional information in route parameters. -This sample app recreates the heroes feature in the "Services" section of the [Tour of Heroes tutorial](tutorial/toh-pt4 "Tour of Heroes: Services"), and reuses much of the code from the . +This sample application recreates the heroes feature in the "Services" section of the [Tour of Heroes tutorial](tutorial/toh-pt4 "Tour of Heroes: Services"), and reuses much of the code from the .