API Docs for: v2.11.0-beta.7
Show:

Ember Class

Module: ember-metal
Parent Module: ember

This namespace contains all Ember methods and functions. Future versions of Ember may overwrite this namespace and therefore, you should avoid adding any new properties.

At the heart of Ember is Ember-Runtime, a set of core functions that provide cross-platform compatibility and object property observing. Ember-Runtime is small and performance-focused so you can use it alongside other cross-platform libraries such as jQuery. For more details, see Ember-Runtime.

Methods

$

() public

Provided by the ember module.

Defined in packages/ember/lib/index.js:540

Alias for jQuery

_addBeforeObserver

(
  • obj
  • path
  • target
  • [method]
)
deprecated private

Parameters:

_immediateObserver

(
  • propertyNames
  • func
)
deprecated private

Defined in packages/ember-metal/lib/mixin.js:772

Deprecated: Use `Ember.observer` instead.

Specify a method that observes property changes.

Ember.Object.extend({
  valueObserver: Ember.immediateObserver('value', function() {
    // Executes whenever the "value" property changes
  })
});

In the future, Ember.observer may become asynchronous. In this event, Ember.immediateObserver will maintain the synchronous behavior.

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

Parameters:

Returns:

func

_warnIfUsingStrippedFeatureFlags

() Void private

Provided by the ember-debug module.

Defined in packages/ember-debug/lib/index.js:165

Will call Ember.warn() if ENABLE_OPTIONAL_FEATURES or any specific FEATURES flag is truthy.

This method is called automatically in debug canary builds.

Returns:

Void:

A

() Ember.NativeArray public

Creates an Ember.NativeArray from an Array like object. Does not modify the original object. Ember.A is not needed if EmberENV.EXTEND_PROTOTYPES is true (the default value). However, it is recommended that you use Ember.A when creating addons for ember or when you can not guarantee that EmberENV.EXTEND_PROTOTYPES will be true.

Example

export default Ember.Component.extend({
  tagName: 'ul',
  classNames: ['pagination'],

  init() {
    this._super(...arguments);

    if (!this.get('content')) {
      this.set('content', Ember.A());
    }
  }
});

Returns:

addListener

(
  • obj
  • eventName
  • target
  • method
  • once
)
public

Add an event listener

Parameters:

  • obj Object
  • 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:

aliasMethod

(
  • methodName
)
public

Makes a method available via an additional name.

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

let goodGuy = App.Person.create();

goodGuy.name();    // 'Tomhuda Katzdale'
goodGuy.moniker(); // 'Tomhuda Katzdale'

Parameters:

  • methodName String

    name of the method to alias

assert

(
  • desc
  • test
)
public

Provided by the ember-debug module.

Defined in packages/ember-debug/lib/index.js:33

Available since 1.0.0

Define an assertion that will throw an exception if the condition is not met.

  • In a production build, this method is defined as an empty function (NOP). Uses of this method in Ember itself are stripped from the ember.prod.js build.
// Test for truthiness
Ember.assert('Must pass a valid object', obj);

// Fail unconditionally
Ember.assert('This code path should never be run');

Parameters:

  • desc String

    A description of the assertion. This will become the text of the Error thrown if the assertion fails.

  • test Boolean

    Must be truthy for the assertion to pass. If falsy, an exception will be thrown.

assign

(
  • original
  • args
)
Object public

Provided by the ember module.

Defined in packages/ember-utils/lib/assign.js:1

Copy properties from a source object to a target object.

var a = { first: 'Yehuda' };
var b = { last: 'Katz' };
var c = { company: 'Tilde Inc.' };
Ember.assign(a, b, c); // a === { first: 'Yehuda', last: 'Katz', company: 'Tilde Inc.' }, b === { last: 'Katz' }, c === { company: 'Tilde Inc.' }

Parameters:

  • original Object

    The object to assign into

  • args Object multiple

    The objects to copy properties from

Returns:

Object:

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.

Parameters:

Returns:

func

beginPropertyChanges

() private chainable

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

Provided by the ember module.

