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


All Ember methods and functions are defined inside of this namespace. You generally should not add new properties to this namespace as it may be overwritten by future versions of Ember.

You can also use the shorthand Em instead of Ember.

Ember-Runtime is a framework that provides core functions for Ember including cross-platform functions, support for property observing and objects. Its focus is on small size and performance. You can use this in place of or along-side other cross-platform libraries such as jQuery.

The core Runtime framework is based on the jQuery API with a number of performance optimizations.

Show:

(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}.@each', echo)   //=> 'foo.bar.@each', 'foo.baz.@each'
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.

$

Alias for jQuery

A

Ember.NativeArray

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 private

Empty function. Useful for some operations. Always returns this.

Returns:

Object

_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

addBeforeObserver

(obj, path, target, method)

Parameters:

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

addListener

(obj, eventName, target, method, once)

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, targetOrMethod, method)

Parameters:

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

aliasMethod

(methodName)

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

arrayComputed

(dependentKeys*, options) Ember.ComputedProperty

Creates a computed property which operates on dependent arrays and is updated with "one at a time" semantics. When items are added or removed from the dependent array(s) an array computed only operates on the change instead of re-evaluating the entire array. This should return an array, if you'd like to use "one at a time" semantics and compute some value other then an array look at Ember.reduceComputed.

If there are more than one arguments the first arguments are considered to be dependent property keys. The last argument is required to be an options object. The options object can have the following three properties.

initialize - An optional initialize function. Typically this will be used to set up state on the instanceMeta object.

removedItem - A function that is called each time an element is removed from the array.

addedItem - A function that is called each time an element is added to the array.

The initialize function has the following signature:

1
function(array, changeMeta, instanceMeta)

array - The initial value of the arrayComputed, an empty array.

changeMeta - An object which contains meta information about the computed. It contains the following properties:

  • property the computed property
  • propertyName the name of the property on the object

instanceMeta - An object that can be used to store meta information needed for calculating your computed. For example a unique computed might use this to store the number of times a given element is found in the dependent array.

The removedItem and addedItem functions both have the following signature:

1
function(accumulatedValue, item, changeMeta, instanceMeta)

accumulatedValue - The value returned from the last time removedItem or addedItem was called or an empty array.

item - the element added or removed from the array

changeMeta - An object which contains meta information about the change. It contains the following properties:

  • property the computed property
  • propertyName the name of the property on the object
  • index the index of the added or removed item
  • item the added or removed item: this is exactly the same as the second arg
  • arrayChanged the array that triggered the change. Can be useful when depending on multiple arrays.

For property changes triggered on an item property change (when depKey is something like someArray.@each.someProperty), changeMeta will also contain the following property:

  • previousValues an object whose keys are the properties that changed on the item, and whose values are the item's previous values.

previousValues is important Ember coalesces item property changes via Ember.run.once. This means that by the time removedItem gets called, item has the new values, but you may need the previous value (eg for sorting & filtering).

instanceMeta - An object that can be used to store meta information needed for calculating your computed. For example a unique computed might use this to store the number of times a given element is found in the dependent array.

The removedItem and addedItem functions should return the accumulated value. It is acceptable to not return anything (ie return undefined) to invalidate the computation. This is generally not a good idea for arrayComputed but it's used in eg max and min.

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
Ember.computed.map = function(dependentKey, callback) {
  var options = {
    addedItem: function(array, item, changeMeta, instanceMeta) {
      var mapped = callback(item);
      array.insertAt(changeMeta.index, mapped);
      return array;
    },
    removedItem: function(array, item, changeMeta, instanceMeta) {
      array.removeAt(changeMeta.index, 1);
      return array;
    }
  };

  return Ember.arrayComputed(dependentKey, options);
};

Parameters:

dependentKeys* [String]
options Object

assert

(desc, test)

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)

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
17
18
19
20
App.PersonView = Ember.View.extend({
  friends: [{ name: 'Tom' }, { name: 'Stefan' }, { name: 'Kris' }],

  valueWillChange: Ember.beforeObserver('content.value', function(obj, keyName) {
    this.changingFrom = obj.get(keyName);
  }),

  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

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

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

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)

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

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

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

create

Defined in packages/ember-metal/lib/platform/create.js:14
Available since 1.8.0

Identical to Object.create(). Implements if not available natively.

createInjectionHelper

(type, validator) private
Defined in packages/ember-runtime/lib/inject.js:21
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)

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)

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.

deprecateFunc

(message, func) Function

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

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

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

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.

You can customize your generated controllers by defining App.ObjectController or App.ArrayController.

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

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

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

immediateObserver

(propertyNames, func)

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

inspect

(obj) String
Defined in packages/ember-metal/lib/utils.js:902
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

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

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

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

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
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
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({});              // 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

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

Forces the passed object to be part of an array. If the object is already an array or array-like, 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

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

metaPath

(obj, path, writable) deprecated private

