Reducing Complexity

[timkindberg]

I ran across this issue in the angularjs core issues. angular/angular.js#1198 (comment)

The discussion evolves into a ui-router argument on complexity. Various users all acknowledge that ui-router is exactly what they need but several say its too complex. Then there is some back and forth about "no it isn't" and "yes it is" and "take it back or else!" and "who's gonna make me?".

So this discussion is opened to throw out ideas on how to reduce complexity and start thinking about cleaning up any actual or potentially confusing aspects of ui-router.

Let's list them here and as items gain traction we'll split them into new issues.

[timkindberg]

Complexity 1: Users not aware that url gets automatically appended to parent. This mixed with abs vs. rel urls causes confusion.

Perhaps users will be more comfortable will one of the following solutions.

Potential Simplifications:

1. Split url property into two properties appendedUrl and absUrl
2. Default all urls as absolute unless a special modifier is used, basically reversing current implementation. So url: "/home" would be absolute and url: "&/home" would be appended. I took the idea of using & from LESS.

[timkindberg]

Complexity 2:
Users are not easily comprehending the way view names work in relation to the state hierarchy and qualified view names.

Perhaps users will be more comfortable will one of the following solutions.

Potential Simplifications:

1. Add constant values for unnamed views and the root unnamed state. This will eliminate the potential for an empty view or state name in a qualified view name. So what is currently "hint@" becomes "hint@$root", and "@" becomes "$unnamed@$root".
2. Maybe we allow some leniency, and if a state attempt to populate a view that does not exist in its parent state view, it continues looking up the state tree for a view that matches.

[nateabele]

Default all urls as absolute unless a special modifier is used, basically reversing current implementation. So url: "/home" would be absolute and url: "&/home" would be appended. I took the idea of using & from LESS.

I actually like this idea quite a bit.

Another thing that was brought up was the whole linking issue, which I've been slacking on the directive for. Once that's done, it should make that whole aspect fairly straightforward.

Users are not easily comprehending the way view names work in relation to the state hierarchy and qualified view names.

I'm actually not even convinced we need that. I've certainly never found a use for it. View hierarchies are de facto independent from states as it is, and coupling them just adds an unnecessary layer of complexity.

[timkindberg]

Complexity 3:
Users are finding it difficult to declare a root state; initial or default state. What is the defacto way to specify the first state of an application? A user should not have to use otherwise() just to create their initial state.

Perhaps users will be more comfortable will one of the following solutions.

Potential Simplifications:

1. Make "/" AND "" (empty url) both create an initial state. Right now only "" works for me.
2. In the instance where you want a state with a url e.g. url: "/home" to be the initial state. Add a method on $stateProvider to set the initial state. $stateProvider.initialState('home'). It's just more friendly.

[timkindberg]

I'm actually not even convinced we need that. I've certainly never found a use for it. View hierarchies are de facto independent from states as it is, and coupling them just adds an unnecessary layer of complexity.

So how would we target views then? Just by name alone?

[nateabele]

Yup. Target by name, and use dot-syntax for nesting. They could be absolute by default, and use the same character as URLs to inherit from the parent.

[laurelnaiad]

I think there are 3 aspects to perceived complexity:

1. Anything that is different than that to which people are accustomed feels complicated. It's human nature.
2. There may be opportunities such as the ones you all are discussing above to make the API more logical to application developers (as in, the API as is makes total sense when you know what the router is doing, but less sense if you approach it naively from "the outside").
3. There may be opportunities to have sensible defaults while leaving things overrideable.
4. Documentation.

I'm going to try to address them individually.

Anything that is diffferent than that to which people are accustomed...
I think it should be a goal for the $state service itself, not a wrapper provider, to be backward-API-compatible with the Angular v1 router. Anything that goes beyond what the stock v1 router does should be instigated with the presence of new properties/methods/etc.

Opportunities to make the API match what an app developer is thinking about

@timkindberg wrote: "Default all urls as absolute unless a special modifier is used, basically reversing current implementation. So url: "/home" would be absolute and url: "&/home" would be appended. I took the idea of using & from LESS.

+$0.02!

Anything that is diffferent than that to which people are accustomed...
Concerning view names:

Users are not easily comprehending the way view names work in relation to the state hierarchy and qualified view names.

Might it help if an object/property hierarchy were available to the app developer at runtime?

Make "/" AND "" (empty url) both create an initial state. Right now only "" works for me.

For sure.