Defined in packages/ember-utils/lib/invoke.js:3

Checks to see if the methodName exists on the obj.

let foo = { bar: function() { return 'bar'; }, baz: null };

Ember.canInvoke(foo, 'bar'); // true
Ember.canInvoke(foo, 'baz'); // false
Ember.canInvoke(foo, 'bat'); // false

Parameters:

  • obj Object

    The object to check for the method

  • methodName String

    The method name to check for

Returns:

Boolean:

changeProperties

(
  • callback
  • [binding]
)
private

Make a series of property changes together in an exception-safe way.

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

Parameters:

  • callback Function
  • [binding] Object optional

compare

(
  • v
  • w
)
Number public

Provided by the ember module.

Defined in packages/ember-runtime/lib/compare.js:40

Compares two javascript values and returns:

  • -1 if the first is smaller than the second,
  • 0 if both are equal,
  • 1 if the first is greater than the second.
Ember.compare('hello', 'hello');  // 0
Ember.compare('abc', 'dfg');      // -1
Ember.compare(2, 1);              // 1

If the types of the two objects are different precedence occurs in the following order, with types earlier in the list considered < types later in the list:

  • undefined
  • null
  • boolean
  • number
  • string
  • array
  • object
  • instance
  • function
  • class
  • date
Ember.compare('hello', 50);       // 1
Ember.compare(50, 'hello');       // -1

Parameters:

  • v Object

    First value to compare

  • w Object

    Second value to compare

Returns:

Number:

-1 if v < w, 0 if v = w and 1 if v > w.

controllerFor

() private

Finds a controller instance.

copy

(
  • obj
  • [deep=false]
)
Object public

Provided by the ember module.

Defined in packages/ember-runtime/lib/copy.js:66

Creates a shallow copy of the passed object. A deep copy of the object is returned if the optional deep argument is true.

If the passed object implements the Ember.Copyable interface, then this function will delegate to the object's copy() method and return the result. See Ember.Copyable for further details.

For primitive values (which are immutable in JavaScript), the passed object is simply returned.

Parameters:

  • obj Object

    The object to clone

  • [deep=false] Boolean optional

    If true, a deep copy of the object is made.

Returns:

Object:

The copied object

createInjectionHelper

(
  • type
  • validator
)
private

Provided by the ember module.

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

Provided by the ember-debug module.

Defined in packages/ember-debug/lib/index.js:61

Display a debug notice.

  • In a production build, this method is defined as an empty function (NOP). Uses of this method in Ember itself are stripped from the ember.prod.js build.
Ember.debug('I\'m a debug notice!');

Parameters:

  • message String

    A debug message to display.

defineProperty

(
  • obj
  • keyName
  • [desc]
  • [data]
)
private

NOTE: This is a low-level method used by other parts of the API. You almost never want to call this method directly. Instead you should use Ember.mixin() to define new properties.

Defines a property on an object. This method works much like the ES5 Object.defineProperty() method except that it can also accept computed properties and other special descriptors.

Normally this method takes only three parameters. However if you pass an instance of Descriptor as the third param then you can pass an optional value as the fourth parameter. This is often more efficient than creating new descriptor hashes for each property.

Examples

// ES5 compatible mode
Ember.defineProperty(contact, 'firstName', {
  writable: true,
  configurable: false,
  enumerable: true,
  value: 'Charles'
});

// define a simple property
Ember.defineProperty(contact, 'lastName', undefined, 'Jolley');

// define a computed property
Ember.defineProperty(contact, 'fullName', Ember.computed('firstName', 'lastName', function() {
  return this.firstName+' '+this.lastName;
}));

Parameters:

  • obj Object

    the object to define this property on. This may be a prototype.

  • keyName String

    the name of the property

  • [desc] Descriptor optional

    an instance of Descriptor (typically a computed property) or an ES5 descriptor. You must provide this or data but not both.

  • [data] optional

    something other than a descriptor, that will become the explicit value of this property.

deprecate

(
  • message
  • test
  • options
)
public

Provided by the ember-debug module.

Defined in packages/ember-debug/lib/deprecate.js:97

Available since 1.0.0

Display a deprecation warning with the provided message and a stack trace (Chrome and Firefox only).

  • In a production build, this method is defined as an empty function (NOP). Uses of this method in Ember itself are stripped from the ember.prod.js build.

Parameters:

  • message String

    A description of the deprecation.

  • test Boolean

    A boolean. If falsy, the deprecation will be displayed.

  • options Object
    • id String

      A unique id for this deprecation. The id can be used by Ember debugging tools to change the behavior (raise, log or silence) for that specific deprecation. The id should be namespaced by dots, e.g. "view.helper.select".

    • until String

      The version of Ember when this deprecation warning will be removed.

    • [url] String optional

      An optional url to the transition guide on the emberjs.com website.

deprecateFunc

(
  • message
  • [options]
  • func
)
Function private

Provided by the ember-debug module.

Defined in packages/ember-debug/lib/index.js:92

Alias an old, deprecated method with its new counterpart.

Display a deprecation warning with the provided message and a stack trace (Chrome and Firefox only) when the assigned method is called.

  • In a production build, this method is defined as an empty function (NOP).
Ember.oldMethod = Ember.deprecateFunc('Please use the new, updated method', Ember.newMethod);

Parameters:

  • message String

    A description of the deprecation.

  • [options] Object optional

    The options object for Ember.deprecate.

  • func Function

    The new function called to replace its deprecated counterpart.

Returns:

Function:

A new function that wraps the original function with a deprecation warning

destroy

(
  • obj
)
Void private

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

Parameters:

  • obj Object

    the object to destroy

Returns:

Void:

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

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

Provided by the ember-routing module.

Defined in packages/ember-routing/lib/system/generate_controller.js:34

Available since 1.3.0

Generates and instantiates a controller extending from controller:basic if present, or Ember.Controller if not.

generateControllerFactory

() private

Generates a controller factory

generateGuid

(
  • [obj]
  • [prefix]
)
String private

Provided by the ember module.

Defined in packages/ember-utils/lib/guid.js:73

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 optional

    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 optional

    Prefix to place in front of the guid. Useful when you want to separate the guid into separate namespaces.

Returns:

String:

the guid

get

(
  • obj
  • keyName
)
Object public

Gets the value of a property on an object. If the property is computed, the function will be invoked. If the property is not defined but the object implements the unknownProperty method then that will be invoked.

Ember.get(obj, "name");

If you plan to run on IE8 and older browsers then you should use this method anytime you want to retrieve a property on an object that you don't know for sure is private. (Properties beginning with an underscore '_' are considered private.)

On all newer browsers, you only need to use this method to retrieve properties if the property might not be defined on the object and you want to respect the unknownProperty handler. Otherwise you can ignore this method.

Note that if the object itself is undefined, this method will throw an error.

Parameters:

  • obj Object

    The object to retrieve from.

  • keyName String

    The property key to retrieve

Returns:

Object:

the property value or null.

getEngineParent

(
  • engine
)
EngineInstance public

getEngineParent retrieves an engine instance's parent instance.

Parameters:

  • engine EngineInstance

    An engine instance.

Returns:

EngineInstance:

The parent engine instance.

getOwner

(
  • object
)
Object public

Provided by the ember-runtime module.

Defined in packages/ember-utils/lib/owner.js:10

Available since 2.3.0

Framework objects in an Ember application (components, services, routes, etc.) are created via a factory and dependency injection system. Each of these objects is the responsibility of an "owner", which handled its instantiation and manages its lifetime.

getOwner fetches the owner object responsible for an instance. This can be used to lookup or resolve other class instances, or register new factories into the owner.

For example, this component dynamically looks up a service based on the audioType passed as an attribute:

// app/components/play-audio.js
import Ember from 'ember';

// Usage:
//
//   {{play-audio audioType=model.audioType audioFile=model.file}}
//
export default Ember.Component.extend({
  audioService: Ember.computed('audioType', function() {
    let owner = Ember.getOwner(this);
    return owner.lookup(service:${this.get('audioType')});
  }),
  click() {
    let player = this.get('audioService');
    player.play(this.get('audioFile'));
  }
});

