From 2c275f6d7ab32c2ef3d1ea5a20b4a862bd9ae626 Mon Sep 17 00:00:00 2001 From: Kapunahele Wong Date: Wed, 7 Oct 2020 16:58:04 -0400 Subject: [PATCH] docs: archive template expression operators doc, move pipes precedence section (#39170) Archives most of the content in the template expression operators doc. The pipes precedence section that was originally in template expression operators moves into the pipes doc with some editing and an addition of a ternary example. PR Close #39170 --- .../examples/pipes/src/app/app.component.html | 6 +- .../examples/pipes/src/app/app.module.ts | 4 +- .../pipes/src/app/precedence.component.html | 13 ++ .../pipes/src/app/precedence.component.ts | 11 ++ aio/content/guide/architecture-components.md | 2 +- aio/content/guide/built-in-directives.md | 6 - aio/content/guide/pipes.md | 14 +- .../guide/template-expression-operators.md | 131 ++++-------------- aio/content/guide/template-statements.md | 2 +- aio/content/navigation.json | 11 +- packages/common/src/directives/ng_if.ts | 2 +- 11 files changed, 78 insertions(+), 124 deletions(-) create mode 100644 aio/content/examples/pipes/src/app/precedence.component.html create mode 100644 aio/content/examples/pipes/src/app/precedence.component.ts diff --git a/aio/content/examples/pipes/src/app/app.component.html b/aio/content/examples/pipes/src/app/app.component.html index b03b8251bc..add2dd2455 100644 --- a/aio/content/examples/pipes/src/app/app.component.html +++ b/aio/content/examples/pipes/src/app/app.component.html @@ -10,6 +10,7 @@ Flying Heroes filter pipe (impure)
Async Hero Message and AsyncPipe
Hero List with caching FetchJsonPipe
+Pipes and Precedence
@@ -80,4 +81,7 @@ -
+
+ + +
diff --git a/aio/content/examples/pipes/src/app/app.module.ts b/aio/content/examples/pipes/src/app/app.module.ts index 8dd502c702..bd551b6fb9 100644 --- a/aio/content/examples/pipes/src/app/app.module.ts +++ b/aio/content/examples/pipes/src/app/app.module.ts @@ -15,6 +15,7 @@ import { HeroBirthday2Component } from './hero-birthday2.component'; import { HeroListComponent } from './hero-list.component'; import { PowerBoostCalculatorComponent } from './power-boost-calculator.component'; import { PowerBoosterComponent } from './power-booster.component'; +import { PrecedenceComponent } from './precedence.component'; @NgModule({ @@ -36,7 +37,8 @@ import { PowerBoosterComponent } from './power-booster.component'; FlyingHeroesPipe, FlyingHeroesImpurePipe, FetchJsonPipe, - ExponentialStrengthPipe + ExponentialStrengthPipe, + PrecedenceComponent ], bootstrap: [AppComponent] }) diff --git a/aio/content/examples/pipes/src/app/precedence.component.html b/aio/content/examples/pipes/src/app/precedence.component.html new file mode 100644 index 0000000000..3b4a208e7e --- /dev/null +++ b/aio/content/examples/pipes/src/app/precedence.component.html @@ -0,0 +1,13 @@ + + +

{{title}}

+ +

Basic uppercase pipe (no precedence considerations necessary): {{ 'text' | uppercase }}

+

The following shows that a pipe has higher precedence than a ternary operator. If the pipe precedence were lower than the ternary operator precedence, the output would be 'TRUE'. Instead it is: {{ true ? 'true' : 'false' | uppercase }}

+

The following shows how parentheses help Angular evaluate the whole statement: + + +{{ (true ? 'true' : 'false') | uppercase }} + +

