`, add `[ngSwitch]` bound to an expression that returns the switch value, such as `feature`. - Though the `feature` value in this example is a string, the switch value can be of any type. + Though the `feature` value in this example is a string, the switch value can be of any type. 1. Bind to `*ngSwitchCase` and `*ngSwitchDefault` on the elements for the cases. - + 1. In the parent component, define `currentItem`, to use it in the `[ngSwitch]` expression. - + 1. In each child component, add an `item` [input property](guide/components/inputs) which is bound to the `currentItem` of the parent component. - The following two snippets show the parent component and one of the child components. - The other child components are identical to `StoutItemComponent`. + The following two snippets show the parent component and one of the child components. + The other child components are identical to `StoutItemComponent`. - + - Animation of NgSwitch

Switch directives also work with built-in HTML elements and web components. For example, you could replace the `` switch case with a `

` as follows. diff --git a/adev/src/content/guide/forms/template-driven-forms.md b/adev/src/content/guide/forms/template-driven-forms.md index bfa422cfde40..4665ed604bba 100644 --- a/adev/src/content/guide/forms/template-driven-forms.md +++ b/adev/src/content/guide/forms/template-driven-forms.md @@ -18,18 +18,18 @@ You can specify validation rules and display validation errors, conditionally al This tutorial teaches you how to do the following: -* Build an Angular form with a component and template -* Use `ngModel` to create two-way data bindings for reading and writing input-control values -* Provide visual feedback using special CSS classes that track the state of the controls -* Display validation errors to users and conditionally allow input from form controls based on the form status -* Share information across HTML elements using [template reference variables](guide/templates/reference-variables) +- Build an Angular form with a component and template +- Use `ngModel` to create two-way data bindings for reading and writing input-control values +- Provide visual feedback using special CSS classes that track the state of the controls +- Display validation errors to users and conditionally allow input from form controls based on the form status +- Share information across HTML elements using [template reference variables](guide/templates/variables#template-reference-variables) ## Build a template-driven form Template-driven forms rely on directives defined in the `FormsModule`. -| Directives | Details | -|:--- |:--- | +| Directives | Details | +| :------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `NgModel` | Reconciles value changes in the attached form element with changes in the data model, allowing you to respond to user input with input validation and error handling. | | `NgForm` | Creates a top-level `FormGroup` instance and binds it to a `` element to track aggregated form value and validation status. As soon as you import `FormsModule`, this directive becomes active by default on all `` tags. You don't need to add a special selector. | | `NgModelGroup` | Creates and binds a `FormGroup` instance to a DOM element. | @@ -39,18 +39,18 @@ Template-driven forms rely on directives defined in the `FormsModule`. In the course of this tutorial, you bind a sample form to data and handle user input using the following steps. 1. Build the basic form. - * Define a sample data model - * Include required infrastructure such as the `FormsModule` + - Define a sample data model + - Include required infrastructure such as the `FormsModule` 1. Bind form controls to data properties using the `ngModel` directive and two-way data-binding syntax. - * Examine how `ngModel` reports control states using CSS classes - * Name controls to make them accessible to `ngModel` + - Examine how `ngModel` reports control states using CSS classes + - Name controls to make them accessible to `ngModel` 1. Track input validity and control status using `ngModel`. - * Add custom CSS to provide visual feedback on the status - * Show and hide validation-error messages + - Add custom CSS to provide visual feedback on the status + - Show and hide validation-error messages 1. Respond to a native HTML button-click event by adding to the model data. 1. Handle form submission using the [`ngSubmit`](api/forms/NgForm#properties) output property of the form. - * Disable the **Submit** button until the form is valid - * After submit, swap out the finished form for different content on the page + - Disable the **Submit** button until the form is valid + - After submit, swap out the finished form for different content on the page ## Build the form @@ -59,48 +59,48 @@ In the course of this tutorial, you bind a sample form to data and handle user i 1. The provided sample application creates the `Actor` class which defines the data model reflected in the form. - + 1. The form layout and details are defined in the `ActorFormComponent` class. - + - The component's `selector` value of "app-actor-form" means you can drop this form in a parent template using the `` tag. + The component's `selector` value of "app-actor-form" means you can drop this form in a parent template using the `` tag. 1. The following code creates a new actor instance, so that the initial form can show an example actor. - + - This demo uses dummy data for `model` and `skills`. - In a real app, you would inject a data service to get and save real data, or expose these properties as inputs and outputs. + This demo uses dummy data for `model` and `skills`. + In a real app, you would inject a data service to get and save real data, or expose these properties as inputs and outputs. 1. The application enables the Forms feature and registers the created form component. - + 1. The form is displayed in the application layout defined by the root component's template. - + - The initial template defines the layout for a form with two form groups and a submit button. - The form groups correspond to two properties of the Actor data model, name and studio. - Each group has a label and a box for user input. + The initial template defines the layout for a form with two form groups and a submit button. + The form groups correspond to two properties of the Actor data model, name and studio. + Each group has a label and a box for user input. - * The **Name** `` control element has the HTML5 `required` attribute - * The **Studio** `` control element does not because `studio` is optional + - The **Name** `` control element has the HTML5 `required` attribute + - The **Studio** `` control element does not because `studio` is optional - The **Submit** button has some classes on it for styling. - At this point, the form layout is all plain HTML5, with no bindings or directives. + The **Submit** button has some classes on it for styling. + At this point, the form layout is all plain HTML5, with no bindings or directives. 1. The sample form uses some style classes from [Twitter Bootstrap](https://getbootstrap.com/css): `container`, `form-group`, `form-control`, and `btn`. - To use these styles, the application's style sheet imports the library. +To use these styles, the application's style sheet imports the library. - + 1. The form requires that an actor's skill is chosen from a predefined list of `skills` maintained internally in `ActorFormComponent`. - The Angular [NgForOf directive](api/common/NgForOf "API reference") iterates over the data values to populate the `` element. - + If you run the application right now, you see the list of skills in the selection control. The input elements are not yet bound to data values or events, so they are still blank and have no behavior. @@ -110,7 +110,7 @@ The input elements are not yet bound to data values or events, so they are still The next step is to bind the input controls to the corresponding `Actor` properties with two-way data binding, so that they respond to user input by updating the data model, and also respond to programmatic changes in the data by updating the display. The `ngModel` directive declared in the `FormsModule` lets you bind controls in your template-driven form to properties in your data model. -When you include the directive using the syntax for two-way data binding, `[(ngModel)]`, Angular can track the value and user interaction of the control and keep the view synced with the model. +When you include the directive using the syntax for two-way data binding, `[(ngModel)]`, Angular can track the value and user interaction of the control and keep the view synced with the model. 1. Edit the template file `actor-form.component.html`. 1. Find the `` tag next to the **Name** label. @@ -124,21 +124,21 @@ HELPFUL: This example has a temporary diagnostic interpolation after each input When you imported the `FormsModule` in your component, Angular automatically created and attached an [NgForm](api/forms/NgForm) directive to the `` tag in the template (because `NgForm` has the selector `form` that matches `` elements). -To get access to the `NgForm` and the overall form status, declare a [template reference variable](guide/templates/reference-variables). +To get access to the `NgForm` and the overall form status, declare a [template reference variable](guide/templates/variables#template-reference-variables). 1. Edit the template file `actor-form.component.html`. 1. Update the `` tag with a template reference variable, `#actorForm`, and set its value as follows. - + - The `actorForm` template variable is now a reference to the `NgForm` directive instance that governs the form as a whole. + The `actorForm` template variable is now a reference to the `NgForm` directive instance that governs the form as a whole. 1. Run the app. 1. Start typing in the **Name** input box. - As you add and delete characters, you can see them appear and disappear from the data model. + As you add and delete characters, you can see them appear and disappear from the data model. - The diagnostic line that shows interpolated values demonstrates that values are really flowing from the input box to the model and back again. +The diagnostic line that shows interpolated values demonstrates that values are really flowing from the input box to the model and back again. ### Naming control elements @@ -158,11 +158,11 @@ After these revisions, the form template should look like the following: You'll notice that: -* Each `` element has an `id` property. - This is used by the `` element's `for` attribute to match the label to its input control. - This is a [standard HTML feature](https://developer.mozilla.org/docs/Web/HTML/Element/label). +- Each `` element has an `id` property. + This is used by the `` element's `for` attribute to match the label to its input control. + This is a [standard HTML feature](https://developer.mozilla.org/docs/Web/HTML/Element/label). -* Each `` element also has the required `name` property that Angular uses to register the control with the form. +- Each `` element also has the required `name` property that Angular uses to register the control with the form. When you have observed the effects, you can delete the `{{ model | json }}` text binding. @@ -178,7 +178,7 @@ These classes can be used to change a control's style based on its state. The following table describes the class names that Angular applies based on the control's state. | States | Class if true | Class if false | -|:--- |:--- |:--- | +| :------------------------------- | :------------ | :------------- | | The control has been visited. | `ng-touched` | `ng-untouched` | | The control's value has changed. | `ng-dirty` | `ng-pristine` | | The control's value is valid. | `ng-valid` | `ng-invalid` | @@ -192,29 +192,30 @@ You use these CSS classes to define the styles for your control based on its sta To see how the classes are added and removed by the framework, open the browser's developer tools and inspect the `` element that represents the actor name. -1. Using your browser's developer tools, find the `` element that corresponds to the **Name** input box. - You can see that the element has multiple CSS classes in addition to "form-control". +1. Using your browser's developer tools, find the `` element that corresponds to the **Name** input box. + You can see that the element has multiple CSS classes in addition to "form-control". 1. When you first bring it up, the classes indicate that it has a valid value, that the value has not been changed since initialization or reset, and that the control has not been visited since initialization or reset. - + - ; + ; - + 1. Take the following actions on the **Name** `` box, and observe which classes appear. - * Look but don't touch. - The classes indicate that it is untouched, pristine, and valid. - * Click inside the name box, then click outside it. - The control has now been visited, and the element has the `ng-touched` class instead of the `ng-untouched` class. + - Look but don't touch. + The classes indicate that it is untouched, pristine, and valid. - * Add slashes to the end of the name. - It is now touched and dirty. + - Click inside the name box, then click outside it. + The control has now been visited, and the element has the `ng-touched` class instead of the `ng-untouched` class. - * Erase the name. - This makes the value invalid, so the `ng-invalid` class replaces the `ng-valid` class. + - Add slashes to the end of the name. + It is now touched and dirty. + + - Erase the name. + This makes the value invalid, so the `ng-invalid` class replaces the `ng-valid` class. ### Create visual feedback for states @@ -273,7 +274,7 @@ Add a conditional error message to the `name` input box, as in the following exa -In this example, you hide the message when the control is either valid or *pristine*. +In this example, you hide the message when the control is either valid or _pristine_. Pristine means the user hasn't changed the value since it was displayed in this form. If you ignore the `pristine` state, you would hide the message only when the value is valid. If you arrive in this component with a new, blank actor or an invalid actor, you'll see the error message immediately, before you've done anything. @@ -292,28 +293,28 @@ To let form users add a new actor, you will add a **New Actor** button that resp 1. In the template, place a "New Actor" ` +``` -This next example features a template reference variable, `#customerInput`. +In this example, every time `isFormValid` changes, Angular automatically sets the `disabled` property of the `HTMLButtonElement` instance. - +### Component and directive properties -HELPFUL: Template expressions cannot refer to anything in the global namespace, except `undefined`. They can't refer to `window` or `document`. Additionally, they can't call `console.log()` or `Math.max()` and are restricted to referencing members of the expression context. +When an element is an Angular component, you can use property bindings to set component input properties using the same square bracket syntax. -### Preventing name collisions +```angular-html + + +``` -The context against which an expression evaluates is the union of the template variables, the directive's context object—if it has one—and the component's members. -If you reference a name that belongs to more than one of these namespaces, Angular applies the following precedence logic to determine the context: +In this example, every time `mySelection` changes, Angular automatically sets the `value` property of the `MyListbox` instance. -1. The template variable name. -1. A name in the directive's context. -1. The component's member names. +You can bind to directive properties as well. -To avoid variables shadowing variables in another context, keep variable names unique. -In the following example, the `AppComponent` template greets the `customer`, Padma. +```angular-html + + The current user's profile photo