Parameters:

  • object Object

    An object with an owner.

Returns:

Object:

An owner object.

getProperties

(
  • obj
  • list
)
Object public

Provided by the ember module.

Defined in packages/ember-metal/lib/get_properties.js:3

To get multiple properties at once, call Ember.getProperties with an object followed by a list of strings or an array:

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

is equivalent to:

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

Parameters:

  • obj Object
  • list String... | Array

    of keys to get

Returns:

Object:

getWithDefault

(
  • obj
  • keyName
  • defaultValue
)
Object public

Retrieves the value of a property from an Object, or a default value in the case that the property returns undefined.

Ember.getWithDefault(person, 'lastName', 'Doe');

Parameters:

  • obj Object

    The object to retrieve from.

  • keyName String

    The name of the property to retrieve

  • defaultValue Object

    The value to return if the property value is undefined

Returns:

Object:

The property value or the defaultValue.

guidFor

(
  • obj
)
String public

Provided by the ember module.

Defined in packages/ember-utils/lib/guid.js:111

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:

info

() private

Provided by the ember-debug module.

Defined in packages/ember-debug/lib/index.js:79

Display an info notice.

  • In a production build, this method is defined as an empty function (NOP). Uses of this method in Ember itself are stripped from the ember.prod.js build.

inspect

(
  • obj
)
String private

Provided by the ember module.

Defined in packages/ember-utils/lib/inspect.js:3

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

Provided by the ember module.

Defined in packages/ember-runtime/lib/utils.js:21

Returns true if the passed object is an array or Array-like.

Objects are considered Array-like if any of the following are true:

  • the object is a native Array
  • the object has an objectAt property
  • the object is an Object, and has a length property

Unlike Ember.typeOf this method returns true even if the passed object is not formally an array but appears to be array-like (i.e. implements Ember.Array)

Ember.isArray();                                          // false
Ember.isArray([]);                                        // true
Ember.isArray(Ember.ArrayProxy.create({ content: [] }));  // true

Parameters:

  • obj Object

    The object to test

Returns:

Boolean:

true if the passed object is an array or Array-like

isBlank

(
  • obj
)
Boolean public

Provided by the ember module.

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.

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

Provided by the ember module.

Defined in packages/ember-metal/lib/is_empty.js:4

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

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

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

Parameters:

  • obj Object

    Value to test

Returns:

Boolean:

isEqual

(
  • a
  • b
)
Boolean public

Provided by the ember module.

Defined in packages/ember-runtime/lib/is-equal.js:1

Compares two objects, returning true if they are equal.

Ember.isEqual('hello', 'hello');                   // true
Ember.isEqual(1, 2);                               // false

isEqual is a more specific comparison than a triple equal comparison. It will call the isEqual instance method on the objects being compared, allowing finer control over when objects should be considered equal to each other.

let Person = Ember.Object.extend({
  isEqual(other) { return this.ssn == other.ssn; }
});

let personA = Person.create({name: 'Muhammad Ali', ssn: '123-45-6789'});
let personB = Person.create({name: 'Cassius Clay', ssn: '123-45-6789'});

Ember.isEqual(personA, personB); // true

Due to the expense of array comparisons, collections will never be equal to each other even if each of their items are equal to each other.

Ember.isEqual([4, 2], [4, 2]);                     // false

Parameters:

  • a Object

    first object to compare

  • b Object

    second object to compare

Returns:

Boolean:

isNone

(
  • obj
)
Boolean public

Provided by the ember module.

Defined in packages/ember-metal/lib/is_none.js:1

Returns true if the passed value is null or undefined. This avoids errors from JSLint complaining about use of ==, which can be technically confusing.

Ember.isNone();              // true
Ember.isNone(null);          // true
Ember.isNone(undefined);     // true
Ember.isNone('');            // false
Ember.isNone([]);            // false
Ember.isNone(function() {}); // false

