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

Alias for jQuery

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

var Pagination = Ember.CollectionView.extend({
  tagName: 'ul',
  classNames: ['pagination'],
  init: function() {
    this._super();
    if (!this.get('content')) {
      this.set('content', Ember.A([]));
    }
  }
});

Add an event listener

Makes a method available via an additional name.

1
2
3
4
5
6
7
8

App.Person = Ember.Object.extend({
  name: function() {
    return 'Tomhuda Katzdale';
  },
  moniker: Ember.aliasMethod('name')
});

var goodGuy = App.Person.create()

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

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

// Test for truthiness
Ember.assert('Must pass a valid object', obj);
// Fail unconditionally
Ember.assert('This code path should never be run')

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
21

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.

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.

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.

Checks to see if the methodName exists on the obj.

1
2
3
4

var foo = {bar: Ember.K, baz: null};
Ember.canInvoke(foo, 'bar'); // true
Ember.canInvoke(foo, 'baz'); // false
Ember.canInvoke(foo, 'bat'); // false

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

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

This helper returns a new property descriptor that wraps the passed computed property function. You can use this helper to define properties with mixins or via Ember.defineProperty().

The function you pass will be used to both get and set property values. The function should accept two parameters, key and value. If value is not undefined you should set the value first. In either case return the current value of the property.

Creates a new property that is an alias for another property on an object. Calls to get or set this property behave as though they were called on the original property.

1
2
3
4
5
6
7
8
9
10
11

Person = Ember.Object.extend({
  name: 'Alex Matchneer',
  nomen: Ember.computed.alias('name')
});

alex = Person.create();
alex.get('nomen'); // 'Alex Matchneer'
alex.get('name');  // 'Alex Matchneer'

alex.set('nomen', '@machty');
alex.get('name');  // '@machty'

A computed property that performs a logical and on the original values for the provided dependent properties.

Example

1
2
3
4
5
6
7
8
9

var Hamster = Ember.Object.extend({
  readyForCamp: Ember.computed.and('hasTent', 'hasBackpack')
});
var hamster = Hamster.create();
hamster.get('readyForCamp'); // false
hamster.set('hasTent', true);
hamster.get('readyForCamp'); // false
hamster.set('hasBackpack', true);
hamster.get('readyForCamp'); // true

A computed property that returns the first truthy value from a list of dependent properties.

Example

1
2
3
4
5
6
7

var Hamster = Ember.Object.extend({
  hasClothes: Ember.computed.any('hat', 'shirt')
});
var hamster = Hamster.create();
hamster.get('hasClothes'); // null
hamster.set('shirt', 'Hawaiian Shirt');
hamster.get('hasClothes'); // 'Hawaiian Shirt'

A computed property that converts the provided dependent property into a boolean value.

1
2
3
4
5
6
7
8
9
10
11

var Hamster = Ember.Object.extend({
  hasBananas: Ember.computed.bool('numBananas')
});
var hamster = Hamster.create();
hamster.get('hasBananas'); // false
hamster.set('numBananas', 0);
hamster.get('hasBananas'); // false
hamster.set('numBananas', 1);
hamster.get('hasBananas'); // true
hamster.set('numBananas', null);
hamster.get('hasBananas'); // false

A computed property that acts like a standard getter and setter, but returns the value at the provided defaultPath if the property itself has not been set to a value

Example

1
2
3
4
5
6
7
8

var Hamster = Ember.Object.extend({
  wishList: Ember.computed.defaultTo('favoriteFood')
});
var hamster = Hamster.create({favoriteFood: 'Banana'});
hamster.get('wishList'); // 'Banana'
hamster.set('wishList', 'More Unit Tests');
hamster.get('wishList'); // 'More Unit Tests'
hamster.get('favoriteFood'); // 'Banana'

A computed property that returns true if the value of the dependent property is null, an empty string, empty array, or empty function.

