Useful Ember.js Functions

While developing stuff with Ember.js I stumbled upon some very nice and handy functions which are built in. This post lists some of them and describes in a short what they are used for.


Hey! This article references a pre-release version of Ember.js. Now that Ember.js has reached a 1.0 API the code samples below are no longer correct and the expressed opinions may no longer be accurate.


Ember

The following functions are defined in packages/ember-runtime/lib/core.js and packages/ember-metal/lib/utils.js respectively.

none

Returns true if argument is null or undefined.

1
2
3
4
5
6
Ember.none(); // true
Ember.none(null); // true
Ember.none(undefined); // true
Ember.none(''); // false
Ember.none([]); // false
Ember.none(function(){}); // false

empty

This utility function constrains the rules on Ember.none by returning false for empty string and empty arrays.

1
2
3
4
5
6
7
Ember.empty(); // true
Ember.empty(null); // true
Ember.empty(undefined); // true
Ember.empty(''); // true
Ember.empty([]); // true
Ember.empty('tobias fünke'); // false
Ember.empty([0,1,2]); // false

isArray

Use this to check if a value is an array. This method also returns true for array-like objects, like the ones implementing Ember.Array.

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

makeArray

If you need a given object to be an array you can use this function. If the passed object is already an array it simply returns it, otherwise it creates an array of length 1, where the passed object is the only item.

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

typeOf

Get the type of the passed argument.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
Ember.typeOf(); // 'undefined'
Ember.typeOf(null); // 'null'
Ember.typeOf(undefined); // 'undefined'
Ember.typeOf('michael'); // 'string'
Ember.typeOf(101); // 'number'
Ember.typeOf(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'

compare

This function compares two objects of possibly different types. It returns -1 if the first argument is smaller, 0 if both are equal and 1 if the first is greater than the second. The comparison order of different types is defined in Ember.ORDER_DEFINITIONS.

1
2
3
Ember.compare('hello', 'hello'); // 0
Ember.compare('abc', 'dfg'); // -1
Ember.compare(2, 1); // 1

isEqual

Checks if the passed two arguments are logically equal. If the first passed object has a isEqual, this function is used. The contents of two arrays are not compared. As stated in the corresponding test, this would be too expensive.

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

copy

Cloning an object can be done via Ember.copy. If the object has the Ember.Copyable mixin its copy function is used. You can create a deep copy of the object by passing true as second argument.

1
Ember.copy('hello'); // 'hello'

inspect

This function is kinda useful during debugging. It returns a string description of a given object.

1
2
3
4
5
console.log( Ember.inspect( Ember.Object.create({
    firstName: 'Hansi',
    lastName: 'Hinterseer',
    age: 58
}) ); // {__ember1331067974108_meta: [object Object] , firstName: Hansi , lastName: Hinterseer , age: 58}

K

Ember.K simply is a function returning this. This might sound not very useful but I use it often during developing a view using the action helper. Because an error is thrown when a specified target cannot handle the triggered action I simply create a property and assign it to Ember.K and continue writing the view. You can even use the shorter alias Em.K.

view.js
1
2
3
4
5
6
Ember.View.create({
    templateName: 'menu',
    home: Ember.K,
    profile: Ember.K,
    links: Ember.K
});
(menu.handlebars) download
1
2
3
4
5
<ul>
  <li {{action "home"}} >Home</li>
  <li {{action "profile"}} >Profile</li>
  <li {{action "links"}} >Links</li>
</ul>

LOG_BINDINGS

This isn’t a function but a boolean flag. If set to true Ember will log all the activity that is happening on the bindings and you’ll get a insight of whats happening below the surface.

LOG_BINDINGS examplelink
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
Ember.LOG_BINDINGS = true;

App = Ember.Application.create();

App.controller = Ember.Object.create({
    name: 'Nellie'
});
App.boundController = Ember.Object.create({
    nameBinding: 'App.controller.name'
});
App.boundBoundController = Ember.Object.create({
    nameBinding: 'App.boundController.name'
});
Ember.run(function() {
    App.boundController.set('name', 'Tobias');
    App.boundBoundController.set('name', 'N. Bluth');
});
logging output
1
2
3
4
Begin: Flush Sync Queue
    Ember.Binding<ember150>(App.controller.name -> name) Tobias -> Nellie
    Ember.Binding<ember156>(App.boundController.name -> name) N. Bluth -> Nellie
End: Flush Sync Queue

Tom Dale talked about this at the Ember.js Meetup, held on 21. February 2012. I encourage you to watch this video if you haven’t already seen it. And watch it again if you already have. It’s about debugging Ember.js apps and it’s shipped with very nice humor, bro.

String

The functions described below are directly available on String’s unless Ember.EXTEND_PROTOTYPES is set to false as described here.

w()

This method extracts each word inside a string separated by spaces. This saves some characters when assigning classNames to an Ember.View

1
2
3
4
5
6
7
'a b c'.w(); // ['a', 'b', 'c']
''.w(); // ['']
'thanks  brother!'.w(); // ['thanks', 'brother!']

Ember.View.create({
    classNames: 'top label label-info bigger'.w() // instead of writing ['top', 'label', 'label-info', 'bigger]
});

fmt()

Formatting of a string can be done via fmt() function. It simply replaces all occurrences of %@ inside a string with the passed arguments. The order of replacement can also be specified.

1
2
'Full name: %@ %@'.fmt('Michael', 'Bluth'); // 'Full name: Michael Bluth'
'%@3 %@1 %@2'.fmt('my', 'world', 'Hello'); // 'Hello my world'

loc()

This method formats the passed string but first checks if its a key in the Ember.STRINGS hash. By doing so it is possible to have a central point for defining the strings used in an application. This also allows internationalization. As stated in the source code its recommended - though not required - to prefix such a string with an underscore so it can be easily distinguished from ‘normal’ strings.

loc() examplelink
1
2
3
4
5
6
7
8
Ember.STRINGS = {
    '_greeting': 'Hello %@',
    '_page X of Y': 'page %@ of %@'
};

'_greeting'.loc('GOB'); // 'Hello GOB'
'_page X of Y'.loc(2,129); // 'page 2 of 129'
'_Not found'.loc(); // '_Not found'

More useful String functions

There are some more functionalities for converting between different String notations: camelize(), decamelize(), dasherize(), underscore()

Comments