Defining Your Routes

You can define groups of routes that work with a resource:

App.Router.map(function() {
  this.resource('posts', { path: '/posts' }, function() {
    this.route('new');
  });
});

As with this.route, you can leave off the path if it's the same as the name of the route, so the following router is equivalent:

App.Router.map(function() {
  this.resource('posts', function() {
    this.route('new');
  });
});

This router creates three routes:

¹ Transitioning to posts or creating a link to posts is equivalent to transitioning to posts.index or linking to posts.index

NOTE: If you define a resource using this.resource and do not supply a function, then the implicit resource.index route is not created. In that case, /resource will only use the ResourceRoute, ResourceController, and resource template.

Routes nested under a resource take the name of the resource plus their name as their route name. If you want to transition to a route (either via transitionTo or {{#link-to}}), make sure to use the full route name (posts.new, not new).

Visiting / renders the index template, as you would expect.

Visiting /posts is slightly different. It will first render the posts template. Then, it will render the posts/index template into the posts template's outlet.

Finally, visiting /posts/new will first render the posts template, then render the posts/new template into its outlet.

NOTE: You should use this.resource for URLs that represent a noun, and this.route for URLs that represent adjectives or verbs modifying those nouns. For example, in the code sample above, when specifying URLs for posts (a noun), the route was defined with this.resource('posts'). However, when defining the new action (a verb), the route was defined with this.route('new').

For multi-word models all the names are camel cased except for the dynamic segment. For example, a model named BigMac would have a resource path of /bigMacs/:big_mac_id, route named bigMac, template named bigMac.

One of the responsibilities of a resource's route handler is to convert a URL into a model.

For example, if we have the resource this.resource('posts');, our route handler might look like this:

App.PostsRoute = Ember.Route.extend({
  model: function() {
    return this.store.find('post');
  }
});

The posts template will then receive a list of all available posts as its context.

Because /posts represents a fixed model, we don't need any additional information to know what to retrieve. However, if we want a route to represent a single post, we would not want to have to hardcode every possible post into the router.

Enter dynamic segments.

A dynamic segment is a portion of a URL that starts with a : and is followed by an identifier.

App.Router.map(function() {
  this.resource('posts');
  this.resource('post', { path: '/post/:post_id' });
});

App.PostRoute = Ember.Route.extend({
  model: function(params) {
    return this.store.find('post', params.post_id);
  }
});

Because this pattern is so common, the above model hook is the default behavior.

For example, if the dynamic segment is :post_id, Ember.js is smart enough to know that it should use the model App.Post (with the ID provided in the URL). Specifically, unless you override model, the route will return this.store.find('post', params.post_id) automatically.

Not coincidentally, this is exactly what Ember Data expects. So if you use the Ember router with Ember Data, your dynamic segments will work as expected out of the box.

If your model does not use the id property in the URL, you should define a serialize method on your route:

App.Router.map(function() {
  this.resource('post', {path: '/posts/:post_slug'});
});

App.PostRoute = Ember.Route.extend({
  model: function(params) {
    // the server returns `{ slug: 'foo-post' }`
    return Ember.$.getJSON('/posts/' + params.post_slug);
  },

  serialize: function(model) {
    // this will make the URL `/posts/foo-post`
    return { post_slug: model.get('slug') };
  }
});

The default serialize method inserts the model's id into the route's dynamic segment (in this case, :post_id).

You can nest both routes and resources:

App.Router.map(function() {
  this.resource('post', { path: '/post/:post_id' }, function() {
    this.route('edit');
    this.resource('comments', function() {
      this.route('new');
    });
  });
});

This router creates five routes:

² :post_id is the post's id. For a post with id = 1, the route will be: /post/1

The comments template will be rendered in the post outlet. All templates under comments (comments/index and comments/new) will be rendered in the comments outlet.

The route, controller, and view class names for the comments resource are not prefixed with Post. Resources always reset the namespace, ensuring that the classes can be re-used between multiple parent resources and that class names don't get longer the deeper nested the resources are.

You are also able to create deeply nested resources in order to preserve the namespace on your routes:

App.Router.map(function() {
  this.resource('foo', function() {
    this.resource('foo.bar', { path: '/bar' }, function() {
      this.route('baz'); // This will be foo.bar.baz
    });
  });
});

This router creates the following routes:

A few routes are immediately available within your application:

• App.ApplicationRoute is entered when your app first boots up. It renders the application template.

• App.IndexRoute is the default route, and will render the index template when the user visits / (unless / has been overridden by your own custom route).

Remember, these routes are part of every application, so you don't need to specify them in App.Router.map.

You can define wildcard routes that will match multiple routes. This could be used, for example, if you'd like a catchall route which is useful when the user enters an incorrect URL not managed by your app.

App.Router.map(function() {
  this.route('catchall', {path: '/*wildcard'});
});

Like all routes with a dynamic segment, you must provide a context when using a {{link-to}} or transitionTo to programatically enter this route.

App.ApplicationRoute = Ember.Route.extend({
  actions: {
    error: function() {
      this.transitionTo('catchall', 'application-error');
    }
  }
});

With this code, if an error bubbles up to the Application route, your application will enter the catchall route and display /application-error in the URL.