diff --git a/aio/content/file-not-found.md b/aio/content/file-not-found.md index cdd57442d411a..46092603ceb6c 100644 --- a/aio/content/file-not-found.md +++ b/aio/content/file-not-found.md @@ -1,7 +1,7 @@ @description
- +

Page Not Found

We're sorry. The page you are looking for cannot be found.

diff --git a/aio/content/guide/animations.md b/aio/content/guide/animations.md index a37f7368b8964..aecf3ede5a34a 100644 --- a/aio/content/guide/animations.md +++ b/aio/content/guide/animations.md @@ -11,11 +11,8 @@ Angular's animation system lets you build animations that run with the same kind performance found in pure CSS animations. You can also tightly integrate your animation logic with the rest of your application code, for ease of control. -
- - Angular animations are built on top of the standard [Web Animations API](https://w3c.github.io/web-animations/) and run natively on [browsers that support it](http://caniuse.com/#feat=web-animation). @@ -23,11 +20,8 @@ For other browsers, a polyfill is required. Grab [`web-animations.min.js` from GitHub](https://github.com/web-animations/web-animations-js) and add it to your page. - -
- -
- - - ## Services -
- Service -
- - +Service _Service_ is a broad category encompassing any value, function, or feature that your application needs. @@ -581,22 +413,12 @@ Yet services are fundamental to any Angular application. Components are big cons Here's an example of a service class that logs to the browser console: - - - - - - + Here's a `HeroService` that uses a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) to fetch heroes. The `HeroService` depends on the `Logger` service and another `BackendService` that handles the server communication grunt work. - - - - - - + Services are everywhere. @@ -615,33 +437,23 @@ It won't complain if you write a "kitchen sink" component with 3000 lines. Angular does help you *follow* these principles by making it easy to factor your application logic into services and make those services available to components through *dependency injection*. -
- - - ## Dependency injection -
- Service -
- - +Service _Dependency injection_ is a way to supply a new instance of a class with the fully-formed dependencies it requires. Most dependencies are services. -Angular uses dependency injection to provide new components with the services they need.
+Angular uses dependency injection to provide new components with the services they need. + +
Angular can tell which services a component needs by looking at the types of its constructor parameters. For example, the constructor of your `HeroListComponent` needs a `HeroService`: - - - - - + When Angular creates a component, it first asks an **injector** for the services that the component requires. @@ -656,37 +468,25 @@ This is *dependency injection*. The process of `HeroService` injection looks a bit like this:
- Service + Service
- If the injector doesn't have a `HeroService`, how does it know how to make one? In brief, you must have previously registered a **provider** of the `HeroService` with the injector. A provider is something that can create or return a service, typically the service class itself. - You can register providers in modules or in components. In general, add providers to the [root module](guide/architecture#modules) so that the same instance of a service is available everywhere. - - - - - - + Alternatively, register at a component level in the `providers` property of the `@Component` metadata: - - - - - - + Registering at a component level means you get a new instance of the service with each new instance of that component. @@ -706,12 +506,8 @@ Points to remember about dependency injection: * Register *providers* with injectors. -
- - - ## Wrap up You've learned the basics about the eight main building blocks of an Angular application: diff --git a/aio/content/guide/attribute-directives.md b/aio/content/guide/attribute-directives.md index b637e49c376a8..32bbffc884192 100644 --- a/aio/content/guide/attribute-directives.md +++ b/aio/content/guide/attribute-directives.md @@ -1,12 +1,4 @@ -@title -Attribute Directives - -@intro -Attribute directives attach behavior to elements. - -@description - - +# Attribute Directives An **Attribute** directive changes the appearance or behavior of a DOM element. @@ -46,8 +38,6 @@ The built-in [NgStyle](guide/template-syntax#ngStyle) directive in the [Template Syntax](guide/template-syntax) guide, for example, can change several element styles at the same time. - - ## Build a simple attribute directive An attribute directive minimally requires building a controller class annotated with @@ -59,10 +49,7 @@ This page demonstrates building a simple _myHighlight_ attribute directive to set an element's background color when the user hovers over that element. You can apply it like this: - - - - + {@a write-directive} @@ -73,12 +60,7 @@ named attribute-directives. Create the following source file in the indicated folder: - - - - - - + The `import` statement specifies symbols from the Angular `core`: @@ -90,7 +72,6 @@ so the code can access the DOM element. Next, the `@Directive` decorator function contains the directive metadata in a configuration object as an argument. - `@Directive` requires a CSS selector to identify the HTML in the template that is associated with the directive. The [CSS selector for an attribute](https://developer.mozilla.org/en-US/docs/Web/CSS/Attribute_selectors) @@ -98,11 +79,8 @@ is the attribute name in square brackets. Here, the directive's selector is `[myHighlight]`. Angular locates all elements in the template that have an attribute named `myHighlight`. -
- - ### Why not call it "highlight"? Though *highlight* is a more concise name than *myHighlight* and would work, @@ -114,11 +92,9 @@ Make sure you do **not** prefix the `highlight` directive name with **`ng`** bec that prefix is reserved for Angular and using it could cause bugs that are difficult to diagnose. For a simple demo, the short prefix, `my`, helps distinguish your custom directive. -
- After the `@Directive` metadata comes the directive's controller class, called `HighlightDirective`, which contains the logic for the directive. Exporting `HighlightDirective` makes it accessible to other components. @@ -140,71 +116,44 @@ In Angular terms, the `