In the instance where you want a state with a url e.g. url: "/home" to be the initial state. Add a method on $stateProvider to set the initial state. $stateProvider.initialState('home'). It's just more friendly.
Seems reasonable as long as it's optional -- this seems like a feature people would ask for without really understanding what they're trying to build.... I suspect most people actually want deep linking combined with the ability to force a login before the deep link is satisfied, or some other way of enabling interstitial routing for splash screens/logins, even if they don't always forumulate the expression of need that way. Interstitials would be pretty complicated, so not on topic here... if having an an "optional mandatory initial state" actually reduces "support costs" then great, but if people confuse it with interstitials it might lead to more support.

Sensible Defaults with Overrideability

As above, I'd say start with the core v1 router. $stateProvider/$state should support its API out of the box. The presence of configuration options supplied to the provider or that appear in state definitions would trigger anything beyond the existing behavior. Make pretty much everything that UI-router does above and beyond the core router an override of the default (stock v1) behavior, and make it's the override overrideable for ultimate power -- option (a) you get basic behavior; option (b) you pick a "fancy" behavior from $state's built in fancy behaviors; option (c) you create you own "fancy" behavior and plug it in. People who stick with (a) never need to worry about (b) and (c) if they're done as overrides.

Documentation

Great documentation is so good that it doesn't even seem that special... because it makes the system being described seem so simple that it wouldn't have needed documentation. That's really hard to do, especially when you know the innards of the system being described. The ui-router documentation was more or less fine for me when I picked it up. I read 8 pages and then looked at the sample contacts app and still refer every once in a while to something or other on one of those 8 pages, even though it's a tossup as to whether it would be easier for me to look at the source code now that I'm kind of familiar with it. So if I'm looking at the docs when I could look at the source, they're already pretty good.

Aside: while content is ultimately more important than style, I gotta mention docular. I'm just getting my feet wet with it, and at present it can't just spit out documenation compatible with gh-pages, but a conversation about documenting angular stuff can't omit docular.

Anyway, to ignore the delivery/authoring format and focus on content... I think there may be opportunities to slice some guides out of a detailed API reference... One guide would be toward using $state(Provider) in a manner that's equivalent to what you get with the stock router (and ideally if $state is backward compatible, this would be a short tutorial!) -- let's call that the "base tutorial". Other tutorials could start with the result of the "base tutorial" and show how to use one additional feature of $state each. So, one tutorial for configuring a child state, one configuring a state with two views, etc... although that could end up with a lot of tutorials, the time might pay off...

I'm actively pursuing making docular-generated documentation gh-pages-compatible (essentially, making it run in hash mode without an active server), and planning to document my offshoot of ui-router, so I might be able to pitch in with chunks of documentation at the API level fairly soon, even my tutorial/guide content would be divergent.

[nateabele]

I think it should be a goal for the $state service itself, not a wrapper provider, to be backward-API-compatible with the Angular v1 router. Anything that goes beyond what the stock v1 router does should be instigated with the presence of new properties/methods/etc.

This could not be more wrong. Angular's existing routing infrastructure is severely limited, and by being URL-centric instead of state-centric, it is wrong in its fundamental concept. Backwards-compatibility with the existing API needs to be broken.

Trying to build incrementally upon a fundamentally broken concept is difficult and awkward, and just ends up being confusing and frustrating for people coming from the old system.

Anyway, we've already had this discussion, and that ship has sailed, so I don't think it's worth talking about. We have an existing compatibility layer that is more than adequate.

[laurelnaiad]

Okey dokey -- didn't know about that.

[timkindberg]

Well hold on @nateabele. @stu-salsbury had great points, and i find myself in deep alignment with his vision. Maybe he's off base a tad about matching the core router API 1-to-1 (which I'm not decided on), but i think he's also saying our router should at least cover everything core router can do for folks who just want simple, plus more. I think he's just spelling out "simplicity" from a high level. I have much more I want to dive into in response to Stu but I'm only on my phone. Perhaps tomorrow. Discussions are always worth having again especially now that we are in a different place.

[ksperling]

I think all these points are valid... I'm wondering if it would be better to split each discussion out into a separate issue though? This thread is already getting quite long. Anyway here are my comments on all three issues listed

URL complexity

