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


PRIVATE

Show:

Methods

Properties

Show:

_qpChanged

private

During Ember.Route#setup observers are created to invoke this method when any of the query params declared in Ember.Controller#queryParams property are changed.

When invoked this method uses the currently active query param update delegate (see Ember.Controller.prototype._qpDelegate for details) and invokes it with the QP key/value being changed.

_qpDelegate

private

This property is updated to various different callback functions depending on the current "state" of the backing route. It is used by Ember.Controller.prototype._qpChanged.

The methods backing each state can be found in the Ember.Route.prototype._qp computed property return value (the .states property). The current values are listed here for the sanity of future travelers:

  • inactive - This state is used when this controller instance is not part of the active route heirarchy. Set in Ember.Route.prototype._reset (a router.js microlib hook) and Ember.Route.prototype.actions.finalizeQueryParamChange.
  • active - This state is used when this controller instance is part of the active route heirarchy. Set in Ember.Route.prototype.actions.finalizeQueryParamChange.
  • allowOverrides - This state is used in Ember.Route.prototype.setup (route.js microlib hook).

replaceRoute

(name, models) public

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 route tree.

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

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.

send

(actionName, context) public

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() {
       this.send('playMusic', 'theme.mp3');
    },
    playMusic(track) {
      // ...
    }
  }
});

Parameters:

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

transitionToRoute

(name, models, options) public

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 route tree.

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

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
3
aController.transitionToRoute('/');
aController.transitionToRoute('/blog/post/1/comment/13');
aController.transitionToRoute('/blog/posts?sort=title');

An options hash with a queryParams property may be provided as the final argument to add query parameters to the destination URL.

1
2
3
4
5
6
aController.transitionToRoute('blogPost', 1, {
  queryParams: { showComments: 'true' }
});

// if you just want to transition the query parameters without changing the route
aController.transitionToRoute({ queryParams: { sort: 'date' } });

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.
options [Object]
optional hash with a queryParams property containing a mapping of query parameters
Show:

actions

Object public

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(msg) {
      // ...
    }
  }
});

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

// `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 or Component's action handler, the value of the this context is the Controller, Route or Component object:

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

It is also possible to call this._super(...arguments) 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() {
      console.debug("trololo");
    }
  }
});

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

      // 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.route("album", function() {
    this.route("song");
  });
});

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

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

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

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.

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

public

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 applied as part of the application's initialization process. In most cases the target property will automatically be set to the logical consumer of actions for the controller.

Default: null