Dependency Injection & Service Lookup

A common use-case for service lookup is that of a singleton service. Often, these services will live near application state, and thus Ember provides an API that makes controller services easy to write.

For example, a session service can easily be made available to this index controller:

var App = Ember.Application.create();
App.SessionController = Ember.Controller.extend({
  isAuthenticated: false
});
// The index controller may need access to that state:
App.IndexController = Ember.Controller.extend({
  needs: ['session'],
  // Using needs, the controller instance will be available on `controllers`
  isLoggedIn: Ember.computed.alias('controllers.session.isAuthenticated')
});

The controllers computed property returns a hash of the controllers listed in needs. Controllers in Ember.js are singletons, meaning the same instance is always returned when they are requested.

A second controller can take advantage of this singleton nature to access the same session object:

App.SignInController = Ember.Controller.extend({
  needs: ['session'],
  isLoggedIn: Ember.computed.alias('controllers.session.isAuthenticated'),
  actions: {
    signIn: function(){
      // There is an alias to the session property, so this change propagates
      // to the session object then the IndexController.
      this.set('isLoggedIn', true);
    }
  }
});

The session object returned in both classes is the same. needs provides us an easy way to share state across controllers.

The needs array can fetch any singleton controller in an Ember application. This can be combined with the render helper to create services that also have access to the DOM.

Let's build a controller that manages audio playback and makes it available to other controllers.

First, we create AudioController and attach it to the DOM by using the render helper. This helper renders a template, and backs that template with a controller of the same name.

{{! application.hbs }}
{{render "audio"}}
{{outlet}}

And we must create an audio.hbs template to render:

{{! audio.hbs }}
<audio id="audio" controls loop>
  <source {{bind-attr src=currentSrc}} type="audio/mpeg"></source>
</audio>
<div>{{currentSrc}}</div>

The render helper will back this template with a controller of the same name. We create that controller, and have it maintain the currentSrc property:

App.AudioController = Ember.Controller.extend({
  currentSrc: null,
  play: function(src){
    this.set('currentSrc', src);
  }
});

To allow other controllers to play audio, we use the needs array to look up our new service:

App.IndexController = Ember.Controller.extend({
  needs: ['audio'],
  actions: {
    selectSrc: function(src){
      this.get('controllers.audio').play(src);
    }
  }
});

When the index controller calls this.get('controllers.audio'), the audio service is returned. Other controllers can also use needs to access the audio service.

A functional version of this example is provided below:

Ember Starter Kit

Services are a simple way to share behavior between controllers and isolate responsibilities in an application. needs is an easy and quick way to create services and share them between an application's controllers.

For a more powerful way to connect Ember.js components, let's look at dependency injection.

When an Ember application starts running, it will create and use a single instance of the Ember.Container object. This container object is responsible for managing factories and the dependencies between them. At the level of the container, a factory can be any framework component. The index template is a factory with the name template:index, and the application route is a factory with the name route:application. The container understands how to use these factories (are they singleton? Should they be instantiated?) and manages their dependencies.

Factory names have two parts segmented by a :. The first segment is the framework component type, and the second is the name of the component requested. Hence, an application view would be named view:application.

If the container does not already have a requested factory, it uses a resolver to discover that factory. The resolver is responsible for mapping the factory name of view:application to the global variable of App.ApplicationView. Tools like Ember CLI may use alternative rules for resolving factories. After optionally adding dependencies to the requested factory, that factory is cached and returned.

Ember's container should be viewed as an implementation detail, and is not part of the supported public API.

Instead of accessing the container directly, Ember provides an API for registering factories and managing injections on the application instance.

There are two ways to access this API. Many Ember applications can access this API directly on the application instance:

App = Ember.Application.create();

App.register('logger:main', {
  log: function(m) {
    console.log(m);
  }
}, { instantiate: false });

App.inject('route', 'logger', 'logger:main');

But Ember CLI applications (and libraries) will need to use a more flexible hook, an initializer:

Ember.Application.initializer({
  name: 'logger',

  initialize: function(container, application) {
    var logger = {
      log: function(m) {
        console.log(m);
      }
    };

    application.register('logger:main', logger, { instantiate: false });
    application.inject('route', 'logger', 'logger:main');
  }
});

Initializers can be declared at any time before an application is instantiated, making them easier to declare than directly registering factories on the application.

Any dependency injection is comprised of two parts. The first is the factory registration:

var logger = {
  log: function(m) {
    console.log(m);
  }
};

application.register('logger:main', logger, { instantiate: false });

The register function adds the factory (logger) into the container. It adds it with the full name of logger:main, and with the option not to instantiate. When the factory is injected onto another object, it will be injected "as-is".

Often, it is preferable to register a factory that can be instantiated:

var Logger = Ember.Object.extend({
  log: function(m) {
    console.log(m);
  }
});

application.register('logger:main', Logger);

This class will be instantiated before it is used by the container. This gives it the important benefit of being able to accept injections of its own.

The second part of dependency injection is, you guessed it, the dependency injection:

application.inject('route', 'logger', 'logger:main');

This is an example of a type injection. Onto all factories of the type route the property, logger will be injected with the factory named logger:main. Routes in this example application can now access the logger:

App = Ember.Application.extend();

App.Logger = Ember.Object.extend({
  log: function(m) {
    console.log(m);
  }
});

App.IndexRoute = Ember.Route.extend({
  activate: function(){
    // The logger property is injected into all routes
    this.logger.log('Entered the index route!');
  }
});

Ember.Application.initializer({
  name: 'logger',

  initialize: function(container, application) {
    application.register('logger:main', App.Logger);
    application.inject('route', 'logger', 'logger:main');
  }
});

App.create();

Injections can also be made on a specific factory by using its full name:

application.inject('route:index', 'logger', 'logger:main');

Injections can be made onto all of Ember's major framework classes, including views, helpers, components, controllers, routes, and the router.

Note: For injections into models (if not using Ember CLI), you need to enable the MODEL_FACTORY_INJECTIONS flag before you initialize your application. You can do this like so:

Ember.MODEL_FACTORY_INJECTIONS = true;

var App = Ember.Application.create({
  // Enable any options
});

What follows is a full implementation of the above logger service:

Ember Starter Kit

Dependency injection and service lookup are two powerful tools in your Ember.js toolset, and every mature Ember application will require their use.