From 7355906a95e02c1aa02222cfea978895fa5df1d8 Mon Sep 17 00:00:00 2001 From: Kara Erickson Date: Wed, 30 Oct 2019 17:28:59 -0700 Subject: [PATCH] docs: add detailed example to ContentChildren change (#33499) PR Close #33499 --- .github/CODEOWNERS | 1 + .../guide/ivy-compatibility-examples.md | 114 ++++++++++++++++++ aio/content/guide/ivy-compatibility.md | 10 +- 3 files changed, 118 insertions(+), 7 deletions(-) create mode 100644 aio/content/guide/ivy-compatibility-examples.md diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 08e0697bfb..2a9054c246 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -890,6 +890,7 @@ testing/** @angular/fw-test /aio/content/guide/migration-ngcc.md @angular/fw-docs-packaging @angular/framework-global-approvers @angular/framework-global-approvers-for-docs-only-changes /aio/content/guide/updating-to-version-9.md @angular/fw-docs-packaging @angular/framework-global-approvers @angular/framework-global-approvers-for-docs-only-changes /aio/content/guide/ivy-compatibility.md @angular/fw-docs-packaging @angular/framework-global-approvers @angular/framework-global-approvers-for-docs-only-changes +/aio/content/guide/ivy-compatibility-examples.md @angular/fw-docs-packaging @angular/framework-global-approvers @angular/framework-global-approvers-for-docs-only-changes # ================================================ diff --git a/aio/content/guide/ivy-compatibility-examples.md b/aio/content/guide/ivy-compatibility-examples.md new file mode 100644 index 0000000000..25fb4cce71 --- /dev/null +++ b/aio/content/guide/ivy-compatibility-examples.md @@ -0,0 +1,114 @@ +# Appendix: Ivy Compatibility Examples + +This appendix is intended to provide more background on Ivy changes. Many of these examples list error messages you may see, so searching by error message might be a good idea if you are debugging. + +
+NOTE: Most of these issues affect a small percentage of applications encountering unusual or rare edge cases. +
+ + +{@a content-children-descendants} +## @ContentChildren Queries Only Match Direct Children By Default + + +### Basic example of change + +Let's say a component (`Comp`) has a `@ContentChildren` query for `'foo'`: + +```html + +
+
+
+ +``` + +In the previous runtime, the `
` with `#foo` would match. +With Ivy, that `
` does not match because it is not a direct child of ``. + + +### Background + +By default, `@ContentChildren` queries have the `descendants` flag set to `false`. + +Previously, "descendants" referred to "descendant directives". +An element could be a match as long as there were no other directives between the element and the requesting directive. +This made sense for directives with nesting like tabs, where nested tab directives might not be desirable to match. +However, this caused surprising behavior for users because adding an unrelated directive like `ngClass` to a wrapper element could invalidate query results. + +For example, with the content query and template below, the last two `Tab` directives would not be matches: + +``` +@ContentChildren(Tab, {descendants: false}) tabs: QueryList +``` + +``` + +
+ One +
+ + A + +
+ Two +
+ +``` + +In addition, the differences between type and string predicates were subtle and sometimes unclear. +For example, if you replace the type predicate above with a `'foo'` string predicate, the matches change: + +``` +@ContentChildren('foo', {descendants: false}) foos: QueryList +``` + +``` + +
+
One
+
+ +
A
+ +
+
Two
+
+ +``` + +Because the previous behavior was inconsistent and surprising to users, we did not want to reproduce it in Ivy. +Instead, we simplified the mental model so that "descendants" refers to DOM nesting only. +Any DOM element between the requesting component and a potential match will invalidate that match. +Type predicates and string predicates also have identical matching behavior. + + +### Example of error + +The error message that you see will depend on how the particular content query is used in the application code. +Frequently, an error is thrown when a property is referenced on the content query result (which is now `undefined`). + +For example, if the component sets the content query results to a property, `foos`, `foos.first.bar` would throw the error: + +``` +Uncaught TypeError: Cannot read property 'bar' of undefined +``` + +If you see an error like this, and the `undefined` property refers to the result of a `@ContentChildren` query, it may well be caused by this change. + + +### Recommended fix + +You can either add the `descendants: true` flag to ignore wrapper elements or remove the wrapper elements themselves. + +Option 1: +``` +@ContentChildren('foo', {descendants: true}) foos: QueryList; +``` + +Option 2: +``` + +
+ +``` \ No newline at end of file diff --git a/aio/content/guide/ivy-compatibility.md b/aio/content/guide/ivy-compatibility.md index c8e86e722c..51332e95dc 100644 --- a/aio/content/guide/ivy-compatibility.md +++ b/aio/content/guide/ivy-compatibility.md @@ -19,11 +19,9 @@ If the errors are gone, switch back to Ivy by removing the changes to the `tscon {@a common-changes} -## Changes You May See +### Changes You May See -Below are a few breaking changes that are more likely than others to be visible as applications are transitioning to Ivy. - -- By default, `@ContentChildren` queries will only search direct child nodes in the DOM hierarchy (previously, they would search any nesting level in the DOM as long as another directive wasn't matched above it). +- By default, `@ContentChildren` queries will only search direct child nodes in the DOM hierarchy (previously, they would search any nesting level in the DOM as long as another directive wasn't matched above it). ([details](guide/ivy-compatibility-examples#content-children-descendants)) - All classes that use Angular DI must have an Angular decorator like `@Directive()` or `@Injectable` (previously, undecorated classes were allowed if an ancestor class or subclass had a decorator). @@ -31,9 +29,7 @@ Below are a few breaking changes that are more likely than others to be visible {@a less-common-changes} -## Less Common Changes - -The following changes will be visible more rarely, as they mostly deal in edge cases or unspecified behavior that is not part of our public API. +### Less Common Changes - Properties like `host` inside `@Component` and `@Directive` decorators can be inherited (previously, only properties with explicit field decorators like `@HostBinding` would be inherited).