Parameters:

obj Object
The object whose meta we are examining
path Array
An array of keys to walk down
writable Boolean
whether or not to create a new meta (or meta property) if one does not already exist or if it's shared with its constructor

mixin

(obj, mixins)

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)

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
  })
});

In the future this method may become asynchronous. If you want to ensure synchronous behavior, use immediateObserver.

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

Parameters:

propertyNames String
func Function

Returns:

func

on

(eventNames, func)

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)

Detects when a specific package of Ember (e.g. 'Ember.Handlebars') 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.Handlebars' function(hbars) {
  hbars.registerHelper(...);
});

Parameters:

name String
name of hook
callback Function
callback to be called

oneWay

(obj, to, from) Ember.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

propertyDidChange

(obj, keyName) Void

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

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

reduceComputed

(dependentKeys*, options) Ember.ComputedProperty

Creates a computed property which operates on dependent arrays and is updated with "one at a time" semantics. When items are added or removed from the dependent array(s) a reduce computed only operates on the change instead of re-evaluating the entire array.

If there are more than one arguments the first arguments are considered to be dependent property keys. The last argument is required to be an options object. The options object can have the following four properties:

initialValue - A value or function that will be used as the initial value for the computed. If this property is a function the result of calling the function will be used as the initial value. This property is required.

initialize - An optional initialize function. Typically this will be used to set up state on the instanceMeta object.

removedItem - A function that is called each time an element is removed from the array.

addedItem - A function that is called each time an element is added to the array.

The initialize function has the following signature:

1
function(initialValue, changeMeta, instanceMeta)

initialValue - The value of the initialValue property from the options object.

changeMeta - An object which contains meta information about the computed. It contains the following properties:

  • property the computed property
  • propertyName the name of the property on the object

instanceMeta - An object that can be used to store meta information needed for calculating your computed. For example a unique computed might use this to store the number of times a given element is found in the dependent array.

The removedItem and addedItem functions both have the following signature:

1
function(accumulatedValue, item, changeMeta, instanceMeta)

accumulatedValue - The value returned from the last time removedItem or addedItem was called or initialValue.

item - the element added or removed from the array

changeMeta - An object which contains meta information about the change. It contains the following properties:

  • property the computed property
  • propertyName the name of the property on the object
  • index the index of the added or removed item
  • item the added or removed item: this is exactly the same as the second arg
  • arrayChanged the array that triggered the change. Can be useful when depending on multiple arrays.

For property changes triggered on an item property change (when depKey is something like someArray.@each.someProperty), changeMeta will also contain the following property:

  • previousValues an object whose keys are the properties that changed on the item, and whose values are the item's previous values.

previousValues is important Ember coalesces item property changes via Ember.run.once. This means that by the time removedItem gets called, item has the new values, but you may need the previous value (eg for sorting & filtering).

instanceMeta - An object that can be used to store meta information needed for calculating your computed. For example a unique computed might use this to store the number of times a given element is found in the dependent array.

The removedItem and addedItem functions should return the accumulated value. It is acceptable to not return anything (ie return undefined) to invalidate the computation. This is generally not a good idea for arrayComputed but it's used in eg max and min.

Note that observers will be fired if either of these functions return a value that differs from the accumulated value. When returning an object that mutates in response to array changes, for example an array that maps everything from some other array (see Ember.computed.map), it is usually important that the same array be returned to avoid accidentally triggering observers.

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
Ember.computed.max = function(dependentKey) {
  return Ember.reduceComputed(dependentKey, {
    initialValue: -Infinity,

    addedItem: function(accumulatedValue, item, changeMeta, instanceMeta) {
      return Math.max(accumulatedValue, item);
    },

    removedItem: function(accumulatedValue, item, changeMeta, instanceMeta) {
      if (item < accumulatedValue) {
        return accumulatedValue;
      }
    }
  });
};

Dependent keys may refer to @this to observe changes to the object itself, which must be array-like, rather than a property of the object. This is mostly useful for array proxies, to ensure objects are retrieved via objectAtContent. This is how you could sort items by properties defined on an item controller.

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
App.PeopleController = Ember.ArrayController.extend({
  itemController: 'person',

  sortedPeople: Ember.computed.sort('@this.@each.reversedName', function(personA, personB) {
    // `reversedName` isn't defined on Person, but we have access to it via
    // the item controller App.PersonController.  If we'd used
    // `content.@each.reversedName` above, we would be getting the objects
    // directly and not have access to `reversedName`.
    //
    var reversedNameA = get(personA, 'reversedName');
    var reversedNameB = get(personB, 'reversedName');

    return Ember.compare(reversedNameA, reversedNameB);
  })
});

App.PersonController = Ember.ObjectController.extend({
  reversedName: function() {
    return reverse(get(this, 'name'));
  }.property('name')
});

