Class Ember
publicThis 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.
$ public
Defined in packages/ember-views/lib/index.js:23
Alias for jQuery
A Ember.NativeArray public
Defined in packages/ember-runtime/lib/system/native_array.js:108
- returns
- Ember.NativeArray
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
1 2 3 4 5 6 7 8 9 10 11 12 |
export default Ember.Component.extend({ tagName: 'ul', classNames: ['pagination'], init() { this._super(...arguments); if (!this.get('content')) { this.set('content', Ember.A()); } } }); |
K Object public
Defined in packages/ember-metal/lib/index.js:407
- returns
- Object
An empty function useful for some operations. Always returns this
.
addListener (obj, eventName, target, method, once) public
Defined in packages/ember-metal/lib/events.js:70
- 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
Defined in packages/ember-metal/lib/observer.js:27
- obj
- _path
- String
- target
- Object|Function
- method
- Function|String
aliasMethod (methodName) public
Defined in packages/ember-metal/lib/mixin.js:673
- methodName
- String
- name of the method to alias
Makes a method available via an additional name.
1 2 3 4 5 6 7 8 9 10 11 |
App.Person = Ember.Object.extend({ name: function() { return 'Tomhuda Katzdale'; }, moniker: Ember.aliasMethod('name') }); let goodGuy = App.Person.create(); goodGuy.name(); // 'Tomhuda Katzdale' goodGuy.moniker(); // 'Tomhuda Katzdale' |
assert (desc, test) public
Defined in packages/ember-debug/lib/index.js:33
- 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.
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.
1 2 3 4 5 |
// Test for truthiness Ember.assert('Must pass a valid object', obj); // Fail unconditionally Ember.assert('This code path should never be run'); |
assign (original, args) Object public
Defined in packages/ember-metal/lib/assign.js:1
- original
- Object
- The object to assign into
- args
- Object
- The objects to copy properties from
- returns
- Object
Copy properties from a source object to a target object.
1 2 3 4 |
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.' } |
bind (obj, to, from) Ember.Binding public
Defined in packages/ember-metal/lib/binding.js:486
- 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
Defined in packages/ember-metal/lib/computed.js:554
- 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.
compare (v, w) Number public
Defined in packages/ember-runtime/lib/compare.js:40
- 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.
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.
1 2 3
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
1 2
Ember.compare('hello', 50); // 1 Ember.compare(50, 'hello'); // -1
copy (obj, deep) Object public
Defined in packages/ember-runtime/lib/copy.js:66
- obj
- Object
- The object to clone
- deep
- Boolean
- If true, a deep copy of the object is made.
- returns
- Object
- The copied object
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.
debug (message) public
Defined in packages/ember-debug/lib/index.js:60
- message
- String
- A debug message to display.
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.
1 |
Ember.debug('I\'m a debug notice!'); |
deprecate (message, test, options) public
Defined in packages/ember-debug/lib/deprecate.js:97
- 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
- An optional url to the transition guide on the emberjs.com website.
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.
get (obj, keyName) Object public
Defined in packages/ember-metal/lib/property_get.js:21
- 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.
getEngineParent (engine) EngineInstance public
Defined in packages/ember-application/lib/system/engine-parent.js:10
- engine
- EngineInstance
- An engine instance.
- returns
- EngineInstance
- The parent engine instance.
getEngineParent
retrieves an engine instance's parent instance.
getOwner (object) Object public
Defined in packages/container/lib/owner.js:10
Available since v2.3.0
- object
- Object
- An object with an owner.
- returns
- Object
- An owner object.
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:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
// 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')); } }); |
getProperties (obj, list) Object public
Defined in packages/ember-metal/lib/get_properties.js:3
- 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:
1 2 |
Ember.getProperties(record, 'firstName', 'lastName', 'zipCode'); // { firstName: 'John', lastName: 'Doe', zipCode: '10011' } |
is equivalent to:
1 2 |
Ember.getProperties(record, ['firstName', 'lastName', 'zipCode']); // { firstName: 'John', lastName: 'Doe', zipCode: '10011' } |
getWithDefault (obj, keyName, defaultValue) Object public
Defined in packages/ember-metal/lib/property_get.js:106
- 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.
Retrieves the value of a property from an Object, or a default value in the
case that the property returns undefined
.
1 |
Ember.getWithDefault(person, 'lastName', 'Doe'); |
guidFor (obj) String public
Defined in packages/ember-metal/lib/utils.js:167
- obj
- Object
- any object, string, number, Element, or primitive
- returns
- String
- the unique guid for this instance.
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.
isArray (obj) Boolean public
Defined in packages/ember-runtime/lib/utils.js:20
- 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.
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
)
1 2 3 |
Ember.isArray(); // false Ember.isArray([]); // true Ember.isArray(Ember.ArrayProxy.create({ content: [] })); // true |
isBlank (obj) Boolean public
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.
1 2 3 4 5 6 7 8 9 10 11 |
Ember.isBlank(); // true Ember.isBlank(null); // true Ember.isBlank(undefined); // true Ember.isBlank(''); // true Ember.isBlank([]); // true Ember.isBlank('\n\t'); // true Ember.isBlank(' '); // true Ember.isBlank({}); // false Ember.isBlank('\n\t Hello'); // false Ember.isBlank('Hello world'); // false Ember.isBlank([1,2,3]); // false |
isEmpty (obj) Boolean public
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.
1 2 3 4 5 6 7 8 9 10 |
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 |
isEqual (a, b) Boolean public
Defined in packages/ember-runtime/lib/is-equal.js:1
- a
- Object
- first object to compare
- b
- Object
- second object to compare
- returns
- Boolean
Compares two objects, returning true if they are equal.
1 2 |
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.
1 2 3 4 5 6 7 8 |
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.
1 |
Ember.isEqual([4, 2], [4, 2]); // false |
isNone (obj) Boolean public
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.
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 |
isPresent (obj) Boolean public
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
.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
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 |
merge (original, updates) Object public
Defined in packages/ember-metal/lib/merge.js:1
- 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.
1 2 3 4 |
Ember.merge({ first: 'Tom' }, { last: 'Dale' }); // { first: 'Tom', last: 'Dale' } var a = { first: 'Yehuda' }; var b = { last: 'Katz' }; Ember.merge(a, b); // a == { first: 'Yehuda', last: 'Katz' }, b == { last: 'Katz' } |
observer (propertyNames, func) public
Defined in packages/ember-metal/lib/mixin.js:703
- propertyNames
- String
- func
- Function
- returns
- func
Specify a method that observes property changes.
1 2 3 4 5 |
Ember.Object.extend({ valueObserver: Ember.observer('value', function() { // Executes whenever the "value" property changes }) }); |
Also available as Function.prototype.observes
if prototype extensions are
enabled.
on (eventNames, func) public
Defined in packages/ember-metal/lib/events.js:280
- eventNames
- String
- func
- Function
- returns
- func
Define a property as a function that should be executed when a specified event or events are triggered.
1 2 3 4 5 6 7 8 9 |
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!' |
removeListener (obj, eventName, target, method) public
Defined in packages/ember-metal/lib/events.js:112
- 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
Defined in packages/ember-metal/lib/observer.js:47
- obj
- path
- String
- target
- Object|Function
- method
- Function|String
runInDebug (func) public
Defined in packages/ember-debug/lib/index.js:127
Available since v1.5.0
- func
- Function
- The function to be executed.
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.
1 2 3 4 5 6 7 |
Ember.runInDebug(() => { Ember.Component.reopen({ didInsertElement() { console.log("I'm happy"); } }); }); |
sendEvent (obj, eventName, params, actions) public
Defined in packages/ember-metal/lib/events.js:195
- 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
Defined in packages/ember-metal/lib/property_set.js:22
- 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.
setOwner (object) Object public
Defined in packages/container/lib/owner.js:54
Available since v2.3.0
- object
- Object
- An object with an owner.
- returns
- Object
- An owner object.
setOwner
forces a new owner on a given object instance. This is primarily
useful in some testing cases.
setProperties (obj, properties) public
Defined in packages/ember-metal/lib/set_properties.js:4
- obj
- properties
- Object
- returns
- properties
Set a list of properties on an object. These properties are set inside
a single beginPropertyChanges
and endPropertyChanges
batch, so
observers will be buffered.
1 2 3 4 5 6 7 |
let anObject = Ember.Object.create(); anObject.setProperties({ firstName: 'Stanley', lastName: 'Stuart', age: 21 }); |
tryInvoke (obj, methodName, args) * public
Defined in packages/ember-metal/lib/utils.js:338
- 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.
1 2 3 4 5 |
let 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
Defined in packages/ember-metal/lib/property_set.js:130
- 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
Defined in packages/ember-runtime/lib/utils.js:55
- item
- Object
- the item to check
- returns
- String
- the type
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:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
| Return Value | Meaning | |---------------|------------------------------------------------------| | 'string' | String primitive or String object. | | 'number' | Number primitive or Number object. | | 'boolean' | Boolean primitive or Boolean object. | | 'null' | Null value | | 'undefined' | Undefined value | | 'function' | A function | | 'array' | An instance of Array | | 'regexp' | An instance of RegExp | | 'date' | An instance of Date | | 'class' | An Ember class (created using Ember.Object.extend()) | | 'instance' | An Ember object instance | | 'error' | An instance of the Error object | | 'object' | A JavaScript object not inheriting from Ember.Object | |
Examples:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 |
Ember.typeOf(); // 'undefined' Ember.typeOf(null); // 'null' Ember.typeOf(undefined); // 'undefined' Ember.typeOf('michael'); // 'string' Ember.typeOf(new String('michael')); // 'string' Ember.typeOf(101); // 'number' Ember.typeOf(new Number(101)); // 'number' Ember.typeOf(true); // 'boolean' Ember.typeOf(new Boolean(true)); // 'boolean' Ember.typeOf(Ember.makeArray); // 'function' Ember.typeOf([1, 2, 90]); // 'array' Ember.typeOf(/abc/); // 'regexp' Ember.typeOf(new Date()); // 'date' Ember.typeOf(Ember.Object.extend()); // 'class' Ember.typeOf(Ember.Object.create()); // 'instance' Ember.typeOf(new Error('teamocil')); // 'error' // 'normal' JavaScript object Ember.typeOf({ a: 'b' }); // 'object' |
warn (message, test, options) public
Defined in packages/ember-debug/lib/warn.js:26
- 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"
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.