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

Commit 893a273

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

File tree

1 file changed

+12
-11
lines changed

1 file changed

+12
-11
lines changed

src/ng/compile.js

Lines changed: 12 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -174,17 +174,18 @@
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 and
179+
* can be either an assignable expression or a literal value. If no `attr` name is specified then the
180+
* attribute name is assumed to be the same as the local name. Given `<widget my-attr="parentModel">`
181+
* and the widget definition `scope: { localModel:'=myAttr' }`, the property `localModel` on the widget's
182+
* scope will reflect the value of `parentModel` on the parent scope. Changes to `parentModel` will be
183+
* reflected in `localModel` and vice versa. If the attribute doesn't exist, an exception will be thrown
184+
* ({@link error/$compile/nonassign $compile:nonassign}). You can avoid this behavior and flag the
185+
* property as optional using `=?` or `=?attr`. By default, the {@link ng.$rootScope.Scope#$watch} method
186+
* is used, the equality check is done by reference. If you need to watch a collection for changes using
187+
* {@link ng.$rootScope.Scope#$watchCollection}, use `=*` or `=*attr` (`=*?` or `=*?attr` if the property
188+
* is optional).
188189
*
189190
* * `&` or `&attr` - provides a way to execute an expression in the context of the parent scope.
190191
* If no `attr` name is specified then the attribute name is assumed to be the same as the

0 commit comments

Comments
 (0)