Skip to content

Commit 0d6325b

Browse files
trekladyonethePunderWoman
authored andcommitted
docs: pipes custom data transform (angular#45505)
PR Close angular#45505
1 parent ee3cfc8 commit 0d6325b

File tree

1 file changed

+63
-0
lines changed

1 file changed

+63
-0
lines changed
Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
# Creating pipes for custom data transformations
2+
3+
Create custom pipes to encapsulate transformations that are not provided with the built-in pipes.
4+
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.
5+
6+
## Marking a class as a pipe
7+
8+
To mark a class as a pipe and supply configuration metadata, apply the [`@Pipe`](/api/core/Pipe "API reference for Pipe") [decorator](/guide/glossary#decorator--decoration "Definition for decorator") to the class.
9+
10+
Use [UpperCamelCase](guide/glossary#case-types "Definition of case types") (the general convention for class names) for the pipe class name, and [camelCase](guide/glossary#case-types "Definition of case types") for the corresponding `name` string.
11+
Do not use hyphens in the `name`.
12+
13+
For details and more examples, see [Pipe names](guide/styleguide#pipe-names "Pipe names in the Angular coding style guide").
14+
15+
Use `name` in template expressions as you would for a built-in pipe.
16+
17+
<div class="alert is-important">
18+
19+
* Include your pipe in the `declarations` field of the `NgModule` metadata in order for it to be available to a template. See the `app.module.ts` file in the example application (<live-example></live-example>). For details, see [NgModules](guide/ngmodules "NgModules introduction").
20+
* Register your custom pipes. The [Angular CLI](cli "CLI Overview and Command Reference") [`ng generate pipe`](cli/generate#pipe "ng generate pipe in the CLI Command Reference") command registers the pipe automatically.
21+
22+
</div>
23+
24+
## Using the PipeTransform interface
25+
26+
Implement the [`PipeTransform`](/api/core/PipeTransform "API reference for PipeTransform") interface in your custom pipe class to perform the transformation.
27+
28+
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.
29+
30+
## Example: Transforming a value exponentially
31+
32+
In a game, you might want to implement a transformation that raises a value exponentially to increase a hero's power.
33+
For example, if the hero's score is 2, boosting the hero's power exponentially by 10 produces a score of 1024.
34+
Use a custom pipe for this transformation.
35+
36+
The following code example shows two component definitions:
37+
38+
* The `exponential-strength.pipe.ts` component defines a custom pipe named `exponentialStrength` with the `transform` method that performs the transformation.
39+
It defines an argument to the `transform` method (`exponent`) for a parameter passed to the pipe.
40+
* The `power-booster.component.ts` component demonstrates how to use the pipe, specifying a value (`2`) and the exponent parameter (`10`).
41+
42+
<code-tabs>
43+
<code-pane header="src/app/exponential-strength.pipe.ts" path="pipes/src/app/exponential-strength.pipe.ts"></code-pane>
44+
<code-pane header="src/app/power-booster.component.ts" path="pipes/src/app/power-booster.component.ts"></code-pane>
45+
</code-tabs>
46+
47+
The browser displays the following:
48+
49+
<code-example language="none">
50+
51+
Power Booster
52+
53+
Superpower boost: 1024
54+
55+
</code-example>
56+
57+
<div class="alert is-helpful">
58+
59+
To examine the behavior of the `exponentialStrength` pipe in the <live-example></live-example>, change the value and optional exponent in the template.
60+
61+
</div>
62+
63+
@reviewed 2022-02-10

0 commit comments

Comments
 (0)