willLeave and willChangeContext events

[ef4]

This supercedes emberjs/ember.js#4233

My intention is to expose a public API that's more fine-grained than willTransition. The problem with willTransition is that it fires on your route regardless of whether your route is actually going to be affected by the transition. The user is left crawling through private state on the transition object to figure out whether their route is really going away or changing context.

This change creates two new events: willLeave and willChangeContext. willLeave fires on routes that will no longer be active after the transition. willChangeContext fires on routes that will still be active but will re-resolve their models. Both of these hooks act like willTransition in the sense that they give you an opportunity to abort the transition before it happens. Common use cases include animating things away or prompting to user to deal with unsaved changes.

If this PR is merged, I'll make a (documentation-only) PR against ember itself. As far as I can tell, no code changes will be necessary there.

I left willTransition alone, so this should be backward compatible with stable Ember APIs.

[ef4]

And here's an example of how this API simplifies my animation demo app and removes dependence on private properties of the transition object: ef4/ember-animation-demo@3f79d70

[machty]

This looks good to me; the only hesitation I have is that we'd probably wanna feature flag this on the Ember side of things so that after we import this code change into Ember (and it goes into beta and then release), if we wanted to change the API in some way, we'd be breaking apps for the folk that looked into router.js and found these seemingly public API hooks. I'll bring this up w the other core folk to see what makes sense.

[ef4]

Right. It's not obvious how to apply Ember's feature flags to a feature like this in router.js. Possibly router.js needs to sniff for the existence of Ember and respect Ember's feature flags. Alternatively, Ember could actively detect and complain about willLeave, etc if it sees them on a user's route without the appropriate feature flag.

[machty]

The other thing we could do is expose methods on Router prototype that send those 3 events and Ember can conditionally stub those out depending on a feature flag. How does that sound?

[machty]

I'll do it :)