You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 5021143
Browse filesBrowse the repository at this point in the historyBrowse files
Copy file name to clipboardExpand all lines: adev-ja/src/content/guide/directives/structural-directives.en.md
+28-39Lines changed: 28 additions & 39 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,13 +2,15 @@
2
2
3
3
Structural directives are directives applied to an `<ng-template>` element that conditionally or repeatedly render the content of that `<ng-template>`.
4
4
5
+
For everyday conditional and repeated rendering, use Angular's built-in [control flow blocks](guide/templates/control-flow) (`@if`, `@for`, and `@switch`). Write a structural directive when you need reusable rendering behavior that control flow doesn't cover, such as gating content behind a permission check or providing a template with data from an external source.
6
+
5
7
## Example use case
6
8
7
-
In this guide you'll build a structural directive which fetches data from a given data source and renders its template when that data is available. This directive is called `SelectDirective`, after the SQL keyword `SELECT`, and match it with an attribute selector `[select]`.
9
+
This guide uses a directive called `SelectDirective` as its running example. The directive fetches data from a given data source and renders its template when that data is available. It is named after the SQL keyword `SELECT` and matched with an attribute selector,`[select]`.
8
10
9
-
`SelectDirective`will have an input naming the data source to be used, which you will call `selectFrom`. The `select` prefix for this input is important for the [shorthand syntax](#structural-directive-shorthand). The directive will instantiate its `<ng-template>` with a template context providing the selected data.
11
+
`SelectDirective`has an input naming the data source to use, called `selectFrom`. The `select` prefix for this input is important for the [shorthand syntax](#structural-directive-shorthand). The directive instantiates its `<ng-template>` with a template context providing the selected data.
10
12
11
-
The following is an example of using this directive directly on an `<ng-template>`would look like:
13
+
Using this directive directly on an `<ng-template>`looks like this:
@@ -18,7 +20,7 @@ The following is an example of using this directive directly on an `<ng-template
18
20
19
21
The structural directive can wait for the data to become available and then render its `<ng-template>`.
20
22
21
-
HELPFUL: Note that Angular's `<ng-template>` element defines a template that doesn't render anything by default, if you just wrap elements in an `<ng-template>` without applying a structural directive those elements will not be rendered.
23
+
HELPFUL: Angular's `<ng-template>` element defines a template that doesn't render anything by default. If you wrap elements in an `<ng-template>` without applying a structural directive, those elements are not rendered.
22
24
23
25
For more information, see the [ng-template API](api/core/ng-template) documentation.
24
26
@@ -60,20 +62,12 @@ You can only apply one structural directive per element when using the shorthand
60
62
61
63
## Creating a structural directive
62
64
63
-
This section guides you through creating the `SelectDirective`.
64
-
65
-
<docs-workflow>
66
-
<docs-steptitle="Generate the directive">
67
-
Using the Angular CLI, run the following command, where `select` is the name of the directive:
65
+
A structural directive is a directive class that injects two dependencies:
68
66
69
-
```shell
70
-
ng generate directive select
71
-
```
67
+
-[`TemplateRef`](api/core/TemplateRef) gives the directive access to the content of the `<ng-template>` it is applied to.
68
+
-[`ViewContainerRef`](api/core/ViewContainerRef) represents the location in the DOM where the directive can render that template.
72
69
73
-
Angular creates the directive class and specifies the CSS selector, `[select]`, that identifies the directive in a template.
74
-
</docs-step>
75
-
<docs-steptitle="Make the directive structural">
76
-
Import `TemplateRef`, `ViewContainerRef`, and `input`. Inject `TemplateRef` and `ViewContainerRef` in the directive as private properties.
70
+
The directive controls rendering by creating, or not creating, embedded views from the template in the view container. The complete `SelectDirective` looks like this:
With `SelectDirective` now scaffolded as a structural directive with its input, you can now add the logic to fetch the data and render the template with it:
@@ -120,10 +96,15 @@ export class SelectDirective {
120
96
}
121
97
```
122
98
123
-
</docs-step>
124
-
</docs-workflow>
99
+
The `selectFrom` input names the data source the directive reads from. It uses [`input.required()`](guide/components/inputs#required-inputs) because the directive can't do anything useful without a data source.
100
+
101
+
When Angular initializes the directive, it loads the data and then renders the template by calling `createEmbeddedView()`. The second argument is the template's _context object_: values the template can bind to with `let` declarations. Assigning the data to the `$implicit` key makes it the default value that `let-data` (or `let data` in shorthand) receives.
125
102
126
-
That's it - `SelectDirective` is up and running. A follow-up step might be to [add template type-checking support](#typing-the-directives-context).
103
+
NOTE: This example renders its template once, when the directive initializes. It does not re-render when the bound data source changes.
104
+
105
+
Once the directive works, consider [adding template type-checking support](#typing-the-directives-context).
106
+
107
+
HELPFUL: The CLI command [`ng generate directive`](tools/cli/schematics) scaffolds a directive along with its test file.
127
108
128
109
## Structural directive syntax reference
129
110
@@ -167,8 +148,8 @@ The following table provides shorthand examples:
| `*myDir="let item of [1,2,3] as items; trackBy: myTrack; index as i"` | `<ng-templatemyDirlet-item [myDirOf]="[1,2,3]"let-items="myDirOf" [myDirTrackBy]="myTrack"let-i="index">` |
| `*myDir="let item of [1,2,3] as items; trackBy: myTrack; index as i"` | `<ng-templatemyDirlet-item [myDirOf]="[1,2,3]"let-items="myDirOf" [myDirTrackBy]="myTrack"let-i="index">` |
0 commit comments