Note: When using Ember.computed.empty to watch an array make sure to use the array.[] syntax so the computed can subscribe to transitions from empty to non-empty states.

Example

1
2
3
4
5
6
7

var ToDoList = Ember.Object.extend({
  done: Ember.computed.empty('todos.[]') // detect array changes
});
var todoList = ToDoList.create({todos: ['Unit Test', 'Documentation', 'Release']});
todoList.get('done'); // false
todoList.get('todos').clear(); // []
todoList.get('done'); // true

A computed property that returns true if the provided dependent property is equal to the given value.

Example

1
2
3
4
5
6
7
8
9

var Hamster = Ember.Object.extend({
  napTime: Ember.computed.equal('state', 'sleepy')
});
var hamster = Hamster.create();
hamster.get('napTime'); // false
hamster.set('state', 'sleepy');
hamster.get('napTime'); // true
hamster.set('state', 'hungry');
hamster.get('napTime'); // false

Filters the array by the callback.

The callback method you provide should have the following signature:

1

function(item);

• item is the current item in the iteration.

Example

1
2
3
4
5
6
7
8
9
10
11
12

App.Hamster = Ember.Object.extend({
  remainingChores: Ember.computed.filter('chores', function(chore) {
    return !chore.done;
  })
});

var hamster = App.Hamster.create({chores: [
  {name: 'cook', done: true},
  {name: 'clean', done: true},
  {name: 'write more unit tests', done: false}
]});
hamster.get('remainingChores'); // [{name: 'write more unit tests', done: false}]

Filters the array by the property and value

Example

1
2
3
4
5
6
7
8
9
10

App.Hamster = Ember.Object.extend({
  remainingChores: Ember.computed.filterBy('chores', 'done', false)
});

var hamster = App.Hamster.create({chores: [
  {name: 'cook', done: true},
  {name: 'clean', done: true},
  {name: 'write more unit tests', done: false}
]});
hamster.get('remainingChores'); // [{name: 'write more unit tests', done: false}]

A computed property that returns true if the provied dependent property is greater than the provided value.

Example

1
2
3
4
5
6
7
8
9

var Hamster = Ember.Object.extend({
  hasTooManyBananas: Ember.computed.gt('numBananas', 10)
});
var hamster = Hamster.create();
hamster.get('hasTooManyBananas'); // false
hamster.set('numBananas', 3);
hamster.get('hasTooManyBananas'); // false
hamster.set('numBananas', 11);
hamster.get('hasTooManyBananas'); // true

A computed property that returns true if the provided dependent property is greater than or equal to the provided value.

Example

1
2
3
4
5
6
7
8
9

var Hamster = Ember.Object.extend({
  hasTooManyBananas: Ember.computed.gte('numBananas', 10)
});
var hamster = Hamster.create();
hamster.get('hasTooManyBananas'); // false
hamster.set('numBananas', 3);
hamster.get('hasTooManyBananas'); // false
hamster.set('numBananas', 10);
hamster.get('hasTooManyBananas'); // true

A computed property which returns a new array with all the duplicated elements from two or more dependeny arrays.

Example

1
2
3
4
5
6
7

var obj = Ember.Object.createWithMixins({
  adaFriends: ['Charles Babbage', 'John Hobhouse', 'William King', 'Mary Somerville'],
  charlesFriends: ['William King', 'Mary Somerville', 'Ada Lovelace', 'George Peacock'],
  friendsInCommon: Ember.computed.intersect('adaFriends', 'charlesFriends')
});

obj.get('friendsInCommon'); // ['William King', 'Mary Somerville']

A computed property that returns true if the provided dependent property is less than the provided value.

Example

1
2
3
4
5
6
7
8
9

var Hamster = Ember.Object.extend({
  needsMoreBananas: Ember.computed.lt('numBananas', 3)
});
var hamster = Hamster.create();
hamster.get('needsMoreBananas'); // true
hamster.set('numBananas', 3);
hamster.get('needsMoreBananas'); // false
hamster.set('numBananas', 2);
hamster.get('needsMoreBananas'); // true