Parameters:

  • obj Object

    Value to test

Returns:

Boolean:

isPresent

(
  • obj
)
Boolean public

Provided by the ember module.

Defined in packages/ember-metal/lib/is_present.js:3

Available since 1.8.0

A value is present if it not isBlank.

Ember.isPresent();                // false
Ember.isPresent(null);            // false
Ember.isPresent(undefined);       // false
Ember.isPresent('');              // false
Ember.isPresent('  ');            // false
Ember.isPresent('\n\t');          // false
Ember.isPresent([]);              // false
Ember.isPresent({ length: 0 })    // false
Ember.isPresent(false);           // true
Ember.isPresent(true);            // true
Ember.isPresent('string');        // true
Ember.isPresent(0);               // true
Ember.isPresent(function() {})    // true
Ember.isPresent({});              // true
Ember.isPresent(false);           // true
Ember.isPresent('\n\t Hello');    // true
Ember.isPresent([1,2,3]);         // true

Parameters:

  • obj Object

    Value to test

Returns:

Boolean:

K

() Object public

Provided by the ember module.

Defined in packages/ember/lib/index.js:208

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

Returns:

Object:

listenersFor

(
  • obj
  • eventName
)
private

Parameters:

makeArray

(
  • obj
)
Array private

Provided by the ember module.

Defined in packages/ember-utils/lib/make-array.js:1

Forces the passed object to be part of an array. If the object is already an array, it will return the object. Otherwise, it will add the object to an array. If obj is null or undefined, it will return an empty array.

Ember.makeArray();            // []
Ember.makeArray(null);        // []
Ember.makeArray(undefined);   // []
Ember.makeArray('lindsay');   // ['lindsay']
Ember.makeArray([1, 2, 42]);  // [1, 2, 42]

let controller = Ember.ArrayProxy.create({ content: [] });

Ember.makeArray(controller) === controller;  // true

Parameters:

  • obj Object

    the object

Returns:

Array:

merge

(
  • original
  • updates
)
Object public

Provided by the ember module.

Defined in packages/ember-metal/lib/merge.js:1

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

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

Parameters:

  • original Object

    The object to merge into

  • updates Object

    The object to copy properties from

Returns:

Object:

meta

(
  • obj
  • [writable=true]
)
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=true] Boolean optional

    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 Object
  • mixins Object multiple

Returns:

obj

observer

(
  • propertyNames
  • func
)
public

Specify a method that observes property changes.

Ember.Object.extend({
  valueObserver: Ember.observer('value', function() {
    // Executes whenever the "value" property changes
  })
});

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

Parameters:

Returns:

func

on

(
  • eventNames
  • func
)
public

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

let Job = Ember.Object.extend({
  logCompleted: Ember.on('completed', function() {
    console.log('Job completed!');
  })
});

let job = Job.create();

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

Parameters:

Returns:

func

onLoad

(
  • name
  • callback
)
private

Detects when a specific package of Ember (e.g. 'Ember.Application') has fully loaded and is available for extension.

The provided callback will be called with the name passed resolved from a string into the object:

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

Parameters:

propertyDidChange

(
  • obj
  • keyName
  • meta
)
Void private

This function is called just after an object property has changed. It will notify any observers and clear caches among other things.

Normally you will not need to call this method directly but if for some reason you can't directly watch a property you can invoke this method manually along with Ember.propertyWillChange() which you should call just before the property value changes.

Parameters:

  • obj Object

    The object with the property that will change

  • keyName String

    The property key (or path) that will change.

  • meta Meta

    The objects meta.

Returns:

Void:

propertyWillChange

(
  • obj
  • keyName
)
Void private

This function is called just before an object property is about to change. It will notify any before observers and prepare caches among other things.

Normally you will not need to call this method directly but if for some reason you can't directly watch a property you can invoke this method manually along with Ember.propertyDidChange() which you should call just after the property value changes.

Parameters:

  • obj Object

    The object with the property that will change

  • keyName String

    The property key (or path) that will change.

Returns:

Void:

