From e27d983402d4dccd69fcc288c3d0ca922fcd37ed Mon Sep 17 00:00:00 2001 From: Matthieu Riegler Date: Thu, 24 Apr 2025 18:08:18 +0200 Subject: [PATCH] docs: remove old pipes docs. (#60996) They were replaced by pipes entry in the template guides. PR Close #60996 --- adev/src/content/guide/pipes/BUILD.bazel | 12 -- .../content/guide/pipes/change-detection.md | 114 ------------------ adev/src/content/guide/pipes/overview.md | 27 ----- adev/src/content/guide/pipes/precedence.md | 28 ----- adev/src/content/guide/pipes/template.md | 54 --------- .../src/content/guide/pipes/transform-data.md | 61 ---------- .../pipes/unwrapping-data-observables.md | 15 --- 7 files changed, 311 deletions(-) delete mode 100644 adev/src/content/guide/pipes/BUILD.bazel delete mode 100644 adev/src/content/guide/pipes/change-detection.md delete mode 100644 adev/src/content/guide/pipes/overview.md delete mode 100644 adev/src/content/guide/pipes/precedence.md delete mode 100644 adev/src/content/guide/pipes/template.md delete mode 100644 adev/src/content/guide/pipes/transform-data.md delete mode 100644 adev/src/content/guide/pipes/unwrapping-data-observables.md diff --git a/adev/src/content/guide/pipes/BUILD.bazel b/adev/src/content/guide/pipes/BUILD.bazel deleted file mode 100644 index cb44db62fd8..00000000000 --- a/adev/src/content/guide/pipes/BUILD.bazel +++ /dev/null @@ -1,12 +0,0 @@ -load("//adev/shared-docs:index.bzl", "generate_guides") - -generate_guides( - name = "pipes", - srcs = glob([ - "*.md", - ]), - data = [ - "//adev/src/content/examples", - ], - visibility = ["//adev:__subpackages__"], -) diff --git a/adev/src/content/guide/pipes/change-detection.md b/adev/src/content/guide/pipes/change-detection.md deleted file mode 100644 index 6edabceaa03..00000000000 --- a/adev/src/content/guide/pipes/change-detection.md +++ /dev/null @@ -1,114 +0,0 @@ -# Change detection with pipes - -Pipes are often used with data-bound values that might change based on user actions. -If the data is a primitive input value, such as `String` or `Number`, or an object reference as input, such as `Date` or `Array`, Angular executes the pipe whenever it detects a change for the value. - - - - - - -The `exponentialStrength` pipe executes every time the user changes the value or the exponent. See the highlighted line above. - -Angular detects each change and immediately runs the pipe. -This is fine for primitive input values. -However, if you change something *inside* a composite object (such as the month of a date, an element of an array, or an object property), you need to understand how change detection works, and how to use an `impure` pipe. - -## How change detection works - -Angular looks for changes to data-bound values in a change detection process that runs after every DOM event: every keystroke, mouse move, timer tick, and server response. -The following example, which doesn't use a pipe, demonstrates how Angular uses its default change detection strategy to monitor and update its display of every hero in the `heroes` array. -The example tabs show the following: - -| Files | Details | -|:--- |:--- | -| `flying-heroes.component.html (v1)` | The `*ngFor` repeater displays the hero names. | -| `flying-heroes.component.ts (v1)` | Provides heroes, adds heroes into the array, and resets the array. | - - - - - - -Angular updates the display every time the user adds a hero. -If the user clicks the **Reset** button, Angular replaces `heroes` with a new array of the original heroes and updates the display. -If you add the ability to remove or change a hero, Angular would detect those changes and update the display as well. - -However, executing a pipe to update the display with every change would slow down your application's performance. -So Angular uses a faster change-detection algorithm for executing a pipe, as described in the next section. - -## Detecting pure changes to primitives and object references - -By default, pipes are defined as *pure* so that Angular executes the pipe only when it detects a *pure change* to the input value or parameters. -A pure change is either a change to a primitive input value \(such as `String`, `Number`, `Boolean`, or `Symbol`\), or a changed object reference \(such as `Date`, `Array`, `Function`, or `Object`\). - -A pure pipe must use a pure function, which is one that processes inputs and returns values without side effects. -In other words, given the same input, a pure function should always return the same output. - -With a pure pipe, Angular ignores changes within objects and arrays because checking a primitive value or object reference is much faster than performing a deep check for differences within objects. -Angular can quickly determine if it can skip executing the pipe and updating the view. - -However, a pure pipe with an array as input might not work the way you want. -To demonstrate this issue, change the previous example to filter the list of heroes to just those heroes who can fly. - -For this, consider we use the `FlyingHeroesPipe` in the `*ngFor` repeater as shown in the following code. -The tabs for the example show the following: - -| Files | Details | -|:--- |:--- | -| flying-heroes.component.html | Template with the new pipe used. | -| flying-heroes.pipe.ts | File with custom pipe that filters flying heroes. | - - - - - - -The application now shows unexpected behavior: When the user adds flying heroes, none of them appear under "Heroes who fly." -This happens because the code that adds a hero does so by pushing it onto the `heroes` array that is used as input for the `flyingHeroes` pipe. - - - -The change detector ignores changes within elements of an array, so the pipe doesn't run. -The reason Angular ignores the changed array element is that the *reference* to the array hasn't changed. -Because the array is the same, Angular does not update the display. - -One way to get the behavior you want is to change the object reference itself. -Replace the array with a new array containing the newly changed elements, and then input the new array to the pipe. -In the preceding example, create an array with the new hero appended, and assign that to `heroes`. -Angular detects the change in the array reference and executes the pipe. - -To summarize, if you mutate the input array, the pure pipe doesn't execute. -If you *replace* the input array, the pipe executes and the display is updated. -As an alternative, use an *impure* pipe to detect changes within composite objects such as arrays, as described in the next section. - -## Detecting impure changes within composite objects - -To execute a custom pipe after a change *within* a composite object, such as a change to an element of an array, you need to define your pipe as `impure` to detect impure changes. -Angular executes an impure pipe every time it detects a change (e.g. every keystroke or mouse event). - -IMPORTANT: While an impure pipe can be useful, be careful using one. -A long-running impure pipe could dramatically slow down your application. - -Make a pipe impure by setting its `pure` flag to `false`: - - - -The following code shows the complete implementation of `FlyingHeroesImpurePipe`, which extends `FlyingHeroesPipe` to inherit its characteristics. -The example shows that you don't have to change anything else—the only difference is setting the `pure` flag as `false` in the pipe metadata. - - - - - - -`FlyingHeroesImpurePipe` is a reasonable candidate for an impure pipe because the `transform` function is trivial and fast: - - - -You can derive a `FlyingHeroesImpureComponent` from `FlyingHeroesComponent`. -As shown in the following code, only the pipe in the template changes. - - diff --git a/adev/src/content/guide/pipes/overview.md b/adev/src/content/guide/pipes/overview.md deleted file mode 100644 index 17889330b07..00000000000 --- a/adev/src/content/guide/pipes/overview.md +++ /dev/null @@ -1,27 +0,0 @@ -# Understanding Pipes - -Use pipes to transform strings, currency amounts, dates, and other data for display. - -## What is a pipe - -Pipes are simple functions to use in templates to accept an input value and return a transformed value. Pipes are useful because you can use them throughout your application, while only declaring each pipe once. -For example, you would use a pipe to show a date as **April 15, 1988** rather than the raw string format. - -You can create your own custom pipes to expose reusable transformations in templates. - -## Built-in pipes - -Angular provides built-in pipes for typical data transformations, including transformations for internationalization (i18n), which use locale information to format data. -The following are commonly used built-in pipes for data formatting: - -- [`DatePipe`](api/common/DatePipe): Formats a date value according to locale rules. -- [`UpperCasePipe`](api/common/UpperCasePipe): Transforms text to all upper case. -- [`LowerCasePipe`](api/common/LowerCasePipe): Transforms text to all lower case. -- [`CurrencyPipe`](api/common/CurrencyPipe): Transforms a number to a currency string, formatted according to locale rules. -- [`DecimalPipe`](/api/common/DecimalPipe): Transforms a number into a string with a decimal point, formatted according to locale rules. -- [`PercentPipe`](api/common/PercentPipe): Transforms a number to a percentage string, formatted according to locale rules. -- [`AsyncPipe`](api/common/AsyncPipe): Subscribe and unsubscribe to an asynchronous source such as an observable. -- [`JsonPipe`](api/common/JsonPipe): Display a component object property to the screen as JSON for debugging. - -NOTE: For a complete list of built-in pipes, see the [pipes API documentation](/api?type=pipe "Pipes API reference summary"). -To learn more about using pipes for internationalization (i18n) efforts, see [formatting data based on locale](guide/i18n/format-data-locale). diff --git a/adev/src/content/guide/pipes/precedence.md b/adev/src/content/guide/pipes/precedence.md deleted file mode 100644 index 4184a36a3b8..00000000000 --- a/adev/src/content/guide/pipes/precedence.md +++ /dev/null @@ -1,28 +0,0 @@ -# Pipe precedence in template expressions - -Sometimes you want to choose between two values, based on some condition, before passing the choice to the pipe. -You could use the JavaScript ternary operator (`?:`) in the template to make that choice. - -Beware! The pipe operator has a higher precedence than the JavaScript ternary operator (`?:`). - -If you simply write the expression as if it were evaluated left-to-right, you might be surprised by the result. For example, - -```ts -condition ? a : b | pipe -``` - -is parsed as - -```ts -condition ? a : (b | pipe) -``` - -The value of `b` passes through `pipe`; the value of `a` *will not*. - -If you want the pipe to apply to the result of the ternary expression, wrap the entire expression in parentheses. For example, - -```ts -(condition ? a : b) | pipe -``` - -In general, you should always use parentheses to be sure Angular evaluates the expression as you intend. diff --git a/adev/src/content/guide/pipes/template.md b/adev/src/content/guide/pipes/template.md deleted file mode 100644 index 21fe89dbe0a..00000000000 --- a/adev/src/content/guide/pipes/template.md +++ /dev/null @@ -1,54 +0,0 @@ -# Using a pipe in a template - -To apply a pipe, use the pipe operator (`|`) within a template expression as shown in the following code example. - - -

The hero's birthday is {{ birthday | date }}

- - -The component's `birthday` value flows through the pipe operator (`|`) to the [`DatePipe`](api/common/DatePipe) whose pipe name is `date`. -The pipe renders the date in the default format like **Apr 07, 2023**. - - -import { Component } from '@angular/core'; -import { DatePipe } from '@angular/common'; - -@Component({ - templateUrl: './app.component.html', - imports: [DatePipe], -}) -export class AppComponent { - birthday = new Date(); -} - - -## Additional parameters for pipes - -Pipes can take additional parameters that configure the transformation. Parameters can be optional or required. - -For example, the `date` pipe takes optional parameters that control the date's display format. -To specify the parameter, follow the pipe name with a colon (`:`) and the parameter value (the format). - - -

The hero's birthday is in {{ birthday | date:'yyyy' }}

- - -Pipes can also take multiple parameters. You can pass multiple parameters by separating these via colons (`:`). -For example, the `date` pipe accepts a second optional parameter for controlling the timezone. - - -

The current time is: {{ currentTime | date:'hh:mm':'UTC' }}

- - -This will display the current time (like `10:53`) in the `UTC` timezone. - -## Chaining pipes - -You can connect multiple pipes so that the output of one pipe becomes the input to the next. - -The following example passes a date to the `DatePipe` and then forwards the result to the [`UpperCasePipe`](api/common/UpperCasePipe 'API reference') pipe. - - -

The hero's birthday is {{ birthday | date }}

-

The hero's birthday is in {{ birthday | date:'yyyy' | uppercase }}

- diff --git a/adev/src/content/guide/pipes/transform-data.md b/adev/src/content/guide/pipes/transform-data.md deleted file mode 100644 index 545275e43e6..00000000000 --- a/adev/src/content/guide/pipes/transform-data.md +++ /dev/null @@ -1,61 +0,0 @@ -# Custom pipes for new transforms - -Create custom pipes to encapsulate transformations that are not provided with the built-in pipes. -Then, use your custom pipe in template expressions, the same way you use built-in pipes—to transform input values to output values for display. - -## Marking a class as a pipe - -To mark a class as a pipe and supply configuration metadata, apply the `@Pipe` to the class. - -Use UpperCamelCase (the general convention for class names) for the pipe class name, and camelCase for the corresponding `name` string. -Do not use hyphens in the `name`. - -For details and more examples, see [Pipe names](/style-guide#pipe-names "Pipe names in the Angular coding style guide"). - -Use `name` in template expressions as you would for a built-in pipe. - -```ts -import { Pipe } from '@angular/core'; - -@Pipe({ - name: 'greet', -}) -export class GreetPipe {} -``` - -## Using the PipeTransform interface - -Implement the [`PipeTransform`](/api/core/PipeTransform "API reference for PipeTransform") interface in your custom pipe class to perform the transformation. - -Angular invokes the `transform` method with the value of a binding as the first argument, and any parameters as the second argument in list form, and returns the transformed value. - -```ts -import { Pipe, PipeTransform } from '@angular/core'; - -@Pipe({ - name: 'greet', -}) -export class GreetPipe implements PipeTransform { - transform(value: string, param1: boolean, param2: boolean): string { - return `Hello ${value}`; - } -} -``` - -## Example: Transforming a value exponentially - -In a game, you might want to implement a transformation that raises a value exponentially to increase a hero's power. -For example, if the hero's score is 2, boosting the hero's power exponentially by 10 produces a score of 1024 (`2**10`). -Use a custom pipe for this transformation. - -The following code example shows two component definitions: - -| Files | Details | -|:--- |:--- | -| `exponential-strength.pipe.ts` | Defines a custom pipe named `exponentialStrength` with the `transform` method that performs the transformation. It defines an argument to the `transform` method \(`exponent`\) for a parameter passed to the pipe. | -| `power-booster.component.ts` | Demonstrates how to use the pipe, specifying a value \(`2`\) and the exponent parameter \(`10`\). | - - - - - diff --git a/adev/src/content/guide/pipes/unwrapping-data-observables.md b/adev/src/content/guide/pipes/unwrapping-data-observables.md deleted file mode 100644 index bdb3d802e36..00000000000 --- a/adev/src/content/guide/pipes/unwrapping-data-observables.md +++ /dev/null @@ -1,15 +0,0 @@ -# Unwrapping data from an observable - -Observables let you pass messages between parts of your application. -You can use observables for event handling, asynchronous programming, and handling multiple values. -Observables can deliver single or multiple values of any type, either synchronously (as a function delivers a value to its caller) or asynchronously on a schedule. - -Use the built-in [`AsyncPipe`](api/common/AsyncPipe "API description of AsyncPipe") to accept an observable as input and subscribe to the input automatically. -Without this pipe, your component code would have to subscribe to the observable to consume its values, extract the resolved values, expose them for binding, and unsubscribe when the observable is destroyed in order to prevent memory leaks. -`AsyncPipe` is a pipe that saves boilerplate code in your component to maintain the subscription and keep delivering values from that observable as they arrive. - -The following code example binds an observable of message strings (`message$`) to a view with the `async` pipe. - - -