Expose $urlRouterUpdateStart event to allow deferrable update()

[rynz]

In many complex applications the first question that is asked is how can I asynchronously request user information before any $stateChangeStart events trigger. Whether it be to incorporate route protection, configuration, redirection etc.

This proposed pull request seeks to answer that question by exposing a new event $urlRouterUpdateStart which can cancel $urlRouter#update() with preventDefault(). update() is then referenced in the $urlRouterUpdateStart event listener and can be called asynchronously/synchronously.

The following example deferrers update() for 2000ms using $timeout asynchronously. The listener's deregistration function is assigned to $off and called when the listener is fired so that the listener will only defer update() once.

angular.module('app', ['ui.router']);
  .run(function($rootScope, $timeout) {
    var $off = $rootScope.$on('$urlRouterUpdateStart', function(evt, update) {
      evt.preventDefault();
      $timeout(update, 2000);
      $off();
    });
  });

[timkindberg]

I'm curious why this can't be done within $stateChangeStart. Is it because by then the url has already changed?

[rynz]

@timkindberg I looked at this event too and yes it's generally because the state transition promises etc are already set in motion and it was very difficult to inject a new promise to defer / replay the transition etc. Users may also want deferred logic that effects the when, otherwise and rule methods of $urlRouterProvider which happen before $stateChangeStart.

I also looked at $locationChangeStart in angular core but there was no way to replay this event without taking a lot of boilerplate code from AngularJS.

Definitely open to other implementations but I do think ui router would benefit greatly by having some sort of deferrable method to load user information / other configuration of an application before a state transition happens with the ability to choose if the deferrable method is run only once, or on every state change call etc.

I actually wonder if it would be possible / plausible to write into angular core an option of passing a promise to preventDefault(somePromise) that waits for the promise to resolve, then continue and if rejects acts as if the event was cancelled.

[nateabele]

There are different ways to handle this use case, of which this is only one. For example, in apps I write, states that can't be transitioned to almost always require API calls that don't resolve until the user has authenticated (hence, the states that trigger them never resolve).

A solution that would be cleaner and require less overhead would be to have update() check $event.defaultPrevented, and provide a public alias to update(), i.e. $urlRouter.sync().

[rynz]

@nateabele Yes I used to take the "grandfather" approach by having a state that resolved it's dependencies first. However I've recently been working with route protection via $stateChangeStart event which is fired before dependencies of a state is resolved. As those are typically for the controller.

I prefer your proposed solution, updating PR now.

[rynz]

@nateabele Updated PR. Sorry my other machine obviously has git default setup incorrectly.

[nateabele]

@2ix No worries. Sorry if I wasn't clear in my previous explanation, but the point was specifically to avoid the overhead of an extra event dispatch. In other words, $urlRouterUpdateStart shouldn't need to exist.

The idea was to use the existing event, as follows:

function update($event) {
  if ($event && $event.defaultPrevented) return;
  /* ... */
}

The current interception of $locationChangeSuccess doesn't need to change, you just need to intercept it yourself and preventDefault() before urlRouter does. Then, when you're done handling your user stuff, you can call sync() (which IMO should look like sync: function() { update(); } so as not to expose the internal function directly). In that case, $event will be undefined and execution will continue as normal.

Make sense?

[rynz]

@nateabele No worries, committed the change for you.

[nateabele]

@2ix Looks perfect. Squash your commits & we'll roll it.

[rynz]

@nateabele Great! How's this?

[nateabele]

@2ix 👍

[rynz]

@nateabele When do you expect this to be built into release for bower users?