removeBeforeObserver

(
  • obj
  • path
  • target
  • [method]
)
deprecated private

Parameters:

removeListener

(
  • obj
  • eventName
  • target
  • method
)
public

Remove an event listener

Arguments should match those passed to Ember.addListener.

Parameters:

  • obj Object
  • 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:

required

() private

Denotes a required property for a mixin

runInDebug

(
  • func
)
public

Provided by the ember-debug module.

Defined in packages/ember-debug/lib/index.js:128

Available since 1.5.0

Run a function meant for debugging.

  • In a production build, this method is defined as an empty function (NOP). Uses of this method in Ember itself are stripped from the ember.prod.js build.
Ember.runInDebug(() => {
  Ember.Component.reopen({
    didInsertElement() {
      console.log("I'm happy");
    }
  });
});

Parameters:

  • func Function

    The function to be executed.

runLoadHooks

(
  • name
  • object
)
private

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

Parameters:

  • name String

    name of hook

  • object Object

    object to pass to callbacks

sendEvent

(
  • obj
  • eventName
  • params
  • actions
)
public

Send an event. The execution of suspended listeners is skipped, and once listeners are removed. A listener without a target is executed on the passed object. If an array of actions is not passed, the actions stored on the passed object are invoked.

Parameters:

  • obj Object
  • eventName String
  • params Array

    Optional parameters for each listener.

  • actions Array

    Optional array of actions (listeners).

Returns:

true

set

(
  • obj
  • keyName
  • value
)
Object public

Sets the value of a property on an object, respecting computed properties and notifying observers and other listeners of the change. If the property is not defined but the object implements the setUnknownProperty method then that will be invoked as well.

Ember.set(obj, "name", value);

Parameters:

  • obj Object

    The object to modify.

  • keyName String

    The property key to set

  • value Object

    The value to set

Returns:

Object:

the passed value.

setEngineParent

(
  • engine
  • parent
)
private

setEngineParent sets an engine instance's parent instance.

Parameters:

  • engine EngineInstance

    An engine instance.

  • parent EngineInstance

    The parent engine instance.

setOwner

(
  • object
  • object
)
public

Provided by the ember-runtime module.

Defined in packages/ember-utils/lib/owner.js:54

Available since 2.3.0

setOwner forces a new owner on a given object instance. This is primarily useful in some testing cases.

Parameters:

  • object Object

    An object instance.

  • object Object

    The new owner object of the object instance.

setProperties

(
  • obj
  • properties
)
public

Set a list of properties on an object. These properties are set inside a single beginPropertyChanges and endPropertyChanges batch, so observers will be buffered.

let anObject = Ember.Object.create();

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

Parameters:

  • obj Object
  • 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 Object
  • 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 Object
  • 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

Provided by the ember module.

Defined in packages/ember-utils/lib/invoke.js:25

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

let d = new Date('03/15/2013');

Ember.tryInvoke(d, 'getTime');              // 1363320000000
Ember.tryInvoke(d, 'setFullYear', [2014]);  // 1394856000000
Ember.tryInvoke(d, 'noSuchMethod', [2014]); // undefined

Parameters:

  • obj Object

    The object to check for the method

  • methodName String

    The method name to check for

  • [args] Array optional

    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

Provided by the ember module.

Defined in packages/ember-runtime/lib/utils.js:56

Returns a consistent type for the passed object.

Use this instead of the built-in typeof to get the type of an item. It will return the same result across all browsers and includes a bit more detail. Here is what will be returned:

| Return Value  | Meaning                                              |
|---------------|------------------------------------------------------|
| 'string'      | String primitive or String object.                   |
| 'number'      | Number primitive or Number object.                   |
| 'boolean'     | Boolean primitive or Boolean object.                 |
| 'null'        | Null value                                           |
| 'undefined'   | Undefined value                                      |
| 'function'    | A function                                           |
| 'array'       | An instance of Array                                 |
| 'regexp'      | An instance of RegExp                                |
| 'date'        | An instance of Date                                  |
| 'filelist'    | An instance of FileList                              |
| 'class'       | An Ember class (created using Ember.Object.extend()) |
| 'instance'    | An Ember object instance                             |
| 'error'       | An instance of the Error object                      |
| 'object'      | A JavaScript object not inheriting from Ember.Object |

