Ember Namespace packages/ember-metal/lib/core.js:8


PUBLIC

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.

You can also use the shorthand Em instead of Ember.

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.

Show:

$

public

Alias for jQuery

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 Ember.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 Ember.EXTEND_PROTOTYPES will be true.

Example

1
2
3
4
5
6
7
8
9
10
11
var Pagination = Ember.CollectionView.extend({
  tagName: 'ul',
  classNames: ['pagination'],

  init: function() {
    this._super.apply(this, arguments);
    if (!this.get('content')) {
      this.set('content', Ember.A());
    }
  }
});

K

Object public

An empty function useful for some operations. Always returns this.

Returns:

Object

_addBeforeObserver

(obj, path, target, method) deprecated private

Parameters:

obj
path String
target Object|Function
method [Function|String]

_immediateObserver

(propertyNames, func) deprecated private

Use Ember.observer instead.

Specify a method that observes property changes.

1
2
3
4
5
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.

Parameters:

propertyNames String
func Function

Returns:

func

_warnIfUsingStrippedFeatureFlags

Void private

Will call Ember.warn() if ENABLEALLFEATURES, 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) private

Makes a method available via an additional name.

1
2
3
4
5
6
7
8
9
10
11
App.Person = Ember.Object.extend({
  name: function() {
    return 'Tomhuda Katzdale';
  },
  moniker: Ember.aliasMethod('name')
});

var 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. Ember build tools will remove any calls to Ember.assert() when doing a production build. Example:

1
2
3
4
5
// 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|Function
Must be truthy for the assertion to pass. If falsy, an exception will be thrown. If this is a function, it will be executed and its return value will be used as condition.

beforeObserver

(propertyNames, func) deprecated private

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.

A _beforeObserver is an alternative form of .observesBefore().

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
App.PersonView = Ember.View.extend({
  friends: [{ name: 'Tom' }, { name: 'Stefan' }, { name: 'Kris' }],

  valueDidChange: Ember.observer('content.value', function(obj, keyName) {
      // only run if updating a value already in the DOM
      if (this.get('state') === 'inDOM') {
        var color = obj.get(keyName) > this.changingFrom ? 'green' : 'red';
        // logic
      }
  }),

  friendsDidChange: Ember.observer('friends.@each.name', function(obj, keyName) {
    // some logic
    // obj.get(keyName) returns friends array
  })
});

Also available as Function.prototype.observesBefore if prototype extensions are enabled.

Parameters:

propertyNames String
func Function

Returns:

func

beginPropertyChanges

private

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:

obj Object
The root object of the transform.
to String
The path to the 'to' side of the binding. Must be relative to obj.
from String
The path to the 'from' side of the binding. Must be relative to obj or a global path.

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.

1
2
3
4
5
var 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.

1
2
3
4
Ember.changeProperties(function() {
  obj1.set('foo', mayBlowUpWhenSet);
  obj2.set('bar', baz);
});

Parameters:

callback Function
binding []

compare

(v, w) Number private

This will compare two javascript values of possibly different types. It will tell you which one is greater than the other by returning:

  • -1 if the first is smaller than the second,
  • 0 if both are equal,
  • 1 if the first is greater than the second.

The order is calculated based on Ember.ORDER_DEFINITION, if types are different. In case they have the same type an appropriate comparison for this type is made.

1
2
3
 Ember.compare('hello', 'hello');  // 0
 Ember.compare('abc', 'dfg');      // -1
 Ember.compare(2, 1);              // 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.

controllerFor

private

Finds a controller instance.

copy

(obj, deep) Object public

Creates a clone of the passed object. This function can take just about any type of object and create a clone of it, including primitive values (which are not actually cloned because they are immutable).

If the passed object implements the copy() method, then this function will simply call that method and return the result. Please see Ember.Copyable for further details.

Parameters:

obj Object
The object to clone
deep Boolean
If true, a deep copy of the object is made

Returns:

Object
The cloned object

createInjectionHelper

(type, validator) private
Defined in packages/ember-runtime/lib/inject.js:19
Available since 1.10.0

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:

type String
The container type the helper will inject
validator Function
A validation callback that is executed at mixin-time

debug

(message) public

