How and when to use Ember.Application register and inject methods?

I'm trying to understand how to use Ember.Application register & inject methods

What use case are these functions designed for? How are they to be used and when?

I'd really like to know!

Ember by default does dependency injection when it boots your application using mostly conventions, for example if you use ember-data then an instance of the store class is injected in every route and controller in your application, so you can later get a reference by simply doing this.get('store') inside any route or controller.

For example here is a code extract where the default store get's registered (taken from the source)

Ember.onLoad('Ember.Application', function(Application) {
  Application.initializer({
    name: "store",

    initialize: function(container, application) {
      application.register('store:main', application.Store);
      ...
    }

    container.lookup('store:main');
  }
});

And then injected (source)

Application.initializer({
  name: "injectStore",

  initialize: function(container, application) {
    application.inject('controller', 'store', 'store:main');
    application.inject('route', 'store', 'store:main');
    application.inject('dataAdapter', 'store', 'store:main');
  }
  ...
});

In other words register and inject are methods to register dependencies and inject them yourself.

Let's assume you have a Session object which you populate after a server request on application start, and which you want to have a reference to in every controller, you could do something like this:

var App = Ember.Application.create({
  ready: function(){
    this.register('session:current', App.Session, {singleton: true});
    this.inject('controller', 'session', 'session:current');
  }
});

App.Session = Ember.Object.extend({
  sessionHash: ''
});

This code would set the session property of every controller instance to a singleton instance of App.Session, so you could in any controller do this.get('session') and get a reference to it, and since it's defined as a singleton it would be always the same session object.

With register you can register controllers, models, views, or any arbitrary object type. inject, in the other hand, can inject onto all instances of a given class. For example inject('model', 'session', 'session:current') would also inject the session property with the session:current instance into all models. To inject the session object, let's say onto the IndexView you could do inject('view:index', 'session', 'session:current').

Although register and inject are very powerful you should use them wisely and only in the case you really know there is no other way to achieve your goal, I guess the lack of documentation is an indicator for discouragement.

Update - No good explanation without a working example

Since It's mostly a must to provide a working example with an explanation, there it goes: http://jsbin.com/usaluc/6/edit. Notice how in the example we can simply access the mentioned sessionHash by referring to the current controller's session object with {{controller.session.sessionHash}} in every route we are in, this is the merit of what we have done by registering and injecting the App.Session object in every controller in the application.

Hope it helps.

A common use case is to provide the current loggedin user property to controllers and routes as in https://github.com/kelonye/ember-user/blob/master/lib/index.js and https://github.com/kelonye/ember-user/blob/master/test/index.js