+``` -The `@for` then lists each `customer` in the `customers` array. +### Attributes - +When you need to set HTML attributes that do not have corresponding DOM properties, such as ARIA attributes or SVG attributes, you can bind attributes to elements in your template with the `attr.` prefix. -The `customer` within the `@for` is in the context of the implicit `` defined by the _@for_. It refers to each `customer` in the `customers` array and displays "Ebony" and "Chiho". "Padma" is not displayed because that name is not in that array. +```angular-html + +

` displays "Padma" which is bound to the value of the `customer` property in the component class. +In this example, every time `listRole` changes, Angular automatically sets the `role` attribute of the `
` element by calling `setAttribute`. -## Expression best practices +If the value of an attribute binding is `null`, Angular removes the attribute by calling `removeAttribute`. -When using a template expression, follow these best practices: +### Text interpolation in properties and attributes -* Use short expressions +You can also use text interpolation syntax in properties and attributes by using the double curly brace syntax instead of square braces around the property or attribute name. When using this syntax, Angular treats the assignment as a property binding. -Use property names or method calls whenever possible. Keep application and business logic in the component, where it is accessible to develop and test. +```angular-html + + +``` -* Quick execution +To bind to an attribute with the text interpolation syntax, prefix the attribute name with `attr.` -Angular executes a template expression after every change detection cycle. Many asynchronous activities trigger change detection cycles, such as promise resolutions, HTTP results, timer events, key presses, and mouse moves. +```angular-html + + `, + ... +}) +export class UserProfile { + listClasses = 'full-width outlined'; + sectionClasses = ['expandable', 'elevated']; + buttonClasses = { + highlighted: true, + embiggened: false, + }; +} +``` - - - - +The above example renders the following DOM: + +```angular-html +
...
+
...
+ +``` + +Angular ignores any string values that are not valid CSS class names. + +When using static CSS classes, directly binding `class`, and binding specific classes, Angular intelligently combines all of the classes in the rendered result. + +```angular-ts +@Component({ + template: `
...`, + ... +}) +export class Listbox { + listType = 'box'; + isExpanded = true; +} +``` + +In the example above, Angular renders the `ul` element with all three CSS classes. + +```angular-html +
+``` + +Angular does not guarantee any specific order of CSS classes on rendered elements. + +When binding `class` to an array or an object, Angular compares the previous value to the current value with the triple-equals operator (`===`). You must create a new object or array instance when you modify these values in order to Angular to apply any updates. + +If an element has multiple bindings for the same CSS class, Angular resolves collisions by following its style precedence order. + +### CSS style properties + +You can also bind to CSS style properties directly on an element. + +```angular-html + +
+``` + +You can further specify units for CSS properties that accept units. + +```angular-html + +
+``` + +You can also set multiple style values in one binding. Angular accepts the following types of value: + +| Description of `style` value | TypeScript type | +| ------------------------------------------------------------------------------------------------------------------------- | --------------------- | +| A string containing zero or more CSS declarations, such as `"display: flex; margin: 8px"`. | `string` | +| An object where each property name is a CSS property name and each corresponding value is the value of that CSS property. | `Record` | + +```angular-ts +@Component({ + template: ` +
...
+
...
+ `, + ... +}) +export class UserProfile { + listStyle = 'display: flex; padding: 8px'; + sectionStyles = { + border: '1px solid black', + font-weight: 'bold', + }; +} +``` + +The above example renders the following DOM. + +```angular-html +
...
+
...
+``` + +When binding `style` to an object, Angular compares the previous value to the current value with the triple-equals operator (`===`). You must create a new object instance when you modify these values in order to Angular to apply any updates. + +If an element has multiple bindings for the same style property, Angular resolves collisions by following its style precedence order. diff --git a/adev/src/content/guide/templates/class-binding.md b/adev/src/content/guide/templates/class-binding.md deleted file mode 100644 index 1e2fedb236d4..000000000000 --- a/adev/src/content/guide/templates/class-binding.md +++ /dev/null @@ -1,94 +0,0 @@ -# Class and style binding - -Use class and style bindings to add and remove CSS class names from an element's `class` attribute and to set styles dynamically. - -## Binding to a single CSS `class` - -To create a single class binding, type the following: - -`[class.sale]="onSale"` - -Angular adds the class when the bound expression, `onSale` is truthy, and it removes the class when the expression is falsy—with the exception of `undefined`. The behavior of `undefined` is specifically useful when multiple bindings to the same class exist across different directives on an element. - -## Binding to multiple CSS classes - -To bind to multiple classes, type the following: - -`[class]="classExpression"` - -The expression can be one of: - -* A space-delimited string of class names. -* An object with class names as the keys and truthy or falsy expressions as the values. -* An array of class names. - -With the object format, Angular adds a class only if its associated value is truthy. - -IMPORTANT: With any object-like expression—such as `object`, `Array`, `Map`, or `Set` —the identity of the object must change for Angular to update the class list. -Updating the property without changing object identity has no effect. - -If there are multiple bindings to the same class name, Angular uses styling precedence to determine which binding to use. - -The following table summarizes class binding syntax. - -| Binding Type | Syntax | Input Type | Example Input Values | -| :------------------- | :-------------------------- | :---------------------- | :----------------------------------- | -| Single class binding | `[class.sale]="onSale"` | `boolean|undefined|null`| `true`, `false` | -| Multi-class binding | `[class]="classExpression"` | `string` | `"my-class-1 my-class-2 my-class-3"` | -| Multi-class binding | `[class]="classExpression"` | `Record` | `{foo: true, bar: false}` | -| Multi-class binding | `[class]="classExpression"` | `Array` | `['foo', 'bar']` | - - -## Binding to a single style - -To create a single style binding, use the prefix `style` followed by a dot and the name of the CSS style. - -For example, to set the `width` style, type the following: `[style.width]="width"` - -Angular sets the property to the value of the bound expression, which is usually a string. Optionally, you can add a unit extension like `em` or `%`, which requires a number type. - -1. To write a style in dash-case, type the following: - -
- -2. To write a style in camelCase, type the following: - -
- -## Binding to multiple styles - -To toggle multiple styles, bind to the `[style]` attribute—for example, `[style]="styleExpression"`. The `styleExpression` can be one of: - -* A string list of styles such as `"width: 100px; height: 100px; background-color: cornflowerblue;"`. -* An object with style names as the keys and style values as the values, such as `{width: '100px', height: '100px', backgroundColor: 'cornflowerblue'}`. - -Note that binding an array to `[style]` is not supported. - -IMPORTANT: When binding `[style]` to an object expression, the identity of the object must change for Angular to update the class list. -Updating the property without changing object identity has no effect. - -### Single and multiple-style binding example - - - -If there are multiple bindings to the same style attribute, Angular uses styling precedence to determine which binding to use. - -The following table summarizes style binding syntax. - -| Binding Type | Syntax | Input Type | Example Input Values | -| :------------------------------ | :-------------------------- | :---------------------- | :------------------------------ | -| Single style binding | `[style.width]="width"` | `string| undefined|null`| `"100px"` | -| Single style binding with units | `[style.width.px]="width"` | `number| undefined|null`| `100` | -| Multi-style binding | `[style]="styleExpression"` | `string` | `"width: 100px; height: 100px"` | -| Multi-style binding | `[style]="styleExpression"` | `Record` | `{width: '100px', height: '100px'}` | - -## Styling precedence - -A single HTML element can have its CSS class list and style values bound to multiple sources (for example, host bindings from multiple directives). - -## What’s next - - - - - diff --git a/adev/src/content/guide/templates/control-flow.md b/adev/src/content/guide/templates/control-flow.md index 1d7d0d5ddef5..77921c9f4507 100644 --- a/adev/src/content/guide/templates/control-flow.md +++ b/adev/src/content/guide/templates/control-flow.md @@ -1,19 +1,20 @@ -# Built-in control flow +# Control flow -Angular templates support _control flow blocks_ that let you conditionally show, hide, and repeat elements. +Angular templates support control flow blocks that let you conditionally show, hide, and repeat elements. -## `@if` block conditionals +Note: This was previously accomplished with the ngIf, ngFor, and \ngSwitch directives. + +## Conditionally display content with `@if`, `@else-if` and `@else` The `@if` block conditionally displays its content when its condition expression is truthy: ```angular-html @if (a > b) { - {{a}} is greater than {{b}} +
{{a}} is greater than {{b}}
} ``` -The `@if` block might have one or more associated `@else` blocks. Immediately after an `@if` block, you can optionally -specify any number of `@else if` blocks and one `@else` block: +If you want to display alternative content, you can do so by providing any number of `@else if` blocks and a singular `@else` block. ```angular-html @if (a > b) { @@ -27,20 +28,21 @@ specify any number of `@else if` blocks and one `@else` block: ### Referencing the conditional expression's result -The new built-in `@if` conditional supports referencing of expression results to keep a solution for common coding -patterns: +The `@if` conditional supports saving the result of the conditional expression into a variable for reuse inside of the block. ```angular-html -@if (users$ | async; as users) { - {{ users.length }} +@if (user.profile.settings.startDate; as startDate) { + {{ startDate }} } ``` -## `@for` block - repeaters +This can be useful for referencing longer expressions that would be easier to read and maintain within the template. + +## Repeat content with the `@for` block -The `@for` repeatedly renders content of a block for each item in a collection. The collection can be represented as any -JavaScript [iterable](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Iteration_protocols) but there -are performance advantages of using a regular `Array`. A basic `@for` loop looks like: +The `@for` block loops through a collection and repeatedly renders the content of a block. The collection can be any JavaScript [iterable](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Iteration_protocols), but Angular has additional performance optimizations for `Array` values. + +A typical `@for` loop looks like: ```angular-html @for (item of items; track item.id) { @@ -48,25 +50,21 @@ are performance advantages of using a regular `Array`. A basic `@for` loop looks } ``` -### `track` for calculating difference of two collections +### Why is `track` in `@for` blocks important? + +The `track` expression allows Angular to maintain a relationship between your data and the DOM nodes on the page. This allows Angular to optimize performance by executing the minimum necessary DOM operations when the data changes. -The value of the `track` expression determines a key used to associate array items with the views in the DOM. Having -clear indication of the item identity allows Angular to execute a minimal set of DOM operations as items are added, -removed or moved in a collection. +Using track effectively can significantly improve your application's rendering performance when looping over data collections. -Using track effectively can significantly enhance your application's performance, especially in loops over data -collections. +Select a property that uniquely identifies each item in the `track` expression. If your data model includes a uniquely identifying property, commonly `id` or `uuid`, use this value. If your data does not include a field like this, strongly consider adding one. -For collections that do not undergo modifications (no items are moved, added, or deleted), using `track $index` is an -efficient strategy. For collections with mutable data or frequent changes, select a property that uniquely identifies -each item to use as your track expression. +For static collections that never change, you can use `$index` to tell Angular to track each item by its index in the collection. -Be aware of the potential for increased DOM re-creation when using object identity as a track key with immutable data -structures, as this can lead to unnecessary performance costs. +If no other option is available, you can specify `identity`. This tells Angular to track the item by its reference identity using the triple-equals operator (`===`). Avoid this option whenever possible as it can lead to significantly slower rendering updates, as Angular has no way to map which data item corresponds to which DOM nodes. -### `$index` and other contextual variables +### Contextual variables in `@for` blocks -Inside `@for` contents, several implicit variables are always available: +Inside `@for` blocks, several implicit variables are always available: | Variable | Meaning | | -------- | --------------------------------------------- | @@ -81,16 +79,15 @@ These variables are always available with these names, but can be aliased via a ```angular-html @for (item of items; track item.id; let idx = $index, e = $even) { - Item #{{ idx }}: {{ item.name }} +
Item #{{ idx }}: {{ item.name }}
} ``` -The aliasing is especially useful in case of using nested `@for` blocks where contextual variable names could collide. +The aliasing is useful when nesting `@for` blocks, letting you read variables from the outer `@for` block from an inner `@for` block. -### `empty` block +### Providing a fallback for `@for` blocks with the `@empty` block -You can optionally include an `@empty` section immediately after the `@for` block content. The content of the `@empty` -block displays when there are no items: +You can optionally include an `@empty` section immediately after the `@for` block content. The content of the `@empty` block displays when there are no items: ```angular-html @for (item of items; track item.name) { @@ -100,55 +97,31 @@ block displays when there are no items: } ``` -## `@switch` block - selection +## Conditionally display content with the `@switch` block -The syntax for `switch` is very similar to `if`, and is inspired by the JavaScript `switch` statement: +While the `@if` block is great for most scenarios, the `@switch` block provides an alternate syntax to conditionally render data. Its syntax closely resembles JavaScript's `switch` statement. ```angular-html -@switch (condition) { - @case (caseA) { - Case A. +@switch (userPermissions) { + @case ('admin') { + } - @case (caseB) { - Case B. + @case ('reviewer') { + + } + @case ('editor') { + } @default { - Default case. + } } ``` -The value of the conditional expression is compared to the case expression using the `===` operator. - -`@switch` does not have fallthrough, so you do not need an equivalent to a `break` or `return` statement. - -The `@default` block is optional and can be omitted. If no `@case` matches the expression and there is no `@default` -block, nothing is shown. - -## Built-in control flow and the `NgIf`, `NgSwitch` and `NgFor` structural directives +The value of the conditional expression is compared to the case expression using the triple-equals (`===`) operator. -The `@if` block replaces `ngIf` for expressing conditional parts of the UI. +`@switch` does not have a fallthrough, so you do not need an equivalent to a `break` or `return` statement in the block. -The `@switch` block replaces `ngSwitch` with major benefits: +You can optionally include a `@default` block. The content of the `@default` block displays if none of the preceding case expressions match the switch value. -- it does not require a container element to hold the condition expression or each conditional template; -- it supports template type-checking, including type narrowing within each branch. - -The `@for` block replaces `ngFor` for iteration, and has several differences compared to its structural -directive `NgFor` predecessor: - -- tracking expression (calculating keys corresponding to object identities) is mandatory but has better ergonomics (it - is enough to write an expression instead of creating the `trackBy` method); -- uses a new optimized algorithm for calculating a minimal number of DOM operations to be performed in response to - changes in a collection, instead of Angular’s customizable diffing implementation (`IterableDiffer`); -- has support for `@empty` blocks. - -The `track` setting replaces `NgFor`'s concept of a `trackBy` function. Because `@for` is built-in, we can provide a -better experience than passing a `trackBy` function, and directly use an expression representing the key instead. -Migrating from `trackBy` to `track` is possible by invoking the `trackBy` function: - -```angular-html -@for (item of items; track itemId($index, item)) { - {{ item.name }} -} -``` +If no `@case` matches the expression and there is no `@default` block, nothing is shown. diff --git a/adev/src/content/guide/templates/defer.md b/adev/src/content/guide/templates/defer.md new file mode 100644 index 000000000000..7290cfdade7e --- /dev/null +++ b/adev/src/content/guide/templates/defer.md @@ -0,0 +1,338 @@ +# Deferred loading with `@defer` + +Deferrable views, also known as `@defer` blocks, reduce the initial bundle size of your application by deferring the loading of code that is not strictly necessary for the initial rendering of a page. This often results in a faster initial load and improvement in Core Web Vitals (CWV), primarily Largest Contentful Paint (LCP) and Time to First Byte (TTFB). + +To use this feature, you can declaratively wrap a section of your template in a @defer block: + +```angular-html +@defer { + +} +``` + +The code for any components, directives, and pipes inside of the `@defer` block is split into a separate JavaScript file and loaded only when necessary, after the rest of the template has been rendered. + +Deferrable views support a variety of triggers, prefetching options, and sub-blocks for placeholder, loading, and error state management. + +## Which dependencies are deferred? + +Components, directives, pipes, and any component CSS styles can be deferred when loading an application. + +In order for the dependencies within a `@defer` block to be deferred, they need to meet two conditions: + +1. They must be standalone. Non-stadalone dependencies cannot be deferred and are still eagerly loaded, even if they are inside of `@defer` blocks. +1. They cannot be referenced outside of `@defer` blocks within the same file. If they are referenced outside of the `@defer` block or referenced within ViewChild queries, the dependencies will be eagerly loaded. + +The _transitive_ dependencies of the components, directives and pipes used in the `@defer` block do not strictly need to be standalone; transitive dependencies can still be declared in an `NgModule` and participate in deferred loading. + +## How to manage different stages of deferred loading + +`@defer` blocks have several sub blocks to allow you to gracefully handle different stages in the deferred loading process. + +### `@defer` + +This is the primary block that defines the section of content that is lazily loaded. It is not rendered initially– deferred content loads and renders once the specified [trigger](/guide/defer#triggers) occurs or the `when` condition is met. + +By default, a @defer block is triggered when the browser state becomes [idle](/guide/defer#on-idle). + +```angular-html +@defer { + +} +``` + +### Show placeholder content with `@placeholder` + +By default, defer blocks do not render any content before they are triggered. + +The `@placeholder` is an optional block that declares what content to show before the `@defer` block is triggered. + +```angular-html +@defer { + +} @placeholder { +
Placeholder content
+} +``` + +While optional, certain triggers may require the presence of either a `@placeholder` or a [template reference variable](/guide/templates/variables#template-reference-variables) to function. See the [Triggers](/guide/defer#triggers) section for more details. + +Angular replaces placeholder content with the main content once loading is complete. You can use any content in the placeholder section including plain HTML, components, directives, and pipes. Keep in mind the _dependencies of the placeholder block are eagerly loaded_. + +The `@placeholder` block accepts an optional parameter to specify the `minimum` amount of time that this placeholder should be shown after the placeholder content initially renders. + +```angular-html +@defer { + +} @placeholder (minimum 500ms) { +
Placeholder content
+} +``` + +This `minimum` parameter is specified in time increments of milliseconds (ms) or seconds (s). You can use this parameter to prevent fast flickering of placeholder content in the case that the deferred dependencies are fetched quickly. + +### Show loading content with `@loading` + +The `@loading` block is an optional block that allows you to declare content that is shown while deferred dependencies are loading. It replaces the `@placeholder` block once loading is triggered. + +```angular-html +@defer { + +} @loading { + +} @placeholder { +
Placeholder content
+} +``` + +Its dependencies are eagerly loaded (similar to `@placeholder`). + +The `@loading` block accepts two optional parameters to help prevent fast flickering of content that may occur when deferred dependencies are fetched quickly,: + +- `minimum` - the minimum amount of time that this placeholder should be shown +- `after` - the amount of time to wait after loading begins before showing the loading template + +```angular-html +@defer { + +} @loading (after 100ms; minimum 1s) { + +} +``` + +Both parameters are specified in time increments of milliseconds (ms) or seconds (s). In addition, the timers for both parameters begin immediately after the loading has been triggered. + +### Show error state when deferred loading fails with `@error` + +The `@error` block is an optional block that displays if deferred loading fails. Similar to `@placeholder` and `@loading`, the dependencies of the @error block are eagerly loaded. + +```angular-html +@defer { + +} @error { +
Failed to load large component.
+} +``` + +## Controlling deferred content loading with triggers + +You can specify triggers that control when Angular loads and displays deferred content. + +When a `@defer` block is triggered, it replaces placeholder content with lazily loaded content. + +Multiple event triggers can be defined by separating them with a semicolon, `;` and will be evaluated as OR conditions. + +There are two types of triggers: `on` and `when`. + +### `on` + +`on` specifies a condition for when the `@defer` block is triggered. + +The available triggers are as follows: + +| Trigger | Description | +| ----------------------------- | ---------------------------------------------------------------------- | +| [`idle`](#idle) | Triggers when the browser is idle. | +| [`viewport`](#viewport) | Triggers when specified content enters the viewport | +| [`interaction`](#interaction) | Triggers when the user interacts with specified element | +| [`hover`](#hover) | Triggers when the mouse hovers over specified area | +| [`immediate`](#immediate) | Triggers immediately after non-deferred content has finished rendering | +| [`timer`](#timer) | Triggers after a specific duration | + +#### `idle` + +The `idle` trigger loads the deferred content once the browser has reached an idle state, based on requestIdleCallback. This is the default behavior with a defer block. + +```angular-html + +@defer { + +} @placeholder { +
Large component placeholder
+} +``` + +#### `viewport` + +The `viewport` trigger loads the deferred content when the specified content enters the viewport using the [Intersection Observer API](https://developer.mozilla.org/docs/Web/API/Intersection_Observer_API). Observed content may be `@placeholder` content or an explicit element reference. + +By default, the `@defer` watches for the placeholder entering the viewport. Placeholders used this way must have a single root element. + +```angular-html +@defer (on viewport) { + +} @placeholder { +
Large component placeholder
+} +``` + +Alternatively, you can specify a [template reference variable](/guide/templates/variables) in the same template as the `@defer` block as the element that is watched to enter the viewport. This variable is passed in as a parameter on the viewport trigger. + +```angular-html +
Hello!
+@defer (on viewport(greeting)) { + +} +``` + +#### `interaction` + +The `interaction` trigger loads the deferred content when the user interacts with the specified element through `click` or `keydown` events. + +By default, the placeholder acts as the interaction element. Placeholders used this way must have a single root element. + +```angular-html +@defer (on interaction) { + +} @placeholder { +
Large component placeholder
+} +``` + +Alternatively, you can specify a [template reference variable](/guide/templates/variables) in the same template as the `@defer` block as the element that is watched to enter the viewport. This variable is passed in as a parameter on the viewport trigger.Z + +```angular-html +
Hello!
+@defer (on interaction(greeting)) { + +} +``` + +#### `hover` + +The `hover` trigger loads the deferred content when the mouse has hovered over the triggered area through the `mouseenter` and `focusin` events. + +By default, the placeholder acts as the interaction element. Placeholders used this way must have a single root element. + +```angular-html +@defer (on hover) { + +} @placeholder { +
Large component placeholder
+} +``` + +Alternatively, you can specify a [template reference variable](/guide/templates/variables) in the same template as the `@defer` block as the element that is watched to enter the viewport. This variable is passed in as a parameter on the viewport trigger. + +```angular-html +
Hello!
+@defer (on interaction(greeting)) { + +} +``` + +#### `immediate` + +The `immediate` trigger loads the deferred content immediately. This means that the deferred block loads as soon as all other non-deferred content has finished rendering. + +```angular-html +@defer (on immediate) { + +} @placeholder { +
Large component placeholder
+} +``` + +#### `timer` + +The `timer` trigger loads the deferred content after a specified duration. + +```angular-html +@defer (on timer(500ms)) { + +} @placeholder { +
Large component placeholder
+} +``` + +The duration parameter must be specified in milliseconds (`ms`) or seconds (`s`). + +### `when` + +The `when` trigger accepts a custom conditional expression and loads the deferred content when the condition becomes truthy. + +```angular-html +@defer (when condition) { + +} @placeholder { +
Large component placeholder
+} +``` + +This is a one-time operation– the `@defer` block does not revert back to the placeholder if the condition changes to a falsy value after becoming truthy. + +## Prefetching data with `prefetch` + +In addition to specifying a condition that determines when deferred content is shown, you can optionally specify a prefetch trigger. This trigger lets you load the JavaScript associated with the `@defer` block before the deferred content is shown. + +Prefetching enables more advanced behaviors, such as letting you start to prefetch resources before a user has actually seen or interacted with a defer block, but might interact with it soon, making the resources available faster. + +You can specify a prefetch trigger similarly to the block's main trigger, but prefixed with the `prefetch` keyword. The block's main trigger and prefetch trigger are separated with a semi-colon character (`;`). + +In the example below, the prefetching starts when a browser becomes idle and the contents of the block is rendered only once the user interacts with the placeholder. + +```angular-html +@defer (on interaction; prefetch on idle) { + +} @placeholder { +
Large component placeholder
+} +``` + +## Testing `@defer` blocks + +Angular provides TestBed APIs to simplify the process of testing `@defer` blocks and triggering different states during testing. By default, `@defer` blocks in tests play through like a defer block would behave in a real application. If you want to manually step through states, you can switch the defer block behavior to `Manual` in the TestBed configuration. + +```angular-ts +it('should render a defer block in different states', async () => { + // configures the defer block behavior to start in "paused" state for manual control. + TestBed.configureTestingModule({deferBlockBehavior: DeferBlockBehavior.Manual}); + @Component({ + // ... + template: ` + @defer { + + } @placeholder { + Placeholder + } @loading { + Loading... + } + ` + }) + class ComponentA {} + // Create component fixture. + const componentFixture = TestBed.createComponent(ComponentA); + // Retrieve the list of all defer block fixtures and get the first block. + const deferBlockFixture = (await componentFixture.getDeferBlocks())[0]; + // Renders placeholder state by default. + expect(componentFixture.nativeElement.innerHTML).toContain('Placeholder'); + // Render loading state and verify rendered output. + await deferBlockFixture.render(DeferBlockState.Loading); + expect(componentFixture.nativeElement.innerHTML).toContain('Loading'); + // Render final state and verify the output. + await deferBlockFixture.render(DeferBlockState.Complete); + expect(componentFixture.nativeElement.innerHTML).toContain('large works!'); +}); +``` + +## Does `@defer` work with `NgModule`? + +`@defer` blocks are compatible with both standalone and NgModule-based components, directives and pipes. However, only standalone components, directives and pipes can be deferred. NgModule-based dependencies are not deferred and are included in the eagerly loaded bundle. + +## How does `@defer` work with server-side rendering (SSR) and static-site generation (SSG)? + +When rendering an application on the server (either using SSR or SSG), defer blocks always render their `@placeholder` (or nothing if a placeholder is not specified). + +Triggers are ignored on the server. + +## Best practices for deferring views + +### Avoid cascading loads with nested `@defer` blocks + +When you have nested `@defer` blocks, they should have different triggers in order to avoid loading simultaneously, which causes cascading requests and may negatively impact page load performance. + +### Avoid layout shifts + +Avoid deferring components that are visible in the user’s viewport on initial load. Doing this may negatively affect Core Web Vitals by causing an increase in cumulative layout shift (CLS). + +In the event this is necessary, avoid `immediate`, `timer`, `viewport`, and custom `when` triggers that cause the content to load during the initial page render. diff --git a/adev/src/content/guide/templates/event-binding.md b/adev/src/content/guide/templates/event-binding.md deleted file mode 100644 index a7fb7715d7b3..000000000000 --- a/adev/src/content/guide/templates/event-binding.md +++ /dev/null @@ -1,85 +0,0 @@ -# Event binding - -Event binding lets you listen for and respond to user actions such as keystrokes, mouse movements, clicks, and touches. - -## Binding to events - -HELPFUL: For information on binding to properties, see [Property binding](guide/templates/property-binding). - -To bind to an event you use the Angular event binding syntax. -This syntax consists of a target event name within parentheses to the left of an equal sign, and a quoted template statement to the right. - -Create the following example; the target event name is `click` and the template statement is `onSave()`. - - - - - -The event binding listens for the button's click events and calls the component's `onSave()` method whenever a click occurs. - - - -### Determining an event target - -To determine an event target, Angular checks if the name of the target event matches an event property of a known directive. - -Create the following example: (Angular checks to see if `myClick` is an event on the custom `ClickDirective`) - - - -If the target event name, `myClick` fails to match an output property of `ClickDirective`, Angular will instead bind to the `myClick` event on the underlying DOM element. - -## Binding to keyboard events - -You can bind to keyboard events using Angular's binding syntax. You can specify the key or code that you would like to bind to keyboard events. The `key` and `code` fields are a native part of the browser keyboard event object. By default, event binding assumes you want to use the `key` field on the keyboard event. You can also use the `code` field. - -Combinations of keys can be separated by a `.` (period). For example, `keydown.enter` will allow you to bind events to the `enter` key. You can also use modifier keys, such as `shift`, `alt`, `control`, and the `command` keys from Mac. The following example shows how to bind a keyboard event to `keydown.shift.t`. - -```angular-html - -``` - -Depending on the operating system, some key combinations might create special characters instead of the key combination that you expect. MacOS, for example, creates special characters when you use the option and shift keys together. If you bind to `keydown.shift.alt.t`, on macOS, that combination produces a `ˇ` character instead of a `t`, which doesn't match the binding and won't trigger your event handler. To bind to `keydown.shift.alt.t` on macOS, use the `code` keyboard event field to get the correct behavior, such as `keydown.code.shiftleft.altleft.keyt` shown in this example. - -```angular-html - -``` - -The `code` field is more specific than the `key` field. The `key` field always reports `shift`, whereas the `code` field will specify `leftshift` or `rightshift`. When using the `code` field, you might need to add separate bindings to catch all the behaviors you want. Using the `code` field avoids the need to handle OS specific behaviors such as the `shift + option` behavior on macOS. - -For more information, visit the full reference for [key](https://developer.mozilla.org/docs/Web/API/UI_Events/Keyboard_event_key_values) and [code](https://developer.mozilla.org/docs/Web/API/UI_Events/Keyboard_event_code_values) to help build out your event strings. - -## Binding to passive events - -Angular also supports [passive event](https://developer.chrome.com/en/docs/lighthouse/best-practices/uses-passive-event-listeners/) listeners. - -This is an advanced technique that is not necessary for most applications. You may find this useful if you need to optimize handling of frequently occurring events that are causing performance problems. - -For example, to make a scroll event passive, it may be necessary to set the special zone.js flag in `src/index.html`: - -```angular-html - - - - - - - - - -``` - -After those steps, if you add event listeners for the `scroll` event, the listeners will be `passive`. - -Note that the above case applies only to applications using zone.js. - -## What's next - - - - - - - diff --git a/adev/src/content/guide/templates/event-listeners.md b/adev/src/content/guide/templates/event-listeners.md new file mode 100644 index 000000000000..80fd3e70834d --- /dev/null +++ b/adev/src/content/guide/templates/event-listeners.md @@ -0,0 +1,99 @@ +# Adding event listeners + +Angular supports defining event listeners on an element in your template by specifying the event name inside parentheses along with a statement that runs even time the event occurs. + +## Listening to native events + +When you want to add event listeners to an HTML element, you wrap the event with parentheses, `()`, which allows you to specify a listener statement. + +```angular-ts +@Component({ + template: ` + + `, + ... +}) +export class AppComponent({ + updateField(): void { + console.log('Field is updated!'); + } +}) +``` + +In this example, Angular calls `updateField` every time the `` element emits a `keyup` event. + +You can add listeners for any native events, such as: `click`, `keydown`, `mouseover`, etc. To learn more, check out the [all available events on elements on MDN](https://developer.mozilla.org/en-US/docs/Web/API/Element#events). + +## Accessing the event argument + +In every template event listener, Angular provides a variable named `$event` that contains a reference to the event object. + +```angular-ts +@Component({ + template: ` + + `, + ... +}) +export class AppComponent { + updateField(event: KeyboardEvent): void { + console.log(`The user pressed: ${event.key}`); + } +} +``` + +## Using key modifiers + +When you want to capture specific keyboard events for a specific key, you might write some code like the following: + +```angular-ts +@Component({ + template: ` + + `, + ... +}) +export class AppComponent { + updateField(event: KeyboardEvent): void { + if (event.key === 'Enter') { + console.log('The user pressed enter in the text field.'); + } + } +} +``` + +However, since this is a common scenario, Angular lets you filter the events by specifying a specific key using the period (`.`) character. By doing so, code can be simplified to: + +```angular-ts +@Component({ + template: ` + + `, + ... +}) +export class AppComponent({ + updateField(event: KeyboardEvent): void { + console.log('The user pressed enter in the text field.'); + } +}) +``` + +You can also add additional key modifiers: + +```angular-html + + +``` + +Angular supports the modifiers `alt`, `control`, `meta`, and `shift`. + +You can specify the key or code that you would like to bind to keyboard events. The key and code fields are a native part of the browser keyboard event object. By default, event binding assumes you want to use the [Key values for keyboard events](https://developer.mozilla.org/docs/Web/API/UI_Events/Keyboard_event_key_values). + +Angular also allows you to specify [Code values for keyboard events](https://developer.mozilla.org/docs/Web/API/UI_Events/Keyboard_event_code_values) by providing a built-in `code` suffix. + +```angular-html + + +``` + +This can be useful for handling keyboard events consistently across different operating systems. For example, when using the Alt key on MacOS devices, the `key` property reports the key based on the character already modified by the Alt key. This means that a combination like Alt + S reports a `key` value of `'ß'`. The `code` property, however, corresponds to the physical or virtual button pressed rather than the character produced. diff --git a/adev/src/content/guide/templates/expression-syntax.md b/adev/src/content/guide/templates/expression-syntax.md new file mode 100644 index 000000000000..74e75c96716f --- /dev/null +++ b/adev/src/content/guide/templates/expression-syntax.md @@ -0,0 +1,113 @@ +# Expression Syntax + +Angular expressions are based on JavaScript, but differ in some key ways. This guide walks through the similarities and differences between Angular expressions and standard JavaScript. + +## Value literals + +Angular supports a subset of [literal values](https://developer.mozilla.org/en-US/docs/Glossary/Literal) from JavaScript. + +### Supported value literals + +| Literal type | Example values | +| ------------ | ------------------------------- | +| String | `'Hello'`, `"World"` | +| Boolean | `true`, `false` | +| Number | `123`, `3.14` | +| Object | `{name: 'Alice'}` | +| Array | `['Onion', 'Cheese', 'Garlic']` | +| null | `null` | + +### Unsupported literals + +| Literal type | Example value | +| --------------- | ------------------- | +| Template string | `\`Hello ${name}\`` | +| RegExp | `/\d+/` | + +## Globals + +Angular expressions support the following [globals](https://developer.mozilla.org/en-US/docs/Glossary/Global_object): + +- [undefined](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/undefined) +- [$any](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#any) + +No other JavaScript globals are supported. Common JavaScript globals include `Number`, `Boolean`, `NaN`, `Infinity`, `parseInt`, and more. + +## Local variables + +Angular automatically makes special local variables available for use in expressions in specific contexts. These special variables always start with the dollar sign character (`$`). + +For example, `@for` blocks make several local variables corresponding to information about the loop, such as `$index`. + +## What operators are supported? + +### Supported operators + +Angular supports the following operators from standard JavaScript. + +| Operator | Example(s) | +| --------------------- | ---------------------------------------- | +| Add / Concatenate | `1 + 2` | +| Subtract | `52 - 3` | +| Multiply | `41 6` | +| Divide | `20 / 4` | +| Remainder (Modulo) | `17 % 5` | +| Parenthesis | `9 * (8 + 4)` | +| Conditional (Ternary) | `a > b ? true : false` | +| And (Logical) | `&&` | +| Or (Logical) | `\|\|` | +| Not (Logical) | `!` | +| Nullish Coalescing | `const foo = null ?? 'default'` | +| Comparison Operators | `<`, `<=`, `>`, `>=`, `==`, `===`, `!==` | +| Unary Negation | `const y = -x` | +| Unary Plus | `const x = +y` | +| Property Accessor | `person['name'] = 'Mirabel'` | + +Angular expressions additionally also support the following non-standard operators: + +| Operator | Example(s) | +| ------------------------------- | ------------------------------ | +| [Pipe](/guides/templates/pipes) | `{{ total \| currency }}` | +| Optional chaining\* | `someObj.someProp?.nestedProp` | +| Non-null assertion (TypeScript) | `someObj!.someProp` | + +\Note: Optional chaining behaves differently from the standard JavaScript version in that if the left side of Angular’s optional chaining operator is `null` or `undefined`, it returns `null` instead of `undefined`. + +### Unsupported operators + +| Operator | Example(s) | +| --------------------- | --------------------------------- | +| All bitwise operators | `&`, `&=`, `~`, `\|=`, `^=`, etc. | +| Assignment operators | `=` | +| Object destructuring | `const { name } = person` | +| Array destructuring | `const [firstItem] = items` | +| Comma operator | `x = (x++, x)` | +| typeof | `typeof 42` | +| void | `void 1` | +| in | `'model' in car` | +| instanceof | `car instanceof Automobile` | +| new | `new Car()` | + +## Lexical context for expressions + +Angular expressions are evaluated within the context of the component class as well as any relevant [template variables](/guide/templates/variables), locals, and globals. + +When referring to class members, `this` is always implied. + +## Declarations + +Generally speaking, declarations are not supported in Angular expressions. This includes, but is not limited to: + +| Declarations | Example(s) | +| --------------- | ------------------------------------------- | +| Variables | `let label = 'abc'`, `const item = 'apple'` | +| Functions | `function myCustomFunction() { }` | +| Arrow Functions | `() => { }` | +| Classes | `class Rectangle { }` | + +# Event listener statements + +Event handlers are statements rather than expressions. While they support all of the same syntax as Angular expressions, the are two key differences: + +1. Statements do support assignment operators (but not destructing assignments) +1. Statements do not support pipes diff --git a/adev/src/content/guide/templates/interpolation.md b/adev/src/content/guide/templates/interpolation.md deleted file mode 100644 index 7e990a4cf27a..000000000000 --- a/adev/src/content/guide/templates/interpolation.md +++ /dev/null @@ -1,24 +0,0 @@ -# Displaying values with interpolation - -Interpolation refers to embedding expressions into marked up text. By default, interpolation uses the double curly braces `{{` and `}}` as delimiters. - -To illustrate how interpolation works, consider an Angular component that contains a `currentCustomer` variable: - - - -Use interpolation to display the value of this variable in the corresponding component template: - - - -Angular replaces `currentCustomer` with the string value of the corresponding component property. In this case, the value is `Maria`. - -In the following example, Angular evaluates the `title` and `itemImageUrl` properties to display some title text and an image. - - - -## What's Next - - - - - diff --git a/adev/src/content/guide/templates/let-template-variables.md b/adev/src/content/guide/templates/let-template-variables.md deleted file mode 100644 index 16576056f9b4..000000000000 --- a/adev/src/content/guide/templates/let-template-variables.md +++ /dev/null @@ -1,105 +0,0 @@ -# Local template variables - -Angular's `@let` syntax allows you to define a local variable and re-use it across the template. - -IMPORTANT: the `@let` syntax is currently in [Developer Preview](/reference/releases#developer-preview). - -## Syntax - -`@let` declarations are similar to [JavaScript's `let`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/let) and -their values can be any valid Angular expression. The expressions will be re-evaluated any time the -template is executed. - -```angular-html -@let name = user.name; -@let greeting = 'Hello, ' + name; -@let data = data$ | async; -@let pi = 3.1459; -@let coordinates = {x: 50, y: 100}; -@let longExpression = 'Lorem ipsum dolor sit amet, consectetur adipiscing elit ' + - 'sed do eiusmod tempor incididunt ut labore et dolore magna ' + - 'Ut enim ad minim veniam...'; -``` - -### Referencing the value of `@let` - -Once you've declared the `@let`, you can reuse it anywhere in the template: - - -```angular-html -@let user = user$ | async; - -@if (user) { -
Hello, {{user.name}}
- - -
- @for (snack of user.favoriteSnacks; track snack.id) { -
{{snack.name}}
- } -
- - -} -``` - -## Assignability - -A key difference between `@let` and JavaScript's `let` is that `@let` cannot be re-assigned -within the template, however its value will be recomputed when Angular runs change detection. - -```angular-html -@let value = 1; - - - -``` - -## Scope - -`@let` declarations are scoped to the current view and its descendants. Since they are not -hoisted, they cannot be accessed by parent views or siblings: - -```angular-html -@let topLevel = value; - -
- @let insideDiv = value; -
- -{{topLevel}} -{{insideDiv}} - -@if (condition) { - {{topLevel + insideDiv}} - - @let nested = value; - - @if (condition) { - {{topLevel + insideDiv + nested}} - } -} - -
- {{topLevel + insideDiv}} - - @let nestedNgIf = value; - -
- {{topLevel + insideDiv + nestedNgIf}} -
-
- -{{nested}} -{{nestedNgIf}} -``` - -## Syntax definition - -The `@let` syntax is formally defined as: - The `@let` keyword. -* Followed by one or more whitespaces, not including new lines. -* Followed by a valid JavaScript name and zero or more whitespaces. -* Followed by the = symbol and zero or more whitespaces. -* Followed by an Angular expression which can be multi-line. -* Terminated by the `;` symbol. diff --git a/adev/src/content/guide/templates/ng-container.md b/adev/src/content/guide/templates/ng-container.md new file mode 100644 index 000000000000..886e5fefa7cb --- /dev/null +++ b/adev/src/content/guide/templates/ng-container.md @@ -0,0 +1,115 @@ +# Grouping elements with ng-container + +`` is a special element in Angular that groups multiple elements together or marks a location in a template without rendering a real element in the DOM. + +```angular-html + +
+ +
User bio
+
Here's some info about the user
+ +
+``` + +```angular-html + +
+
User bio
+
Here's some info about the user
+
+``` + +You can apply directives to `` to add behaviors or configuration to a part of your template. + +Angular ignores all attribute bindings and event listeners applied to ``, including those applied via directive. + +## Using `` to display dynamic contents + +`` can act as a placeholder for rendering dynamic content. + +### Rendering components + +You can use Angular's built-in `NgComponentOutlet` directive to dynamically render a component to the location of the ``. + +```angular-ts +@Component({ + template: ` +
Your profile
+ + ` +}) +export class UserProfile { + isAdmin = input(false); + profileComponent = computed(() => this.isAdmin() ? AdminProfile : BasicUserProfile); +} +``` + +In the example above, the `NgComponentOutlet` directive dynamically renders either `AdminProfile` or `BasicUserProfile` in the location of the `` element. + +### Rendering template fragments + +You can use Angular's built-in `NgTemplateOutlet` directive to dynamically render a template fragment to the location of the ``. + +```angular-ts +@Component({ + template: ` +
Your profile
+ + + This is the admin profile + This is the basic profile + ` +}) +export class UserProfile { + isAdmin = input(false); + adminTemplate = viewChild('admin', {read: TemplateRef}); + basicTemplate = viewChild('basic', {read: TemplateRef}); + profileTemplate = computed(() => this.isAdmin() ? adminTemplate : basicTemplate); +} +``` + +In the example above, the `ngTemplateOutlet` directive dynamically renders one of two template fragments in the location of the `` element. + +For more information regarding NgTemplateOutlet, see the [NgTemplateOutlets API documentation page](/api/common/NgTemplateOutlet). + +## Using `` with structural directives + +You can also apply structural directives to `` elements. Common examples of this include `ngIf`and `ngFor`. + +```angular-html + +
Admin Dashboard
+ + + + +
{{ item.title }}
+
{{ item.description }}
+ +``` + +## Using `` for injection + +See the Dependency Injection guide for more information on Angular's dependency injection system. + +When you apply a directive to ``, descendant elements can inject the directive or anything that the directive provides. Use this when you want to declaratively provide a value to a specific part of your template. + +```angular-ts +@Directive({ + selector: '[theme]', +}) +export class Theme { + // Create an input that accepts 'light' or 'dark`, defaulting to 'light'. + mode = input<'light' | 'dark'>('light'); +} +``` + +```angular-html + + + + +``` + +In the example above, the `ProfilePic` and `UserBio` components can inject the `Theme` directive and apply styles based on its `mode`. diff --git a/adev/src/content/guide/templates/ng-content.md b/adev/src/content/guide/templates/ng-content.md new file mode 100644 index 000000000000..387eed89a39b --- /dev/null +++ b/adev/src/content/guide/templates/ng-content.md @@ -0,0 +1,39 @@ +# Render templates from a parent component with `ng-content` + +`` is a special element that accepts markup or a template fragment and controls how components render content. It does not render a real DOM element. + +Here is an example of a `BaseButton` component that accepts any markup from its parent. + +```angular-ts +// ./base-button/base-button.component.ts +import { Component } from '@angular/core'; + +@Component({ + selector: 'button[baseButton]', + standalone: true, + template: ` + + `, +}) +export class BaseButton {} +``` + +```angular-ts +// ./app.component.ts +import { Component } from '@angular/core'; +import { BaseButtonComponent } from './base-button/base-button.component.ts'; + +@Component({ + selector: 'app-root', + standalone: true, + imports: [BaseButton], + template: ` + + `, +}) +export class AppComponent {} +``` + +For more detail, check out the [`` in-depth guide](/guide/components/content-projection) for other ways you can leverage this pattern. diff --git a/adev/src/content/guide/templates/ng-template.md b/adev/src/content/guide/templates/ng-template.md new file mode 100644 index 000000000000..7bd451c295d3 --- /dev/null +++ b/adev/src/content/guide/templates/ng-template.md @@ -0,0 +1,278 @@ +# Create template fragments with ng-template + +Inspired by the [native `

One-Two
Five	Six

Nested component's list of items:

Pass an object from parent to nested component:

Template reference variables

Pass value to an event handler

Template reference variable with disabled button

Reference variables, forms, and NgForm

Template Reference Variable Scope

Accessing in a child template

Accessing from outside parent template. (Doesn't work.)

*ngFor and template reference variable scope

Accessing a on an ng-template

Template Syntax

Interpolation

- {{ title }} - -

Expression context

Statement context

New Mental Model

Property vs. Attribute (img examples)

Buttons

Property Binding

Attribute Binding

Class Binding

Style Binding

Event Binding

Two-way Binding

De-sugared two-way binding

NgModel (two-way) Binding

Result: {{ currentHero.name }}

NgClass Binding

NgStyle Binding

[ngStyle] binding to currentStyles - CSS property names

NgIf Binding

NgFor Binding

*ngFor with index

*ngFor trackBy

NgSwitch Binding

Template reference variables

Example Form

Inputs and Outputs

Pipes

Safe navigation operator ?.

Non-null assertion operator !.

$any type cast function $any( ).

Enums in binding

SVG Templates

Two-way Binding

De-sugared two-way binding

Hello, {{user.name}}

User bio

User bio

Your profile

Your profile

Admin Dashboard

{{ item.title }}

Component with a fragment

Exported by

Accessing a on an `ng-template`