docs($compile): add more info about optional bindings #16025
Conversation
This also deletes the incorrect info that a missing attribute in a non-optional binding will throw. Closes angular#15989
| 'localName2': '=attr', // OK | ||
| 'localName3': '<?attr', // OK | ||
| 'localName4': ' = attr', // OK | ||
| 'localName5': 'attr', // ERROR: missing mode @&= |
| 'localName': '@', // OK | ||
| 'localName2': '=attr', // OK | ||
| 'localName3': '<?attr', // OK | ||
| 'localName4': ' = attr', // OK |
There was a problem hiding this comment.
No idea. It's just a list of examples. * also makes no appearance
| @@ -303,16 +303,15 @@ | |||
| * name. Given `<my-component my-attr="parentModel">` and the isolate scope definition `scope: { | |||
| * localModel: '=myAttr' }`, the property `localModel` on the directive's scope will reflect the | |||
| * value of `parentModel` on the parent scope. Changes to `parentModel` will be reflected in | |||
| * `localModel` and vice versa. Optional attributes should be marked as such with a question mark: | |||
There was a problem hiding this comment.
The suggestion about optional attributes seems correct. Why remove it?
There was a problem hiding this comment.
I've removed it because I centralized the info after the individual descriptions.
| @@ -303,16 +303,15 @@ | |||
| * name. Given `<my-component my-attr="parentModel">` and the isolate scope definition `scope: { | |||
| * localModel: '=myAttr' }`, the property `localModel` on the directive's scope will reflect the | |||
| * value of `parentModel` on the parent scope. Changes to `parentModel` will be reflected in | |||
| * `localModel` and vice versa. Optional attributes should be marked as such with a question mark: | |||
| * `=?` or `=?attr`. If the binding expression is non-assignable, or if the attribute isn't | |||
There was a problem hiding this comment.
This info sounds correct too. Why remove it?
There was a problem hiding this comment.
It's not correct: http://plnkr.co/edit/AU3n1j9SPhx9FErCyvfj?p=preview
See #6064
There was a problem hiding this comment.
It is correct: http://plnkr.co/edit/7x6kyfbpWIFCFgTmZb2Z?p=preview
As mentioned below, it will only throw _"upon discovering changes to the local value, since it will be impossible to sync
- them back to the parent scope"_
There was a problem hiding this comment.
You are right, thanks. This is a more specific case than is handled by the PR.
| * will be thrown upon discovering changes to the local value, since it will be impossible to sync | ||
| * them back to the parent scope. By default, the {@link ng.$rootScope.Scope#$watch `$watch`} | ||
| * method is used for tracking changes, and the equality check is based on object identity. | ||
| * However, if an object literal or an array literal is passed as the binding expression, the | ||
| * equality check is done by value (using the {@link angular.equals} function). It's also possible | ||
| * to watch the evaluated value shallowly with {@link ng.$rootScope.Scope#$watchCollection | ||
| * `$watchCollection`}: use `=*` or `=*attr` (`=*?` or `=*?attr` if the attribute is optional). | ||
| * `$watchCollection`}: use `=*` or `=*attr` |
There was a problem hiding this comment.
Like above, the info about optional attributes is further down. Note that the &, < and @ sections have nothing about optional attributes either.
src/ng/compile.js
Outdated
| @@ -347,6 +346,36 @@ | |||
| * and values into the expression wrapper fn. For example, if the expression is `increment(amount)` | |||
| * then we can specify the amount value by calling the `localFn` as `localFn({amount: 22})`. | |||
| * | |||
| * All 4 kinds of bindings (`@`, `=`, `<`, and `&`) can be made optional by adding `?` to the expression. | |||
| * The marker must come before the attribute name. | |||
| * See the {@link error/$compile/iscp the Invalid Isolate Scope Definition error} for definition examples. | |||
src/ng/compile.js
Outdated
| * All 4 kinds of bindings (`@`, `=`, `<`, and `&`) can be made optional by adding `?` to the expression. | ||
| * The marker must come before the attribute name. | ||
| * See the {@link error/$compile/iscp the Invalid Isolate Scope Definition error} for definition examples. | ||
| * This is useful to refine the interface directives provides. |
| notoptional: '=', | ||
| optional: '=?', | ||
| }, | ||
| bindToController: true, |
There was a problem hiding this comment.
Don't you need a controllerAs here?
There was a problem hiding this comment.
Nope: #15110
This is actually quite powerful ...
There was a problem hiding this comment.
Oh...you just can't use it on the template. Cool 😃
This also deletes the incorrect info that a missing attribute
in a non-optional binding will throw.
Closes #15989
What kind of change does this PR introduce? (Bug fix, feature, docs update, ...)
docs
What is the current behavior? (You can also link to an open issue here)
missing / incorrect info
What is the new behavior (if this is a feature change)?
info!
Does this PR introduce a breaking change?
101% not
Please check if the PR fulfills these requirements
Other information: