Add docs about transitions

Author: mjackson

docs/ConfirmingNavigation.md

@@ -0,0 +1,57 @@
+## Confirming Navigation
+
+React Router provides a [`routerWillLeave` lifecycle hook](Glossary.md#routehook) that React [component](Glossary.md#component)s may use to prevent a transition from happening or to prompt the user before leaving a [route](Glossary.md#route). `routerWillLeave` may either 1) `return false` to cancel the transition or 2) `return` a prompt message that will prompt the user for confirmation before leaving the route.
+
+To install this hook, use the `Lifecycle` mixin in one of your [route component](Glossary.md#routecomponent)s.
+
+```js
+import { Lifecycle } from 'react-router';
+
+var Home = React.createClass({
+
+  // Assuming Home is a route component, it may use the
+  // Lifecycle mixin to get a routerWillLeave method.
+  mixins: [ Lifecycle ],
+  
+  routerWillLeave(nextLocation) {
+    if (!this.state.isSaved)
+      return 'Your work is not saved! Are you sure you want to leave?';
+  },
+
+  // ...
+
+});
+```
+
+If you need a `routerWillLeave` hook in a deeply nested component, simply use the `RouteContext` mixin in your [route component](Glossary.md#routecomponent) to put the `route` in context.
+
+```js
+import { Lifecycle, RouteContext } from 'react-router';
+
+var Home = React.createClass({
+
+  // Home should provide its route in context
+  // for descendants further down the hierarchy.
+  mixins: [ RouteContext ],
+
+  render() {
+    return <NestedForm />;
+  }
+
+});
+
+var NestedForm = React.createClass({
+
+  // Descendants use the Lifecycle mixin to get
+  // a routerWillLeave method.
+  mixins: [ Lifecycle ],
+
+  routerWillLeave(nextLocation) {
+    if (!this.state.isSaved)
+      return 'Your work is not saved! Are you sure you want to leave?';
+  },
+
+  // ...
+
+});
+```

docs/README.md

@@ -3,7 +3,7 @@
 - [Introduction](Introduction.md)
 - [Route Configuration](RouteConfiguration.md)
 - [Route Matching](RouteMatching.md)
-- [Transitions](Transitions.md)
+- [Confirming Navigation](ConfirmingNavigation.md)
 - [Glossary](Glossary.md)
 
 - [Dynamic Routing](DynamicRouting.md)

docs/RouteConfiguration.md

@@ -67,7 +67,7 @@ URL                     | Components
 
 ### Adding an Index
 
-Imagine we'd like to render another component inside of `App` when the URL is `/`. Currently, `this.props.children` is `undefined` in this case. We can use an `<IndexRoute>` to specify a "default" page.
+Imagine we'd like to render another component inside of `App` when the URL is `/`. Currently, `this.props.children` inside of `App`'s `render` method is `undefined` in this case. We can use an `<IndexRoute>` to specify a "default" page.
 
 ```js
 import { IndexRoute } from 'react-router';
@@ -92,7 +92,7 @@ React.render((
 ), document.body);
 ```
 
-Now, `this.props.children` will be a `<Dashboard>` element inside `App`'s `render` method! This functionality is similar to Apache's [`DirectoryIndex`](http://httpd.apache.org/docs/2.4/mod/mod_dir.html#directoryindex) or nginx's [`index`](http://nginx.org/en/docs/http/ngx_http_index_module.html#index) directive.
+Now, inside `App`'s `render` method `this.props.children` will be a `<Dashboard>` element! This functionality is similar to Apache's [`DirectoryIndex`](http://httpd.apache.org/docs/2.4/mod/mod_dir.html#directoryindex) or nginx's [`index`](http://nginx.org/en/docs/http/ngx_http_index_module.html#index) directive, both of which allow you to specify a file such as `index.html` when the request URL matches a directory path.
 
 Our sitemap now looks like this:
 
@@ -105,7 +105,7 @@ URL                     | Components
 
 ### Decoupling the UI from the URL
 
-It would be nice if we could remove the `/inbox` segment from the `/inbox/messages/:id` URL, but still render `Message` nested inside the `App -> Inbox` UI. We can use an absolute path for that.
+It would be nice if we could remove the `/inbox` segment from the `/inbox/messages/:id` URL pattern, but still render `Message` nested inside the `App -> Inbox` UI. Absolute `path`s let us do exactly that.
 
 ```js
 React.render((
@@ -122,6 +122,8 @@ React.render((
 ), document.body);
 ```
 
+The ability to use absolute paths in deeply nested routes gives us complete control over what the URL looks like! We don't have to add more segments to the URL just to get nested UI.
+
 We can now render the following URLs:
 
 URL                     | Components
@@ -131,15 +133,13 @@ URL                     | Components
 `/inbox`                | `App -> Inbox`
 `/messages/:id`         | `App -> Inbox -> Message`
 
-The ability to use absolute paths in deeply nested routes gives us complete control over what the URL looks like! We don't have to add more segments to the URL just to get nested UI.
-
 **Note**: Absolute paths may not be used in route config that is [dynamically loaded](DynamicLoading.md).
 
 ### Preserving URLs
 
-But wait just a minute ... we just changed a URL! [That's not cool](http://www.w3.org/Provider/Style/URI.html). Now everyone who had a link to `/inbox/messages/5` has a **broken link**. :(
+Wait a minute ... we just changed a URL! [That's not cool](http://www.w3.org/Provider/Style/URI.html). Now everyone who had a link to `/inbox/messages/5` has a **broken link**. :(
 
-Not to worry. Redirects to the rescue!
+Not to worry. We can use a `<Redirect>` to make sure that URL still works!
 
 ```js
 import { Redirect } from 'react-router';
@@ -160,11 +160,23 @@ React.render((
 ), document.body);
 ```
 
-Now when someone clicks on that link to `/inbox/messages/5` they'll automatically be redirected to `/messages/5`. We don't hate our users anymore! :highfive:
+Now when someone clicks on that link to `/inbox/messages/5` they'll automatically be redirected to `/messages/5`. :highfive:
+
+### Enter and Leave Hooks
+
+[Route](Glossary.md#route)s may also define [`onEnter`](Glossary.md#enterhook) and [`onLeave`](Glossary.md#leavehook) hooks that are invoked once a transition has been [confirmed](ConfirmingNavigation.md). These hooks are useful for various things like [requiring auth](https://github.com/rackt/react-router/tree/master/examples/auth-flow) when a route is entered and saving stuff to persistent storage before a route unmounts.
+
+During a transition, [`onLeave` hooks](Glossary.md#leavehook) run first on all routes we are leaving, starting with the leaf route on up to the first common ancestor route. Next, [`onEnter` hooks](Glossary.md#enterhook) run starting with the first parent route we're entering down to the leaf route.
+
+Continuing with our example above, if a user clicked on a link to `/about` from `/messages/5`, the following hooks would run in this order:
+
+  - `onLeave` on the `/messages/:id` route
+  - `onLeave` on the `/inbox` route
+  - `onEnter` on the `/about` route
 
 ### Alternate Configuration
 
-Since [route](Glossary.md#route)s are usually nested, it's useful to use a concise nested syntax like [JSX](https://facebook.github.io/jsx/) to describe their relationship to one another. However, you may use an array of [route](Glossary.md#route) objects if you prefer to avoid using JSX.
+Since [route](Glossary.md#route)s are usually nested, it's useful to use a concise nested syntax like [JSX](https://facebook.github.io/jsx/) to describe their relationship to one another. However, you may also use an array of plain [route](Glossary.md#route) objects if you prefer to avoid using JSX.
 
 The route config we've discussed up to this point could also be specified like this: