Ember.ControllerMixin Class packages_es6/ember-runtime/lib/controllers/controller.js:13


Ember.ControllerMixin provides a standard interface for all classes that compose Ember's controller layer: Ember.Controller, Ember.ArrayController, and Ember.ObjectController.

Show:

child

Container

Returns a new child of the current container. These children are configured to correctly inherit from the current container.

Returns:

Container

controllerFor

deprecated

Use needs instead

describe

(fullName) String

A hook that can be used to describe how the resolver will attempt to find the factory.

For example, the default Ember .describe returns the full class name (including namespace) where Ember's resolver expects to find the fullName.

Parameters:

fullName String

Returns:

String
described fullName

destroy

A depth first traversal, destroying the container, its descendant containers and all their managed objects.

eachLocal

(callback, binding)

Iterate and invoke a callback for each local key-value pair.

Parameters:

callback Function
binding Object

factoryInjection

(factoryName, property, injectionName)

Defines factory injection rules.

Similar to regular injection rules, but are run against factories, via Container#lookupFactory.

These rules are used to inject objects onto factories when they are looked up.

Two forms of injections are possible:

  • Injecting one fullName on another fullName
  • Injecting one fullName on a type

Example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
var container = new Container();

container.register('store:main', Store);
container.register('store:secondary', OtherStore);
container.register('model:user', User);
container.register('model:post', Post);

// injecting one fullName on another type
container.factoryInjection('model', 'store', 'store:main');

// injecting one fullName on another fullName
container.factoryInjection('model:post', 'secondaryStore', 'store:secondary');

var UserFactory = container.lookupFactory('model:user');
var PostFactory = container.lookupFactory('model:post');
var store = container.lookup('store:main');

UserFactory.store instanceof Store; //=> true
UserFactory.secondaryStore instanceof OtherStore; //=> false

PostFactory.store instanceof Store; //=> true
PostFactory.secondaryStore instanceof OtherStore; //=> true

// and both models share the same source instance
UserFactory.store === PostFactory.store; //=> true

Parameters:

factoryName String
property String
injectionName String

factoryTypeInjection

(type, property, fullName) private

Used only via factoryInjection.

Provides a specialized form of injection, specifically enabling all factory of one type to be injected with a reference to another object.

For example, provided each factory of type model needed a store. one would do the following:

1
2
3
4
5
6
7
8
9
10
var container = new Container();

container.register('store:main', SomeStore);

container.factoryTypeInjection('model', 'store', 'store:main');

var store = container.lookup('store:main');
var UserFactory = container.lookupFactory('model:user');

UserFactory.store instanceof SomeStore; //=> true

Parameters:

type String
property String
fullName String

get

(key) Any

Retrieve the value given a key, if the value is present at the current level use it, otherwise walk up the parent hierarchy and try again. If no matching key is found, return undefined.

Parameters:

key String

Returns:

Any

has

(key) Boolean

Check for the existence of given a key, if the key is present at the current level return true, otherwise walk up the parent hierarchy and try again. If no matching key is found, return false.

Parameters:

key String

Returns:

Boolean

injection

(factoryName, property, injectionName)

Defines injection rules.

These rules are used to inject dependencies onto objects when they are instantiated.

Two forms of injections are possible:

  • Injecting one fullName on another fullName
  • Injecting one fullName on a type

Example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
var container = new Container();

container.register('source:main', Source);
container.register('model:user', User);
container.register('model:post', Post);

// injecting one fullName on another fullName
// eg. each user model gets a post model
container.injection('model:user', 'post', 'model:post');

// injecting one fullName on another type
container.injection('model', 'source', 'source:main');

var user = container.lookup('model:user');
var post = container.lookup('model:post');

user.source instanceof Source; //=> true
post.source instanceof Source; //=> true

user.post instanceof Post; //=> true

// and both models share the same source
user.source === post.source; //=> true

Parameters:

factoryName String
property String
injectionName String

lookup

(fullName, options) Any

