Ember.js router v2 App.Router.map inconsistent in documentation?

Question

I'm creating an app with ember.js. I started on PRE.2 but ended up using ember-data v11 so upgraded to master for ember proper. This meant having to change to the new v2 router interface (which as a side note I think is so much better, so thank you.)

I'm having a couple of problems trying to figure out how it works, I'm deep in the guide but there are a couple of inconsistencies I can't quite get my head around:

1)

It seems there are two different conventions used to configure the route map:

In the 'Templates' section, a match().to() interface is used

App.Router.map(function(match) {
  match('/').to('index');
  match('/posts').to('posts');
  match('/posts/:post_id').to('post');
});

( this method is also used in Tom Dale's gist )

In the 'Routing' section, a resource / route interface is used:

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

Here it states that a "resource" should be used for noun routes, and "route" for verb routes.

Then in the "Redirecting to a different URL" section, this noun/verb convention isn't followed:

App.Router.map(function(match) {
  this.resource('topCharts', function() {
    this.route('choose', { path: '/' });
    this.route('albums');
    this.route('songs');
    this.route('artists');
    this.route('playlists');
  });
});

My first question is:

Going forward, what is the proper convention for creating routes?

My second question follows on from that and is more relevant to my application:

How do I link from a top level "resource" route to a nested "route" route and pass through the appropriate models?

( there is an example of this in the 'Links' section of the 'Templates' doc, but it pertains to the match().to() interface, and I'm specifically working with the resource/route interface )

Here's my example:

I have created a simple site structure based on streams, a stream consists of details, a set of posts, handles and history. My routing is set up like so:

App.Router.map(function() {
  this.resource('streams');
  this.resource('stream', { path: '/stream/:stream_id' }, function(){
    this.route('details');
    this.route('posts');
    this.route('handles');
    this.route('history');
  });
});

My streams route looks like this:

App.StreamsRoute = Ember.Route.extend({
  model: function() { 
    return App.Stream.find(); 
  },
  setupController: function(controller, model) { 
    controller.set('content', model); 
  }
});

and the template:

<script type="text/x-handlebars" data-template-name="streams">
  <ul>
  {{#each stream in controller}}
    <li>{{#linkTo "stream" stream}} {{stream.title}} {{/linkTo}}</li>
  {{/each}}
  </ul>
</script>

My stream (singular) route:

<script type="text/x-handlebars" data-template-name="stream">
  <nav>
    {{#linkTo "stream.details" }}Details{{/linkTo}}
  </nav>
  {{outlet}}
</script>

Now, I'd like to link to my sub route "details", but I'm not sure what to place in the linkTo so that my model (which is a stream) is passed down into this sub-route:

App.StreamDetailsRoute = Ember.Route.extend({ });

My "details" template just displays some attributes off the stream object.

<script type="text/x-handlebars" data-template-name="stream/details">
  <h2>Stream Details</h2>
  <p>Id: {{id}}</p>
  <p>Title: {{title}}</p>
</script>

I will also want to link through to posts, history and handles sub-routes and be able to display these aggregations based on the stream model. I'm not sure exactly how to do this. I assume I need to use setupController to get the items to display, I'm just not sure how to get the stream object down into these sub routes.

Mike Grassotti Mike Grassotti · Accepted Answer · 2013-01-17T13:16:55

Going forward, what is the proper convention for creating routes?

The Resource/Route approach as described in http://emberjs.com/guides/routing/defining-your-routes/

How do I link from a top level "resource" route to a nested "route" route and pass through the appropriate models?

Specify the name of a route as the first parameter, followed by any contexts that are required. So in your example, when creating a link to "stream.details" from the stream template you need to specify this as the context.

{{#linkTo "stream.details" this}}Details{{/linkTo}}

The approach described in http://emberjs.com/guides/templates/links/ still covers the basics.

When in doubt I recommend checking the test cases for link_helper. For example: https://github.com/emberjs/ember.js/blob/master/packages/ember/tests/helpers/link_to_test.js#L249

Ember.js router v2 App.Router.map inconsistent in documentation?

1 Answers