A computed property that returns true if the provided dependent property is less than or equal to the provided value.

Example

1
2
3
4
5
6
7
8
9

var Hamster = Ember.Object.extend({
  needsMoreBananas: Ember.computed.lte('numBananas', 3)
});
var hamster = Hamster.create();
hamster.get('needsMoreBananas'); // true
hamster.set('numBananas', 5);
hamster.get('needsMoreBananas'); // false
hamster.set('numBananas', 3);
hamster.get('needsMoreBananas'); // true

Returns an array mapped via the callback

The callback method you provide should have the following signature:

1

function(item);

• item is the current item in the iteration.

Example

1
2
3
4
5
6
7
8

App.Hamster = Ember.Object.extend({
  excitingChores: Ember.computed.map('chores', function(chore) {
    return chore.toUpperCase() + '!';
  })
});

var hamster = App.Hamster.create({chores: ['cook', 'clean', 'write more unit tests']});
hamster.get('excitingChores'); // ['COOK!', 'CLEAN!', 'WRITE MORE UNIT TESTS!']

Returns an array mapped to the specified key.

Example

1
2
3
4
5
6
7
8
9
10

App.Person = Ember.Object.extend({
  childAges: Ember.computed.mapBy('children', 'age')
});

var lordByron = App.Person.create({children: []});
lordByron.get('childAges'); // []
lordByron.get('children').pushObject({name: 'Augusta Ada Byron', age: 7});
lordByron.get('childAges'); // [7]
lordByron.get('children').pushObjects([{name: 'Allegra Byron', age: 5}, {name: 'Elizabeth Medora Leigh', age: 8}]);
lordByron.get('childAges'); // [7, 5, 8]

A computed property which matches the original value for the dependent property against a given RegExp, returning true if they values matches the RegExp and false if it does not.

Example

1
2
3
4
5
6
7
8
9

var User = Ember.Object.extend({
  hasValidEmail: Ember.computed.match('email', /^.+@.+\..+$/)
});
var user = User.create({loggedIn: false});
user.get('hasValidEmail'); // false
user.set('email', '');
user.get('hasValidEmail'); // false
user.set('email', 'ember_hamster@example.com');
user.get('hasValidEmail'); // true

A computed property that calculates the maximum value in the dependent array. This will return -Infinity when the dependent array is empty.

Example

1
2
3
4
5
6
7
8
9
10
11

App.Person = Ember.Object.extend({
  childAges: Ember.computed.mapBy('children', 'age'),
  maxChildAge: Ember.computed.max('childAges')
});

var lordByron = App.Person.create({children: []});
lordByron.get('maxChildAge'); // -Infinity
lordByron.get('children').pushObject({name: 'Augusta Ada Byron', age: 7});
lordByron.get('maxChildAge'); // 7
lordByron.get('children').pushObjects([{name: 'Allegra Byron', age: 5}, {name: 'Elizabeth Medora Leigh', age: 8}]);
lordByron.get('maxChildAge'); // 8

A computed property that calculates the minimum value in the dependent array. This will return Infinity when the dependent array is empty.

Example

1
2
3
4
5
6
7
8
9
10
11

App.Person = Ember.Object.extend({
  childAges: Ember.computed.mapBy('children', 'age'),
  minChildAge: Ember.computed.min('childAges')
});

var lordByron = App.Person.create({children: []});
lordByron.get('minChildAge'); // Infinity
lordByron.get('children').pushObject({name: 'Augusta Ada Byron', age: 7});
lordByron.get('minChildAge'); // 7
lordByron.get('children').pushObjects([{name: 'Allegra Byron', age: 5}, {name: 'Elizabeth Medora Leigh', age: 8}]);
lordByron.get('minChildAge'); // 5