Given a fullName return a corresponding instance.

The default behaviour is for lookup to return a singleton instance. The singleton is scoped to the container, allowing multiple containers to all have their own locally scoped singletons.

1
2
3
4
5
6
7
8
9
10
11
12
var container = new Container();
container.register('api:twitter', Twitter);

var twitter = container.lookup('api:twitter');

twitter instanceof Twitter; // => true

// by default the container will return singletons
var twitter2 = container.lookup('api:twitter');
twitter2 instanceof Twitter; // => true

twitter === twitter2; //=> true

If singletons are not wanted an optional flag can be provided at lookup.

1
2
3
4
5
6
7
var container = new Container();
container.register('api:twitter', Twitter);

var twitter = container.lookup('api:twitter', { singleton: false });
var twitter2 = container.lookup('api:twitter', { singleton: false });

twitter === twitter2; //=> false

Parameters:

fullName String
options Object

Returns:

Any

lookupFactory

(fullName) Any

Given a fullName return the corresponding factory.

Parameters:

fullName String

Returns:

Any

makeToString

(factory, fullName) Function

Parameters:

factory Any
fullName String

Returns:

Function
toString function

normalize

(fullName) String

A hook to enable custom fullName normalization behaviour

Parameters:

fullName String

Returns:

String
normalized fullName

options

(type, options)

Parameters:

type String
options Object

optionsForType

(type, options)

Allow registering options for all factories of a type.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
var container = new Container();

// if all of type `connection` must not be singletons
container.optionsForType('connection', { singleton: false });

container.register('connection:twitter', TwitterConnection);
container.register('connection:facebook', FacebookConnection);

var twitter = container.lookup('connection:twitter');
var twitter2 = container.lookup('connection:twitter');

twitter === twitter2; // => false

var facebook = container.lookup('connection:facebook');
var facebook2 = container.lookup('connection:facebook');

facebook === facebook2; // => false

Parameters:

type String
options Object

register

(fullName, factory, options)

Registers a factory for later injection.

Example:

1
2
3
4
5
var container = new Container();

container.register('model:user', Person, {singleton: false });
container.register('fruit:favorite', Orange);
container.register('communication:main', Email, {singleton: false});

Parameters:

fullName String
factory Function
options Object

remove

(key)

Delete the given key

Parameters:

key String

replaceRoute

(name, models)

Transition into another route while replacing the current URL, if possible. This will replace the current history entry instead of adding a new one. Beside that, it is identical to transitionToRoute in all other respects.

1
2
aController.replaceRoute('blogPosts');
aController.replaceRoute('blogPosts.recentEntries');

Optionally supply a model for the route in question. The model will be serialized into the URL using the serialize hook of the route:

1
aController.replaceRoute('blogPost', aPost);

If a literal is passed (such as a number or a string), it will be treated as an identifier instead. In this case, the model hook of the route will be triggered:

1
aController.replaceRoute('blogPost', 1);

Multiple models will be applied last to first recursively up the resource tree.

1
2
3
4
5
6
7
8
App.Router.map(function() {
  this.resource('blogPost', {path:':blogPostId'}, function(){
    this.resource('blogComment', {path: ':blogCommentId'});
  });
});

aController.replaceRoute('blogComment', aPost, aComment);
aController.replaceRoute('blogComment', 1, 13);

It is also possible to pass a URL (a string that starts with a /). This is intended for testing and debugging purposes and should rarely be used in production code.

1
2
aController.replaceRoute('/');
aController.replaceRoute('/blog/post/1/comment/13');

Parameters:

name String
the name of the route or a URL
models ...Object
the model(s) or identifier(s) to be used while transitioning to the route.

replaceWith

deprecated

reset

resolve

(fullName) Function

Given a fullName return the corresponding factory.

By default resolve will retrieve the factory from its container's registry.

1
2
3
4
var container = new Container();
container.register('api:twitter', Twitter);

container.resolve('api:twitter') // => Twitter

