#

API Docs for: v2.11.1
Show: Inherited Protected Private Deprecated

# Ember.ControllerMixin Class

Uses

- Ember.ActionHandler

Defined in: `packages/ember-runtime/lib/mixins/controller.js:5`
Module: ember-routing
Parent Module: ember

- Index
- Methods
- Properties

## Item Index

### Methods

- _qpChanged
- _qpDelegate
- replaceRoute
- send
- transitionToRoute

### Properties

- actions
- model
- queryParams
- target

## Methods

### `_qpChanged`

() private

Defined in `packages/ember-routing/lib/ext/controller.js:45`

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

Defined in `packages/ember-routing/lib/ext/controller.js:24`

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

Defined in `packages/ember-routing/lib/ext/controller.js:145`

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.

    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:

    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:

    aController.replaceRoute('blogPost', 1);

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

    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.

    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

Inherited from Ember.ActionHandler: `packages/ember-runtime/lib/mixins/action_handler.js:148`

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 ```js 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

Defined in `packages/ember-routing/lib/ext/controller.js:66`

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

    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:

    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:

    aController.transitionToRoute('blogPost', 1);

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

    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.

    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.

    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

  optional hash with a queryParams property containing a mapping of query parameters

## Properties

### `actions`

Object public

Inherited from Ember.ActionHandler: `packages/ember-runtime/lib/mixins/action_handler.js:27`

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.: ```js 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: ```js 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: ```js 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: ```js 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`

Unknown public

Provided by the ember module.

Defined in `packages/ember-runtime/lib/mixins/controller.js:35`

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

### `queryParams`

Unknown public

Defined in `packages/ember-routing/lib/ext/controller.js:13`

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`

Unknown public

Provided by the ember module.

Defined in `packages/ember-runtime/lib/mixins/controller.js:15`

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