Skip to content
This repository was archived by the owner on Apr 12, 2024. It is now read-only.

Commit b163540

Browse files
committed
docs($compile): refine explanation of =-bindings
The current version of this paragraph is in many ways inaccurate and confusing.
1 parent 2f0a50b commit b163540

File tree

1 file changed

+16
-11
lines changed

1 file changed

+16
-11
lines changed

src/ng/compile.js

Lines changed: 16 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -174,17 +174,22 @@
174174
* `localName` property on the widget scope. The `name` is read from the parent scope (not
175175
* component scope).
176176
*
177-
* * `=` or `=attr` - set up bi-directional binding between a local scope property and the
178-
* parent scope property of name defined via the value of the `attr` attribute. If no `attr`
179-
* name is specified then the attribute name is assumed to be the same as the local name.
180-
* Given `<widget my-attr="parentModel">` and widget definition of
181-
* `scope: { localModel:'=myAttr' }`, then widget scope property `localModel` will reflect the
182-
* value of `parentModel` on the parent scope. Any changes to `parentModel` will be reflected
183-
* in `localModel` and any changes in `localModel` will reflect in `parentModel`. If the parent
184-
* scope property doesn't exist, it will throw a NON_ASSIGNABLE_MODEL_EXPRESSION exception. You
185-
* can avoid this behavior using `=?` or `=?attr` in order to flag the property as optional. If
186-
* you want to shallow watch for changes (i.e. $watchCollection instead of $watch) you can use
187-
* `=*` or `=*attr` (`=*?` or `=*?attr` if the property is optional).
177+
* * `=` or `=attr` - set up a bidirectional binding between a local scope property and an expression
178+
* passed via the attribute `attr`. The expression is evaluated in the context of the parent scope.
179+
* If no `attr` name is specified then the attribute name is assumed to be the same as the local
180+
* name. Given `<widget my-attr="parentModel">` and the widget definition `scope: { localModel:
181+
* '=myAttr' }`, the property `localModel` on the widget's scope will reflect the value of
182+
* `parentModel` on the parent scope. Changes to `parentModel` will be reflected in `localModel`
183+
* and vice versa. Optional attributes should be marked as such with a question mark: `=?` or
184+
* `=?attr`. If the binding expression is non-assignable, or if the attribute isn't optional and
185+
* doesn't exist, an exception ({@link error/$compile/nonassign `$compile:nonassign`}) will be
186+
* thrown on discovering changes to the local value since it'll be impossible to sync it with the
187+
* parent scope in this case. By default, the {@link ng.$rootScope.Scope#$watch `$watch`} method is
188+
* used for tracking changes, and the equality check is done by reference. However, if an object
189+
* literal or an array literal is passed as the binding expression, the equality check is done by
190+
* value (the {@link angular.equals} function is used). It's also possible to watch the evaluated
191+
* value shallowly with {@link ng.$rootScope.Scope#$watchCollection `$watchCollection`}: use `=*`
192+
* or `=*attr` (`=*?` or `=*?attr` if the attribute is optional).
188193
*
189194
* * `&` or `&attr` - provides a way to execute an expression in the context of the parent scope.
190195
* If no `attr` name is specified then the attribute name is assumed to be the same as the

0 commit comments

Comments
 (0)