Routing Edit Page

Defining Your Routes

When your application starts, the router is responsible for displaying templates, loading data, and otherwise setting up application state. It does so by matching the current URL to the routes that you've defined.

1
2
3
4

App.Router.map(function() {
  this.route("about", { path: "/about" });
  this.route("favorites", { path: "/favs" });
});

When the user visits /, Ember.js will render the index template. Visiting /about renders the about template, and /favs renders the favorites template.

Note that you can leave off the path if it is the same as the route name. In this case, the following is equivalent to the above example:

1
2
3
4

App.Router.map(function() {
  this.route("about");
  this.route("favorites", { path: "/favs" });
});

Inside your templates, you can use {{linkTo}} to navigate between routes, using the name that you provided to the route method (or, in the case of /, the name index).

1
2
3
4
5
6

{{#linkTo "index"}}<img class="logo">{{/linkTo}}

<nav>
  {{#linkTo "about"}}About{{/linkTo}}
  {{#linkTo "favorites"}}Favorites{{/linkTo}}
</nav>

The {{linkTo}} helper will also add an active class to the link that points to the currently active route.

You can customize the behavior of a route by creating an Ember.Route subclass. For example, to customize what happens when your user visits /, create an App.IndexRoute:

1
2
3
4
5
6

App.IndexRoute = Ember.Route.extend({
  setupController: function(controller) {
    // Set the IndexController's `title`
    controller.set('title', "My App");
  }
});

The IndexController is the starting context for the index template. Now that you've set title, you can use it in the template:

1
2

<!-- get the title from the IndexController -->
<h1>{{title}}</h1>

(If you don't explicitly define an App.IndexController, Ember.js will automatically generate one for you.)

Ember.js automatically figures out the names of routes and controllers based on the name you pass to this.route.

Resources

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

1
2
3
4
5

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:

1
2
3
4
5

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 {{#linkTo}}, 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.

Dynamic Segments

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('/blog_posts');, our route handler might look like this:

1
2
3
4
5

App.BlogPostsRoute = Ember.Route.extend({
  model: function() {
    return App.BlogPost.all();
  }
});

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

Because /blog_posts represents a fixed model, we don't need any additional information to know what to use. 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.

1
2
3
4
5
6
7
8
9
10

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

App.PostRoute = Ember.Route.extend({
  model: function(params) {
    return App.Post.find(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 App.Post.find(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.

Nested Resources

You cannot nest routes, but you can nest resources:

1
2
3
4
5
6
7
8

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.