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

Commit 574f25b

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 574f25b

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 and
179+
* must 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. Optional attributes should be marked as such with a question
184+
* mark: `=?` or `=?attr`. If the binding expression is non-assignable, or if the attribute isn't
185+
* optional and doesn't exist, an exception ({@link error/$compile/nonassign `$compile:nonassign`}) will
186+
* be 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} method is used, and the
188+
* equality check is done by reference. However, if an object literal or an array literal is passed as
189+
* the binding expression, the equality check is done by value (the {@link angular.equals} function is
190+
* used). If you need to shallowly watch the properties of the evaluated value using
191+
* {@link ng.$rootScope.Scope#$watchCollection}, use `=*` or `=*attr` (`=*?` or `=*?attr` if the
192+
* 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)