Ember.Route Class
The Ember.Route
class is used to define individual routes. Refer to
the routing guide for documentation.
Item Index
Methods
- _lazyInjections
- _onLookup
- _populateQPMeta
- _reset
- _scheduledDestroy
- _setRouteName
- _stashNames
- _updatingQPChanged
- activate
- addObserver
- afterModel
- beforeModel
- beginPropertyChanges
- cacheFor
- contextDidChange
- controllerFor
- deactivate
- decrementProperty
- deserialize
- deserializeQueryParam
- destroy
- disconnectOutlet
- endPropertyChanges
- enter
- exit
- findModel
- generateController
- get
- getProperties
- getWithDefault
- has
- hasObserverFor
- incrementProperty
- init
- intermediateTransitionTo
- model
- modelFor
- notifyPropertyChange
- off
- on
- one
- paramsFor
- propertyDidChange
- propertyWillChange
- queryParamsDidChange
- redirect
- refresh
- removeObserver
- render
- renderTemplate
- reopen
- reopenClass
- replaceWith
- resetController
- send
- serialize
- serializeQueryParam
- serializeQueryParamKey
- set
- setProperties
- setup
- setupController
- store
- teardownViews
- toggleProperty
- toString
- transitionTo
- trigger
- willDestroy
Properties
Methods
_lazyInjections
()
Object
private
Returns:
_onLookup
()
private
_populateQPMeta
()
private
Populates the QP meta information in the BucketCache.
_reset
()
private
_scheduledDestroy
()
private
destroy
method.
_setRouteName
-
name
Sets the name for this route, including a fully resolved name for routes inside engines.
Parameters:
-
name
String
_stashNames
()
private
_updatingQPChanged
()
private
activate
()
public
This hook is executed when the router enters the route. It is not executed when the model for the route changes.
addObserver
-
key
-
target
-
method
context
parameter:
`
javascript
fooDidChange: function(sender, key, value, rev) { };
`
The sender is the object that changed. The key is the property that
changes. The value property is currently reserved and unused. The rev
is the last property revision of the object when it changed, which you can
use to detect if the key value has really changed or not.
If you pass a context
parameter, the context will be passed before the
revision like so:
`
javascript
fooDidChange: function(sender, key, value, context, rev) { };
`
Usually you will not need the value, context or revision parameters at
the end. In this case, it is common to write observer methods that take
only a sender and key value as parameters or, if you aren't interested in
any of these values, to write an observer that has no parameters at all.
afterModel
-
resolvedModel
-
transition
This hook is called after this route's model has resolved.
It follows identical async/promise semantics to beforeModel
but is provided the route's resolved model in addition to
the transition
, and is therefore suited to performing
logic that can only take place after the model has already
resolved.
import Ember from 'ember';
export default Ember.Route.extend({
afterModel(posts, transition) {
if (posts.get('length') === 1) {
this.transitionTo('post.show', posts.get('firstObject'));
}
}
});
Refer to documentation for beforeModel
for a description
of transition-pausing semantics when a promise is returned
from this hook.
Parameters:
-
resolvedModel
Objectthe value returned from
model
, or its resolved value if it was a promise -
transition
Transition
Returns:
if the value returned from this hook is a promise, the transition will pause until the transition resolves. Otherwise, non-promise return values are not utilized in any way.
beforeModel
-
transition
This hook is the first of the route entry validation hooks
called when an attempt is made to transition into a route
or one of its children. It is called before model
and
afterModel
, and is appropriate for cases when:
- A decision can be made to redirect elsewhere without needing to resolve the model first.
- Any async operations need to occur first before the model is attempted to be resolved.
This hook is provided the current transition
attempt
as a parameter, which can be used to .abort()
the transition,
save it for a later .retry()
, or retrieve values set
on it from a previous hook. You can also just call
this.transitionTo
to another route to implicitly
abort the transition
.
You can return a promise from this hook to pause the transition until the promise resolves (or rejects). This could be useful, for instance, for retrieving async code from the server that is required to enter a route.
Parameters:
-
transition
Transition
Returns:
if the value returned from this hook is a promise, the transition will pause until the transition resolves. Otherwise, non-promise return values are not utilized in any way.
beginPropertyChanges
()
Ember.Observable
private
endPropertyChanges()
to deliver the deferred change notifications and end
deferring.
Returns:
cacheFor
-
keyName
Parameters:
-
keyName
String
Returns:
contextDidChange
()
private
Called when the context is changed by router.js.
controllerFor
-
name
Returns the resolved model of the current route, or a parent (or any ancestor) route in a route hierarchy.
The controller instance must already have been created, either through entering the
associated route or using generateController
.
import Ember from 'ember';
export default Ember.Route.extend({
setupController(controller, post) {
this._super(controller, post);
this.controllerFor('posts').set('currentPost', post);
}
});
Parameters:
-
name
Stringthe name of the route or controller
Returns:
deactivate
()
public
This hook is executed when the router completely exits this route. It is not executed when the model for the route changes.
decrementProperty
-
keyName
-
decrement
`
javascript
player.decrementProperty('lives');
orc.decrementProperty('health', 5);
`
Parameters:
-
keyName
StringThe name of the property to decrement -
decrement
NumberThe amount to decrement by. Defaults to 1
Returns:
deserialize
-
params
-
transition
Parameters:
-
params
Objectthe parameters extracted from the URL
-
transition
Transition
Returns:
the model for this route.
Router.js hook.
deserializeQueryParam
-
value
-
urlKey
-
defaultValueType
Deserializes value of the query parameter based on defaultValueType
destroy
()
Ember.Object
public
isDestroyed
flag and removing its
metadata, which effectively destroys observers and bindings.
If you try to set a property on a destroyed object, an exception will be
raised.
Note that destruction is scheduled for the end of the run loop and does not
happen immediately. It will set an isDestroying flag immediately.
Returns:
receiver
disconnectOutlet
-
options
Disconnects a view that has been rendered into an outlet.
You may pass any or all of the following options to disconnectOutlet
:
outlet
: the name of the outlet to clear (default: 'main')parentView
: the name of the view containing the outlet to clear (default: the view rendered by the parent route)
Example:
import Ember from 'ember';
export default App.Route.extend({
actions: {
showModal(evt) {
this.render(evt.modalName, {
outlet: 'modal',
into: 'application'
});
},
hideModal(evt) {
this.disconnectOutlet({
outlet: 'modal',
parentView: 'application'
});
}
}
});
Alternatively, you can pass the outlet
name directly as a string.
Example:
import Ember from 'ember';
export default App.Route.extend({
actions: {
showModal(evt) {
// ...
},
hideModal(evt) {
this.disconnectOutlet('modal');
}
}
});
Parameters:
-
options
Object | Stringthe options hash or outlet name
endPropertyChanges
()
Ember.Observable
private
beginPropertyChanges()
at the beginning of the changes to defer change
notifications. When you are done making changes, call this method to
deliver the deferred change notifications and end deferring.
Returns:
enter
()
private
exit
()
private
findModel
-
type
-
value
Parameters:
-
type
Stringthe model type
-
value
Objectthe value passed to find
generateController
-
name
Generates a controller for a route.
Example
import Ember from 'ember';
export default Ember.Route.extend({
setupController(controller, post) {
this._super(controller, post);
this.generateController('posts');
}
});
Parameters:
-
name
Stringthe name of the controller
get
-
keyName
object[keyName]
or object.keyName
,
however it supports both computed properties and the unknownProperty
handler.
Because get
unifies the syntax for accessing all these kinds
of properties, it can make many refactorings easier, such as replacing a
simple property with a computed property, or vice versa.
### Computed Properties
Computed properties are methods defined with the property
modifier
declared at the end, such as:
`
javascript
fullName: Ember.computed('firstName', 'lastName', function() {
return this.get('firstName') + ' ' + this.get('lastName');
})
`
When you call get
on a computed property, the function will be
called and the return value will be returned instead of the function
itself.
### Unknown Properties
Likewise, if you try to call get
on a property whose value is
undefined
, the unknownProperty()
method will be called on the object.
If this method returns any value other than undefined
, it will be returned
instead. This allows you to implement "virtual" properties that are
not defined upfront.
Parameters:
-
keyName
StringThe property to retrieve
Returns:
getProperties
-
list
getProperties
with a list of strings or an array:
`
javascript
record.getProperties('firstName', 'lastName', 'zipCode');
// { firstName: 'John', lastName: 'Doe', zipCode: '10011' }
`
is equivalent to:
`
javascript
record.getProperties(['firstName', 'lastName', 'zipCode']);
// { firstName: 'John', lastName: 'Doe', zipCode: '10011' }
`
Parameters:
-
list
String... | Arrayof keys to get
Returns:
getWithDefault
-
keyName
-
defaultValue
undefined
.
`
javascript
person.getWithDefault('lastName', 'Doe');
`
Parameters:
-
keyName
StringThe name of the property to retrieve -
defaultValue
ObjectThe value to return if the property value is undefined
Returns:
has
-
name
Parameters:
-
name
StringThe name of the event
Returns:
hasObserverFor
-
key
true
if the object currently has observers registered for a
particular key. You can use this method to potentially defer performing
an expensive action until someone begins observing a particular property
on the object.
Parameters:
-
key
StringKey to check
Returns:
incrementProperty
-
keyName
-
increment
`
javascript
person.incrementProperty('age');
team.incrementProperty('score', 2);
`
Parameters:
-
keyName
StringThe name of the property to increment -
increment
NumberThe amount to increment by. Defaults to 1
Returns:
init
()
public
`
javascript
const Person = Ember.Object.extend({
init() {
alert(Name is ${this.get('name')}
);
}
});
let steve = Person.create({
name: "Steve"
});
// alerts 'Name is Steve'.
`
NOTE: If you do override init
for a framework class like Ember.View
,
be sure to call this._super(...arguments)
in your
init
declaration! If you don't, Ember may not have an opportunity to
do important setup work, and you'll see strange behavior in your
application.
intermediateTransitionTo
-
name
-
models
Perform a synchronous transition into another route without attempting
to resolve promises, update the URL, or abort any currently active
asynchronous transitions (i.e. regular transitions caused by
transitionTo
or URL changes).
This method is handy for performing intermediate transitions on the
way to a final destination route, and is called internally by the
default implementations of the error
and loading
handlers.
Parameters:
-
name
Stringthe name of the route
-
models
...Objectthe model(s) to be used while transitioning to the route.
model
-
params
-
transition
A hook you can implement to convert the URL into the model for this route.
// ...
Router.map(function() {
this.route('post', { path: '/posts/:post_id' });
});
export default Router;
The model for the post
route is store.findRecord('post', params.post_id)
.
By default, if your route has a dynamic segment ending in _id
:
- The model class is determined from the segment (
post_id
's class isApp.Post
) - The find method is called on the model class with the value of the dynamic segment.
Note that for routes with dynamic segments, this hook is not always
executed. If the route is entered through a transition (e.g. when
using the link-to
Handlebars helper or the transitionTo
method
of routes), and a model context is already provided this hook
is not called.
A model context does not include a primitive string or number, which does cause the model hook to be called.
Routes without dynamic segments will always execute the model hook.
// no dynamic segment, model hook always called
this.transitionTo('posts');
// model passed in, so model hook not called
thePost = store.findRecord('post', 1);
this.transitionTo('post', thePost);
// integer passed in, model hook is called
this.transitionTo('post', 1);
// model id passed in, model hook is called
// useful for forcing the hook to execute
thePost = store.findRecord('post', 1);
this.transitionTo('post', thePost.id);
This hook follows the asynchronous/promise semantics
described in the documentation for beforeModel
. In particular,
if a promise returned from model
fails, the error will be
handled by the error
hook on Ember.Route
.
Example
import Ember from 'ember';
export default Ember.Route.extend({
model(params) {
return this.store.findRecord('post', params.post_id);
}
});
Parameters:
-
params
Objectthe parameters extracted from the URL
-
transition
Transition
Returns:
the model for this route. If a promise is returned, the transition will pause until the promise resolves, and the resolved value of the promise will be used as the model for this route.
modelFor
-
name
Returns the resolved model of a parent (or any ancestor) route
in a route hierarchy. During a transition, all routes
must resolve a model object, and if a route
needs access to a parent route's model in order to
resolve a model (or just reuse the model from a parent),
it can call this.modelFor(theNameOfParentRoute)
to
retrieve it. If the ancestor route's model was a promise,
its resolved result is returned.
Example
// ...
Router.map(function() {
this.route('post', { path: '/post/:post_id' }, function() {
this.route('comments', { resetNamespace: true });
});
});
export default Router;
import Ember from 'ember';
export default Ember.Route.extend({
afterModel() {
this.set('post', this.modelFor('post'));
}
});
Parameters:
-
name
Stringthe name of the route
Returns:
the model object
notifyPropertyChange
-
keyName
propertyWillChange
and propertyDidChange
in
succession.
Parameters:
-
keyName
StringThe property key to be notified about.
Returns:
off
-
name
-
target
-
method
Parameters:
Returns:
on
-
name
-
[target]
-
method
`
javascript
person.on('didLoad', function() {
// fired once the person has loaded
});
`
An optional target can be passed in as the 2nd argument that will
be set as the "this" for the callback. This is a good way to give your
function access to the object triggering the event. When the target
parameter is used the callback becomes the third argument.
Parameters:
Returns:
one
-
name
-
[target]
-
method
`one
` when
you only care about the first time an event has taken place.
This function takes an optional 2nd argument that will become the "this"
value for the callback. If this argument is passed then the 3rd argument
becomes the function.
Parameters:
Returns:
paramsFor
-
name
Returns a hash containing the parameters of an ancestor route.
Example
// ...
Router.map(function() {
this.route('member', { path: ':name' }, function() {
this.route('interest', { path: ':interest' });
});
});
export default Ember.Route.extend({
queryParams: {
memberQp: { refreshModel: true }
}
});
export default Ember.Route.extend({
queryParams: {
interestQp: { refreshModel: true }
},
model() {
return this.paramsFor('member');
}
});
If we visit /turing/maths?memberQp=member&interestQp=interest
the model for
the member.interest
route is hash with:
name
:turing
memberQp
:member
Parameters:
-
name
String
Returns:
hash containing the parameters of the route name
propertyDidChange
-
keyName
get()
or set()
on it. In this case, you can use this
method and propertyWillChange()
instead. Calling these two methods
together will notify all observers that the property has potentially
changed value.
Note that you must always call propertyWillChange
and propertyDidChange
as a pair. If you do not, it may get the property change groups out of
order and cause notifications to be delivered more often than you would
like.
Parameters:
-
keyName
StringThe property key that has just changed.
Returns:
propertyWillChange
-
keyName
get()
or set()
on it. In this case, you can use this
method and propertyDidChange()
instead. Calling these two methods
together will notify all observers that the property has potentially
changed value.
Note that you must always call propertyWillChange
and propertyDidChange
as a pair. If you do not, it may get the property change groups out of
order and cause notifications to be delivered more often than you would
like.
Parameters:
-
keyName
StringThe property key that is about to change.
Returns:
queryParamsDidChange
-
changed
-
totalPresent
-
removed
This action is called when one or more query params have changed. Bubbles.
Parameters:
-
changed
ObjectKeys are names of query params that have changed.
-
totalPresent
ObjectKeys are names of query params that are currently set.
-
removed
ObjectKeys are names of query params that have been removed.
Returns:
redirect
-
model
-
transition
A hook you can implement to optionally redirect to another route.
If you call this.transitionTo
from inside of this hook, this route
will not be entered in favor of the other hook.
redirect
and afterModel
behave very similarly and are
called almost at the same time, but they have an important
distinction in the case that, from one of these hooks, a
redirect into a child route of this route occurs: redirects
from afterModel
essentially invalidate the current attempt
to enter this route, and will result in this route's beforeModel
,
model
, and afterModel
hooks being fired again within
the new, redirecting transition. Redirects that occur within
the redirect
hook, on the other hand, will not cause
these hooks to be fired again the second time around; in
other words, by the time the redirect
hook has been called,
both the resolved model and attempted entry into this route
are considered to be fully validated.
Parameters:
-
model
Objectthe model for this route
-
transition
Transitionthe transition object associated with the current transition
refresh
()
Transition
public
Refresh the model on this route and any child routes, firing the
beforeModel
, model
, and afterModel
hooks in a similar fashion
to how routes are entered when transitioning in from other route.
The current route params (e.g. article_id
) will be passed in
to the respective model hooks, and if a different model is returned,
setupController
and associated route hooks will re-fire as well.
An example usage of this method is re-querying the server for the latest information using the same parameters as when the route was first entered.
Note that this will cause model
hooks to fire even on routes
that were provided a model object when the route was initially
entered.
Returns:
the transition object associated with this attempted transition
removeObserver
-
key
-
target
-
method
addObserver()
and your
target will no longer receive notifications.
render
-
name
-
[options]
render
is used to render a template into a region of another template
(indicated by an {{outlet}}
). render
is used both during the entry
phase of routing (via the renderTemplate
hook) and later in response to
user interaction.
For example, given the following minimal router and templates:
// ...
Router.map(function() {
this.route('photos');
});
export default Router;
<!-- application.hbs -->
<div class='something-in-the-app-hbs'>
{{outlet "anOutletName"}}
</div>
<!-- photos.hbs -->
<h1>Photos</h1>
You can render photos.hbs
into the "anOutletName"
outlet of
application.hbs
by calling render
:
import Ember from 'ember';
export default Ember.Route.extend({
renderTemplate() {
this.render('photos', {
into: 'application',
outlet: 'anOutletName'
})
}
});
render
additionally allows you to supply which controller
and
model
objects should be loaded and associated with the rendered template.
import Ember from 'ember';
export default Ember.Route.extend({
renderTemplate(controller, model){
this.render('posts', { // the template to render, referenced by name
into: 'application', // the template to render into, referenced by name
outlet: 'anOutletName', // the outlet inside options.template
to render into.
controller: 'someControllerName', // the controller to use for this template, referenced by name
model: model // the model to set on options.controller
.
})
}
});
The string values provided for the template name, and controller will eventually pass through to the resolver for lookup. See Ember.Resolver for how these are mapped to JavaScript objects in your application. The template to render into needs to be related to either the current route or one of its ancestors.
Not all options need to be passed to render
. Default values will be used
based on the name of the route specified in the router or the Route's
controllerName
and templateName
properties.
For example:
// ...
Router.map(function() {
this.route('index');
this.route('post', { path: '/posts/:post_id' });
});
export default Router;
import Ember from 'ember';
export default Ember.Route.extend({
renderTemplate() {
this.render(); // all defaults apply
}
});
The name of the route, defined by the router, is post
.
The following equivalent default options will be applied when
the Route calls render
:
this.render('post', { // the template name associated with 'post' Route
into: 'application', // the parent route to 'post' Route
outlet: 'main', // {{outlet}} and {{outlet 'main'}} are synonymous,
controller: 'post', // the controller associated with the 'post' Route
})
By default the controller's model
will be the route's model, so it does not
need to be passed unless you wish to change which model is being used.
Parameters:
-
name
Stringthe name of the template to render
-
[options]
Object optionalthe options
-
[into]
String optionalthe template to render into, referenced by name. Defaults to the parent template
-
[outlet]
String optionalthe outlet inside
options.template
to render into. Defaults to 'main' -
[controller]
String | Object optionalthe controller to use for this template, referenced by name or as a controller instance. Defaults to the Route's paired controller
-
[model]
Object optionalthe model object to set on
options.controller
. Defaults to the return value of the Route's model hook
-
renderTemplate
-
controller
-
model
A hook you can use to render the template for the current route.
This method is called with the controller for the current route and the
model supplied by the model
hook. By default, it renders the route's
template, configured with the controller for the route.
This method can be overridden to set up and render additional or alternative templates.
import Ember from 'ember';
export default Ember.Route.extend({
renderTemplate(controller, model) {
let favController = this.controllerFor('favoritePost');
// Render the favoritePost
template into
// the outlet posts
, and display the favoritePost
// controller.
this.render('favoritePost', {
outlet: 'posts',
controller: favController
});
}
});
Parameters:
-
controller
Objectthe route's controller
-
model
Objectthe route's model
reopen
()
public
`
javascript
const MyObject = Ember.Object.extend({
name: 'an object'
});
o = MyObject.create();
o.get('name'); // 'an object'
MyObject.reopen({
say(msg){
console.log(msg);
}
})
o2 = MyObject.create();
o2.say("hello"); // logs "hello"
o.say("goodbye"); // logs "goodbye"
`
To add functions and properties to the constructor itself,
see reopenClass
reopenClass
()
public
`
javascript
const MyObject = Ember.Object.extend({
name: 'an object'
});
MyObject.reopenClass({
canBuild: false
});
MyObject.canBuild; // false
o = MyObject.create();
`
In other words, this creates static properties and functions for the class.
These are only available on the class and not on any instance of that class.
`
javascript
const Person = Ember.Object.extend({
name: "",
sayHello() {
alert("Hello. My name is " + this.get('name'));
}
});
Person.reopenClass({
species: "Homo sapiens",
createPerson(newPersonsName){
return Person.create({
name:newPersonsName
});
}
});
let tom = Person.create({
name: "Tom Dale"
});
let yehuda = Person.createPerson("Yehuda Katz");
tom.sayHello(); // "Hello. My name is Tom Dale"
yehuda.sayHello(); // "Hello. My name is Yehuda Katz"
alert(Person.species); // "Homo sapiens"
`
Note that species
and createPerson
are *not* valid on the tom
and yehuda
variables. They are only valid on Person
.
To add functions and properties to instances of
a constructor by extending the constructor's prototype
see reopen
replaceWith
-
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 transitionTo
in all other respects. See
'transitionTo' for additional information regarding multiple models.
Example
// ...
Router.map(function() {
this.route('index');
this.route('secret');
});
export default Router;
import Ember from 'ember';
export default Ember.Route.extend({
afterModel() {
if (!authorized()){
this.replaceWith('index');
}
}
});
Parameters:
-
name
Stringthe name of the route or a URL
-
models
...Objectthe model(s) or identifier(s) to be used while transitioning to the route.
Returns:
the transition object associated with this attempted transition
resetController
-
controller
-
isExiting
-
transition
A hook you can use to reset controller values either when the model changes or the route is exiting.
import Ember from 'ember';
export default Ember.Route.extend({
resetController(controller, isExiting, transition) {
if (isExiting) {
controller.set('page', 1);
}
}
});
Parameters:
-
controller
Controllerinstance
-
isExiting
Boolean -
transition
Object
send
-
name
-
args
Sends an action to the router, which will delegate it to the currently
active route hierarchy per the bubbling rules explained under actions
.
Example
// ...
Router.map(function() {
this.route('index');
});
export default Router;
import Ember from 'ember';
export default Ember.Route.extend({
actions: {
track(arg) {
console.log(arg, 'was clicked');
}
}
});
import Ember from 'ember';
export default Ember.Route.extend({
actions: {
trackIfDebug(arg) {
if (debug) {
this.send('track', arg);
}
}
}
});
Parameters:
-
name
Stringthe name of the action to trigger
-
args
...
serialize
-
model
-
params
A hook you can implement to convert the route's model into parameters for the URL.
// ...
Router.map(function() {
this.route('post', { path: '/posts/:post_id' });
});
import Ember from 'ember';
export default Ember.Route.extend({
model(params) {
// the server returns { id: 12 }
return Ember.$.getJSON('/posts/' + params.post_id);
},
serialize(model) {
// this will make the URL /posts/12
return { post_id: model.id };
}
});
The default serialize
method will insert the model's id
into the
route's dynamic segment (in this case, :post_id
) if the segment contains '_id'.
If the route has multiple dynamic segments or does not contain '_id', serialize
will return Ember.getProperties(model, params)
This method is called when transitionTo
is called with a context
in order to populate the URL.
Parameters:
-
model
Objectthe routes model
-
params
Arrayan Array of parameter names for the current route (in the example,
['post_id']
.
Returns:
the serialized parameters
serializeQueryParam
-
value
-
urlKey
-
defaultValueType
Serializes value of the query parameter based on defaultValueType
serializeQueryParamKey
-
controllerPropertyName
Serializes the query parameter key
Parameters:
-
controllerPropertyName
String
set
-
keyName
-
value
`
javascript
record.set("key", value);
`
This method is generally very similar to calling object["key"] = value
or
object.key = value
, except that it provides support for computed
properties, the setUnknownProperty()
method and property observers.
### Computed Properties
If you try to set a value on a key that has a computed property handler
defined (see the get()
method for an example), then set()
will call
that method, passing both the value and key instead of simply changing
the value itself. This is useful for those times when you need to
implement a property that is composed of one or more member
properties.
### Unknown Properties
If you try to set a value on a key that is undefined in the target
object, then the setUnknownProperty()
handler will be called instead. This
gives you an opportunity to implement complex "virtual" properties that
are not predefined on the object. If setUnknownProperty()
returns
undefined, then set()
will simply set the value on the object.
### Property Observers
In addition to changing the property, set()
will also register a property
change with the object. Unless you have placed this call inside of a
beginPropertyChanges()
and endPropertyChanges(),
any "local" observers
(i.e. observer methods declared on the same object), will be called
immediately. Any "remote" observers (i.e. observer methods declared on
another object) will be placed in a queue and called at a later time in a
coalesced manner.
Parameters:
-
keyName
StringThe property to set -
value
ObjectThe value to set ornull
.
Returns:
setProperties
-
hash
beginPropertyChanges
and endPropertyChanges
batch, so
observers will be buffered.
`
javascript
record.setProperties({ firstName: 'Charles', lastName: 'Jolley' });
`
Parameters:
-
hash
Objectthe hash of keys and values to set
Returns:
setup
()
private
This hook is the entry point for router.js
setupController
-
controller
-
model
A hook you can use to setup the controller for the current route.
This method is called with the controller for the current route and the
model supplied by the model
hook.
By default, the setupController
hook sets the model
property of
the controller to the model
.
If you implement the setupController
hook in your Route, it will
prevent this default behavior. If you want to preserve that behavior
when implementing your setupController
function, make sure to call
_super
:
import Ember from 'ebmer';
export default Ember.Route.extend({
model() {
return this.store.findAll('photo');
},
setupController(controller, model) {
// Call _super for default behavior
this._super(controller, model);
// Implement your custom setup after
this.controllerFor('application').set('showingPhotos', true);
}
});
The provided controller will be one resolved based on the name of this route.
If no explicit controller is defined, Ember will automatically create one.
As an example, consider the router:
// ...
Router.map(function() {
this.route('post', { path: '/posts/:post_id' });
});
export default Router;
For the post
route, a controller named App.PostController
would
be used if it is defined. If it is not defined, a basic Ember.Controller
instance would be used.
Example
import Ember from 'ember';
export default Ember.Route.extend({
setupController(controller, model) {
controller.set('model', model);
}
});
Parameters:
-
controller
Controllerinstance
-
model
Object
store
-
store
Store property provides a hook for data persistence libraries to inject themselves.
By default, this store property provides the exact same functionality previously in the model hook.
Currently, the required interface is:
store.find(modelName, findArguments)
Parameters:
-
store
Object
teardownViews
()
private
toggleProperty
-
keyName
`
javascript
starship.toggleProperty('warpDriveEngaged');
`
Parameters:
-
keyName
StringThe name of the property to toggle
Returns:
toString
()
String
public
toString
typically does, in a generic way for all Ember
objects.
`
javascript
const Person = Ember.Object.extend()
person = Person.create()
person.toString() //=> "`
If the object's class is not defined on an Ember namespace, it will
indicate it is a subclass of the registered superclass:
`
javascript
const Student = Person.extend()
let student = Student.create()
student.toString() //=> "<(subclass of Person):ember1025>"
`
If the method toStringExtension
is defined, its return value will be
included in the output.
`
javascript
const Teacher = Person.extend({
toStringExtension() {
return this.get('fullName');
}
});
teacher = Teacher.create()
teacher.toString(); //=> "`
Returns:
transitionTo
-
name
-
models
-
[options]
Transition the application into another route. The route may be either a single route or route path:
this.transitionTo('blogPosts');
this.transitionTo('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:
this.transitionTo('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:
this.transitionTo('blogPost', 1);
Multiple models will be applied last to first recursively up the route tree.
// ...
Router.map(function() {
this.route('blogPost', { path:':blogPostId' }, function() {
this.route('blogComment', { path: ':blogCommentId' });
});
});
export default Router;
this.transitionTo('blogComment', aPost, aComment);
this.transitionTo('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.
this.transitionTo('/');
this.transitionTo('/blog/post/1/comment/13');
this.transitionTo('/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.
this.transitionTo('blogPost', 1, {
queryParams: { showComments: 'true' }
});
// if you just want to transition the query parameters without changing the route
this.transitionTo({ queryParams: { sort: 'date' } });
See also replaceWith.
Simple Transition Example
// ...
Router.map(function() {
this.route('index');
this.route('secret');
this.route('fourOhFour', { path: '*:' });
});
export default Router;
import Ember from 'ember':
export Ember.Route.extend({
actions: {
moveToSecret(context) {
if (authorized()) {
this.transitionTo('secret', context);
} else {
this.transitionTo('fourOhFour');
}
}
}
});
Transition to a nested route
// ...
Router.map(function() {
this.route('articles', { path: '/articles' }, function() {
this.route('new');
});
});
export default Router;
import Ember from 'ember';
export default Ember.Route.extend({
actions: {
transitionToNewArticle() {
this.transitionTo('articles.new');
}
}
});
Multiple Models Example
// ...
Router.map(function() {
this.route('index');
this.route('breakfast', { path: ':breakfastId' }, function() {
this.route('cereal', { path: ':cerealId' });
});
});
export default Router;
import Ember from 'ember';
export default Ember.Route.extend({
actions: {
moveToChocolateCereal() {
let cereal = { cerealId: 'ChocolateYumminess' };
let breakfast = { breakfastId: 'CerealAndMilk' };
this.transitionTo('breakfast.cereal', breakfast, cereal);
}
}
});
Nested Route with Query String Example
// ...
Router.map(function() {
this.route('fruits', function() {
this.route('apples');
});
});
export default Router;
import Ember from 'ember';
export default Ember.Route.extend({
actions: {
transitionToApples() {
this.transitionTo('fruits.apples', { queryParams: { color: 'red' } });
}
}
});
Parameters:
-
name
Stringthe name of the route or a URL
-
models
...Objectthe model(s) or identifier(s) to be used while transitioning to the route.
-
[options]
Object optionaloptional hash with a queryParams property containing a mapping of query parameters
Returns:
the transition object associated with this attempted transition
trigger
-
name
-
args
`
javascript
person.on('didEat', function(food) {
console.log('person ate some ' + food);
});
person.trigger('didEat', 'broccoli');
// outputs: person ate some broccoli
`
Parameters:
-
name
StringThe name of the event
-
args
Object...Optional arguments to pass on
willDestroy
()
public
Properties
_activeQPChanged
Unknown
private
_names
Unknown
private
_optionsForQueryParam
Unknown
private
_qp
Unknown
private
actions
Object
public
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
concatenatedProperties
Array
public
classNames
property of Ember.View
.
Here is some sample code showing the difference between a concatenated
property and a normal one:
`
javascript
const Bar = Ember.Object.extend({
// Configure which properties to concatenate
concatenatedProperties: ['concatenatedProperty'],
someNonConcatenatedProperty: ['bar'],
concatenatedProperty: ['bar']
});
const FooBar = Bar.extend({
someNonConcatenatedProperty: ['foo'],
concatenatedProperty: ['foo']
});
let fooBar = FooBar.create();
fooBar.get('someNonConcatenatedProperty'); // ['foo']
fooBar.get('concatenatedProperty'); // ['bar', 'foo']
`
This behavior extends to object creation as well. Continuing the
above example:
`
javascript
let fooBar = FooBar.create({
someNonConcatenatedProperty: ['baz'],
concatenatedProperty: ['baz']
})
fooBar.get('someNonConcatenatedProperty'); // ['baz']
fooBar.get('concatenatedProperty'); // ['bar', 'foo', 'baz']
`
Adding a single property that is not an array will just add it in the array:
`
javascript
let fooBar = FooBar.create({
concatenatedProperty: 'baz'
})
view.get('concatenatedProperty'); // ['bar', 'foo', 'baz']
`
Using the concatenatedProperties
property, we can tell Ember to mix the
content of the properties.
In Ember.Component
the classNames
, classNameBindings
and
attributeBindings
properties are concatenated.
This feature is available for you to use throughout the Ember object model,
although typical app developers are likely to use it infrequently. Since
it changes expectations about behavior of properties, you should properly
document its usage in each individual concatenated property (to not
mislead your users to think they can override the property in a subclass).
Default: null
controller
Ember.Controller
public
The controller associated with this route.
Example
import Ember from 'ember';
export default Ember.Route.extend({
actions: {
willTransition(transition) {
if (this.controller.get('userHasEnteredData') &&
!confirm('Are you sure you want to abandon progress?')) {
transition.abort();
} else {
// Bubble the willTransition
action so that
// parent routes can decide whether or not to abort.
return true;
}
}
}
});
controllerName
String
public
The name of the controller to associate with this route.
By default, Ember will lookup a route's controller that matches the name
of the route (i.e. App.PostController
for App.PostRoute
). However,
if you would like to define a specific controller to use, you can do so
using this property.
This is useful in many ways, as the controller specified will be:
- passed to the
setupController
method. - used as the controller for the template being rendered by the route.
- returned from a call to
controllerFor
for the route.
Default: null
isDestroyed
Unknown
public
true
the observers and bindings were already
removed by the effect of calling the destroy()
method.
Default: false
isDestroying
Unknown
public
destroy()
method has been called.
The object stays intact until the end of the run loop at which point
the isDestroyed
flag is set.
Default: false
mergedProperties
Array
public
queryParams
property of routes.
Here is some sample code showing the difference between a merged
property and a normal one:
`
javascript
const Bar = Ember.Object.extend({
// Configure which properties are to be merged
mergedProperties: ['mergedProperty'],
someNonMergedProperty: {
nonMerged: 'superclass value of nonMerged'
},
mergedProperty: {
page: {replace: false},
limit: {replace: true}
}
});
const FooBar = Bar.extend({
someNonMergedProperty: {
completelyNonMerged: 'subclass value of nonMerged'
},
mergedProperty: {
limit: {replace: false}
}
});
let fooBar = FooBar.create();
fooBar.get('someNonMergedProperty');
// => { completelyNonMerged: 'subclass value of nonMerged' }
//
// Note the entire object, including the nonMerged property of
// the superclass object, has been replaced
fooBar.get('mergedProperty');
// => {
// page: {replace: false},
// limit: {replace: false}
// }
//
// Note the page remains from the superclass, and the
// limit
property's value of false
has been merged from
// the subclass.
`
This behavior is not available during object create
calls. It is only
available at extend
time.
In Ember.Route
the queryParams
property is merged.
This feature is available for you to use throughout the Ember object model,
although typical app developers are likely to use it infrequently. Since
it changes expectations about behavior of properties, you should properly
document its usage in each individual merged property (to not
mislead your users to think they can override the property in a subclass).
Default: null
queryParams
Object
public
Configuration hash for this route's queryParams. The possible
configuration options and their defaults are as follows
(assuming a query param whose controller property is page
):
queryParams: {
page: {
// By default, controller query param properties don't
// cause a full transition when they are changed, but
// rather only cause the URL to update. Setting
// refreshModel
to true will cause an "in-place"
// transition to occur, whereby the model hooks for
// this route (and any child routes) will re-fire, allowing
// you to reload models (e.g., from the server) using the
// updated query param values.
refreshModel: false,
// By default, changes to controller query param properties
// cause the URL to update via pushState
, which means an
// item will be added to the browser's history, allowing
// you to use the back button to restore the app to the
// previous state before the query param property was changed.
// Setting replace
to true will use replaceState
(or its
// hash location equivalent), which causes no browser history
// item to be added. This options name and default value are
// the same as the link-to
helper's replace
option.
replace: false,
// By default, the query param URL key is the same name as
// the controller property name. Use as
to specify a
// different URL key.
as: 'page'
}
}
routeName
String
public
The name of the route, dot-delimited.
For example, a route found at app/routes/posts/post.js
will have
a routeName
of posts.post
.
templateName
String
public
The name of the template to use by default when rendering this routes template.
import Ember from 'ember';
export default Ember.Route.extend({
templateName: 'posts/list'
});
import PostsList from '../posts/list';
export default PostsList.extend();
import PostsList from '../posts/list';
export default PostsList.extend();
Default: null
Events
activate
public
This event is triggered when the router enters the route. It is not executed when the model for the route changes.
import Ember from 'ember';
export default Ember.Route.extend({
collectAnalytics: Ember.on('activate', function(){
collectAnalytics();
})
});
deactivate
public
This event is triggered when the router completely exits this route. It is not executed when the model for the route changes.
import Ember from 'ember';
export default Ember.Route.extend({
trackPageLeaveAnalytics: Ember.on('deactivate', function(){
trackPageLeaveAnalytics();
})
});
didTransition
public
The didTransition
action is fired after a transition has
successfully been completed. This occurs after the normal model
hooks (beforeModel
, model
, afterModel
, setupController
)
have resolved. The didTransition
action has no arguments,
however, it can be useful for tracking page views or resetting
state on the controller.
import Ember from 'ember';
export default Ember.Route.extend({
actions: {
didTransition() {
this.controller.get('errors.base').clear();
return true; // Bubble the didTransition event
}
}
});
error
public
When attempting to transition into a route, any of the hooks
may return a promise that rejects, at which point an error
action will be fired on the partially-entered routes, allowing
for per-route error handling logic, or shared error handling
logic defined on a parent route.
Here is an example of an error handler that will be invoked for rejected promises from the various hooks on the route, as well as any unhandled errors from child routes:
import Ember from 'ember';
export default Ember.Route.extend({
beforeModel() {
return Ember.RSVP.reject('bad things!');
},
actions: {
error(error, transition) {
// Assuming we got here due to the error in beforeModel
,
// we can expect that error === "bad things!",
// but a promise model rejecting would also
// call this hook, as would any errors encountered
// in afterModel
.
// The error
hook is also provided the failed
// transition
, which can be stored and later
// .retry()
d if desired.
this.transitionTo('login');
}
}
});
error
actions that bubble up all the way to ApplicationRoute
will fire a default error handler that logs the error. You can
specify your own global default error handler by overriding the
error
handler on ApplicationRoute
:
import Ember from 'ember';
export default Ember.Route.extend({
actions: {
error(error, transition) {
this.controllerFor('banner').displayError(error.message);
}
}
});
Event Payload:
-
error
Error -
transition
Transition
loading
public
The loading
action is fired on the route when a route's model
hook returns a promise that is not already resolved. The current
Transition
object is the first parameter and the route that
triggered the loading event is the second parameter.
export default Ember.Route.extend({
actions: {
loading(transition, route) {
let controller = this.controllerFor('foo');
controller.set('currentlyLoading', true);
transition.finally(function() {
controller.set('currentlyLoading', false);
});
}
}
});
Event Payload:
-
transition
Transition -
route
Ember.RouteThe route that triggered the loading event
willTransition
public
The willTransition
action is fired at the beginning of any
attempted transition with a Transition
object as the sole
argument. This action can be used for aborting, redirecting,
or decorating the transition from the currently active routes.
A good example is preventing navigation when a form is half-filled out:
import Ember from 'ember';
export default Ember.Route.extend({
actions: {
willTransition(transition) {
if (this.controller.get('userHasEnteredData')) {
this.controller.displayNavigationConfirm();
transition.abort();
}
}
}
});
You can also redirect elsewhere by calling
this.transitionTo('elsewhere')
from within willTransition
.
Note that willTransition
will not be fired for the
redirecting transitionTo
, since willTransition
doesn't
fire when there is already a transition underway. If you want
subsequent willTransition
actions to fire for the redirecting
transition, you must first explicitly call
transition.abort()
.
To allow the willTransition
event to continue bubbling to the parent
route, use return true;
. When the willTransition
method has a
return value of true
then the parent route's willTransition
method
will be fired, enabling "bubbling" behavior for the event.
Event Payload:
-
transition
Transition