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

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.

Answer 1

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