A computed property that returns true if the value of the dependent property is null or undefined. This avoids errors from JSLint complaining about use of ==, which can be technically confusing.

Example

1
2
3
4
5
6
7
8
9

var Hamster = Ember.Object.extend({
  isHungry: Ember.computed.none('food')
});
var hamster = Hamster.create();
hamster.get('isHungry'); // true
hamster.set('food', 'Banana');
hamster.get('isHungry'); // false
hamster.set('food', null);
hamster.get('isHungry'); // true

A computed property that returns the inverse boolean value of the original value for the dependent property.

Example

1
2
3
4
5
6
7

var User = Ember.Object.extend({
  isAnonymous: Ember.computed.not('loggedIn')
});
var user = User.create({loggedIn: false});
user.get('isAnonymous'); // true
user.set('loggedIn', true);
user.get('isAnonymous'); // false

A computed property that returns true if the value of the dependent property is NOT null, an empty string, empty array, or empty function.

Example

1
2
3
4
5
6
7

var Hamster = Ember.Object.extend({
  hasStuff: Ember.computed.notEmpty('backpack')
});
var hamster = Hamster.create({backpack: ['Food', 'Sleeping Bag', 'Tent']});
hamster.get('hasStuff'); // true
hamster.get('backpack').clear(); // []
hamster.get('hasStuff'); // false

Where computed.alias aliases get and set, and allows for bidirectional data flow, computed.oneWay only provides an aliased get. The set will not mutate the upstream property, rather causes the current property to become the value set. This causes the downstream property to permentantly diverge from the upstream property.

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

User = Ember.Object.extend({
  firstName: null,
  lastName: null,
  nickName: Ember.computed.oneWay('firstName')
});

user = User.create({
  firstName: 'Teddy',
  lastName:  'Zeenny'
});

user.get('nickName');
# 'Teddy'

user.set('nickName', 'TeddyBear');
# 'TeddyBear'

user.get('firstName');
# 'Teddy'

A computed property which performs a logical or on the original values for the provided dependent properties.

Example

1
2
3
4
5
6
7

var Hamster = Ember.Object.extend({
  readyForRain: Ember.computed.or('hasJacket', 'hasUmbrella')
});
var hamster = Hamster.create();
hamster.get('readyForRain'); // false
hamster.set('hasJacket', true);
hamster.get('readyForRain'); // true

A computed property which returns a new array with all the properties from the first dependent array that are not in the second dependent array.

Example

1
2
3
4
5
6
7
8
9
10

App.Hamster = Ember.Object.extend({
  likes: ['banana', 'grape', 'kale'],
  wants: Ember.computed.setDiff('likes', 'fruits')
});

var hamster = App.Hamster.create({fruits: [
  'grape',
  'kale',
]});
hamster.get('wants'); // ['banana']

A computed property which returns a new array with all the properties from the first dependent array sorted based on a property or sort function.

The callback method you provide should have the following signature:

1

function(itemA, itemB);

• itemA the first item to compare.
• itemB the second item to compare.

This function should return -1 when itemA should come before itemB. It should return 1 when itemA should come after itemB. If the itemA and itemB are equal this function should return 0.

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

var ToDoList = Ember.Object.extend({
  todosSorting: ['name'],
  sortedTodos: Ember.computed.sort('todos', 'todosSorting'),
  priorityTodos: Ember.computed.sort('todos', function(a, b){
    if (a.priority > b.priority) {
      return 1;
    } else if (a.priority < b.priority) {
      return -1;
    }
    return 0;
  }),
});
var todoList = ToDoList.create({todos: [
  {name: 'Unit Test', priority: 2},
  {name: 'Documentation', priority: 3},
  {name: 'Release', priority: 1}
]});

todoList.get('sortedTodos'); // [{name:'Documentation', priority:3}, {name:'Release', priority:1}, {name:'Unit Test', priority:2}]
todoList.get('priorityTodos'); // [{name:'Release', priority:1}, {name:'Unit Test', priority:2}, {name:'Documentation', priority:3}]