` element is the attribute **host**. Put the template in its own app.component.html file that looks like this: - - - - - - + Now reference this template in the `AppComponent`: - - - - - - + Next, add an `import` statement to fetch the `Highlight` directive and add that class to the `declarations` NgModule metadata. This way Angular recognizes the directive when it encounters `myHighlight` in the template. - - - - - - + Now when the app runs, the `myHighlight` directive highlights the paragraph text. - -

- First Highlight +
+ First Highlight
- -
- - ### Your directive isn't working? Did you remember to add the directive to the `declarations` attribute of `@NgModule`? It is easy to forget! Open the console in the browser tools and look for an error like this: - EXCEPTION: Template parse errors: Can't bind to 'myHighlight' since it isn't a known property of 'p'. - - - Angular detects that you're trying to bind to *something* but it can't find this directive in the module's `declarations` array. After specifying `HighlightDirective` in the `declarations` array, Angular knows it can apply the directive to components declared in this module. -
- - To summarize, Angular found the `myHighlight` attribute on the `

` element. It created an instance of the `HighlightDirective` class and injected a reference to the `

` element into the directive's constructor @@ -222,31 +171,18 @@ and respond by setting or clearing the highlight color. Begin by adding `HostListener` to the list of imported symbols; add the `Input` symbol as well because you'll need it soon. - - - - - - + Then add two eventhandlers that respond when the mouse enters or leaves, each adorned by the `HostListener` decorator. - - - - - - + The `@HostListener` decorator lets you subscribe to events of the DOM element that hosts an attribute directive, the `

` in this case. -

- - Of course you could reach into the DOM with standard JavaScript and and attach event listeners manually. There are at least three problems with _that_ approach: @@ -254,39 +190,24 @@ There are at least three problems with _that_ approach: 1. The code must *detach* the listener when the directive is destroyed to avoid memory leaks. 1. Talking to DOM API directly isn't a best practice. -
- - The handlers delegate to a helper method that sets the color on the DOM element, `el`, which you declare and initialize in the constructor. - - - - - - + Here's the updated directive in full: - - - - - - + Run the app and confirm that the background color appears when the mouse hovers over the `p` and disappears as it moves out. - -
- Second Highlight +
+ Second Highlight
- {@a bindings} ## Pass values into the directive with an _@Input_ data binding @@ -296,16 +217,10 @@ In this section, you give the developer the power to set the highlight color whi Start by adding a `highlightColor` property to the directive class like this: - - - - - - + {@a input} - ### Binding to an _@Input_ property Notice the `@Input` decorator. It adds metadata to the class that makes the directive's `highlightColor` property available for binding. @@ -315,39 +230,19 @@ Without that input metadata, Angular rejects the binding; see [below](guide/attr Try it by adding the following directive binding variations to the `AppComponent` template: - - - - - - + Add a `color` property to the `AppComponent`. - - - - - - + Let it control the highlight color with a property binding. - - - - - - + That's good, but it would be nice to _simultaneously_ apply the directive and set the color _in the same attribute_ like this. - - - - - - + The `[myHighlight]` attribute binding both applies the highlighting directive to the `

