Ember.Application Class
PUBLIC
Extends: Ember.Engine
Uses: RegistryProxyMixin
Defined in: packages/ember-application/lib/system/application.js:45
Module: ember-application
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:
let App = Ember.Application.create({ 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:
let App = Ember.Application.create({ 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:
let 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 events Ember components use, see components/handling-events.
Initializers
Libraries on top of Ember can add initializers, like so:
Ember.Application.initializer({ name: 'api-adapter', initialize: function(application) { application.register('api-adapter:main', ApiAdapter); } });
Initializers provide an opportunity to access the internal registry, 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:
let 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.
Please login to continue.