Dependent keys whose values are not arrays are treated as regular dependencies: when they change, the computed property is completely recalculated. It is sometimes useful to have dependent arrays with similar semantics. Dependent keys which end in .[] do not use "one at a time" semantics. When an item is added or removed from such a dependency, the computed property is completely recomputed.

When the computed property is completely recomputed, the accumulatedValue is discarded, it starts with initialValue again, and each item is passed to addedItem in turn.

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
Ember.Object.extend({
  // When `string` is changed, `computed` is completely recomputed.
  string: 'a string',

  // When an item is added to `array`, `addedItem` is called.
  array: [],

  // When an item is added to `anotherArray`, `computed` is completely
  // recomputed.
  anotherArray: [],

  computed: Ember.reduceComputed('string', 'array', 'anotherArray.[]', {
    addedItem: addedItemCallback,
    removedItem: removedItemCallback
  })
});

Parameters:

dependentKeys* [String]
options Object

removeBeforeObserver

(obj, path, target, method)

Parameters:

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

removeListener

(obj, eventName, target, method)

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)

Parameters:

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

required

Denotes a required property for a mixin

runInDebug

(func)
Defined in packages/ember-debug/lib/main.js:178
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(function() {
  Ember.Handlebars.EachView.reopen({
    didInsertElement: function() {
      console.log('I\'m happy');
    }
  });
});

Parameters:

func Function
The function to be executed.

runLoadHooks

(name, object)

Called when an Ember.js package (e.g Ember.Handlebars) 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)

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

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)

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:

obj

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

tryCatchFinally

(tryable, catchable, finalizer, binding) * deprecated

Use JavaScript's native try/catch/finally instead

Provides try/catch/finally functionality, while working around Safari's double finally bug.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
var tryable = function() {
  for (i = 0, l = listeners.length; i < l; i++) {
    listener = listeners[i];
    beforeValues[i] = listener.before(name, time(), payload);
  }

  return callback.call(binding);
};

var catchable = function(e) {
  payload = payload || {};
  payload.exception = e;
};

var finalizer = function() {
  for (i = 0, l = listeners.length; i < l; i++) {
    listener = listeners[i];
    listener.after(name, time(), payload, beforeValues[i]);
  }
};

Ember.tryCatchFinally(tryable, catchable, finalizer);

Parameters:

tryable Function
The function to run the try callback
catchable Function
The function to run the catchable callback
finalizer Function
The function to run the finally callback
binding [Object]
The optional calling object. Defaults to 'this'

Returns:

*
The return value is the that of the finalizer, unless that value is undefined, in which case it is the return value of the tryable.

tryFinally

(tryable, finalizer, binding) * deprecated

Use JavaScript's native try/finally

Provides try/finally functionality, while working around Safari's double finally bug.

1
2
3
4
5
6
7
8
9
10
var tryable = function() {
  someResource.lock();
  runCallback(); // May throw error.
};

var finalizer = function() {
  someResource.unlock();
};

Ember.tryFinally(tryable, finalizer);

Parameters:

tryable Function
The function to run the try callback
finalizer Function
The function to run the finally callback
binding [Object]
The optional calling object. Defaults to 'this'

Returns:

*
The return value is the that of the finalizer, unless that value is undefined, in which case it is the return value of the tryable

tryInvoke

(obj, methodName, args) *

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

(obj, 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:

obj Object
The object to modify.
path String
The property path to set
value Object
The value to set

typeOf

(item) String

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

unknownProperty

(keyName, value)

You can directly access mapped properties by simply requesting them. The unknownProperty handler will generate an EachArray of each item.

Parameters:

keyName String
value *

validatePropertyInjections

(factory) private
Defined in packages/ember-runtime/lib/inject.js:41
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)

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, keyName) 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
keyName 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:

ArrayPolyfills

Array polyfills to support ES5 features in older browsers.

ENV

Hash

Standard environmental variables. You can define these in a global EmberENV variable before loading Ember to control various configuration settings.

For backwards compatibility with earlier versions of Ember the global ENV variable will be used if EmberENV is not defined.

EXTEND_PROTOTYPES

Boolean

Determines whether Ember should enhance some built-in object prototypes to provide a more friendly API. If enabled, a few methods will be added to Function, String, and Array. Object.prototype will not be enhanced, which is the one that causes most trouble for people.

In general we recommend leaving this option set to true since it rarely conflicts with other code. If you need to turn it off however, you can define an EmberENV.EXTEND_PROTOTYPES config to disable it.

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

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

Determines whether Ember logs a full stack trace during deprecation warnings

Default: true

LOG_VERSION

Boolean

Determines whether Ember logs info about version of used libraries

Default: true

SHIM_ES5

Boolean

Determines whether Ember should add ECMAScript 5 Array shims to older browsers.

Default: Ember.EXTEND_PROTOTYPES

STRINGS

Hash

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

Hash

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 static

Default: 'VERSION_STRING_PLACEHOLDER'

Show:

onerror

(error)

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