From a08f6d9795c70c39d1349af6aa9d3f5baad04536 Mon Sep 17 00:00:00 2001 From: Kara Erickson Date: Wed, 29 Jan 2020 17:31:09 -0800 Subject: [PATCH] docs(ivy): clean up class binding docs and update to v9 behavior (#35066) PR Close #35066 --- .../src/app/app.component.html | 32 +++++++-------- .../src/app/app.component.ts | 7 ++-- aio/content/guide/template-syntax.md | 40 +++++++++++-------- 3 files changed, 42 insertions(+), 37 deletions(-) diff --git a/aio/content/examples/attribute-binding/src/app/app.component.html b/aio/content/examples/attribute-binding/src/app/app.component.html index 7a2fb3311f..a314891788 100644 --- a/aio/content/examples/attribute-binding/src/app/app.component.html +++ b/aio/content/examples/attribute-binding/src/app/app.component.html @@ -29,26 +29,24 @@

Class binding

- -

toggle the "special" class on/off with a property:

-
The class binding is special.
- -

binding to class.special overrides the class attribute:

-
This one is not so special.
- -

Using the bind- syntax:

-
This class binding is special too.
- - -

Add a class:

-
Add another class
+

Bind to a specific class

+ +
This class binding is special.
- -

Overwrite all existing classes with a new class:

-
Reset all classes at once
- + + +

Using the bind- syntax:

+ +
This class binding is special too.
+ + + +

Bind to multiple classes

+ +
Add multiple classes
+
diff --git a/aio/content/examples/attribute-binding/src/app/app.component.ts b/aio/content/examples/attribute-binding/src/app/app.component.ts index f79b22c817..043ee92e95 100644 --- a/aio/content/examples/attribute-binding/src/app/app.component.ts +++ b/aio/content/examples/attribute-binding/src/app/app.component.ts @@ -8,8 +8,9 @@ import { Component } from '@angular/core'; export class AppComponent { actionName = 'Go for it'; isSpecial = true; - itemClearance = true; - resetClasses = 'new-class'; canSave = true; - + someClasses = 'foo bar'; + classExpr = 'special foo'; + styleExpr = 'color: red'; + color = 'blue'; } diff --git a/aio/content/guide/template-syntax.md b/aio/content/guide/template-syntax.md index 7b54caa71a..496d7a460c 100644 --- a/aio/content/guide/template-syntax.md +++ b/aio/content/guide/template-syntax.md @@ -895,7 +895,7 @@ Instead, you'd use property binding and write it like this: Add and remove CSS class names from an element's `class` attribute with a **class binding**. -Here's how to set the attribute without binding in plain HTML: +Here's how to set the attribute without a binding in plain HTML: ```html @@ -903,27 +903,33 @@ Here's how to set the attribute without binding in plain HTML: ``` Class binding syntax resembles property binding, but instead of an element property between brackets, start with the prefix `class`, -optionally followed by a dot (`.`) and the name of a CSS class: `[class.class-name]`. - -You can replace that with a binding to a string of the desired class names; this is an all-or-nothing, replacement binding. - - - - -You can also add a class to an element without overwriting the classes already on the element: - - - -Finally, you can bind to a specific class name. +optionally followed by a dot (`.`) and the name of a CSS class: `[class.class-name]`. Angular adds the class when the template expression evaluates to truthy. It removes the class when the expression is falsy. + +Binding to a specific class is additive, so it won't overwrite other class bindings or static classes unless the class names are duplicated. - +In the example below, the final class list for the `
` will be `"item clearance special"` if `isSpecial` is truthy, and only `"item clearance"` if it is falsy. -While this technique is suitable for toggling a single class name, -consider the [`NgClass`](guide/template-syntax#ngClass) directive when -managing multiple class names at the same time. + +You can also use the alternative class binding syntax that replaces square brackets with the `bind-` keyword: + + + +If there are multiple classes you'd like to toggle, you can bind to the `[class]` property directly. +Binding to `[class]` is additive, so it shouldn't overwrite other class bindings or static classes unless the class names are duplicated*. + + + +The expression attached to the `[class]` binding is most often a string list of class names like `"clearance special"`. + +You can also format the expression as an object with class names as the keys and truthy/falsy expressions as the values, like `{clearance: true, special: false}`. +In this case, Angular will add a class only if its associated value is truthy. +It's important to note that with object format, the identity of the object must change for the class list to be updated. +Updating the property without changing object identity will have no effect. + +*This is true for Angular version 9 and later. For Angular version 8, see v8.angular.io