Class Ember public

Defined in: packages/ember-metal/lib/core.js:8

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.

You can also use the shorthand Em instead of Ember.

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

Methods

$ public

Module: ember

Defined in packages/ember-views/lib/main.js:46

Alias for jQuery

A : Ember.NativeArray public

Module: ember

Defined in packages/ember-runtime/lib/system/native_array.js:114

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

var Pagination = Ember.CollectionView.extend({
  tagName: 'ul',
  classNames: ['pagination'],

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

K : Object public

Module: ember

Defined in packages/ember-metal/lib/core.js:207

returns: Object

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

addListener (obj, eventName, target, method, once) public

Module: ember

Defined in packages/ember-metal/lib/events.js:107

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

Add an event listener

addObserver (obj, _path, target, method) public

Module: ember

Defined in packages/ember-metal/lib/observer.js:28

obj
_path: String
target: Object|Function
method: Function|String

assert (desc, test) public

Module: ember

Defined in packages/ember-debug/lib/main.js:24

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.

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:

// Test for truthiness
Ember.assert('Must pass a valid object', obj);

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

bind (obj, to, from) : Ember.Binding public

Module: ember

Defined in packages/ember-metal/lib/binding.js:476

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

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.

cacheFor (obj, key) : Object public

Module: ember

Defined in packages/ember-metal/lib/computed.js:604

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

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.

copy (obj, deep) : Object public

Module: ember

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

obj: Object; The object to clone
deep: Boolean; If true, a deep copy of the object is made
returns: Object; The cloned 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.

create public

Module: ember

Defined in packages/ember-metal/lib/platform/create.js:15

Available since v1.8.0

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

debug (message) public

Module: ember

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

message: String; A debug message to display.

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

Ember.debug('I\'m a debug notice!');

deprecate (message, test, options) public

Module: ember

Defined in packages/ember-debug/lib/main.js:95

message: String; A description of the deprecation.
test: Boolean|Function; An optional boolean. If falsy, the deprecation will be displayed. If this is a function, it will be executed and its return value will be used as condition.
options: Object; An optional object that can be used to pass in a url to the transition guide on the emberjs.com website, and a unique id for this deprecation. The id can be used by Ember debugging tools to change the behavior (raise, log or silence) for that specific deprecation. The id should be namespaced by dots, e.g. "view.helper.select".

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.

get (obj, keyName) : Object public

Module: ember

Defined in packages/ember-metal/lib/property_get.js:24

obj: Object; The object to retrieve from.
keyName: String; The property key to retrieve
returns: Object; the property value or null.

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.

getProperties (obj, list) : Object public

Module: ember

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

obj: Object
list: String...|Array; of keys to get
returns: Object

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

isArray (obj) : Boolean public

Module: ember

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

obj: Object; The object to test
returns: Boolean; true if the passed object is an array or Array-like

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)

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

isBlank (obj) : Boolean public

Module: ember

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

Available since v1.5.0

obj: Object; Value to test
returns: Boolean

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

isEmpty (obj) : Boolean public

Module: ember

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

obj: Object; Value to test
returns: 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.

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

isEqual (a, b) : Boolean public

Module: ember

Defined in packages/ember-runtime/lib/core.js:6

a: Object; first object to compare
b: Object; second object to compare
returns: 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.

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

isNone (obj) : Boolean public

Module: ember

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

obj: Object; Value to test
returns: 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.

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

isPresent (obj) : Boolean public

Module: ember

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

Available since v1.8.0

obj: Object; Value to test
returns: Boolean

A value is present if it not isBlank.

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

merge (original, updates) : Object public

Module: ember

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

original: Object; The object to merge into
updates: Object; The object to copy properties from
returns: Object

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

on (eventNames, func) : public

Module: ember

Defined in packages/ember-metal/lib/events.js:392

eventNames: String
func: Function
returns: func

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

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

oneWay (obj, to, from) : Ember.Binding public

Module: ember

Defined in packages/ember-metal/lib/binding.js:494

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

removeListener (obj, eventName, target, method) public

Module: ember

Defined in packages/ember-metal/lib/events.js:146

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

Remove an event listener

Arguments should match those passed to Ember.addListener.

removeObserver (obj, path, target, method) public

Module: ember

Defined in packages/ember-metal/lib/observer.js:48

obj
path: String
target: Object|Function
method: Function|String

runInDebug (func) public

Module: ember

Defined in packages/ember-debug/lib/main.js:212

Available since v1.5.0

func: Function; The function to be executed.

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

Ember.runInDebug(() => {
  Ember.Component.reopen({
    didInsertElement() {
      console.log("I'm happy");
    }
  });
});

sendEvent (obj, eventName, params, actions) : public

Module: ember

Defined in packages/ember-metal/lib/events.js:301

obj
eventName: String
params: Array; Optional parameters for each listener.
actions: Array; Optional array of actions (listeners).
returns: true

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.

set (obj, keyName, value) : Object public

Module: ember

Defined in packages/ember-metal/lib/property_set.js:16

obj: Object; The object to modify.
keyName: String; The property key to set
value: Object; The value to set
returns: Object; the passed value.

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.

setProperties (obj, properties) : public

Module: ember

Defined in packages/ember-metal/lib/set_properties.js:5

obj
properties: Object
returns: obj

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

var anObject = Ember.Object.create();

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

tryInvoke (obj, methodName, args) : * public

Module: ember

Defined in packages/ember-metal/lib/utils.js:540

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

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

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

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

trySet (root, path, value) public

Module: ember

Defined in packages/ember-metal/lib/property_set.js:154

root: Object; The object to modify.
path: String; The property path to set
value: Object; The value to set

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.

typeOf (item) : String public

Module: ember

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

item: Object; the item to check
returns: String; the type

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:

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

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'

warn (message, test) public

Module: ember

Defined in packages/ember-debug/lib/main.js:60

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

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

Properties

ArrayPolyfills public

Module: ember

Defined in packages/ember-metal/lib/array.js:122

Array polyfills to support ES5 features in older browsers.

ENV public

Module: ember

Defined in packages/ember-metal/lib/core.js:60

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

EXTEND_PROTOTYPES public

Module: ember

Defined in packages/ember-metal/lib/core.js:149

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

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

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

LOG_BINDINGS public

Module: ember

Defined in packages/ember-metal/lib/binding.js:26

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.

LOG_STACKTRACE_ON_DEPRECATION public

Module: ember

Defined in packages/ember-metal/lib/core.js:174

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

LOG_VERSION public

Module: ember

Defined in packages/ember-metal/lib/core.js:196

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

SHIM_ES5 public

Module: ember

Defined in packages/ember-metal/lib/core.js:185

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

VERSION public

Module: ember

Defined in packages/ember-metal/lib/core.js:49

The semantic version.

Events

onerror (error) public

Module: ember

Defined in packages/ember-metal/lib/main.js:392

error: Exception; the error object

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.