An instance of Ember.Application is the starting point for every Ember application. It helps to instantiate, initialize and coordinate the many objects that make up your app.

Each Ember app has one and only one Ember.Application object. In fact, the very first thing you should do in your application is create the instance:

window.App = Ember.Application.create();

Typically, the application object is the only global variable. All other classes in your app should be properties on the Ember.Application instance, which highlights its first role: a global namespace.

For example, if you define a view class, it might look like this:

App.MyView = Ember.View.extend();

By default, calling Ember.Application.create() will automatically initialize your application by calling the Ember.Application.initialize() method. If you need to delay initialization, you can call your app's deferReadiness() method. When you are ready for your app to be initialized, call its advanceReadiness() method.

You can define a ready method on the Ember.Application instance, which will be run by Ember when the application is initialized.

Because Ember.Application inherits from Ember.Namespace, any classes you create will have useful string representations when calling toString(). See the Ember.Namespace documentation for more information.

While you can think of your Ember.Application as a container that holds the other classes in your application, there are several other responsibilities going on under-the-hood that you may want to understand.

Event Delegation

Ember uses a technique called event delegation. This allows the framework to set up a global, shared event listener instead of requiring each view to do it manually. For example, instead of each view registering its own mousedown listener on its associated element, Ember sets up a mousedown listener on the body.

If a mousedown event occurs, Ember will look at the target of the event and start walking up the DOM node tree, finding corresponding views and invoking their mouseDown method as it goes.

Ember.Application has a number of default events that it listens for, as well as a mapping from lowercase events to camel-cased view method names. For example, the keypress event causes the keyPress method on the view to be called, the dblclick event causes doubleClick to be called, and so on.

If there is a bubbling browser event that Ember does not listen for by default, you can specify custom events and their corresponding view method names by setting the application's customEvents property:

App = Ember.Application.create({
  customEvents: {
    // add support for the paste event
    paste: "paste"
  }
});

By default, the application sets up these event listeners on the document body. However, in cases where you are embedding an Ember application inside an existing page, you may want it to set up the listeners on an element inside the body.

For example, if only events inside a DOM element with the ID of ember-app should be delegated, set your application's rootElement property:

window.App = Ember.Application.create({
  rootElement: '#ember-app'
});

The rootElement can be either a DOM element or a jQuery-compatible selector string. Note that views appended to the DOM outside the root element will not receive events. If you specify a custom root element, make sure you only append views inside it!

To learn more about the advantages of event delegation and the Ember view layer, and a list of the event listeners that are setup by default, visit the Ember View Layer guide.

Initializers

Libraries on top of Ember can add initializers, like so:

Ember.Application.initializer({
  name: 'api-adapter',

  initialize: function(container, application) {
    application.register('api-adapter:main', ApiAdapter);
  }
});

Initializers provide an opportunity to access the container, which organizes the different components of an Ember application. Additionally they provide a chance to access the instantiated application. Beyond being used for libraries, initializers are also a great way to organize dependency injection or setup in your own application.

Routing

In addition to creating your application's router, Ember.Application is also responsible for telling the router when to start routing. Transitions between routes can be logged with the LOG_TRANSITIONS flag, and more detailed intra-transition logging can be logged with the LOG_TRANSITIONS_INTERNAL flag:

window.App = Ember.Application.create({
  LOG_TRANSITIONS: true, // basic logging of successful transitions
  LOG_TRANSITIONS_INTERNAL: true // detailed logging of all routing steps
});

By default, the router will begin trying to translate the current URL into application state once the browser emits the DOMContentReady event. If you need to defer routing, you can call the application's deferReadiness() method. Once routing can begin, call the advanceReadiness() method.

If there is any setup required before routing begins, you can implement a ready() method on your app that will be invoked immediately before routing begins.