Class Application

import Application from '@ember/application';

An instance of Application is the starting point for every Ember application. It instantiates, initializes and coordinates the objects that make up your app.

Each Ember app has one and only one Application object. Although Ember CLI creates this object implicitly, the Application class is defined in the app/app.js. You can define a ready method on the Application class, which will be run by Ember when the application is initialized.

const App = Application.extend({
  ready() {
    // your code here
  }
})

Because Application ultimately 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 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. It is also important to understand that an Application is different from an ApplicationInstance. Refer to the Guides to understand the difference between these.

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.

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:

import Application from '@ember/application';

let App = Application.extend({
  customEvents: {
    // add support for the paste event
    paste: 'paste'
  }
});

To prevent Ember from setting up a listener for a default event, specify the event name with a null value in the customEvents property:

import Application from '@ember/application';

let App = Application.extend({
  customEvents: {
    // prevent listeners for mouseenter/mouseleave events
    mouseenter: null,
    mouseleave: null
  }
});

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:

import Application from '@ember/application';

let App = Application.extend({
  rootElement: '#ember-app'
});

The rootElement can be either a DOM element or a CSS 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 events Ember components use, see

components/handling-events.

Initializers

To add behavior to the Application's boot process, you can define initializers in the app/initializers directory, or with ember generate initializer using Ember CLI. These files should export a named initialize function which will receive the created application object as its first argument.

export function initialize(application) {
  // application.inject('route', 'foo', 'service:foo');
}

Application initializers can be used for a variety of reasons including:

• setting up external libraries
• injecting dependencies
• setting up event listeners in embedded apps
• deferring the boot process using the deferReadiness and advanceReadiness APIs.

Routing

In addition to creating your application's router, 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:

import Application from '@ember/application';

let App = 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.