Ember Class
This namespace contains all Ember methods and functions. Future versions of Ember may overwrite this namespace and therefore, you should avoid adding any new properties.
At the heart of Ember is Ember-Runtime, a set of core functions that provide cross-platform compatibility and object property observing. Ember-Runtime is small and performance-focused so you can use it alongside other cross-platform libraries such as jQuery. For more details, see Ember-Runtime.
Item Index
Methods
- $
- _addBeforeObserver deprecated
- _immediateObserver deprecated
- _warnIfUsingStrippedFeatureFlags
- A
- addListener
- addObserver
- aliasMethod
- assert
- assign
- beforeObserver deprecated
- beginPropertyChanges
- bind
- cacheFor
- canInvoke
- changeProperties
- compare
- controllerFor
- copy
- createInjectionHelper
- debug
- defineProperty
- deprecate
- deprecateFunc
- destroy
- endPropertyChanges
- expandProperties
- generateController
- generateControllerFactory
- generateGuid
- get
- getEngineParent
- getOwner
- getProperties
- getWithDefault
- guidFor
- hasListeners
- info
- inspect
- isArray
- isBlank
- isEmpty
- isEqual
- isNone
- isPresent
- K
- listenersFor
- makeArray
- merge
- meta
- mixin
- observer
- on
- onLoad
- propertyDidChange
- propertyWillChange
- removeBeforeObserver deprecated
- removeListener
- removeObserver
- required
- runInDebug
- runLoadHooks
- sendEvent
- set
- setEngineParent
- setOwner
- setProperties
- suspendListener
- suspendListeners
- tryInvoke
- trySet
- typeOf
- validatePropertyInjections
- warn
- watch
- watchedEvents
- wrap
Events
Methods
$
()
public
Alias for jQuery
_addBeforeObserver
-
obj
-
path
-
target
-
[method]
_immediateObserver
-
propertyNames
-
func
Specify a method that observes property changes.
Ember.Object.extend({
valueObserver: Ember.immediateObserver('value', function() {
// Executes whenever the "value" property changes
})
});
In the future, Ember.observer
may become asynchronous. In this event,
Ember.immediateObserver
will maintain the synchronous behavior.
Also available as Function.prototype.observesImmediately
if prototype extensions are
enabled.
Returns:
func
_warnIfUsingStrippedFeatureFlags
()
Void
private
Will call Ember.warn()
if ENABLE_OPTIONAL_FEATURES or
any specific FEATURES flag is truthy.
This method is called automatically in debug canary builds.
Returns:
A
()
Ember.NativeArray
public
Creates an Ember.NativeArray
from an Array like object.
Does not modify the original object. Ember.A is not needed if
EmberENV.EXTEND_PROTOTYPES
is true
(the default value). However,
it is recommended that you use Ember.A when creating addons for
ember or when you can not guarantee that EmberENV.EXTEND_PROTOTYPES
will be true
.
Example
export default Ember.Component.extend({
tagName: 'ul',
classNames: ['pagination'],
init() {
this._super(...arguments);
if (!this.get('content')) {
this.set('content', Ember.A());
}
}
});
Returns:
addListener
-
obj
-
eventName
-
target
-
method
-
once
Add an event listener
addObserver
-
obj
-
_path
-
target
-
[method]
aliasMethod
-
methodName
Makes a method available via an additional name.
App.Person = Ember.Object.extend({
name: function() {
return 'Tomhuda Katzdale';
},
moniker: Ember.aliasMethod('name')
});
let goodGuy = App.Person.create();
goodGuy.name(); // 'Tomhuda Katzdale'
goodGuy.moniker(); // 'Tomhuda Katzdale'
Parameters:
-
methodName
Stringname of the method to alias
assert
-
desc
-
test
Define an assertion that will throw an exception if the condition is not met.
- In a production build, this method is defined as an empty function (NOP). Uses of this method in Ember itself are stripped from the ember.prod.js build.
// Test for truthiness
Ember.assert('Must pass a valid object', obj);
// Fail unconditionally
Ember.assert('This code path should never be run');
Parameters:
-
desc
StringA description of the assertion. This will become the text of the Error thrown if the assertion fails.
-
test
BooleanMust be truthy for the assertion to pass. If falsy, an exception will be thrown.
assign
-
original
-
args
Copy properties from a source object to a target object.
var a = { first: 'Yehuda' };
var b = { last: 'Katz' };
var c = { company: 'Tilde Inc.' };
Ember.assign(a, b, c); // a === { first: 'Yehuda', last: 'Katz', company: 'Tilde Inc.' }, b === { last: 'Katz' }, c === { company: 'Tilde Inc.' }
Parameters:
-
original
ObjectThe object to assign into
-
args
Object multipleThe objects to copy properties from
Returns:
beforeObserver
-
propertyNames
-
func
When observers fire, they are called with the arguments obj
, keyName
.
Note, @each.property
observer is called per each add or replace of an element
and it's not called with a specific enumeration item.
A _beforeObserver
fires before a property changes.
Returns:
func
beginPropertyChanges
()
private
chainable
bind
-
obj
-
to
-
from
Global helper method to create a new binding. Just pass the root object
along with a to
and from
path to create and connect the binding.
Parameters:
Returns:
binding instance
cacheFor
-
obj
-
key
Returns the cached value for a property, if one exists. This can be useful for peeking at the value of a computed property that is generated lazily, without accidentally causing it to be created.
Parameters:
-
obj
Objectthe object whose property you want to check
-
key
Stringthe name of the property whose cached value you want to return
Returns:
the cached value
canInvoke
-
obj
-
methodName
Checks to see if the methodName
exists on the obj
.
let foo = { bar: function() { return 'bar'; }, baz: null };
Ember.canInvoke(foo, 'bar'); // true
Ember.canInvoke(foo, 'baz'); // false
Ember.canInvoke(foo, 'bat'); // false
Parameters:
-
obj
ObjectThe object to check for the method
-
methodName
StringThe method name to check for
Returns:
changeProperties
-
callback
-
[binding]
Make a series of property changes together in an exception-safe way.
Ember.changeProperties(function() {
obj1.set('foo', mayBlowUpWhenSet);
obj2.set('bar', baz);
});
Parameters:
-
callback
Function -
[binding]
Object optional
compare
-
v
-
w
Compares two javascript values and returns:
- -1 if the first is smaller than the second,
- 0 if both are equal,
- 1 if the first is greater than the second.
Ember.compare('hello', 'hello'); // 0
Ember.compare('abc', 'dfg'); // -1
Ember.compare(2, 1); // 1
If the types of the two objects are different precedence occurs in the
following order, with types earlier in the list considered <
types
later in the list:
- undefined
- null
- boolean
- number
- string
- array
- object
- instance
- function
- class
- date
Ember.compare('hello', 50); // 1
Ember.compare(50, 'hello'); // -1
Parameters:
-
v
ObjectFirst value to compare
-
w
ObjectSecond value to compare
Returns:
-1 if v < w, 0 if v = w and 1 if v > w.
controllerFor
()
private
Finds a controller instance.
copy
-
obj
-
[deep=false]
Creates a shallow copy of the passed object. A deep copy of the object is
returned if the optional deep
argument is true
.
If the passed object implements the Ember.Copyable
interface, then this
function will delegate to the object's copy()
method and return the
result. See Ember.Copyable
for further details.
For primitive values (which are immutable in JavaScript), the passed object is simply returned.
Parameters:
-
obj
ObjectThe object to clone
-
[deep=false]
Boolean optionalIf true, a deep copy of the object is made.
Returns:
The copied object
createInjectionHelper
-
type
-
validator
This method allows other Ember modules to register injection helpers for a
given container type. Helpers are exported to the inject
namespace as the
container type itself.
debug
-
message
Display a debug notice.
- In a production build, this method is defined as an empty function (NOP). Uses of this method in Ember itself are stripped from the ember.prod.js build.
Ember.debug('I\'m a debug notice!');
Parameters:
-
message
StringA debug message to display.
defineProperty
-
obj
-
keyName
-
[desc]
-
[data]
NOTE: This is a low-level method used by other parts of the API. You almost
never want to call this method directly. Instead you should use
Ember.mixin()
to define new properties.
Defines a property on an object. This method works much like the ES5
Object.defineProperty()
method except that it can also accept computed
properties and other special descriptors.
Normally this method takes only three parameters. However if you pass an
instance of Descriptor
as the third param then you can pass an
optional value as the fourth parameter. This is often more efficient than
creating new descriptor hashes for each property.
Examples
// ES5 compatible mode
Ember.defineProperty(contact, 'firstName', {
writable: true,
configurable: false,
enumerable: true,
value: 'Charles'
});
// define a simple property
Ember.defineProperty(contact, 'lastName', undefined, 'Jolley');
// define a computed property
Ember.defineProperty(contact, 'fullName', Ember.computed('firstName', 'lastName', function() {
return this.firstName+' '+this.lastName;
}));
Parameters:
-
obj
Objectthe object to define this property on. This may be a prototype.
-
keyName
Stringthe name of the property
-
[desc]
Descriptor optionalan instance of
Descriptor
(typically a computed property) or an ES5 descriptor. You must provide this ordata
but not both. -
[data]
optionalsomething other than a descriptor, that will become the explicit value of this property.
deprecate
-
message
-
test
-
options
Display a deprecation warning with the provided message and a stack trace (Chrome and Firefox only).
- In a production build, this method is defined as an empty function (NOP). Uses of this method in Ember itself are stripped from the ember.prod.js build.
Parameters:
-
message
StringA description of the deprecation.
-
test
BooleanA boolean. If falsy, the deprecation will be displayed.
-
options
Object-
id
StringA unique id for this deprecation. The id can be used by Ember debugging tools to change the behavior (raise, log or silence) for that specific deprecation. The id should be namespaced by dots, e.g. "view.helper.select".
-
until
StringThe version of Ember when this deprecation warning will be removed.
-
[url]
String optionalAn optional url to the transition guide on the emberjs.com website.
-
deprecateFunc
-
message
-
[options]
-
func
Alias an old, deprecated method with its new counterpart.
Display a deprecation warning with the provided message and a stack trace (Chrome and Firefox only) when the assigned method is called.
- In a production build, this method is defined as an empty function (NOP).
Ember.oldMethod = Ember.deprecateFunc('Please use the new, updated method', Ember.newMethod);
Parameters:
Returns:
A new function that wraps the original function with a deprecation warning
destroy
-
obj
Tears down the meta on an object so that it can be garbage collected. Multiple calls will have no effect.
Parameters:
-
obj
Objectthe object to destroy
Returns:
endPropertyChanges
()
private
expandProperties
-
pattern
-
callback
Expands pattern
, invoking callback
for each expansion.
The only pattern supported is brace-expansion, anything else will be passed
once to callback
directly.
Example
function echo(arg){ console.log(arg); }
Ember.expandProperties('foo.bar', echo); //=> 'foo.bar'
Ember.expandProperties('{foo,bar}', echo); //=> 'foo', 'bar'
Ember.expandProperties('foo.{bar,baz}', echo); //=> 'foo.bar', 'foo.baz'
Ember.expandProperties('{foo,bar}.baz', echo); //=> 'foo.baz', 'bar.baz'
Ember.expandProperties('foo.{bar,baz}.[]', echo) //=> 'foo.bar.[]', 'foo.baz.[]'
Ember.expandProperties('{foo,bar}.{spam,eggs}', echo) //=> 'foo.spam', 'foo.eggs', 'bar.spam', 'bar.eggs'
Ember.expandProperties('{foo}.bar.{baz}') //=> 'foo.bar.baz'
generateController
()
private
Generates and instantiates a controller extending from controller:basic
if present, or Ember.Controller
if not.
generateControllerFactory
()
private
Generates a controller factory
generateGuid
-
[obj]
-
[prefix]
Generates a new guid, optionally saving the guid to the object that you
pass in. You will rarely need to use this method. Instead you should
call Ember.guidFor(obj)
, which return an existing guid if available.
Parameters:
-
[obj]
Object optionalObject the guid will be used for. If passed in, the guid will be saved on the object and reused whenever you pass the same object again.
If no object is passed, just generate a new guid.
-
[prefix]
String optionalPrefix to place in front of the guid. Useful when you want to separate the guid into separate namespaces.
Returns:
the guid
get
-
obj
-
keyName
Gets the value of a property on an object. If the property is computed,
the function will be invoked. If the property is not defined but the
object implements the unknownProperty
method then that will be invoked.
Ember.get(obj, "name");
If you plan to run on IE8 and older browsers then you should use this method anytime you want to retrieve a property on an object that you don't know for sure is private. (Properties beginning with an underscore '_' are considered private.)
On all newer browsers, you only need to use this method to retrieve
properties if the property might not be defined on the object and you want
to respect the unknownProperty
handler. Otherwise you can ignore this
method.
Note that if the object itself is undefined
, this method will throw
an error.
Parameters:
-
obj
ObjectThe object to retrieve from.
-
keyName
StringThe property key to retrieve
Returns:
the property value or null
.
getEngineParent
-
engine
getEngineParent
retrieves an engine instance's parent instance.
Parameters:
-
engine
EngineInstanceAn engine instance.
Returns:
The parent engine instance.
getOwner
-
object
Framework objects in an Ember application (components, services, routes, etc.) are created via a factory and dependency injection system. Each of these objects is the responsibility of an "owner", which handled its instantiation and manages its lifetime.
getOwner
fetches the owner object responsible for an instance. This can
be used to lookup or resolve other class instances, or register new factories
into the owner.
For example, this component dynamically looks up a service based on the
audioType
passed as an attribute:
// app/components/play-audio.js
import Ember from 'ember';
// Usage:
//
// {{play-audio audioType=model.audioType audioFile=model.file}}
//
export default Ember.Component.extend({
audioService: Ember.computed('audioType', function() {
let owner = Ember.getOwner(this);
return owner.lookup(service:${this.get('audioType')}
);
}),
click() {
let player = this.get('audioService');
player.play(this.get('audioFile'));
}
});
Parameters:
-
object
ObjectAn object with an owner.
Returns:
An owner object.
getProperties
-
obj
-
list
To get multiple properties at once, call Ember.getProperties
with an object followed by a list of strings or an array:
Ember.getProperties(record, 'firstName', 'lastName', 'zipCode');
// { firstName: 'John', lastName: 'Doe', zipCode: '10011' }
is equivalent to:
Ember.getProperties(record, ['firstName', 'lastName', 'zipCode']);
// { firstName: 'John', lastName: 'Doe', zipCode: '10011' }
Parameters:
-
obj
Object -
list
String... | Arrayof keys to get
Returns:
getWithDefault
-
obj
-
keyName
-
defaultValue
Retrieves the value of a property from an Object, or a default value in the
case that the property returns undefined
.
Ember.getWithDefault(person, 'lastName', 'Doe');
Parameters:
-
obj
ObjectThe object to retrieve from.
-
keyName
StringThe name of the property to retrieve
-
defaultValue
ObjectThe value to return if the property value is undefined
Returns:
The property value or the defaultValue.
guidFor
-
obj
Returns a unique id for the object. If the object does not yet have a guid,
one will be assigned to it. You can call this on any object,
Ember.Object
-based or not, but be aware that it will add a _guid
property.
You can also use this method on DOM Element objects.
Parameters:
-
obj
Objectany object, string, number, Element, or primitive
Returns:
the unique guid for this instance.
info
()
private
Display an info notice.
- In a production build, this method is defined as an empty function (NOP). Uses of this method in Ember itself are stripped from the ember.prod.js build.
inspect
-
obj
Convenience method to inspect an object. This method will attempt to convert the object into a useful string description.
It is a pretty simple implementation. If you want something more robust, use something like JSDump: https://github.com/NV/jsDump
Parameters:
-
obj
ObjectThe object you want to inspect.
Returns:
A description of the object
isArray
-
obj
Returns true if the passed object is an array or Array-like.
Objects are considered Array-like if any of the following are true:
- the object is a native Array
- the object has an objectAt property
- the object is an Object, and has a length property
Unlike Ember.typeOf
this method returns true even if the passed object is
not formally an array but appears to be array-like (i.e. implements Ember.Array
)
Ember.isArray(); // false
Ember.isArray([]); // true
Ember.isArray(Ember.ArrayProxy.create({ content: [] })); // true
Parameters:
-
obj
ObjectThe object to test
Returns:
true if the passed object is an array or Array-like
isBlank
-
obj
A value is blank if it is empty or a whitespace string.
Ember.isBlank(); // true
Ember.isBlank(null); // true
Ember.isBlank(undefined); // true
Ember.isBlank(''); // true
Ember.isBlank([]); // true
Ember.isBlank('\n\t'); // true
Ember.isBlank(' '); // true
Ember.isBlank({}); // false
Ember.isBlank('\n\t Hello'); // false
Ember.isBlank('Hello world'); // false
Ember.isBlank([1,2,3]); // false
Parameters:
-
obj
ObjectValue to test
Returns:
isEmpty
-
obj
Verifies that a value is null
or an empty string, empty array,
or empty function.
Constrains the rules on Ember.isNone
by returning true for empty
string and empty arrays.
Ember.isEmpty(); // true
Ember.isEmpty(null); // true
Ember.isEmpty(undefined); // true
Ember.isEmpty(''); // true
Ember.isEmpty([]); // true
Ember.isEmpty({}); // false
Ember.isEmpty('Adam Hawkins'); // false
Ember.isEmpty([0,1,2]); // false
Ember.isEmpty('\n\t'); // false
Ember.isEmpty(' '); // false
Parameters:
-
obj
ObjectValue to test
Returns:
isEqual
-
a
-
b
Compares two objects, returning true if they are equal.
Ember.isEqual('hello', 'hello'); // true
Ember.isEqual(1, 2); // false
isEqual
is a more specific comparison than a triple equal comparison.
It will call the isEqual
instance method on the objects being
compared, allowing finer control over when objects should be considered
equal to each other.
let Person = Ember.Object.extend({
isEqual(other) { return this.ssn == other.ssn; }
});
let personA = Person.create({name: 'Muhammad Ali', ssn: '123-45-6789'});
let personB = Person.create({name: 'Cassius Clay', ssn: '123-45-6789'});
Ember.isEqual(personA, personB); // true
Due to the expense of array comparisons, collections will never be equal to each other even if each of their items are equal to each other.
Ember.isEqual([4, 2], [4, 2]); // false
Parameters:
-
a
Objectfirst object to compare
-
b
Objectsecond object to compare
Returns:
isNone
-
obj
Returns true if the passed value is null or undefined. This avoids errors from JSLint complaining about use of ==, which can be technically confusing.
Ember.isNone(); // true
Ember.isNone(null); // true
Ember.isNone(undefined); // true
Ember.isNone(''); // false
Ember.isNone([]); // false
Ember.isNone(function() {}); // false
Parameters:
-
obj
ObjectValue to test
Returns:
isPresent
-
obj
A value is present if it not isBlank
.
Ember.isPresent(); // false
Ember.isPresent(null); // false
Ember.isPresent(undefined); // false
Ember.isPresent(''); // false
Ember.isPresent(' '); // false
Ember.isPresent('\n\t'); // false
Ember.isPresent([]); // false
Ember.isPresent({ length: 0 }) // false
Ember.isPresent(false); // true
Ember.isPresent(true); // true
Ember.isPresent('string'); // true
Ember.isPresent(0); // true
Ember.isPresent(function() {}) // true
Ember.isPresent({}); // true
Ember.isPresent(false); // true
Ember.isPresent('\n\t Hello'); // true
Ember.isPresent([1,2,3]); // true
Parameters:
-
obj
ObjectValue to test
Returns:
K
()
Object
public
An empty function useful for some operations. Always returns this
.
Returns:
makeArray
-
obj
Forces the passed object to be part of an array. If the object is already
an array, it will return the object. Otherwise, it will add the object to
an array. If obj is null
or undefined
, it will return an empty array.
Ember.makeArray(); // []
Ember.makeArray(null); // []
Ember.makeArray(undefined); // []
Ember.makeArray('lindsay'); // ['lindsay']
Ember.makeArray([1, 2, 42]); // [1, 2, 42]
let controller = Ember.ArrayProxy.create({ content: [] });
Ember.makeArray(controller) === controller; // true
Parameters:
-
obj
Objectthe object
Returns:
merge
-
original
-
updates
Merge the contents of two objects together into the first object.
Ember.merge({ first: 'Tom' }, { last: 'Dale' }); // { first: 'Tom', last: 'Dale' }
var a = { first: 'Yehuda' };
var b = { last: 'Katz' };
Ember.merge(a, b); // a == { first: 'Yehuda', last: 'Katz' }, b == { last: 'Katz' }
Parameters:
-
original
ObjectThe object to merge into
-
updates
ObjectThe object to copy properties from
Returns:
meta
-
obj
-
[writable=true]
Retrieves the meta hash for an object. If writable
is true ensures the
hash is writable for this object as well.
The meta object contains information about computed property descriptors as well as any watched properties and other information. You generally will not access this information directly but instead work with higher level methods that manipulate this hash indirectly.
Parameters:
-
obj
ObjectThe object to retrieve meta for
-
[writable=true]
Boolean optionalPass
false
if you do not intend to modify the meta hash, allowing the method to avoid making an unnecessary copy.
Returns:
the meta hash for an object
mixin
-
obj
-
mixins
Parameters:
-
obj
Object -
mixins
Object multiple
Returns:
obj
observer
-
propertyNames
-
func
Specify a method that observes property changes.
Ember.Object.extend({
valueObserver: Ember.observer('value', function() {
// Executes whenever the "value" property changes
})
});
Also available as Function.prototype.observes
if prototype extensions are
enabled.
Returns:
func
on
-
eventNames
-
func
Define a property as a function that should be executed when a specified event or events are triggered.
let Job = Ember.Object.extend({
logCompleted: Ember.on('completed', function() {
console.log('Job completed!');
})
});
let job = Job.create();
Ember.sendEvent(job, 'completed'); // Logs 'Job completed!'
Returns:
func
onLoad
-
name
-
callback
Detects when a specific package of Ember (e.g. 'Ember.Application') has fully loaded and is available for extension.
The provided callback
will be called with the name
passed
resolved from a string into the object:
Ember.onLoad('Ember.Application' function(hbars) {
hbars.registerHelper(...);
});
propertyDidChange
-
obj
-
keyName
-
meta
This function is called just after an object property has changed. It will notify any observers and clear caches among other things.
Normally you will not need to call this method directly but if for some
reason you can't directly watch a property you can invoke this method
manually along with Ember.propertyWillChange()
which you should call just
before the property value changes.
Parameters:
-
obj
ObjectThe object with the property that will change
-
keyName
StringThe property key (or path) that will change.
-
meta
MetaThe objects meta.
Returns:
propertyWillChange
-
obj
-
keyName
This function is called just before an object property is about to change. It will notify any before observers and prepare caches among other things.
Normally you will not need to call this method directly but if for some
reason you can't directly watch a property you can invoke this method
manually along with Ember.propertyDidChange()
which you should call just
after the property value changes.
Parameters:
-
obj
ObjectThe object with the property that will change
-
keyName
StringThe property key (or path) that will change.
Returns:
removeBeforeObserver
-
obj
-
path
-
target
-
[method]
removeListener
-
obj
-
eventName
-
target
-
method
Remove an event listener
Arguments should match those passed to Ember.addListener
.
removeObserver
-
obj
-
path
-
target
-
[method]
required
()
private
Denotes a required property for a mixin
runInDebug
-
func
Run a function meant for debugging.
- In a production build, this method is defined as an empty function (NOP). Uses of this method in Ember itself are stripped from the ember.prod.js build.
Ember.runInDebug(() => {
Ember.Component.reopen({
didInsertElement() {
console.log("I'm happy");
}
});
});
Parameters:
-
func
FunctionThe function to be executed.
runLoadHooks
-
name
-
object
Called when an Ember.js package (e.g Ember.Application) has finished loading. Triggers any callbacks registered for this event.
Parameters:
-
name
Stringname of hook
-
object
Objectobject to pass to callbacks
sendEvent
-
obj
-
eventName
-
params
-
actions
Send an event. The execution of suspended listeners is skipped, and once listeners are removed. A listener without a target is executed on the passed object. If an array of actions is not passed, the actions stored on the passed object are invoked.
Parameters:
-
obj
Object -
eventName
String -
params
ArrayOptional parameters for each listener.
-
actions
ArrayOptional array of actions (listeners).
Returns:
true
set
-
obj
-
keyName
-
value
Sets the value of a property on an object, respecting computed properties
and notifying observers and other listeners of the change. If the
property is not defined but the object implements the setUnknownProperty
method then that will be invoked as well.
Ember.set(obj, "name", value);
Parameters:
-
obj
ObjectThe object to modify.
-
keyName
StringThe property key to set
-
value
ObjectThe value to set
Returns:
the passed value.
setEngineParent
-
engine
-
parent
setEngineParent
sets an engine instance's parent instance.
Parameters:
-
engine
EngineInstanceAn engine instance.
-
parent
EngineInstanceThe parent engine instance.
setOwner
-
object
-
object
setOwner
forces a new owner on a given object instance. This is primarily
useful in some testing cases.
Parameters:
-
object
ObjectAn object instance.
-
object
ObjectThe new owner object of the object instance.
setProperties
-
obj
-
properties
Set a list of properties on an object. These properties are set inside
a single beginPropertyChanges
and endPropertyChanges
batch, so
observers will be buffered.
let anObject = Ember.Object.create();
anObject.setProperties({
firstName: 'Stanley',
lastName: 'Stuart',
age: 21
});
Parameters:
-
obj
Object -
properties
Object
Returns:
properties
suspendListener
-
obj
-
eventName
-
target
-
method
-
callback
Suspend listener during callback.
This should only be used by the target of the event listener when it is taking an action that would cause the event, e.g. an object might suspend its property change listener while it is setting that property.
suspendListeners
-
obj
-
eventNames
-
target
-
method
-
callback
Suspends multiple listeners during a callback.
tryInvoke
-
obj
-
methodName
-
[args]
Checks to see if the methodName
exists on the obj
,
and if it does, invokes it with the arguments passed.
let d = new Date('03/15/2013');
Ember.tryInvoke(d, 'getTime'); // 1363320000000
Ember.tryInvoke(d, 'setFullYear', [2014]); // 1394856000000
Ember.tryInvoke(d, 'noSuchMethod', [2014]); // undefined
Parameters:
-
obj
ObjectThe object to check for the method
-
methodName
StringThe method name to check for
-
[args]
Array optionalThe arguments to pass to the method
Returns:
the return value of the invoked method or undefined if it cannot be invoked
trySet
-
root
-
path
-
value
Error-tolerant form of Ember.set
. Will not blow up if any part of the
chain is undefined
, null
, or destroyed.
This is primarily used when syncing bindings, which may try to update after an object has been destroyed.
Parameters:
-
root
ObjectThe object to modify.
-
path
StringThe property path to set
-
value
ObjectThe value to set
typeOf
-
item
Returns a consistent type for the passed object.
Use this instead of the built-in typeof
to get the type of an item.
It will return the same result across all browsers and includes a bit
more detail. Here is what will be returned:
| Return Value | Meaning |
|---------------|------------------------------------------------------|
| 'string' | String primitive or String object. |
| 'number' | Number primitive or Number object. |
| 'boolean' | Boolean primitive or Boolean object. |
| 'null' | Null value |
| 'undefined' | Undefined value |
| 'function' | A function |
| 'array' | An instance of Array |
| 'regexp' | An instance of RegExp |
| 'date' | An instance of Date |
| 'filelist' | An instance of FileList |
| 'class' | An Ember class (created using Ember.Object.extend()) |
| 'instance' | An Ember object instance |
| 'error' | An instance of the Error object |
| 'object' | A JavaScript object not inheriting from Ember.Object |
Examples:
Ember.typeOf(); // 'undefined'
Ember.typeOf(null); // 'null'
Ember.typeOf(undefined); // 'undefined'
Ember.typeOf('michael'); // 'string'
Ember.typeOf(new String('michael')); // 'string'
Ember.typeOf(101); // 'number'
Ember.typeOf(new Number(101)); // 'number'
Ember.typeOf(true); // 'boolean'
Ember.typeOf(new Boolean(true)); // 'boolean'
Ember.typeOf(Ember.makeArray); // 'function'
Ember.typeOf([1, 2, 90]); // 'array'
Ember.typeOf(/abc/); // 'regexp'
Ember.typeOf(new Date()); // 'date'
Ember.typeOf(event.target.files); // 'filelist'
Ember.typeOf(Ember.Object.extend()); // 'class'
Ember.typeOf(Ember.Object.create()); // 'instance'
Ember.typeOf(new Error('teamocil')); // 'error'
// 'normal' JavaScript object
Ember.typeOf({ a: 'b' }); // 'object'
Parameters:
-
item
Objectthe item to check
Returns:
the type
validatePropertyInjections
-
factory
Validation function that runs per-type validation functions once for each injected type encountered.
Parameters:
-
factory
ObjectThe factory object
warn
-
message
-
test
-
options
Display a warning with the provided message.
- In a production build, this method is defined as an empty function (NOP). Uses of this method in Ember itself are stripped from the ember.prod.js build.
Parameters:
-
message
StringA warning to display.
-
test
BooleanAn optional boolean. If falsy, the warning will be displayed.
-
options
ObjectAn object that can be used to pass a unique
id
for this warning. Theid
can be used by Ember debugging tools to change the behavior (raise, log, or silence) for that specific warning. Theid
should be namespaced by dots, e.g. "ember-debug.feature-flag-with-features-stripped"
watch
-
obj
-
_keyPath
Starts watching a property on an object. Whenever the property changes,
invokes Ember.propertyWillChange
and Ember.propertyDidChange
. This is the
primitive used by observers and dependent keys; usually you will never call
this method directly but instead use higher level methods like
Ember.addObserver()
Parameters:
-
obj
Object -
_keyPath
String
watchedEvents
-
obj
Return a list of currently watched events
Parameters:
-
obj
Object
Properties
BOOTED
Boolean
private
Whether searching on the global for new Namespace instances is enabled.
This is only exported here as to not break any addons. Given the new visit API, you will have issues if you treat this as a indicator of booted.
Internally this is only exposing a flag in Namespace.
GUID_KEY
String
private
final
A unique key used to assign guids and other private metadata to objects. If you inspect an object in your browser debugger you will often see these. They can be safely ignored.
On browsers that support it, these properties are added with enumeration disabled so they won't show up when you iterate over your properties.
STRINGS
Object
private
Defines the hash of localized strings for the current language. Used by
the Ember.String.loc()
helper. To localize, add string values to this
hash.
TEMPLATES
Object
private
Global hash of shared templates. This will automatically be populated by the build tools so that you can store your Handlebars templates in separate files that get loaded into JavaScript at buildtime.
Events
onerror
public
A function may be assigned to Ember.onerror
to be called when Ember
internals encounter an error. This is useful for specialized error handling
and reporting code.
Ember.onerror = function(error) {
Em.$.ajax('/report-error', 'POST', {
stack: error.stack,
otherInformation: 'whatever app state you want to provide'
});
};
Internally, Ember.onerror
is used as Backburner's error handler.
Event Payload:
-
error
Exceptionthe error object