Examples:

Ember.typeOf();                       // 'undefined'
Ember.typeOf(null);                   // 'null'
Ember.typeOf(undefined);              // 'undefined'
Ember.typeOf('michael');              // 'string'
Ember.typeOf(new String('michael'));  // 'string'
Ember.typeOf(101);                    // 'number'
Ember.typeOf(new Number(101));        // 'number'
Ember.typeOf(true);                   // 'boolean'
Ember.typeOf(new Boolean(true));      // 'boolean'
Ember.typeOf(Ember.makeArray);        // 'function'
Ember.typeOf([1, 2, 90]);             // 'array'
Ember.typeOf(/abc/);                  // 'regexp'
Ember.typeOf(new Date());             // 'date'
Ember.typeOf(event.target.files);     // 'filelist'
Ember.typeOf(Ember.Object.extend());  // 'class'
Ember.typeOf(Ember.Object.create());  // 'instance'
Ember.typeOf(new Error('teamocil'));  // 'error'

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

Parameters:

  • item Object

    the item to check

Returns:

String:

the type

validatePropertyInjections

(
  • factory
)
private

Provided by the ember module.

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
  • options
)
public

Provided by the ember-debug module.

Defined in packages/ember-debug/lib/warn.js:26

Available since 1.0.0

Display a warning with the provided message.

  • In a production build, this method is defined as an empty function (NOP). Uses of this method in Ember itself are stripped from the ember.prod.js build.

Parameters:

  • message String

    A warning to display.

  • test Boolean

    An optional boolean. If falsy, the warning will be displayed.

  • options Object

    An object that can be used to pass a unique id for this warning. The id can be used by Ember debugging tools to change the behavior (raise, log, or silence) for that specific warning. The id should be namespaced by dots, e.g. "ember-debug.feature-flag-with-features-stripped"

watch

(
  • obj
  • _keyPath
)
private

Starts watching a property on an object. Whenever the property changes, invokes Ember.propertyWillChange and Ember.propertyDidChange. This is the primitive used by observers and dependent keys; usually you will never call this method directly but instead use higher level methods like Ember.addObserver()

Parameters:

watchedEvents

(
  • obj
)
private

Return a list of currently watched events

Parameters:

  • obj Object

wrap

(
  • func
  • superFunc
)
Function private

Provided by the ember module.

Defined in packages/ember-utils/lib/super.js:30

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:

Returns:

Function:

wrapped function.

Properties

BOOTED

Boolean private

Provided by the ember module.

Defined in packages/ember/lib/index.js:434

Whether searching on the global for new Namespace instances is enabled.

This is only exported here as to not break any addons. Given the new visit API, you will have issues if you treat this as a indicator of booted.

Internally this is only exposing a flag in Namespace.

GUID_KEY

String private final

Provided by the ember module.

Defined in packages/ember-utils/lib/guid.js:38

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 final

Provided by the ember module.

Defined in packages/ember-utils/lib/guid.js:24

Prefix used for guids through out Ember.

STRINGS

Object private

Provided by the ember module.

Defined in packages/ember/lib/index.js:418

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

Provided by the ember module.

Defined in packages/ember/lib/index.js:504

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

Provided by the ember module.

Defined in packages/ember/lib/index.js:524

The semantic version

Events

onerror

public

Provided by the ember module.

Defined in packages/ember/lib/index.js:181

A function may be assigned to Ember.onerror to be called when Ember internals encounter an error. This is useful for specialized error handling and reporting code.

Ember.onerror = function(error) {
                      Em.$.ajax('/report-error', 'POST', {
                        stack: error.stack,
                        otherInformation: 'whatever app state you want to provide'
                      });
                    };
                    

Internally, Ember.onerror is used as Backburner's error handler.

Event Payload:

  • error Exception

    the error object