Display a debug notice. Ember build tools will remove any calls to Ember.debug() when doing a production build.

1
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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
// 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(function() {
  return this.firstName+' '+this.lastName;
}).property('firstName', '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). Ember build tools will remove any calls to Ember.deprecate() when doing a production build.

Parameters:

message String
A description of the deprecation.
test Boolean|Function
An optional boolean. If falsy, the deprecation will be displayed. If this is a function, it will be executed and its return value will be used as condition.
options Object
An optional object that can be used to pass in a `url` to the transition guide on the emberjs.com website, and 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".

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.

Ember build tools will not remove calls to Ember.deprecateFunc(), though no warnings will be shown in production.

1
Ember.oldMethod = Ember.deprecateFunc('Please use the new, updated method', Ember.newMethod);

Parameters:

message String
A description of the deprecation.
options [Object]
The options object for Ember.deprecate.
func Function
The new function called to replace its deprecated counterpart.

Returns:

Function
a new function that wrapped 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

endPropertyChanges

private

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

1
2
3
4
5
6
7
8
9
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:

pattern String
The property pattern to expand.
callback Function
The callback to invoke. It is invoked once per expansion, and is passed the expansion.

generateController

private

Generates and instantiates a controller.

The type of the generated controller factory is derived from the context. If the context is an array an array controller is generated, if an object, an object controller otherwise, a basic controller is generated.

generateControllerFactory

private

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.

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`.

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:

1
2
Ember.getProperties(record, 'firstName', 'lastName', 'zipCode');
// { firstName: 'John', lastName: 'Doe', zipCode: '10011' }

is equivalent to:

1
2
Ember.getProperties(record, ['firstName', 'lastName', 'zipCode']);
// { firstName: 'John', lastName: 'Doe', zipCode: '10011' }

Parameters:

obj Object
list String...|Array
of keys to get

Returns:

Object

guidFor

(obj) String private

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

inspect

(obj) String private
Defined in packages/ember-metal/lib/utils.js:500
Available since 1.4.0

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.

Ember Array Protocol:

  • the object has an objectAt property
  • the object is a native Array
  • 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 array but appears to be array-like (i.e. implements Ember.Array)

1
2
3
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
Defined in packages/ember-metal/lib/is_blank.js:3
Available since 1.5.0

A value is blank if it is empty or a whitespace string.

1
2
3
4
5
6
7
8
9
10
11
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.

1
2
3
4
5
6
7
8
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

Parameters:

obj Object
Value to test

Returns:

Boolean

isEqual

(a, b) Boolean public

Compares two objects, returning true if they are logically equal. This is a deeper comparison than a simple triple equal. For sets it will compare the internal objects. For any other object that implements isEqual() it will respect that method.

1
2
3
Ember.isEqual('hello', 'hello');  // true
Ember.isEqual(1, 2);              // false
Ember.isEqual([4, 2], [4, 2]);    // false

Parameters:

a Object
first object to compare
b Object
second object to compare

Returns:

Boolean

isGlobalPath

(path) private

Returns true if the provided path is global (e.g., MyApp.fooController.bar) instead of local (foo.bar.baz).

Parameters:

path String

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.

1
2
3
4
5
6
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
Defined in packages/ember-metal/lib/is_present.js:3
Available since 1.8.0

A value is present if it not isBlank.

1
2
3
4
5
6
7
8
9
10
11
12
Ember.isPresent();                // false
Ember.isPresent(null);            // false
Ember.isPresent(undefined);       // false
Ember.isPresent(false);           // false
Ember.isPresent('');              // false
Ember.isPresent([]);              // false
Ember.isPresent('\n\t');          // false
Ember.isPresent('  ');            // false
Ember.isPresent({});              // true
Ember.isPresent('\n\t Hello');    // true
Ember.isPresent('Hello world');   // true
Ember.isPresent([1,2,3]);         // true

Parameters:

obj Object
Value to test

Returns:

Boolean

keys

(obj) Array private

Returns all of the keys defined on an object or hash. This is useful when inspecting objects for debugging. On browsers that support it, this uses the native Object.keys implementation.

Parameters:

obj Object

Returns:

Array
Array containing keys of obj

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.

1
2
3
4
5
6
7
8
9
Ember.makeArray();            // []
Ember.makeArray(null);        // []
Ember.makeArray(undefined);   // []
Ember.makeArray('lindsay');   // ['lindsay']
Ember.makeArray([1, 2, 42]);  // [1, 2, 42]

var 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.

1
2
3
4
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

normalizeTuple

(target, path) Array private

Normalizes a target/path pair to reflect that actual target/path that should be observed, etc. This takes into account passing in global property paths (i.e. a path beginning with a capital letter not defined on the target).

Parameters:

target Object
The current target. May be `null`.
path String
A path on the target or a global property path.

Returns:

Array
a temporary array with the normalized target/path pair.

observer

(propertyNames, func) private

Specify a method that observes property changes.

1
2
3
4
5
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.

Parameters:

propertyNames String
func Function

Returns:

func

on

(eventNames, func) public

Define a property as a function that should be executed when a specified event or events are triggered.

1
2
3
4
5
6
7
8
9
var Job = Ember.Object.extend({
  logCompleted: Ember.on('completed', function() {
    console.log('Job completed!');
  })
});

var job = Job.create();

Ember.sendEvent(job, 'completed'); // Logs 'Job completed!'

Parameters:

eventNames String
func Function

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:

1
2
3
Ember.onLoad('Ember.Application' function(hbars) {
  hbars.registerHelper(...);
});

Parameters:

name String
name of hook
callback Function
callback to be called

propertyDidChange

(obj, keyName) 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.

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) deprecated private

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]

required

private

Denotes a required property for a mixin

runInDebug

(func) public
Defined in packages/ember-debug/lib/main.js:213
Available since 1.5.0

Run a function meant for debugging. Ember build tools will remove any calls to Ember.runInDebug() when doing a production build.

1
2
3
4
5
6
7
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.

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.

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.

1
2
3
4
5
6
7
var 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:

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`
callback Function

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.

1
2
3
4
5
var 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 item.

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:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
| 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                                  |
| '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:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
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(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
Defined in packages/ember-runtime/lib/inject.js:39
Available since 1.10.0

Validation function that runs per-type validation functions once for each injected type encountered.

Parameters:

factory Object
The factory object

warn

(message, test) public

Display a warning with the provided message. Ember build tools will remove any calls to Ember.warn() when doing a production build.

Parameters:

message String
A warning to display.
test Boolean
An optional boolean. If falsy, the warning will be displayed.

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.

Parameters:

func Function
The function to call
superFunc Function
The super function.

Returns:

Function
wrapped function.
Show:

ENV

Object public

The hash of environment variables used to control various configuration settings. To specify your own or override default settings, add the desired properties to a global hash named EmberENV (or ENV for backwards compatibility with earlier versions of Ember). The EmberENV hash must be created before loading Ember.

EXTEND_PROTOTYPES

Boolean public

Determines whether Ember should add to Array, Function, and String native object prototypes, a few extra methods in order to provide a more friendly API.

We generally recommend leaving this option set to true however, if you need to turn it off, you can add the configuration property EXTEND_PROTOTYPES to EmberENV and set it to false.

Note, when disabled (the default configuration for Ember Addons), you will instead have to access all methods and functions from the Ember namespace.

Default: true

GUID_KEY

String private constant

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_PREFIX

String private constant

Prefix used for guids through out Ember.

LOG_BINDINGS

Boolean public

Debug parameter you can turn on. This will log all bindings that fire to the console. This should be disabled in production code. Note that you can also enable this from the console or temporarily.

Default: false

LOG_STACKTRACE_ON_DEPRECATION

Boolean public

The LOG_STACKTRACE_ON_DEPRECATION property, when true, tells Ember to log a full stack trace during deprecation warnings.

Default: true

LOG_VERSION

Boolean public

The LOG_VERSION property, when true, tells Ember to log versions of all dependent libraries in use.

Default: true

SHIM_ES5

Boolean public

The SHIM_ES5 property, when true, tells Ember to add ECMAScript 5 Array shims to older browsers.

Default: Ember.EXTEND_PROTOTYPES

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.

VERSION

String public static

The semantic version.

Default: 'VERSION_STRING_PLACEHOLDER'

Show:

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.

1
2
3
4
5
6
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