fix(chips): regression where chips model gets out of sync with view

[Splaktar]

PR Checklist

Please check that your PR fulfills the following requirements:

• The commit message follows our guidelines
• Tests for the changes have been added or this is not a bug fix / enhancement
• Docs have been added, updated, or were not required

PR Type

What kind of change does this PR introduce?

[x] Bugfix
[ ] Enhancement
[x] Documentation content changes
[ ] Code style update (formatting, local variables)
[ ] Refactoring (no functional changes, no api changes)
[ ] Build related changes
[ ] CI related changes
[ ] Infrastructure changes
[ ] Other... Please describe:

What is the current behavior?

There was a breaking change in 1.1.9 related to the enhancement to support ng-change on md-chips. This was introduced in #11166 where the passed in model and the items Array is replaced via Array.slice. This appears to have led to the issues listed below and may be related to #11218 as well.

Issue Number:
Fixes #11304. Fixes #11301.

What is the new behavior?

• fix issue where view and model get out of sync
• manually call ngChange as it won't be triggered by ngModel for chips
• add ng-change test to contact-chips
• refinements to chips and contact-chips docs
• remove references to filter-selected on contact-chips
• it was disabled 2 years ago
• remove use of angular.lowercase which is removed in AngularJS 1.7

Does this PR introduce a breaking change?

[ ] Yes
[x] No

Other information

[gkalpak]

Why not call $setViewValue()? This will break expected ngModel behavior.

[Splaktar]

With what value? Calling $setViewValue(this.items.slice()) is what caused these regressions (issues linked in OP). Calling $setViewValue(this.items) doesn't trigger ngChange, but I guess I could try that again now that we're doing it manually.

[Splaktar]

this.ngModelCtrl.$setViewValue(this.items); does seem to work now with the manual triggering of ngChange. Will update.

[gkalpak]

I see. So, yeah, calling $setViewValue(this.items) might not work (since it uses === to compare to previous value) and thus will not perform the expected operations (update classes, validate, call $viewChangeListeners).

As a workaround, maybe you could call $viewChangeListeners yourself, which I think it a better approach than manually calling ngChange (relevant AngularJS code):

angular.forEach(ngModelCtrl.$viewChangeListeners, function(listener) {
  try {
    listener();
  } catch (e) {
    $exceptionHandler(e);
  }
});

[Splaktar]

Excellent, thank you. That seems to work and resolves the argument naming issue.

[gkalpak]

AFAICT, this will not be called correctly. Since you are defining a scope binding (via ngChange: '&'), you need to pass an object that maps arguments to values. For example, if you have ng-change="onChange(items)", then you need to call it with this.ngChange({items: this.items}).

[Splaktar]

Is this.ngChange({items: this.items}) the solution?
Does that work if they do something like ng-change=onChange(myItems)?

Since we're using controllerAs and bindToController: true, is there a better way to hook up/into ngChange?

[gkalpak]

The key has to be the same as what they used as variable name. Essentially, a & binding allows you to evaluate an expression on the parent scope (of an isolate scope) and pass certain data. For security reasons, AngularJS creates and passes a wrapper to the isolate scope. So, the isolate scope does not get direct access to the expression (most often a method). What it gets is a wrapper function that takes a map of argument names to values and calls the expression on the parent scope with these values.

For example, having a parentMethod: '&' binding and using the component as parent-method="doStuff(arg1, arg2)", allows the component's isolate scope to call this.parentMethod({arg1: 'value1', arg2: 'value2'}), which will eventually call doStuff('value1', 'value2') on the parent scope.

So, you need to know what arguments are used in the expression.

Usually, we don't have this issue with ngChange, because there is no isolate scope. In cases like this (where you have an isolate scope and you can't just .$eval(attrs.ngChange)), a common approach is to specify (i.e. document) that in the ngChange expression the chips will be available as $chips or $items (or whatever name you choose).

Then, people can use ng-change="onChipsChange($chips)" and you can call it with this.ngChange({$chips: this.items}) (and their onChipsChange() method will be called with this.items as argument).

[Splaktar]

Thank you very much for the explanation! That is quite helpful.

It looks like this is not needed due to the suggested change in #11310 (comment).

[jelbourn]

I confirmed that that internal app w/ the chips problem works with this.

[jelbourn]

LGTM