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

aio/content/examples/pipes/src/app/app.component.html

@@ -10,6 +10,7 @@
 <a href="#flying-heroes-impure">Flying Heroes filter pipe (impure)</a><br>
 <a href="#hero-message">Async Hero Message and AsyncPipe</a><br>
 <a href="#hero-list">Hero List with caching FetchJsonPipe</a><br>
+<a href="#pipe-precedence">Pipes and Precedence</a><br>
 
 
 <hr>
@@ -80,4 +81,7 @@
 <a id="hero-list"></a>
 <app-hero-list></app-hero-list>
 
-<div style="margin-top:12em;"></div>
+<hr>
+<a id="pipe-precedence"></a>
+<app-precedence></app-precedence>
+<hr>

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]
 })

aio/content/examples/pipes/src/app/precedence.component.html

@@ -0,0 +1,13 @@
+<!-- #docplaster-->
+<!-- #docregion -->
+<h2>{{title}}</h2>
+
+<p>Basic uppercase pipe (no precedence considerations necessary): {{ 'text' | uppercase }}</p>
+<p>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 }}</p>
+<p>The following shows how parentheses help Angular evaluate the whole statement:
+<!-- #docregion precedence -->
+<!-- use parentheses in the third operand so the pipe applies to the whole expression -->
+{{ (true ? 'true' : 'false') | uppercase }}
+<!-- #enddocregion precedence -->
+</p>
+

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';
+}

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}}`
 

aio/content/guide/built-in-directives.md

@@ -265,12 +265,6 @@ The `nullCustomer` will not be displayed as long as it is `null`.
 
 <code-example path="built-in-directives/src/app/app.component.html" region="NgIf-2b" header="src/app/app.component.html"></code-example>
 
-<div class="alert is-helpful">
-
-See also the
-[safe navigation operator](guide/template-expression-operators#safe-navigation-operator "Safe navigation operator (?.)") below.
-
-</div>
 <hr/>
 
 {@a ngFor}

aio/content/guide/pipes.md

@@ -57,9 +57,7 @@ The tabs in the example show the following:
   </code-pane>
 </code-tabs>
 
-The component's `birthday` value flows through the
+The component's `birthday` value flows through the pipe operator, `|` to the [`date`](api/common/DatePipe) function.
-[pipe operator](guide/template-expression-operators#pipe) ( | ) 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.
 
 </div>
+
+## 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`.
+
+<code-example path="pipes/src/app/precedence.component.html" region="precedence" header="src/app/precedence.component.html">
+</code-example>

aio/content/guide/template-expression-operators.md

@@ -1,13 +1,19 @@
-<!-- {@a expression-operators} -->
-
 # Template expression operators
 
-The Angular template expression language employs a subset of JavaScript syntax supplemented with a few special operators
+<div class="callout is-critical">
-for specific scenarios. The next sections cover three of these operators:
 
-* [pipe](guide/template-expression-operators#pipe)
+<header>Marked for archiving</header>
-* [safe navigation operator](guide/template-expression-operators#safe-navigation-operator)
+
-* [non-null assertion operator](guide/template-expression-operators#non-null-assertion-operator)
+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).
+
+</div>
+
+The Angular template expression language employs a subset of JavaScript syntax supplemented with a few special operators
+for specific scenarios.
 
 <div class="alert is-helpful">
 
@@ -15,111 +21,26 @@ See the <live-example></live-example> for a working example containing the code
 
 </div>
 
-{@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 (`|`):
-
-<code-example path="template-expression-operators/src/app/app.component.html" region="uppercase-pipe" header="src/app/app.component.html"></code-example>
-
-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:
-
-<code-example path="template-expression-operators/src/app/app.component.html" region="pipe-chain" header="src/app/app.component.html"></code-example>
-
-And you can also [apply parameters](guide/pipes#parameterizing-a-pipe) to a pipe:
-
-<code-example path="template-expression-operators/src/app/app.component.html" region="date-pipe" header="src/app/app.component.html"></code-example>
-
-The `json` pipe is particularly helpful for debugging bindings:
-
-<code-example path="template-expression-operators/src/app/app.component.html" region="json-pipe" header="src/app/app.component.html"></code-example>
-
-The generated output would look something like this:
-
-<code-example language="json">
-  { "name": "Telephone",
-    "manufactureDate": "1980-02-25T05:00:00.000Z",
-    "price": 98 }
-</code-example>
-
-<div class="alert is-helpful">
-
-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.
-
-</div>
-
-
-<hr/>
-
-{@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`.
-
-<code-example path="template-expression-operators/src/app/app.component.html" region="safe" header="src/app/app.component.html"></code-example>
-
-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`.
-
-<code-example language="html">
-  The null item name is {{nullItem.name}}
-</code-example>
-
-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:
-
-<code-example language="bash">
-  TypeError: Cannot read property 'name' of null.
-</code-example>
-
-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`.
-
-
-<hr/>
-
 {@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
+For example, you can assert that `item` properties are also defined.
-[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.
 
 <code-example path="template-expression-operators/src/app/app.component.html" region="non-null" header="src/app/app.component.html"></code-example>
 
-When the Angular compiler turns your template into TypeScript code,
+Often, you want to make sure that any property bindings aren't `null` or `undefined`.
-it prevents TypeScript from reporting that `item.color` might be `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, `!`, is optional unless you turn on strict null checks.
-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.
+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/
 
 <code-example path="built-in-template-functions/src/app/app.component.html" region="any-type-cast-function-1" header="src/app/app.component.html"></code-example>
 
-When the Angular compiler turns this template into TypeScript code,
+Using `$any()` prevents TypeScript from reporting that `bestByDate` is not a member of the `item` object.
-it prevents TypeScript from reporting that `bestByDate` is not a member of the `item`
-object when it runs type checking on the template.
 
-The `$any()` cast function also works with `this` to allow access to undeclared members of
+The `$any()` cast function also works with `this` to allow access to undeclared members of the component.
-the component.
 
 <code-example path="built-in-template-functions/src/app/app.component.html" region="any-type-cast-function-2" header="src/app/app.component.html"></code-example>
 
 The `$any()` cast function works anywhere in a binding expression where a method call is valid.
-

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
 

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",
+              "url": "guide/template-reference-variables",
-              "title": "Template expression operators",
+              "title": "Template reference variables",
-              "tooltip": "Introductory guide to transforming data, ensuring safe navigation, and guarding against null variables in templates."
+              "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",

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.
  *