title: Ember.js router v2 App.Router.map inconsistent in documentation?
body: <p>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.)</p>
  
  <p>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:</p>
  
  <p>1) </p>
  
  <p>It seems there are two different conventions used to configure the route map:</p>
  
  <p>In the 'Templates' section, a match().to() interface is used</p>
  
  <pre><code>App.Router.map(function(match) {
    match('/').to('index');
    match('/posts').to('posts');
    match('/posts/:post_id').to('post');
  });
  </code></pre>
  
  <p>( this method is also used in Tom Dale's <a href="https://gist.github.com/3981133" rel="nofollow" title="gist">gist</a> )</p>
  
  <p>In the 'Routing' section, a resource / route interface is used:</p>
  
  <pre><code>App.Router.map(function() {
    this.resource('posts', function() {
      this.route('new');
    });
  });
  </code></pre>
  
  <p>Here it states that a "resource" should be used for noun routes, and "route" for verb routes.</p>
  
  <p>Then in the "Redirecting to a different URL" section, this noun/verb convention isn't followed:</p>
  
  <pre><code>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');
    });
  });
  </code></pre>
  
  <p>My first question is: </p>
  
  <p><em>Going forward, what is the proper convention for creating routes?</em></p>
  
  <p>My second question follows on from that and is more relevant to my application:</p>
  
  <p><em>How do I link from a top level "resource" route to a nested "route" route and pass through the appropriate models?</em></p>
  
  <p>( 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 )</p>
  
  <p>Here's my example:</p>
  
  <p>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:</p>
  
  <pre><code>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');
    });
  });
  </code></pre>
  
  <p>My streams route looks like this:</p>
  
  <pre><code>App.StreamsRoute = Ember.Route.extend({
    model: function() { 
      return App.Stream.find(); 
    },
    setupController: function(controller, model) { 
      controller.set('content', model); 
    }
  });
  </code></pre>
  
  <p>and the template:</p>
  
  <pre><code>&lt;script type="text/x-handlebars" data-template-name="streams"&gt;
    &lt;ul&gt;
    {{#each stream in controller}}
      &lt;li&gt;{{#linkTo "stream" stream}} {{stream.title}} {{/linkTo}}&lt;/li&gt;
    {{/each}}
    &lt;/ul&gt;
  &lt;/script&gt;
  </code></pre>
  
  <p>My stream (singular) route:</p>
  
  <pre><code>&lt;script type="text/x-handlebars" data-template-name="stream"&gt;
    &lt;nav&gt;
      {{#linkTo "stream.details" }}Details{{/linkTo}}
    &lt;/nav&gt;
    {{outlet}}
  &lt;/script&gt;
  </code></pre>
  
  <p>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:</p>
  
  <pre><code>App.StreamDetailsRoute = Ember.Route.extend({ });
  </code></pre>
  
  <p>My "details" template just displays some attributes off the stream object.</p>
  
  <pre><code>&lt;script type="text/x-handlebars" data-template-name="stream/details"&gt;
    &lt;h2&gt;Stream Details&lt;/h2&gt;
    &lt;p&gt;Id: {{id}}&lt;/p&gt;
    &lt;p&gt;Title: {{title}}&lt;/p&gt;
  &lt;/script&gt;
  </code></pre>
  
  <p>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.</p>