Ember.ControllerMixin Class packages/ember-runtime/lib/mixins/controller.js:6


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

Show:

_calculateCacheKey

private

_qpChanged

private

_updateCacheParams

private

controllerFor

deprecated

Use needs instead

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

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

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.

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:

_cacheMeta

private

_normalizedQueryParams

private

_qpDelegate

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

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

model

public

The controller's current model. When retrieving or modifying a controller's model, this property should be used instead of the content property.

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: []

queryParams

public

Defines which query parameters the controller accepts. If you give the names ['category','page'] it will bind the values of these query parameters to the variables this.category and this.page

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