Design

[ProLoser]

Specifications and Votes

https://github.com/angular-ui/router/wiki

Resources

https://github.com/bennadel/AngularJS-Routing

https://github.com/vincentdieltiens/Angular-Multi-View

angular/angular.js#1198

https://github.com/angular/angular.js/wiki/Routing-Design-Discussion

[vincentdieltiens]

First of all, I'm happy to try coding with you guys a better routing system :)

I suggest that each participant sees the 2 other solutions (Like @ProLoser said)

I think that the first step, before implementation, is to determine what we want or need. In other words we have to set the specifications of this project.

So this is what i think is important :

• a system that makes the relation between one route (url) with one or more views or controllers.
• a system that supports nested views
• a system that can reload views only if necessary. By this I mean that:
  • lets the route #/resources list the resources
  • lets the route #/resources/:resourceId list the resources and show the selected resource
  • if the user go directly (via browser location bar) to #/resources/42, it must load the list of resources and the resource 42
  • if the user goes from #/resources to /resources/42, it must only load the resource 42 (the list of resources doesn't change)
  • if the user goes from #/resources/42 to #/resources, it can (it must be a choice) not reload the list of resources but it can clear the view containing the resource 42 (or not, i have one case in my project where i don't want to clear some views, i can explain it if you want)
• a system that doesn't change to much the code of an application that comes from angularJS routing system to our system. By This, i mean, we don't have to change the whole structure of a project if it uses this routing system. Only routes registrations must be changed (not templates/controllers, or not a lot)

From what I can see of other projects, here are few notices :

• In the solution of @hkdobrev :
  • there is no support of control of what can be (re)loaded or cleared.
  • if the user goes directly using the location bar, it loads only one view ! That is the main reason why i didn't use his solution before implementing mine
• In the solution of @bennadel :
  • as he says, it is for simple logic websites not for complex systems.

Here are some pros that my solution offers (by this, I do not mean that it's perfect) :

• The solution handles well nested views (actually in my project at work, i've 4 levels... and it's not the most complicated part of the project)
• The developper can determine when a view have to be reloaded or cleared. (But it's not always easy to understand)
• The solution proposes only to change the directive ngView by multiView and the $route provider of AngularJS by the multiRouteProvider. That means that that whole structure of the project does not have to be changed completely.

Well, i'm excited about your point of view ;-)

Vincent

[lrlopez]

@vincentdieltiens Cool, I didn't know about your proposal.

I'd like to add a summary and some additional comments about both @bennadel and @vincentdieltiens approaches: (@hkdobrev proposal lacks "selective" reloading, which I think is critical for any multiview system).

• About @bennadel solution:
  • The key of this proposal is using an "action path"
    • An action path is a colon delimited sequence of values (i.e. "dashboard.clients.detail").
    • Each possible route is matched to an action path.
    • Each of the values in an action path is associated to a controller (and optionally any number of route params) which is responsible for rendering the content (i.e. "/show/:customerID" path matches "dashboard.clients.detail" with param "customerID").
    • Different controllers can share an action path prefix (i.e. "dashboard" and "dashboard.clients"). This behavior allows easy implementation of nested views.
    • Each controller only reacts to changes to its prefix in the action path, and also in the relevant params. This allows partial refreshing as the view only gets updated if the param changes (i.e. customerID) or the view appears/disappears from the URL.
  • Pros/cons
    • Pro: It's easy to understand how it works (his blog entry clarifies it even further).
    • Pro: Action path easies hierarchical subview design.
    • Con: It's rather difficult to implement a subview (you need a lot of "skeleton" code).
    • Con: A subview cannot be reused easily (i.e. using the same view for "dashboard.clients.detail" and "dashboard.provider.detail" even if the show the same kind of data).
• About @vincentdieltiens solution: (please correct me if I'm wrong)
  • His proposal is based on defining multiple controllers in every route
    • Each controller is associated to a subview (and its template) and has access to all the route params.
    • When a route changes, each controller gets questioned twice:
      • Do you need to be run again? This allows the subview to check if some kind of update is needed on itself.
      • Do you want to be kept in memory? This allows the subview and its controller to be persistant even if it gets out of scope.
  • Pros/cons
    • Pro: It's also easy to understand how the inner code works.
    • Pro: Creating a subview is simple.
    • Pro: It allows reusing subviews/controllers in different routes (i.e. same code to show details for clients and providers).
    • Con: It's not integrated directly into the Angular native routing system. But it is a minor one because it works as a drop-in replacement. Don't get me wrong, but this could lead to missing some routing enhancements/fixes that get pushed into the main project (i.e. angular/angular.js@c639261 and angular/angular.js@faf02f0 )
    • Con: Some controller parameters have misleading names (i.e. "execute" function... may something similar to "updateNeeded" could be a better name)

Good work Ben & Vicent :)

[vincentdieltiens]

@lrlopez Thanks. My solution is rather new. There is also a topic about this : https://groups.google.com/forum/#!msg/angular/ayG1hCUOfX0/eVxb7fNqRgQJ

I need to read more in-deph the solution @bennadel . I will try to do this quickly :)

@lrlopez : you are right about my solution. When i developped it, i didn't find good names (I often lacking of vocabulary in English).

I didn't have proposed my solution to the angularjs team because :

• I wanted to test it correctly before. Also i did'nt have time (and because I didn't have the fortitude...) to write test. The angularjs team don't accept enhanced that not come with test.
• There are somes parts that could be enhanced. One example is storing some informations (oldRouteInfo and persist) using the data() function of jqLite/jQuery.