Alias for Ember.computed.uniq.

A computed property which returns a new array with all the unique elements from one or more dependent arrays.

Example

1
2
3
4
5
6
7
8
9
10
11

App.Hamster = Ember.Object.extend({
  uniqueFruits: Ember.computed.uniq('fruits')
});

var hamster = App.Hamster.create({fruits: [
  'banana',
  'grape',
  'kale',
  'banana'
]});
hamster.get('uniqueFruits'); // ['banana', 'grape', 'kale']

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 clone() method, then this function will simply call that method and return the result.

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

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!");

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.

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

Tears down the meta on an object so that it can be garbage collected. Multiple calls will have no effect.

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.

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.

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

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

Verifies that a value is null or an empty string, empty array, or empty function.

Constrains the rules on Ember.isNone by returning false for empty string and empty arrays.

1
2
3
4
5
6
7

Ember.isEmpty();                // true
Ember.isEmpty(null);            // true
Ember.isEmpty(undefined);       // true
Ember.isEmpty('');              // true
Ember.isEmpty([]);              // true
Ember.isEmpty('Adam Hawkins');  // false
Ember.isEmpty([0,1,2]);         // false

Test that a feature is enabled. Parsed by Ember's build tools to leave experimental features out of beta/stable builds.

You can define the following configuration options:

• ENV.ENABLE_ALL_FEATURES - force all features to be enabled.
• ENV.ENABLE_OPTIONAL_FEATURES - enable any features that have not been explicitly enabled/disabled.

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

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

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.

Forces the passed object to be part of an array. If the object is already an array or array-like, returns the object. Otherwise adds the object to an array. If obj is null or undefined, returns an empty array.

1
2
3
4
5
6
7
8

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

Merge the contents of two objects together into the first object.

1
2
3

Ember.merge({first: 'Tom'}, {last: 'Dale'}); // {first: 'Tom', last: 'Dale'}
var a = {first: 'Yehuda'}, b = {last: 'Katz'};
Ember.merge(a, b); // a == {first: 'Yehuda', last: 'Katz'}, b == {last: 'Katz'}

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.

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

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

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: javascript Ember.onLoad('Ember.Handlebars' function(hbars){ hbars.registerHelper(...); });

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.

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.

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.call(null, 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'),
        reversedNameB = get(personB, 'reversedName');

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

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

Remove an event listener

Arguments should match those passed to Ember.addListener.

Denotes a required property for a mixin

Called when an Ember.js package (e.g Ember.Handlebars) has finished loading. Triggers any callbacks registered for this event.

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.

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.

If you plan to run on IE8 and older browsers then you should use this method anytime you want to set 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 set properties if the property might not be defined on the object and you want to respect the setUnknownProperty handler. Otherwise you can ignore this method.

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

anObject.setProperties({
  firstName: "Stanley",
  lastName: "Stuart",
  age: "21"
})

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

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

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

1
2
3
4
5
6
7
8

var tryable = function() {
  someResource.lock();
  runCallback(); // May throw error.
};
var finalizer = function() {
  someResource.unlock();
};
Ember.tryFinally(tryable, finalizer);

Checks to see if the methodName exists on the obj, and if it does, invokes it with the arguments passed.

1
2
3
4

var d = new Date('03/15/2013');
Ember.tryInvoke(d, 'getTime'); // 1363320000000
Ember.tryInvoke(d, 'setFullYear', [2014]); // 1394856000000
Ember.tryInvoke(d, 'noSuchMethod', [2014]); // undefined

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.

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

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

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(Ember.Object.extend());  // 'class'
Ember.typeOf(Ember.Object.create());  // 'instance'
Ember.typeOf(new Error('teamocil'));  // 'error'

// "normal" JavaScript object
Ember.typeOf({a: 'b'});              // 'object'

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