Absolute vs relative -- I haven't really seen anybody use absolute URLs, so making that the default seems counter intuitive. The problem with absolute URLs is that you have to repeat any parameters the parent defines. That seems easy enough when the parent doesn't have any (stuff like '/home' or '/contacts'), but in a real world app many states are going to have parameters. I think having a separate 'absUrl' property would be OK from the point of view of intent being more obvious, on the other hand it's just going to result in a bunch of extra logic and error handling (handle the case where both url and absUrl are specified). I think this can just be covered by better documentation. I think the "&/bla" syntax for relative URLs is fine. We could even encourage using both "^/abs" and "&/rel" (and start failing on unprefixed URLs at some point). That way the URLs always have some indication of how they're interpreted.

Multiple views
This seems to be a largely misunderstood area; at least based on some of the questions asked in issues here (even though the people that don't have problems with it obviously won't be asking any questions, so I guess it's a bit skewed).

The thinking behind how the qualified view names work right now is that a parent state provides ui-view tags effectively as (named) places in the DOM, and child states fill in those places. Doing away with the idea of qualified names entirely would mean that this becomes very brittle, because it will be easy to accidentally have multiple views with the same name, especially when we implement "components" as reusable stateful entities that can be loaded into a ui-view. It would also effectively prevent us from having unnamed ui-views. I do agree that there are some improvements that can be made with respect to how views look up their content to make some cases that currently require fully qualified names to "just work".

I disagree with @nateabele that nesting views should be independent of the state hierarchy. The concept of parent states providing ui-views for their children is inherently hierarchical, and this nesting approach fits very well with applications with multiple levels of navigation. The sample application (even though not a good example of a complex app) hardly uses named views at all, because the navigation and how states are nested match up.

There's an anti-pattern I've seen in a few questions where people define a bunch of ui-views in their top level HTML file (e.g. top-nav, sidebar, content, footer, ...) and then each and every state populates all of those views. This means the every view is re-rendered for every state change, and it becomes difficult for a state to have a different overall layout (plus controllers become tricky because they are local to each view). If every state is really meant to re-render the entire screen, then there should be just a single top-level ui-view tag and then the state simply populates 1 view rather than 5. The main purpose of this pattern seems to be to DRY up the scaffolding of static HTML that defines the overall layout of those screen regions, but there should be a better way to achieve that without messing up the entire state/view structure in the process. I wonder if this approach is based on the fact that in $route nesting of routes just didn't make sense, whereas it is somewhat easier to understand how it would have generalized to multiple (non-nested) named views.

default urls

Yes, we should definitely handle the "" vs "/" case. The concept of a "start" state is somewhat misleading (except in apps where no state has a URL) because it assumes that the app is being started from it's root URL rather than from a deep link, but both those cases are equaly valid (and are really the same). In the same way a web site has no "default page" other than the home page ("/") -- the 'default' page or state is simply the one with the URL "/" because the URL doesn't contain anything else. Doing an unconditional transitionTo() in run or configure is always wrong, because it ignores the location (except in apps that don't use URLs for the state at all).

So once we've treated "" as "/" I think there's essentially nothing to do here. This leaves the option open for people to have a redirect like .when("/", "/home") instead of changing the URL of the home state to "/", but I don't see any inherent advantage by having that additional redirect.

backwards compatibility

Agree with @nateabele -- we don't want to cripple ui-router by shoehorning it onto $routeProvider. Ultimately people will have to learn to think about states differently than they did about routes, and I think by making $state be too much like just an extension of $route we're actually making that harder for people to realize.

[ksperling]

If we want to provide a short cut for defining redirects, we could allow something like this

.state('home', {
  url: '/home',
  urlAlias: '/'
})

which would make $stateProvider do a $urlRouterProvider.when('/', '/home') for you. We could allow multiple aliases as an array.

[ksperling]

(This won't work correctly when a child state and it's parent both have aliases though, as redirects would need to be created for all combinations of parent and/or child using any of their aliases.)

[laurelnaiad]

@ksperling, that's pretty much what I did in $detour, so it looks like this for the contacts sample (ignore that this is in json format):

        "detail": {
          "definition": {
            "url": "/{contactId}",
            "aliases": {"/c?id": "/:id", "/user/{id}": "/:id"},
            "resolveByService": {
              "something": "getContactIdFromParams"
            },
//...

The aliases support the ^ syntax for specifying absolute paths if desired.

[ksperling]

The problems with aliases is the combinatorial explosion of rules from combining every child alias with every parent alias... in either case it doesn't seem like a particularly high-value feature. Except for providing backwards compatibility with existing URLs of your app, what's the point of aliases?