Observable
Ember.Observable Class
PUBLIC
Defined in: packages/ember-runtime/lib/mixins/observable.js:26
Module: ember-runtime
Overview
This mixin provides properties and property observing functionality, core features of the Ember object model.
Properties and observers allow one object to observe changes to a property on another object. This is one of the fundamental ways that models, controllers and views communicate with each other in an Ember application.
Any object that has this mixin applied can be used in observer operations. That includes Ember.Object
and most objects you will interact with as you write your Ember application.
Note that you will not generally apply this mixin to classes yourself, but you will use the features provided by this module frequently, so it is important to understand how to use it.
Using get()
and set()
Because of Ember's support for bindings and observers, you will always access properties using the get method, and set properties using the set method. This allows the observing objects to be notified and computed properties to be handled properly.
More documentation about get
and set
are below.
Observing Property Changes
You typically observe property changes simply by using the Ember.observer
function in classes that you write.
For example:
Ember.Object.extend({ valueObserver: Ember.observer('value', function(sender, key, value, rev) { // Executes whenever the "value" property changes // See the addObserver method for more information about the callback arguments }) });
Although this is the most common way to add an observer, this capability is actually built into the Ember.Object
class on top of two methods defined in this mixin: addObserver
and removeObserver
. You can use these two methods to add and remove observers yourself if you need to do so at runtime.
To add an observer for a property, call:
object.addObserver('propertyKey', targetObject, targetAction)
This will call the targetAction
method on the targetObject
whenever the value of the propertyKey
changes.
Note that if propertyKey
is a computed property, the observer will be called when any of the property dependencies are changed, even if the resulting value of the computed property is unchanged. This is necessary because computed properties are not computed until get
is called.
addObserver (key, target, method) public
Adds an observer on a property.
This is the core method used to register an observer for a property.
Once you call this method, any time the key's value is set, your observer will be notified. Note that the observers are triggered any time the value is set, regardless of whether it has actually changed. Your observer should be prepared to handle that.
Observer Methods
Observer methods have the following signature:
export default Ember.Component.extend({ init() { this._super(...arguments); this.addObserver('foo', this, 'fooDidChange'); }, fooDidChange(sender, key, value, rev) { // your code } });
The sender
is the object that changed. The key
is the property that changes. The value
property is currently reserved and unused. The rev
is the last property revision of the object when it changed, which you can use to detect if the key value has really changed or not.
Usually you will not need the value or revision parameters at the end. In this case, it is common to write observer methods that take only a sender and key value as parameters or, if you aren't interested in any of these values, to write an observer that has no parameters at all.
Parameters:
-
key
String
- The key to observe
-
target
Object
- The target object to invoke
-
method
String|Function
- The method to invoke
beginPropertyChangesEmber.Observable
private
Begins a grouping of property changes.
You can use this method to group property changes so that notifications will not be sent until the changes are finished. If you plan to make a large number of changes to an object at one time, you should call this method at the beginning of the changes to begin deferring change notifications. When you are done making changes, call endPropertyChanges()
to deliver the deferred change notifications and end deferring.
Returns:
cacheFor (keyName) Object
public
Returns the cached value of a computed property, if it exists. This allows you to inspect the value of a computed property without accidentally invoking it if it is intended to be generated lazily.
Parameters:
-
keyName
String
Returns:
-
Object
- The cached value of the computed property, if any
decrementProperty (keyName, decrement) Number
public
Set the value of a property to the current value minus some amount.
player.decrementProperty('lives'); orc.decrementProperty('health', 5);
Parameters:
-
keyName
String
- The name of the property to decrement
-
decrement
Number
- The amount to decrement by. Defaults to 1
Returns:
-
Number
- The new property value
endPropertyChangesEmber.Observable
private
Ends a grouping of property changes.
You can use this method to group property changes so that notifications will not be sent until the changes are finished. If you plan to make a large number of changes to an object at one time, you should call beginPropertyChanges()
at the beginning of the changes to defer change notifications. When you are done making changes, call this method to deliver the deferred change notifications and end deferring.
Returns:
get (keyName) Object
public
Retrieves the value of a property from the object.
This method is usually similar to using object[keyName]
or object.keyName
, however it supports both computed properties and the unknownProperty handler.
Because get
unifies the syntax for accessing all these kinds of properties, it can make many refactorings easier, such as replacing a simple property with a computed property, or vice versa.
Computed Properties
Computed properties are methods defined with the property
modifier declared at the end, such as:
fullName: Ember.computed('firstName', 'lastName', function() { return this.get('firstName') + ' ' + this.get('lastName'); })
When you call get
on a computed property, the function will be called and the return value will be returned instead of the function itself.
Unknown Properties
Likewise, if you try to call get
on a property whose value is undefined
, the unknownProperty()
method will be called on the object. If this method returns any value other than undefined
, it will be returned instead. This allows you to implement "virtual" properties that are not defined upfront.
Parameters:
-
keyName
String
- The property to retrieve
Returns:
-
Object
- The property value or undefined.
getProperties (list) Object
public
To get the values of multiple properties at once, call getProperties
with a list of strings or an array:
record.getProperties('firstName', 'lastName', 'zipCode'); // { firstName: 'John', lastName: 'Doe', zipCode: '10011' }
is equivalent to:
record.getProperties(['firstName', 'lastName', 'zipCode']); // { firstName: 'John', lastName: 'Doe', zipCode: '10011' }
Parameters:
-
list
String...|Array
- of keys to get
Returns:
-
Object
getWithDefault (keyName, defaultValue) Object
public
Retrieves the value of a property, or a default value in the case that the property returns undefined
.
person.getWithDefault('lastName', 'Doe');
Parameters:
-
keyName
String
- The name of the property to retrieve
-
defaultValue
Object
- The value to return if the property value is undefined
Returns:
-
Object
- The property value or the defaultValue.
hasObserverFor (key) Boolean
private
Returns true
if the object currently has observers registered for a particular key. You can use this method to potentially defer performing an expensive action until someone begins observing a particular property on the object.
Parameters:
-
key
String
- Key to check
Returns:
-
Boolean
incrementProperty (keyName, increment) Number
public
Set the value of a property to the current value plus some amount.
person.incrementProperty('age'); team.incrementProperty('score', 2);
Parameters:
-
keyName
String
- The name of the property to increment
-
increment
Number
- The amount to increment by. Defaults to 1
Returns:
-
Number
- The new property value
notifyPropertyChange (keyName) Ember.Observable
public
Convenience method to call propertyWillChange
and propertyDidChange
in succession.
Parameters:
-
keyName
String
- The property key to be notified about.
Returns:
propertyDidChange (keyName) Ember.Observable
private
Notify the observer system that a property has just changed.
Sometimes you need to change a value directly or indirectly without actually calling get()
or set()
on it. In this case, you can use this method and propertyWillChange()
instead. Calling these two methods together will notify all observers that the property has potentially changed value.
Note that you must always call propertyWillChange
and propertyDidChange
as a pair. If you do not, it may get the property change groups out of order and cause notifications to be delivered more often than you would like.
Parameters:
-
keyName
String
- The property key that has just changed.
Returns:
propertyWillChange (keyName) Ember.Observable
private
Notify the observer system that a property is about to change.
Sometimes you need to change a value directly or indirectly without actually calling get()
or set()
on it. In this case, you can use this method and propertyDidChange()
instead. Calling these two methods together will notify all observers that the property has potentially changed value.
Note that you must always call propertyWillChange
and propertyDidChange
as a pair. If you do not, it may get the property change groups out of order and cause notifications to be delivered more often than you would like.
Parameters:
-
keyName
String
- The property key that is about to change.
Returns:
removeObserver (key, target, method) public
Remove an observer you have previously registered on this object. Pass the same key, target, and method you passed to addObserver()
and your target will no longer receive notifications.
Parameters:
-
key
String
- The key to observe
-
target
Object
- The target object to invoke
-
method
String|Function
- The method to invoke
set (keyName, value) Object
public
Sets the provided key or path to the value.
record.set("key", value);
This method is generally very similar to calling object["key"] = value
or object.key = value
, except that it provides support for computed properties, the setUnknownProperty()
method and property observers.
Computed Properties
If you try to set a value on a key that has a computed property handler defined (see the get()
method for an example), then set()
will call that method, passing both the value and key instead of simply changing the value itself. This is useful for those times when you need to implement a property that is composed of one or more member properties.
Unknown Properties
If you try to set a value on a key that is undefined in the target object, then the setUnknownProperty()
handler will be called instead. This gives you an opportunity to implement complex "virtual" properties that are not predefined on the object. If setUnknownProperty()
returns undefined, then set()
will simply set the value on the object.
Property Observers
In addition to changing the property, set()
will also register a property change with the object. Unless you have placed this call inside of a beginPropertyChanges()
and endPropertyChanges(),
any "local" observers (i.e. observer methods declared on the same object), will be called immediately. Any "remote" observers (i.e. observer methods declared on another object) will be placed in a queue and called at a later time in a coalesced manner.
Parameters:
-
keyName
String
- The property to set
-
value
Object
- The value to set or `null`.
Returns:
-
Object
- The passed value
setProperties (hash) Object
public
Sets a list of properties at once. These properties are set inside a single beginPropertyChanges
and endPropertyChanges
batch, so observers will be buffered.
record.setProperties({ firstName: 'Charles', lastName: 'Jolley' });
Parameters:
-
hash
Object
- the hash of keys and values to set
Returns:
-
Object
- The passed in hash
toggleProperty (keyName) Boolean
public
Set the value of a boolean property to the opposite of its current value.
starship.toggleProperty('warpDriveEngaged');
Parameters:
-
keyName
String
- The name of the property to toggle
Returns:
-
Boolean
- The new property value
© 2017 Yehuda Katz, Tom Dale and Ember.js contributors
Licensed under the MIT License.
https://emberjs.com/api/classes/Ember.Observable.html