Ember
Ember Namespace
PUBLIC
Defined in: packages/ember-metal/lib/core.js:8
Module: ember-metal
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.
$public
Alias for jQuery
AEmber.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:
KObject
public
An empty function useful for some operations. Always returns this
.
Returns:
-
Object
_addBeforeObserver (obj, path, target, method) deprecatedprivate
Parameters:
- obj
-
path
String
-
target
Object|Function
-
method
[Function|String]
_immediateObserver (propertyNames, func) deprecatedprivate
Use Ember.observer
instead.
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
_warnIfUsingStrippedFeatureFlagsVoid
private
Will call Ember.warn()
if ENABLEOPTIONALFEATURES or any specific FEATURES flag is truthy.
This method is called automatically in debug canary builds.
Returns:
-
Void
addListener (obj, eventName, target, method, once) public
Add an event listener
Parameters:
- obj
-
eventName
String
-
target
Object|Function
- A target object or a function
-
method
Function|String
- A function or the name of a function to be called on `target`
-
once
Boolean
- A flag whether a function should only be called once
addObserver (obj, _path, target, method) public
Parameters:
- obj
-
_path
String
-
target
Object|Function
-
method
[Function|String]
aliasMethod (methodName) public
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
String
- name of the method to alias
assert (desc, test) public
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
String
- A description of the assertion. This will become the text of the Error thrown if the assertion fails.
-
test
Boolean
- Must be truthy for the assertion to pass. If falsy, an exception will be thrown.
assign (original, args) Object
public
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
Object
- The object to assign into
-
args
Object
- The objects to copy properties from
Returns:
-
Object
beforeObserver (propertyNames, func) deprecatedprivate
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
beginPropertyChangesprivate
bind (obj, to, from) Ember-Binding
public
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:
-
Ember-Binding
- binding instance
cacheFor (obj, key) Object
public
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
Object
- the object whose property you want to check
-
key
String
- the name of the property whose cached value you want to return
Returns:
-
Object
- the cached value
canInvoke (obj, methodName) Boolean
private
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
Object
- The object to check for the method
-
methodName
String
- The method name to check for
Returns:
-
Boolean
changeProperties (callback, binding) private
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
[]
compare (v, w) Number
public
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
Object
- First value to compare
-
w
Object
- Second value to compare
Returns:
-
Number
- -1 if v < w, 0 if v = w and 1 if v > w.
controllerForprivate
Finds a controller instance.
copy (obj, deep) Object
public
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
Object
- The object to clone
-
deep
[Boolean]
- If true, a deep copy of the object is made.
Returns:
-
Object
- The copied object
createInjectionHelper (type, validator) private
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.
Parameters:
debug (message) public
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
String
- A debug message to display.
defineProperty (obj, keyName, desc, data) private
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
Object
- the object to define this property on. This may be a prototype.
-
keyName
String
- the name of the property
-
desc
[Descriptor]
- an instance of `Descriptor` (typically a computed property) or an ES5 descriptor. You must provide this or `data` but not both.
-
data
[*]
- something other than a descriptor, that will become the explicit value of this property.
deprecate (message, test, options) public
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
String
- A description of the deprecation.
-
test
Boolean
- A boolean. If falsy, the deprecation will be displayed.
-
options
Object
-
-
id
String
- A 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
String
- The version of Ember when this deprecation warning will be removed.
-
url
[String]
- An optional url to the transition guide on the emberjs.com website.
-
id
deprecateFunc (message, options, func) Function
private
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:
-
Function
- A new function that wraps the original function with a deprecation warning
destroy (obj) Void
private
Tears down the meta on an object so that it can be garbage collected. Multiple calls will have no effect.
Parameters:
-
obj
Object
- the object to destroy
Returns:
-
Void
endPropertyChangesprivate
expandProperties (pattern, callback) private
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'
Parameters:
generateControllerprivate
Generates and instantiates a controller extending from controller:basic
if present, or Ember.Controller
if not.
generateControllerFactoryprivate
Generates a controller factory
generateGuid (obj, prefix) String
private
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]
- Object 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]
- Prefix to place in front of the guid. Useful when you want to separate the guid into separate namespaces.
Returns:
-
String
- the guid
get (obj, keyName) Object
public
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
Object
- The object to retrieve from.
-
keyName
String
- The property key to retrieve
Returns:
-
Object
- the property value or `null`.
getEngineParent (engine) EngineInstance
public
getEngineParent
retrieves an engine instance's parent instance.
Parameters:
-
engine
EngineInstance
- An engine instance.
Returns:
-
EngineInstance
- The parent engine instance.
getOwner (object) Object
public
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
Object
- An object with an owner.
Returns:
-
Object
- An owner object.
getProperties (obj, list) Object
public
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...|Array
- of keys to get
Returns:
-
Object
getWithDefault (obj, keyName, defaultValue) Object
public
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
Object
- The object to retrieve from.
-
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.
guidFor (obj) String
public
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
Object
- any object, string, number, Element, or primitive
Returns:
-
String
- the unique guid for this instance.
hasListeners (obj, eventName) private
Parameters:
- obj
-
eventName
String
infoprivate
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) String
private
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
Object
- The object you want to inspect.
Returns:
-
String
- A description of the object
isArray (obj) Boolean
public
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
Object
- The object to test
Returns:
-
Boolean
- true if the passed object is an array or Array-like
isBlank (obj) Boolean
public
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
Object
- Value to test
Returns:
-
Boolean
isEmpty (obj) Boolean
public
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
Object
- Value to test
Returns:
-
Boolean
isEqual (a, b) Boolean
public
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
Object
- first object to compare
-
b
Object
- second object to compare
Returns:
-
Boolean
isNone (obj) Boolean
public
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
Object
- Value to test
Returns:
-
Boolean
isPresent (obj) Boolean
public
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
Object
- Value to test
Returns:
-
Boolean
listenersFor (obj, eventName) private
Parameters:
- obj
-
eventName
String
makeArray (obj) Array
private
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
Object
- the object
Returns:
-
Array
merge (original, updates) Object
public
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
Object
- The object to merge into
-
updates
Object
- The object to copy properties from
Returns:
-
Object
meta (obj, writable) Object
private
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
Object
- The object to retrieve meta for
-
writable
[Boolean]
- Pass `false` if you do not intend to modify the meta hash, allowing the method to avoid making an unnecessary copy.
Returns:
-
Object
- the meta hash for an object
mixin (obj, mixins) private
Parameters:
- obj
- mixins
Returns:
- obj
observer (propertyNames, func) public
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) public
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) private
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) Void
private
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
Object
- The object with the property that will change
-
keyName
String
- The property key (or path) that will change.
-
meta
Meta
- The objects meta.
Returns:
-
Void
propertyWillChange (obj, keyName) Void
private
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
Object
- The object with the property that will change
-
keyName
String
- The property key (or path) that will change.
Returns:
-
Void
removeBeforeObserver (obj, path, target, method) deprecatedprivate
Parameters:
- obj
-
path
String
-
target
Object|Function
-
method
[Function|String]
removeListener (obj, eventName, target, method) public
Remove an event listener
Arguments should match those passed to Ember.addListener
.
Parameters:
- obj
-
eventName
String
-
target
Object|Function
- A target object or a function
-
method
Function|String
- A function or the name of a function to be called on `target`
removeObserver (obj, path, target, method) public
Parameters:
- obj
-
path
String
-
target
Object|Function
-
method
[Function|String]
requiredprivate
Denotes a required property for a mixin
runInDebug (func) public
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
Function
- The function to be executed.
runLoadHooks (name, object) private
Called when an Ember.js package (e.g Ember.Application) has finished loading. Triggers any callbacks registered for this event.
Parameters:
-
name
String
- name of hook
-
object
Object
- object to pass to callbacks
sendEvent (obj, eventName, params, actions) public
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
-
eventName
String
-
params
Array
- Optional parameters for each listener.
-
actions
Array
- Optional array of actions (listeners).
Returns:
- true
set (obj, keyName, value) Object
public
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
Object
- The object to modify.
-
keyName
String
- The property key to set
-
value
Object
- The value to set
Returns:
-
Object
- the passed value.
setEngineParent (engine, parent) private
setEngineParent
sets an engine instance's parent instance.
Parameters:
-
engine
EngineInstance
- An engine instance.
-
parent
EngineInstance
- The parent engine instance.
setOwner (object, object) public
setOwner
forces a new owner on a given object instance. This is primarily useful in some testing cases.
Parameters:
-
object
Object
- An object instance.
-
object
Object
- The new owner object of the object instance.
setProperties (obj, properties) public
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
-
properties
Object
Returns:
- properties
suspendListener (obj, eventName, target, method, callback) private
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.
Parameters:
suspendListeners (obj, eventNames, target, method, callback) private
Suspends multiple listeners during a callback.
Parameters:
- obj
-
eventNames
Array
- Array of event names
-
target
Object|Function
- A target object or a function
-
method
Function|String
- A function or the name of a function to be called on `target`
-
callback
Function
tryInvoke (obj, methodName, args) *
public
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
Object
- The object to check for the method
-
methodName
String
- The method name to check for
-
args
[Array]
- The 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) public
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
Object
- The object to modify.
-
path
String
- The property path to set
-
value
Object
- The value to set
typeOf (item) String
public
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
Object
- the item to check
Returns:
-
String
- the type
validatePropertyInjections (factory) private
Validation function that runs per-type validation functions once for each injected type encountered.
Parameters:
-
factory
Object
- The factory object
warn (message, test, options) public
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
String
- A warning to display.
-
test
Boolean
- An optional boolean. If falsy, the warning will be displayed.
-
options
Object
- An object that can be used to pass a unique `id` for this warning. The `id` can be used by Ember debugging tools to change the behavior (raise, log, or silence) for that specific warning. The `id` should be namespaced by dots, e.g. "ember-debug.feature-flag-with-features-stripped"
watch (obj, _keyPath) private
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
-
_keyPath
String
watchedEvents (obj) private
Return a list of currently watched events
Parameters:
- obj
wrap (func, superFunc) Function
private
Wraps the passed function so that this._super
will point to the superFunc when the function is invoked. This is the primitive we use to implement calls to super.
Returns:
-
Function
- wrapped function.
onerror (error) 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.
Parameters:
-
error
Exception
- the error object
BOOTEDBoolean
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_KEYString
privateconstant
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.
GUID_PREFIXString
privateconstant
Prefix used for guids through out Ember.
STRINGSObject
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.
TEMPLATESObject
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.
VERSIONString
public
The semantic version
© 2017 Yehuda Katz, Tom Dale and Ember.js contributors
Licensed under the MIT License.
https://emberjs.com/api/classes/Ember.html