Start on Transitions page

Author: mjackson

docs/Glossary.md

@@ -136,6 +136,12 @@ The term *route component* refers to a [component](#component) that is directly
 
 A *route config* is an array of [route](#route)s that specifies the order in which routes should be tried when the router attempts to match a URL.
 
+### RouteHook
+
+    type RouteHook = (nextLocation?: Location) => any;
+
+A *route hook* is a function that is used to prevent the user from leaving a route. On normal transitions, it receives the next [location](#location) as an argument and must either `return false` to cancel the transition or `return` a prompt message to show the user. When invoked during the `beforeunload` event in web browsers, it does not receive any arguments and must `return` a prompt message to cancel the transition.
+
 ### RoutePattern
 
     type RoutePattern = string;

docs/README.md

@@ -3,8 +3,8 @@
 - [Introduction](Introduction.md)
 - [Route Configuration](RouteConfiguration.md)
 - [Route Matching](RouteMatching.md)
-- [Dynamic Routing](DynamicRouting.md)
-- [Advanced Usage](AdvancedUsage.md)
-- [Server Rendering](ServerRendering.md)
 - [Transitions](Transitions.md)
 - [Glossary](Glossary.md)
+
+- [Dynamic Routing](DynamicRouting.md)
+- [Server Rendering](ServerRendering.md)

docs/Transitions.md

@@ -0,0 +1,53 @@
+## Transitions
+
+TODO: talk about onEnter/onLeave
+
+### Lifecycle Method
+
+React Router provides a [`routerWillLeave` lifecycle hook](Glossary.md#routehook) that React [component](Glossary.md#component)s may use to prevent the user from leaving a [route](Glossary.md#route) by `return`ing either `false` or a prompt message.
+
+To install this hook, use the `Lifecycle` mixin either directly in one of your [route component](Glossary.md#routecomponent)s or in a component further down the hierarchy whose [route component](Glossary.md#routecomponent) uses the `RouteContext` mixin.
+
+```js
+import { Lifecycle, RouteContext } from 'react-router';
+
+// Assuming Home is a route component, it may use the
+// Lifecycle mixin directly.
+var Home = React.createClass({
+
+  mixins: [ Lifecycle ],
+  
+  routerWillLeave(nextLocation) {
+    if (!this.state.isSaved)
+      return 'Your work is not saved! Are you sure you want to leave?';
+  },
+
+  // ...
+
+});
+
+// Otherwise, Home should provide its route in context
+// for descendants further down the hierarchy.
+var Home = React.createClass({
+
+  mixins: [ RouteContext ],
+
+  render() {
+    return <NestedForm />;
+  }
+
+});
+
+var NestedForm = React.createClass({
+
+  mixins: [ Lifecycle ],
+
+  routerWillLeave(nextLocation) {
+    if (!this.state.isSaved)
+      return 'Your work is not saved! Are you sure you want to leave?';
+  },
+
+  // ...
+
+});
+```