` element and sets the directive's highlight color with a property binding. @@ -356,62 +251,35 @@ That's a crisp, compact syntax. You'll have to rename the directive's `highlightColor` property to `myHighlight` because that's now the color property binding name. - - - - - - + This is disagreeable. The word, `myHighlight`, is a terrible property name and it doesn't convey the property's intent. - {@a input-alias} - ### Bind to an _@Input_ alias Fortunately you can name the directive property whatever you want _and_ **_alias it_** for binding purposes. Restore the original property name and specify the selector as the alias in the argument to `@Input`. - - - - - - + _Inside_ the directive the property is known as `highlightColor`. _Outside_ the directive, where you bind to it, it's known as `myHighlight`. You get the best of both worlds: the property name you want and the binding syntax you want: - - - - - - + Now that you're binding to `highlightColor`, modify the `onMouseEnter()` method to use it. If someone neglects to bind to `highlightColor`, highlight in red: - - - - - - + Here's the latest version of the directive class. - - - - - - + ## Write a harness to try it @@ -421,30 +289,18 @@ lets you pick the highlight color with a radio button and bind your color choice Update app.component.html as follows: - - - - - - + Revise the `AppComponent.color` so that it has no initial value. - - - - - - + Here are the harness and directive in action. - -

- Highlight v.2 +
+ Highlight v.2
- {@a second-property} ## Bind to a second property @@ -457,22 +313,12 @@ Let the template developer set the default color. Add a second **input** property to `HighlightDirective` called `defaultColor`: - - - - - - + Revise the directive's `onMouseEnter` so that it first tries to highlight with the `highlightColor`, then with the `defaultColor`, and falls back to "red" if both properties are undefined. - - - - - - + How do you bind to a second property when you're already binding to the `myHighlight` attribute name? @@ -480,26 +326,17 @@ As with components, you can add as many directive property bindings as you need The developer should be able to write the following template HTML to both bind to the `AppComponent.color` and fall back to "violet" as the default color. - - - - - - + Angular knows that the `defaultColor` binding belongs to the `HighlightDirective` because you made it _public_ with the `@Input` decorator. Here's how the harness should work when you're done coding. - -
- Final Highlight +
+ Final Highlight
- - - ## Summary This page covered how to: @@ -511,33 +348,13 @@ This page covered how to: The final source code follows: - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + @@ -551,21 +368,11 @@ You can also experience and download the - - - - + You've seen it with an alias: - - - - - - + Either way, the `@Input` decorator tells Angular that this property is _public_ and available for binding by a parent component. @@ -597,12 +404,7 @@ You can tell if `@Input` is needed by the position of the property name in a bin Now apply that reasoning to the following example: - - - - - - + * The `color` property in the expression on the right belongs to the template's component. The template and its component trust each other. diff --git a/aio/content/guide/cli-quickstart.md b/aio/content/guide/cli-quickstart.md index 93398910c4479..5ccbf6ca29fd0 100644 --- a/aio/content/guide/cli-quickstart.md +++ b/aio/content/guide/cli-quickstart.md @@ -126,8 +126,8 @@ on `http://localhost:4200/`. Your app greets you with a message: -
- The app works! +
+ The app works!
@@ -147,9 +147,7 @@ You can find it in `./src/app/app.component.ts`. Open the component file and change the `title` property from _app works!_ to _My First Angular App_: - - - + @@ -158,14 +156,12 @@ The browser reloads automatically with the revised title. That's nice, but it co Open `src/app/app.component.css` and give the component some style. - + - - -
- Output of QuickStart app +
+ Output of QuickStart app
@@ -205,103 +201,34 @@ Any files outside of this folder are meant to support building your app.
- -
- src -
- +
src
- -
- app -
- +
app
- -
- app.component.css -
- -
- app.component.html -
- -
- app.component.spec.ts -
- -
- app.component.ts -
- -
- app.module.ts -
- -
- -
- assets +
app.component.css
+
app.component.html
+
app.component.spec.ts
+
app.component.ts
+
app.module.ts
- +
assets
- -
- .gitkeep -
- -
- -
- environments +
.gitkeep
- +
environments
- -
- environment.prod.ts -
- -
- environment.ts -
- -
- -
- favicon.ico -
- -
- index.html -
- -
- main.ts -
- -
- polyfills.ts +
environment.prod.ts
+
environment.ts
- -
- styles.css -
- -
- test.ts -
- -
- tsconfig.app.json -
- -
- tsconfig.spec.json -
- +
favicon.ico
+
index.html
+
main.ts
+
polyfills.ts
+
styles.css
+
test.ts
+
tsconfig.app.json
+
tsconfig.spec.json
-
@@ -313,82 +240,66 @@ Any files outside of this folder are meant to support building your app. - - - - - - - - - - - + + - - - + + - - - + + - - - + + - - - + + - - - + + - - - + + - - - + + - - - + + - - - + - - - + `tsconfig.{app|spec}.json` + - -
File Purpose
- app/app.component.{ts,html,css,spec.ts} - + `app/app.component.{ts,html,css,spec.ts}` + Defines the `AppComponent` along with an HTML template, CSS stylesheet, and a unit test. It is the **root** component of what will become a tree of nested components as the application evolves. -
- app/app.module.ts - + `app/app.module.ts` + Defines `AppModule`, the [root module](guide/appmodule "AppModule: the root module") that tells Angular how to assemble the application. Right now it declares only the `AppComponent`. Soon there will be more components to declare. -
- assets/* - + `assets/*` + A folder where you can put images and anything else to be copied wholesale when you build your application. -
- environments/* - + `environments/*` + This folder contains one file for each of your destination environments, each exporting simple configuration variables to use in your application. @@ -397,215 +308,139 @@ Any files outside of this folder are meant to support building your app. or maybe different analytics tokens. You might even use some mock services. Either way, the CLI has you covered. -
- favicon.ico - + `favicon.ico` + Every site wants to look good on the bookmark bar. Get started with your very own Angular icon. -
- index.html - + `index.html` + The main HTML page that is served when someone visits your site. Most of the time you'll never need to edit it. The CLI automatically adds all `js` and `css` files when building your app so you never need to add any `<script>` or `<link>` tags here manually. -
- main.ts - + `main.ts` + The main entry point for your app. Compiles the application with the [JIT compiler](guide/glossary#jit) and bootstraps the application's root module (`AppModule`) to run in the browser. You can also use the [AOT compiler](guide/glossary#ahead-of-time-aot-compilation) without changing any code by passing in `--aot` to `ng build` or `ng serve`. -
- polyfills.ts - + `polyfills.ts` + Different browsers have different levels of support of the web standards. Polyfills help normalize those differences. You should be pretty safe with `core-js` and `zone.js`, but be sure to check out the [Browser Support guide](guide/browser-support) for more information. -
- styles.css - + `styles.css` + Your global styles go here. Most of the time you'll want to have local styles in your components for easier maintenance, but styles that affect all of your app need to be in a central place. -
- test.ts - + `test.ts` + This is the main entry point for your unit tests. It has some custom configuration that might be unfamiliar, but it's not something you'll need to edit.
- tsconfig.{app|spec}.json - - TypeScript compiler configuration for the Angular app (`tsconfig.app.json`) and for the unit tests (`tsconfig.spec.json`). -
- - - ### The root folder + The `src/` folder is just one of the items inside the project's root folder. Other files help you build, test, maintain, document, and deploy the app. These files go in the root folder next to `src/`.
- -
- my-app -
- +
my-app
- -
- e2e -
- +
e2e
- -
- app.e2e-spec.ts -
- -
- app.po.ts -
- -
- tsconfig.e2e.json -
- -
- -
- node_modules/... -
- -
- src/... -
- -
- .angular-cli.json -
- -
- .editorconfig -
- -
- .gitignore -
- -
- karma.conf.js -
- -
- package.json -
- -
- protractor.conf.js -
- -
- README.md -
- -
- tsconfig.json -
- -
- tslint.json +
app.e2e-spec.ts
+
app.po.ts
+
tsconfig.e2e.json
- +
node_modules/...
+
src/...
+
.angular-cli.json
+
.editorconfig
+
.gitignore
+
karma.conf.js
+
package.json
+
protractor.conf.js
+
README.md
+
tsconfig.json
+
tslint.json
-
- - @@ -613,207 +448,170 @@ These files go in the root folder next to `src/`. - - - - - - - - - - - + + - - - + - - - - + + - - - + + - - - + + - - - + + - - - + + - - - + + - - - + + - - - + + - - - + - -
File Purpose
- e2e/ - + `e2e/` + Inside `e2e/` live the End-to-End tests. They shouldn't be inside `src/` because e2e tests are really a separate app that just so happens to test your main app. That's also why they have their own `tsconfig.e2e.json`. -
- node_modules/ - + `node_modules/` + `Node.js` creates this folder and puts all third party modules listed in `package.json` inside of it.
- .angular-cli.json - + `.angular-cli.json` + Configuration for Angular CLI. In this file you can set several defaults and also configure what files are included when your project is build. Check out the official documentation if you want to know more. -
- .editorconfig - + `.editorconfig` + Simple configuration for your editor to make sure everyone that uses your project has the same basic configuration. Most editors support an `.editorconfig` file. See http://editorconfig.org for more information. -
- .gitignore - + `.gitignore` + Git configuration to make sure autogenerated files are not commited to source control. -
- karma.conf.js - + `karma.conf.js` + Unit test configuration for the [Karma test runner](https://karma-runner.github.io), used when running `ng test`. -
- package.json - + `package.json` + `npm` configuration listing the third party packages your project uses. You can also add your own [custom scripts](https://docs.npmjs.com/misc/scripts) here. -
- protractor.conf.js - + `protractor.conf.js` + End-to-end test configuration for [Protractor](http://www.protractortest.org/), used when running `ng e2e`. -
- README.md - + `README.md` + Basic documentation for your project, pre-filled with CLI command information. Make sure to enhance it with project documentation so that anyone checking out the repo can build your app! -
- tsconfig.json - + `tsconfig.json` + TypeScript compiler configuration for your IDE to pick up and give you helpful tooling. -
- tslint.json - + `tslint.json` + Linting configuration for [TSLint](https://palantir.github.io/tslint/) together with [Codelyzer](http://codelyzer.com/), used when running `ng lint`. Linting helps keep your code style consistent.
- -
- - ### Next Step If you're new to Angular, continue with the @@ -821,4 +619,3 @@ If you're new to Angular, continue with the You can skip the "Setup" step since you're already using the Angular CLI setup.
- diff --git a/aio/content/guide/component-interaction.md b/aio/content/guide/component-interaction.md index c5b4bbd07a8ac..336d9aaf2cc29 100644 --- a/aio/content/guide/component-interaction.md +++ b/aio/content/guide/component-interaction.md @@ -55,8 +55,8 @@ and each iteration's `hero` instance to the child's `hero` property. The running application displays three heroes: -
- Parent-to-child +
+ Parent-to-child
@@ -99,8 +99,8 @@ Here's the `NameParentComponent` demonstrating name variations including a name -
- Parent-to-child-setter +
+ Parent-to-child-setter
@@ -157,8 +157,8 @@ The `VersionParentComponent` supplies the `minor` and `major` values and binds b Here's the output of a button-pushing sequence: -
- Parent-to-child-onchanges +
+ Parent-to-child-onchanges
@@ -211,8 +211,8 @@ The framework passes the event argument—represented by `$event`—to t and the method processes it: -
- Child-to-parent +
+ Child-to-parent
@@ -273,8 +273,8 @@ uses interpolation to display the child's `seconds` property. Here we see the parent and child working together. -
- countdown timer +
+ countdown timer
@@ -425,8 +425,8 @@ the parent `MissionControlComponent` and the `AstronautComponent` children, facilitated by the service: -
- bidirectional-service +
+ bidirectional-service
diff --git a/aio/content/guide/dependency-injection-in-action.md b/aio/content/guide/dependency-injection-in-action.md index 3f1065487412c..8bcdf3a55cc40 100644 --- a/aio/content/guide/dependency-injection-in-action.md +++ b/aio/content/guide/dependency-injection-in-action.md @@ -173,8 +173,8 @@ and the framework does the rest. Once all the dependencies are in place, the `AppComponent` displays the user information: -
- Logged In User +
+ Logged In User
@@ -339,8 +339,8 @@ And the template displays this data-bound property. Find this example in live code and confirm that the three `HeroBioComponent` instances have their own cached hero data. -
- Bios +
+ Bios
@@ -405,8 +405,8 @@ placing it in the `` slot of the `HeroBioComponent` template: It looks like this, with the hero's telephone number from `HeroContactComponent` projected above the hero description: -
- bio and contact +
+ bio and contact
@@ -442,8 +442,8 @@ Thanks to `@Optional()`, Angular sets the `loggerService` to null and the rest o Here's the `HeroBiosAndContactsComponent` in action. -
- Bios with contact into +
+ Bios with contact into
@@ -452,8 +452,8 @@ If you comment out the `@Host()` decorator, Angular now walks up the injector an until it finds the logger at the `AppComponent` level. The logger logic kicks in and the hero display updates with the gratuitous "!!!", indicating that the logger was found. -
- Without @Host +
+ Without @Host
@@ -497,8 +497,8 @@ first without a value (yielding the default color) and then with an assigned col The following image shows the effect of mousing over the `` tag. -
- Highlighted bios +
+ Highlighted bios
{@a providers} @@ -575,8 +575,8 @@ You need other ways to deliver dependency values and that means you need other w The `HeroOfTheMonthComponent` example demonstrates many of the alternatives and why you need them. It's visually simple: a few properties and the logs produced by a logger. -
- Hero of the month +
+ Hero of the month
@@ -730,8 +730,8 @@ Now put it to use in a simplified version of the `HeroOfTheMonthComponent`. The `HeroOfTheMonthComponent` constructor's `logger` parameter is typed as `MinimalLogger` so only the `logs` and `logInfo` members are visible in a TypeScript-aware editor: -
- MinimalLogger restricted API +
+ MinimalLogger restricted API
@@ -745,8 +745,8 @@ Behind the scenes, Angular actually sets the `logger` parameter to the full serv The following image, which displays the logging date, confirms the point: -
- DateLoggerService entry +
+ DateLoggerService entry
@@ -943,8 +943,8 @@ In this contrived example, `SortedHeroesComponent` inherits from `HeroesBaseComp to display a *sorted* list of heroes. -
- Sorted Heroes +
+ Sorted Heroes
@@ -1156,8 +1156,8 @@ the same way you've done it before: Here's *Alex* and family in action: -
- Alex in action +
+ Alex in action
@@ -1217,8 +1217,8 @@ which *is* what parent means. Here's *Alice*, *Barry* and family in action: -
- Alice in action +
+ Alice in action
diff --git a/aio/content/guide/displaying-data.md b/aio/content/guide/displaying-data.md index 2a7576e983654..afaf34083a3f4 100644 --- a/aio/content/guide/displaying-data.md +++ b/aio/content/guide/displaying-data.md @@ -17,8 +17,8 @@ conditionally show a message below the list. The final UI looks like this: -
- Final UI +
+ Final UI