Help to clarify Ember Routing documentation. What is the proper way to structure routes for a master-detail like application?

[mattmazzola]

Hi,

I have a design where one route which shows a list of items and when the user clicks on any of those items, the details are shown in place of the original list.

I reference master-detail style designs in the title because that is what most people are familiar with, but this case is not master-detail. In the case of master-detail the list of items would remain shown while the details are displayed for the selected item. In my case I want the details to replace the list.

I’ve seen a lot of back-and forth on this issue about whether it’s more appropriate to nest the routes or keep them on the same level. I’ve created a jsbin for each case to show the differences in design and was hoping someone would help explain why one is better or at least add some more objective pros and cons below.

1. Example with same level Routes:

JS Bin

Pros: People’s main argument for this structure is a semantic opinion that routes should reflect the structure of the templates with respect to the application. Since the templates are being rendered at the same hierarchial level then the routes should also be at the same level.

Cons: The structure often ends up with things like:

  this.resource('things');
this.resource('thing', {path: 'things/:id'});

To me this bad because you are having two routes with the same path which kind of goes against the DRY principal and is confusing. If this was a practice why would we ever have nested routes.

.2. Nested Routes:

JS Bin

Pros: Again in the semantics here, you must first visit the parent resource in order to select/visit an item from that resource, so it makes more sense for the item to be nested within.

Cons: I think people against nested routes think that overriding the Route#renderTemplate method is considered a hack since it could be avoided with the above approach.

There was another article previously that went through some troubleshooting in the area here:

Nested resource rendering into main outlet and linkTo issue

Hi there! I’m writing a sample app with Ember just to get the core idea and discover what’s possible. My sample app is almost working, but there’s an issue with it. Here’s the link: http://codepen.io/fnando/pen/FcwsK I decided to render the nested resource into the main outlet. The problem is that when I try to go to the parent resource, the page isn’t rendered at all. No errors, no nothing. Just blankness. A browser reload make it work. It must be some hook I’m not setting, so any help woul…

I hope this article can help find best practices for this use case and hopefully we can have someone update the Ember ‘defining route’ docs:

Defining Your Routes - Routing - Ember Guides

to make this super clear.
In my opinion, the docs are misleading because they have an example with blog posts which is assumed to be referring to a true master-detail layout which, (I believe, but may be wrong) implies nested routing; however, the snippet below shows same level routes as seen here:

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

which I think causes confusion and although we know it works, is not necessary.

Also, based on RESTful url practices, the endpoint for a post, should only add a specific identifier to the service endpoint which serves all of the posts. This is another reason for using nested resources, because you remove the ability to mess up the path naming conventions. If you add a post resource within the posts resource you are guaranteed to use that path.

[mattmazzola]

I had another thought which might help sway peoples opinions and come up with a definitive answer.

Tom Dale always talks about how the URL is the key to web applications and this was one of the reasons why they put so much emphasis on the router in Ember. He also says that when people start building ember applications they should start with the URLs and thus the routes, and this is why I think getting this part of the documentation clear and ensuring a common understanding amongst the community is well worth it.

Tom Dale’s Talk at JSConf on importance of url:

Tom Dale: Stop Breaking the Web -- JSConf EU 2013

The setup analogy is a bit long so I linked directly to the URL part, but you should watch the whole thing. (Also, he drops the f-bomb at the end http://www.youtube.com/watch?feature=player_embedded&v=OSEXpsVcTxI#t=1671)

From what I understand, the router is there to map urls to a state of the application and I think all the arguments people have with how templates are rendered is over thinking the problem.

I think it can come down to a simple rule: Whenever there is a slash in the url, that translates to a nested route in the router.

For instance, there is a note in the guides about when it is appropriate to use resource vs route which I think is very clear. Hopefully we can get something this simple for the scenarios I’m talking about.

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.

[mpl]

This was the most frustrating thing for me when I first started using Ember. No clear direction for how to lay things out for simple CRUD actions, and even though real URLs are touted as being one of its best features, the blog demo video uses if editing type statements in the controller, rather than routing to a /edit route.

I’m coming from a Rails/Backbone.js background, so, I’m used to their styles of URLs. Here’s an example of how I would set up routes for a user index:

App.Router.map(function () {
  this.resource('users', { path: '/users/' }, function () {
    this.route('new', { path: '/new' });
    this.route('show', { path: '/:user_id' });
    this.route('edit', { path: '/:user_id/edit' });
  });
});

The resulting URLs are:

• /users - The user index, or list
• /users/new - A form for creating a new user
• /users/:id/ - A single user profile
• /users/:id/edit - A form for editing the user

Thoughts? Opinions? Also, first post!

[drapergeek]

@mpl I think in most cases the if editing is used because linking the user to an edit route is not very typical. I haven’t seen many cases where I would bookmark an edit page or send a user the link to an edit page either. I think in that case, having a route doesn’t necessarily make sense.

Also my first post, hope it was helpful!

[oneiota]

This is something we are also wrestling with mid our ember app build.

I believe the problem stems from ember being geared towards Master/Detail application layouts.

Which is great unless you are developing a mobile web application or building a web application using mobile first principles.

I agree with Tom Dale that the URL is the key to web applications and that routes should reflect the applications current state.

@drapergeek - hence there is a need for end routes such as edit and create.