Optionally the container can be provided with a custom resolver. If provided, resolve will first provide the custom resolver the opportunity to resolve the fullName, otherwise it will fallback to the registry.

1
2
3
4
5
6
7
var container = new Container();
container.resolver = function(fullName) {
  // lookup via the module system of choice
};

// the twitter factory is added to the module system
container.resolve('api:twitter') // => Twitter

Parameters:

fullName String

Returns:

Function
fullName's factory

send

(actionName, context)

Triggers a named action on the ActionHandler. Any parameters supplied after the actionName string will be passed as arguments to the action target function.

If the ActionHandler has its target property set, actions may bubble to the target. Bubbling happens when an actionName can not be found in the ActionHandler's actions hash or if the action target function returns true.

Example

1
2
3
4
5
6
7
8
9
10
App.WelcomeRoute = Ember.Route.extend({
  actions: {
    playTheme: function() {
       this.send('playMusic', 'theme.mp3');
    },
    playMusic: function(track) {
      // ...
    }
  }
});

Parameters:

actionName String
The action to trigger
context *
a context to send with the action

set

(key, value)

Set the given value for the given key, at the current level.

Parameters:

key String
value Any

transitionTo

deprecated

transitionToRoute

(name, models)

Transition the application into another route. The route may be either a single route or route path:

1
2
aController.transitionToRoute('blogPosts');
aController.transitionToRoute('blogPosts.recentEntries');

Optionally supply a model for the route in question. The model will be serialized into the URL using the serialize hook of the route:

1
aController.transitionToRoute('blogPost', aPost);

If a literal is passed (such as a number or a string), it will be treated as an identifier instead. In this case, the model hook of the route will be triggered:

1
aController.transitionToRoute('blogPost', 1);

Multiple models will be applied last to first recursively up the resource tree.

1
2
3
4
5
6
7
8
App.Router.map(function() {
  this.resource('blogPost', {path:':blogPostId'}, function(){
    this.resource('blogComment', {path: ':blogCommentId'});
  });
});

aController.transitionToRoute('blogComment', aPost, aComment);
aController.transitionToRoute('blogComment', 1, 13);

It is also possible to pass a URL (a string that starts with a /). This is intended for testing and debugging purposes and should rarely be used in production code.

1
2
aController.transitionToRoute('/');
aController.transitionToRoute('/blog/post/1/comment/13');

See also replaceRoute.

Parameters:

name String
the name of the route or a URL
models ...Object
the model(s) or identifier(s) to be used while transitioning to the route.

typeInjection

(type, property, fullName) private

Used only via injection.

Provides a specialized form of injection, specifically enabling all objects of one type to be injected with a reference to another object.

For example, provided each object of type controller needed a router. one would do the following:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
var container = new Container();

container.register('router:main', Router);
container.register('controller:user', UserController);
container.register('controller:post', PostController);

container.typeInjection('controller', 'router', 'router:main');

var user = container.lookup('controller:user');
var post = container.lookup('controller:post');

user.router instanceof Router; //=> true
post.router instanceof Router; //=> true

// both controllers share the same router
user.router === post.router; //=> true

Parameters:

type String
property String
fullName String

unregister

(fullName)

Unregister a fullName

1
2
3
4
5
6
7
var container = new Container();
container.register('model:user', User);

container.lookup('model:user') instanceof User //=> true

container.unregister('model:user')
container.lookup('model:user') === undefined //=> true

Parameters:

fullName String

willMergeMixin

private

Moves actions to _actions at extend time. Note that this currently modifies the mixin themselves, which is technically dubious but is practically of little consequence. This may change in the future.

Show:

_options

InheritingDict private

Default: null

_typeOptions

InheritingDict private

actions

Hash

The collection of functions, keyed by name, available on this ActionHandler as action targets.

These functions will be invoked when a matching {{action}} is triggered from within a template and the application's current route is this route.

Actions can also be invoked from other parts of your application via ActionHandler#send.

The actions hash will inherit action handlers from the actions hash defined on extended parent classes or mixins rather than just replace the entire hash, e.g.:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
App.CanDisplayBanner = Ember.Mixin.create({
  actions: {
    displayBanner: function(msg) {
      // ...
    }
  }
});

App.WelcomeRoute = Ember.Route.extend(App.CanDisplayBanner, {
  actions: {
    playMusic: function() {
      // ...
    }
  }
});

// `WelcomeRoute`, when active, will be able to respond
// to both actions, since the actions hash is merged rather
// then replaced when extending mixins / parent classes.
this.send('displayBanner');
this.send('playMusic');

Within a Controller, Route, View or Component's action handler, the value of the this context is the Controller, Route, View or Component object:

1
2
3
4
5
6
7
8
9
App.SongRoute = Ember.Route.extend({
  actions: {
    myAction: function() {
      this.controllerFor("song");
      this.transitionTo("other.route");
      ...
    }
  }
});

It is also possible to call this._super() from within an action handler if it overrides a handler defined on a parent class or mixin:

Take for example the following routes:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
App.DebugRoute = Ember.Mixin.create({
  actions: {
    debugRouteInformation: function() {
      console.debug("trololo");
    }
  }
});

App.AnnoyingDebugRoute = Ember.Route.extend(App.DebugRoute, {
  actions: {
    debugRouteInformation: function() {
      // also call the debugRouteInformation of mixed in App.DebugRoute
      this._super();

      // show additional annoyance
      window.alert(...);
    }
  }
});

Bubbling

By default, an action will stop bubbling once a handler defined on the actions hash handles it. To continue bubbling the action, you must return true from the handler:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
App.Router.map(function() {
  this.resource("album", function() {
    this.route("song");
  });
});

App.AlbumRoute = Ember.Route.extend({
  actions: {
    startPlaying: function() {
    }
  }
});

App.AlbumSongRoute = Ember.Route.extend({
  actions: {
    startPlaying: function() {
      // ...

      if (actionShouldAlsoBeTriggeredOnParentRoute) {
        return true;
      }
    }
  }
});

Default: null

cache

InheritingDict

children

Array

Default: []

controllers

Object

Stores the instances of other controllers available from within this controller. Any controller listed by name in the needs property will be accessible by name through this property.

1
2
3
4
5
6
7
App.CommentsController = Ember.ArrayController.extend({
  needs: ['post'],
  postTitle: function(){
    var currentPost = this.get('controllers.post'); // instance of App.PostController
    return currentPost.get('title');
  }.property('controllers.post.title')
});

Default: null

dict

Object

Object used to store the current nodes data.

Default: Object

injections

Object

Default: {}

needs

Array

An array of other controller objects available inside instances of this controller via the controllers property:

For example, when you define a controller:

1
2
3
App.CommentsController = Ember.ArrayController.extend({
  needs: ['post']
});

The application's single instance of these other controllers are accessible by name through the controllers property:

1
this.get('controllers.post'); // instance of App.PostController

Given that you have a nested controller (nested resource):

1
2
App.CommentsNewController = Ember.ObjectController.extend({
});

When you define a controller that requires access to a nested one:

1
2
3
App.IndexController = Ember.ObjectController.extend({
  needs: ['commentsNew']
});

You will be able to get access to it:

1
this.get('controllers.commentsNew'); // instance of App.CommentsNewController

This is only available for singleton controllers.

Default: []

parent

InheritingDict

Default: null

registry

InheritingDict

resolver

function

target

The object to which actions from the view should be sent.

For example, when a Handlebars template uses the {{action}} helper, it will attempt to send the action to the view's controller's target.

By default, the value of the target property is set to the router, and is injected when a controller is instantiated. This injection is defined in Ember.Application#buildContainer, and is applied as part of the applications initialization process. It can also be set after a controller has been instantiated, for instance when using the render helper in a template, or when a controller is used as an itemController. In most cases the target property will automatically be set to the logical consumer of actions for the controller.

Default: null

typeInjections

InheritingDict