+ diff --git a/aio/content/examples/pipes/src/app/precedence.component.ts b/aio/content/examples/pipes/src/app/precedence.component.ts new file mode 100644 index 0000000000..c4132c881f --- /dev/null +++ b/aio/content/examples/pipes/src/app/precedence.component.ts @@ -0,0 +1,11 @@ +import { Component } from '@angular/core'; + +@Component({ + selector: 'app-precedence', + templateUrl: './precedence.component.html', + styles: [] +}) + +export class PrecedenceComponent { + title = 'Pipes and Precedence'; +} diff --git a/aio/content/guide/architecture-components.md b/aio/content/guide/architecture-components.md index cbe9221411..8f38847295 100644 --- a/aio/content/guide/architecture-components.md +++ b/aio/content/guide/architecture-components.md @@ -126,7 +126,7 @@ Angular pipes let you declare display-value transformations in your template HTM Angular defines various pipes, such as the [date](api/common/DatePipe) pipe and [currency](api/common/CurrencyPipe) pipe; for a complete list, see the [Pipes API list](api?type=pipe). You can also define new pipes. -To specify a value transformation in an HTML template, use the [pipe operator (|)](guide/template-expression-operators#pipe). +To specify a value transformation in an HTML template, use the [pipe operator (|)](guide/pipes). `{{interpolated_value | pipe_name}}` diff --git a/aio/content/guide/built-in-directives.md b/aio/content/guide/built-in-directives.md index 987939144b..c70531358d 100644 --- a/aio/content/guide/built-in-directives.md +++ b/aio/content/guide/built-in-directives.md @@ -265,12 +265,6 @@ The `nullCustomer` will not be displayed as long as it is `null`. -
- -See also the -[safe navigation operator](guide/template-expression-operators#safe-navigation-operator "Safe navigation operator (?.)") below. - -
{@a ngFor} diff --git a/aio/content/guide/pipes.md b/aio/content/guide/pipes.md index 7a49dabffa..8ad1974aae 100644 --- a/aio/content/guide/pipes.md +++ b/aio/content/guide/pipes.md @@ -57,9 +57,7 @@ The tabs in the example show the following: -The component's `birthday` value flows through the -[pipe operator](guide/template-expression-operators#pipe) ( | ) to the [`date`](api/common/DatePipe) -function. +The component's `birthday` value flows through the pipe operator, `|` to the [`date`](api/common/DatePipe) function. {@a parameterizing-a-pipe} @@ -438,3 +436,13 @@ The `fetch` and `fetch-json` pipes display the heroes as shown in Figure 5. The built-in [JsonPipe](api/common/JsonPipe "API description for JsonPipe") provides a way to diagnose a mysteriously failing data binding or to inspect an object for future binding. + +## Pipes and precedence + +The pipe operator has a higher precedence than the ternary operator (`?:`), which means `a ? b : c | x` is parsed as `a ? b : (c | x)`. +The pipe operator cannot be used without parentheses in the first and second operands of `?:`. + +Due to precedence, if you want a pipe to apply to the result of a ternary, wrap the entire expression in parentheses; for example, `(a ? b : c) | x`. + + + diff --git a/aio/content/guide/template-expression-operators.md b/aio/content/guide/template-expression-operators.md index ca392601d5..82633c4354 100644 --- a/aio/content/guide/template-expression-operators.md +++ b/aio/content/guide/template-expression-operators.md @@ -1,13 +1,19 @@ - - # Template expression operators -The Angular template expression language employs a subset of JavaScript syntax supplemented with a few special operators -for specific scenarios. The next sections cover three of these operators: +
-* [pipe](guide/template-expression-operators#pipe) -* [safe navigation operator](guide/template-expression-operators#safe-navigation-operator) -* [non-null assertion operator](guide/template-expression-operators#non-null-assertion-operator) +
Marked for archiving
+ +To ensure that you have the best experience possible, this topic is marked for archiving until we determine that it clearly conveys the most accurate information possible. + +In the meantime, this topic might be helpful: [Hierarchical injectors](guide/hierarchical-dependency-injection). + +If you think this content should not be archived, please file a [GitHub issue](https://github.com/angular/angular/issues/new?template=3-docs-bug.md). + +
+ +The Angular template expression language employs a subset of JavaScript syntax supplemented with a few special operators +for specific scenarios.
@@ -15,111 +21,26 @@ See the for a working example containing the code
-{@a pipe} - -## The pipe operator (`|`) - -The result of an expression might require some transformation before you're ready to use it in a binding. -For example, you might display a number as a currency, change text to uppercase, or filter a list and sort it. - -Pipes are simple functions that accept an input value and return a transformed value. -They're easy to apply within template expressions, using the pipe operator (`|`): - - - -The pipe operator passes the result of an expression on the left to a pipe function on the right. - -You can chain expressions through multiple pipes: - - - -And you can also [apply parameters](guide/pipes#parameterizing-a-pipe) to a pipe: - - - -The `json` pipe is particularly helpful for debugging bindings: - - - -The generated output would look something like this: - - - { "name": "Telephone", - "manufactureDate": "1980-02-25T05:00:00.000Z", - "price": 98 } - - -
- -The pipe operator has a higher precedence than the ternary operator (`?:`), -which means `a ? b : c | x` is parsed as `a ? b : (c | x)`. -Nevertheless, for a number of reasons, -the pipe operator cannot be used without parentheses in the first and second operands of `?:`. -A good practice is to use parentheses in the third operand too. - -
- - -
- -{@a safe-navigation-operator} - -## The safe navigation operator ( `?` ) and null property paths - -The Angular safe navigation operator, `?`, guards against `null` and `undefined` -values in property paths. Here, it protects against a view render failure if `item` is `null`. - - - -If `item` is `null`, the view still renders but the displayed value is blank; you see only "The item name is:" with nothing after it. - -Consider the next example, with a `nullItem`. - - - The null item name is {{nullItem.name}} - - -Since there is no safe navigation operator and `nullItem` is `null`, JavaScript and Angular would throw a `null` reference error and break the rendering process of Angular: - - - TypeError: Cannot read property 'name' of null. - - -Sometimes however, `null` values in the property -path may be OK under certain circumstances, -especially when the value starts out null but the data arrives eventually. - -With the safe navigation operator, `?`, Angular stops evaluating the expression when it hits the first `null` value and renders the view without errors. - -It works perfectly with long property paths such as `a?.b?.c?.d`. - - -
- {@a non-null-assertion-operator} ## The non-null assertion operator ( `!` ) -As of Typescript 2.0, you can enforce [strict null checking](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-2-0.html "Strict null checking in TypeScript") with the `--strictNullChecks` flag. TypeScript then ensures that no variable is unintentionally `null` or `undefined`. +When you use TypeScript's `--strictNullChecks` flag, you can prevent the type checker from throwing an error with Angular's non-null assertion operator, `!`. -In this mode, typed variables disallow `null` and `undefined` by default. The type checker throws an error if you leave a variable unassigned or try to assign `null` or `undefined` to a variable whose type disallows `null` and `undefined`. +The Angular non-null assertion operator causes the TypeScript type checker to suspend strict `null` and `undefined` checks for a specific property expression. -The type checker also throws an error if it can't determine whether a variable will be `null` or `undefined` at runtime. You tell the type checker not to throw an error by applying the postfix -[non-null assertion operator, !](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-2-0.html#non-null-assertion-operator "Non-null assertion operator"). - -The Angular non-null assertion operator, `!`, serves the same purpose in -an Angular template. For example, you can assert that `item` properties are also defined. +For example, you can assert that `item` properties are also defined. -When the Angular compiler turns your template into TypeScript code, -it prevents TypeScript from reporting that `item.color` might be `null` or `undefined`. +Often, you want to make sure that any property bindings aren't `null` or `undefined`. +However, there are situations in which such states are acceptable. +For those situations, you can use Angular's non-null assertion operator to prevent TypeScript from reporting that a property is `null` or `undefined`. -Unlike the [_safe navigation operator_](guide/template-expression-operators#safe-navigation-operator "Safe navigation operator (?)"), -the non-null assertion operator does not guard against `null` or `undefined`. -Rather, it tells the TypeScript type checker to suspend strict `null` checks for a specific property expression. +The non-null assertion operator, `!`, is optional unless you turn on strict null checks. + +For more information, see TypeScript's [strict null checking](http://www.typescriptlang.org/docs/handbook/release-notes/typescript-2-0.html "Strict null checking in TypeScript"). -The non-null assertion operator, `!`, is optional with the exception that you must use it when you turn on strict null checks. {@a any-type-cast-function} @@ -131,14 +52,10 @@ the expression to the [`any` type](https://www.typescriptlang.org/docs/handbook/ -When the Angular compiler turns this template into TypeScript code, -it prevents TypeScript from reporting that `bestByDate` is not a member of the `item` -object when it runs type checking on the template. +Using `$any()` prevents TypeScript from reporting that `bestByDate` is not a member of the `item` object. -The `$any()` cast function also works with `this` to allow access to undeclared members of -the component. +The `$any()` cast function also works with `this` to allow access to undeclared members of the component. The `$any()` cast function works anywhere in a binding expression where a method call is valid. - diff --git a/aio/content/guide/template-statements.md b/aio/content/guide/template-statements.md index f6eddc14da..7cabdd7381 100644 --- a/aio/content/guide/template-statements.md +++ b/aio/content/guide/template-statements.md @@ -37,7 +37,7 @@ The following JavaScript and template expression syntax is not allowed: * increment and decrement operators, `++` and `--` * operator assignment, such as `+=` and `-=` * the bitwise operators, such as `|` and `&` -* the [pipe operator](guide/template-expression-operators#pipe) +* the [pipe operator](guide/pipes) ## Statement context diff --git a/aio/content/navigation.json b/aio/content/navigation.json index 581474479e..951e7bca3b 100644 --- a/aio/content/navigation.json +++ b/aio/content/navigation.json @@ -193,9 +193,14 @@ "tooltip": "Introductory guide to sharing data between a class and a template." }, { - "url": "guide/template-expression-operators", - "title": "Template expression operators", - "tooltip": "Introductory guide to transforming data, ensuring safe navigation, and guarding against null variables in templates." + "url": "guide/template-reference-variables", + "title": "Template reference variables", + "tooltip": "Introductory guide to referring to DOM elements within a template." + }, + { + "url": "guide/inputs-outputs", + "title": "Inputs and Outputs", + "tooltip": "Introductory guide to sharing data between parent and child directives or components." }, { "url": "guide/svg-in-templates", diff --git a/packages/common/src/directives/ng_if.ts b/packages/common/src/directives/ng_if.ts index 26704b8592..f525a907d6 100644 --- a/packages/common/src/directives/ng_if.ts +++ b/packages/common/src/directives/ng_if.ts @@ -100,7 +100,7 @@ import {Directive, EmbeddedViewRef, Input, TemplateRef, ViewContainerRef, ɵstri * * The conditional displays the data only if `userStream` returns a value, * so you don't need to use the - * [safe-navigation-operator](guide/template-expression-operators#safe-navigation-operator) (`?.`) + * safe-navigation-operator (`?.`) * to guard against null values when accessing properties. * You can display an alternative template while waiting for the data. *