So, you are right, I have to merge my solution with the enhancements/fixes that are applied to the angularjs Routing system.
But, if we made a really good solution we can also pull-request it ... :)

There is also one Pro of my solution : it works with the syntax of the angularJS routing system. So no breaking.

[ProLoser]

I didn't understand the @bennadel solution at first. I was getting confused between the routes and action paths, the action paths in no way resemble the routes. Creating a second layer of abstraction people must learn and fundamentally understand.

My vote is @vincentdieltiens approach (overall) with some modifications. An ideal world I aim to use the core routing system. However I realize this may not be enough.

On @vincentdieltiens's solution:

• It should be 1 module, not two
• All options should degrade to expected behavior gracefully and should be minimalist:
  • Passing a string rather than an array to controllers to specify 1 controller
  • Having 1 view without a name (so it can be inferred as app-wide)
  • Resolve support (might be done by execute or persist?)
  • Generating the ID from the route string + controller?

My main concern is intuitive usage

[ProLoser]

I also like @jeme suggestion of using sub-routes. It would be fairly trivial to add recursive appending:

.when('/article', {
  controller: 'ArticleList',
  templateUrl: 'articles/index.html',
  subroutes: {
    '/:articleId[/:tab]' : { // -> '/article/:articleId[/:tab]' (the :tab token is optional, the :articleId is mandatory)
      controller: 'ArticleDetails',
      templateUrl: 'articles/details.html'
    },
    '/categories' : { // -> '/article/categories'
      controller: 'ArticleCategoryList',
      templateUrl: 'articles/categories/index.html',
      subroutes: {
        '/:categoryId' : { // -> '/article/categories/:categoryId'
          controller: 'ArticleCategoryDetails',
          templateUrl: 'articles/categories/details.html',
        }
      }
    }
  }
})

Actually after writing that ^^ I find that syntax fucking smexy. AND super intuitive!

[bennadel]

Few key hurdles trying to allow each view partial to remain as independent as I could; and, to allow each view partial to respond only to relevant changes. We have need for three different, distinct layouts and several layers of nesting.

[vincentdieltiens]

For the two solutions proposed by @ProLoser :

• The first one: For small projects, it's a cool way of writing things. But what if you have (and that's my case) :
  • A list of customers (/customers)
  • Where a customer has general informations tab (/customers/:customerId)
  • A tab with contacts in this company (/customers/:customerId/contacts) (with a subroutes for /customers/:customerId/contacts/:contactId)
  • A tab for prices deaded with this customer (/customer/:customerId/prices)
  • And other tabs ?

How do you deal with /customers/:customerId/contacts and /customers/:customerId/prices ?
In other words, this proposal doesn't support multiples subviews correctly.

• The second one: This is far better than the first one. It is sexy but there is one constraint (correct me if i'm wrong) : you have to define your route with subroutes in the same module. I explain. In my project (sorry for always using it, but it's my main real example ;-)), I seperate my controllers, for readability and maintenability, in differents modules : customer, customer.contact, customer.prices, customer.statistics, and so on. I like to define routes that are related to the contact module in the contact module. It's easier to manage and to maintain. But contact routes are subroutes of the customer routes...

That's why, in my solution, I store "super" controllers (controllers that are used for several routes), in global variables that can be accessed in different modules. And It's not a good way (i prefer to avoid global variables).

It will be great to find a solution with the proposition of @jeme where we can "append" subroutes.
Maybe something like :

$routeProvider.when('/article', {
  controller: 'ArticleList',
  templateUrl: 'articles/index.html',
  subroutes: {
     ...
  }
});

$routeProvider.addSubroutes('/article', '/article/:id/coments', {
  controller: 'ArticleCommentList',
  templateUrl: 'articles/comment/index.html',
  subroutes: {
    ...
  }
});

Maybe an other idea ?

[lrlopez]

@bennadel, welcome!

I also like @jeme proposal of subroutes. They successfully degrade to the AngularJS traditional routing if subroutes are not used. This means that is backward compatible so allows older code and examples to continue working even if the new routing model gets pulled into the main codebase. They are also cleaner to understand and to implement. So, 👍

About @ProLoser idea of optional parameters, may be now is the right time to propose enhancements to the route specification. Some weeks ago I had a look into the different proposals, and one of the most flexible was @xealot's angular/angular.js#1634, which uses the werkzeug routing syntax.

That new syntax would allow to specify the typed parameters (integer only, path which includes slashes, etc). I.e. "/client/int:bar" or "/search/path:where/string:what".

The new implementation also remembers the generated regexp for each route in order to reduce the overhead, so it should be even faster than the original code.

We could use @xealot work as a base and expand the syntax to include optional params (which I find extremely useful) or, if is interesting enough, we could fully implement werkzeug route spec (i.e. minlength, maxlength, maps, etc.)

Of course there are other alternatives that are worth a look (first section).

What do you think?

[lrlopez]

@vincentdieltiens,

I think the case of /customers/:customerId/contacts and /customers/:customerId/prices would be covered by something similar to this:

.when('/customers/:customerId', {
  controller: 'CustomerCtrl',
  templateUrl: 'customers/index.html',
  subroutes: {
    '/contacts' : {
      controller: 'CustomerContactsDetailCtrl',
      templateUrl: 'contacts/details.html'
    },
    '/prices' : {
      controller: 'CustomerPricesDetailCtrl',
      templateUrl: 'prices/details.html'
    }
  }
})

What I miss is another parameter that specifies which subview should the template of each subroute render in. Without it, you are implying that each view can one have one subview inside, and that may not be ok on some cases.

Take a look into this:

You'd need to specify in which view you'd like to render each template of every subroute (the main route could always be rendered on the top one, ngView). This would also be backward compatible with the current routing implementation.

.when('/customers', {
  controller: 'CustomerManagementCtrl',
  templateUrl: 'customers/index.html',
  subroutes: {
    '/manage' : {
      controller: 'CustomerListCtrl',
      templateUrl: 'customers/list.html',
      subview: 'CustomerListView'
    },
    '/:customerId' : {
      controller: 'CustomerDetailCtrl',
      templateUrl: 'customers/detail.html',
      subview: 'CustomerDetailView'
    }
  }
})

Also, dynamically adding subroutes would be nice, but I'm concerned that it could break the relation between one route and its relevant subviews. Why? Because if the browser reloads the page, it could lead to a different set of routing rules if you're not careful enough.

[vincentdieltiens]

@lrlopez

I had understood the idea. But that's does not allow to register subroutes in several modules and that's a pity.

[jeme]

Appreciated that people like the idea of sub-routes, basically I ended up defining the "interface" as i wanted it before I started implementing the solution. Thats where I often start anyways... If things are to complex or obscure they pose to big a barrier in my experience, and then they get no traction...

I might question a little if this is something we can add to Angular-UI alone, currently I have core changes to route.js. This might be a change that ultimately won't be difficult to get into the Angular stream though as it is isolated and should be backwards compatible... Currently I have had more of a prototyping approach to it, so haven't worked much with testing etc...

Anyways... Within the router I have changed the parseRoute to the following (which in long term should be the only needed change to route):

/**
 * @returns the current active route, by matching it against the URL
 */
function parseRoute() {
    // Match a route
    var params, match;
    forEach(routes, function (route, path) {
        if (!match && (match = matchRoute(route, route, path, $location.path()))) {
            return match;
        }
    });
    // No route matched; fallback to "otherwise" route
    return match || routes[null] && inherit(routes[null], { params: {}, pathParams: {} });
}

/**
 * @returns the root route if it or any of it's decendants are a match.
 */
function matchRoute(root, route, fullPath, currentPath) {
    var params, match;
    if (!match && (params = matcher(currentPath, fullPath))) {
        match = inherit(root, {
            params: extend({}, $location.search(), params),
            pathParams: params
        });
        match.$route = root;
        if (route != root) {
            match.$subroute = route;
        }
    }

    if (route.subroutes) {
        forEach(route.subroutes, function (subroute, subpath) {
            if (!match) {
                match = matchRoute(root, subroute, fullPath + subpath, currentPath);
            }
        });
    }
    return match;
}

You can also see my fork here: https://github.com/jeme/angular.js

Still getting into the way they structure their code, so fighting allot with what closures there is etc.
The above works in my sample atm. though... (and I can see now I have forgotten to delete params in the parseRoute method it self... Oh well >.<)

[vincentdieltiens]

@jeme : with your syntax, how will you determine :

• if a subview must be cleared or not ?
• if a controller (of a subview) must be executed or not ?

[jeme]

@vincentdieltiens currently it is left to the controller since I don't have a directive implemented yet that supports sub-routing, but the idea is that you go down the ladder until you hit something that is changed, from there you execute the views... (that also means that I as of now don't have sub controllers, what @ProLoser typed was an extented version of what I had)

This will require that we know the actual route-chain post route update, that is not added to the above yet as i have to do things very incrementally right now, simply because I am not that familiar with the original source, this also boils down to a requirement that ones the routing part is done it should be fully backwards compatible...

One of the things I would like to provide however is a flexibility where you might choose to execute an entire route if it's parameters has changed, or in the controller react to that change... As often when parameters change, we wan't to use the same template, yet populate it with different data, so re-executing that route in that case also seems "un-needed" to me...

Instead the controller could just react to the route, load the data and update the scope... I have yet to find a design for that though, where it is optional behavior.