more doc updates

ryanflorence · ryanflorence · commit e56a117b049e · 2015-12-28T15:33:04.000-08:00
diff --git a/docs/API.md b/docs/API.md
@@ -5,7 +5,8 @@
   - [Link](#link)
   - [IndexLink](#indexlink)
   - [RouterContext](#routercontext)
-  - RoutingContext (Deprecated, use `RouterContext`)
+    - [context.router](#context-router)
+  - RoutingContext (deprecated, use `RouterContext`)
 
 * [Configuration Components](#configuration-components)
   - [Route](#route)
@@ -18,12 +19,12 @@
   - [Named Components](#named-components)
 
 * [Mixins](#mixins)
-  - [Lifecycle](#lifecycle-mixin) (Deprecated)
-  - [History](#history-mixin) (Deprecated)
-  - [RouteContext](#routecontext-mixin) (Deprecated)
+  - [Lifecycle](#lifecycle-mixin) (deprecated)
+  - [History](#history-mixin) (deprecated)
+  - [RouteContext](#routecontext-mixin) (deprecated)
 
 * [Utilities](#utilities)
-  * [useRoutes](#useroutescreatehistory) (Deprecated)
+  * [useRoutes](#useroutescreatehistory) (deprecated)
   * [match](#match-routes-location-options--cb)
   * [createRoutes](#createroutesroutes)
   * [PropTypes](#proptypes)
@@ -42,7 +43,12 @@ One or many [`Routes`](#route) or [`PlainRoutes`](#plainroute). When the history
 Alias for `children`.
 
 ##### `history`
-The history the router should listen to from the `history` package.
+The history the router should listen to. Typically `browserHistory` or `hashHistory`.
+
+```js
+import { browserHistory } from 'react-router'
+ReactDOM.render(<Router history={browserHistory}/>, el)
+```
 
 ##### `createElement(Component, props)`
 When the router is ready to render a branch of route components, it will use this function to create the elements. You may want to take control of creating the elements when you're using some sort of data abstraction, like setting up subscriptions to stores, or passing in some sort of application module to each component via props.
@@ -88,7 +94,7 @@ Please see the [`examples/`](/examples) directory of the repository for extensiv
 ### Link
 The primary way to allow users to navigate around your application. `<Link>` will render a fully accessible anchor tag with the proper href.
 
-A `<Link>` also knows when the route it links to is active and automatically applies its `activeClassName` and/or `activeStyle` when it is.
+A `<Link>` can know when the route it links to is active and automatically apply an `activeClassName` and/or `activeStyle` when given either prop.
 
 #### Props
 ##### `to`
@@ -135,11 +141,50 @@ Given a route like `<Route path="/users/:userId" />`:
 ```
 
 ### IndexLink
-Docs coming so soon!
+Docs coming so soon! Please see the `active-links` example.
 
 ### RouterContext
-A `<RouterContext>` renders the component tree for a given router state and sets the history object and the current location in context.
+A `<RouterContext>` renders the component tree for a given router state. Its used by `Router` but also useful for server rendering and integrating in brownfield development.
+
+It also provides a `router` object on `context`.
+
+#### `context.router`
+
+Contains data and methods relevant to routing. Most useful for imperatively transitioning around the application.
+
+##### `push(pathnameOrLoc)`
+Transitions to a new URL, adding a new entry in the browser history.
+
+```js
+router.push('/users/12')
+// or with location descriptor
+router.push({
+  pathname: '/users/12',
+  query: { modal: true },
+  state: { fromDashboard: true }
+})
+```
+
+##### `replace(pathnameOrLoc)`
+Identical to `push` except replaces the current history entry with a new one.
+
+##### `go(n)`
+Go forward or backward in the history by `n` or `-n`.
 
+##### `goBack()`
+Go back one entry in the history.
+
+##### `goForward()`
+Go forward one entry in the history.
+
+##### `createPath(pathname, query)`
+Stringifies the query into the pathname, using the router's config.
+
+##### `createHref(pathname, query)`
+Creates a URL, using the router's config. For example, it will add `#/` in front of the `pathname` for hash history.
+
+##### `isActive(pathnameOrLoc, onlyActiveOnIndex)`
+Returns `true` or `false` depending on if the `pathnameOrLoc` is active. Will be true for every route in the route branch matched (child route is active, therefore parent is too), unless `onlyActiveOnIndex` is specified, in which case it will only match the exact path.
 
 
 ## Configuration Components
@@ -418,10 +463,9 @@ All the same props as [Redirect](#redirect) except for `from`.
 ## Route Components
 A route's component is rendered when that route matches the URL. The router will inject the following properties into your component when it's rendered:
 
-#### `history`
-The Router's history [history](https://github.com/rackt/history/blob/master/docs).
+### Injected Props
 
-Useful mostly for transitioning around with `this.props.history.pushState(state, path, query)`
+#### `history` (deprecated)
 
 #### `location`
 The current [location](https://github.com/rackt/history/blob/master/docs/Location.md).
@@ -512,173 +556,19 @@ class Users extends React.Component {
 
 ## Mixins
 
-## Lifecycle Mixin
-Adds a hook to your component instance that is called when the router is about to navigate away from the route the component is configured on, with the opportunity to cancel the transition. Mostly useful for forms that are partially filled out.
-
-On standard transitions, `routerWillLeave` receives a single argument: the `location` we're transitioning to. To cancel the transition, return false.
-
-To prompt the user for confirmation, return a prompt message (string). `routerWillLeave` does not receive a location object during the beforeunload event in web browsers (assuming you're using the `useBeforeUnload` history enhancer). In this case, it is not possible for us to know the location we're transitioning to so `routerWillLeave` must return a prompt message to prevent the user from closing the tab.
-
-#### Lifecycle Methods
-##### `routerWillLeave(nextLocation)`
-Called when the router is attempting to transition away from the route that rendered this component.
-
-##### arguments
-- `nextLocation` - the next location
-
-
+## Lifecycle Mixin [deprecated]
+Deprecated, please see the `CHANGES.md`.
 
-## History Mixin
-Adds the router's `history` object to your component instance.
-
-**Note**: You do not need this mixin for route components, it's already available as `this.props.history`. This is for components deeper in the render tree that need access to the router's `history` object.
-
-#### Methods
-##### `pushState(state, pathname, query)`
-Transitions to a new URL.
-
-###### arguments
-- `state` - the location state.
-- `pathname` - the full URL with or without the query.
-- `query` - an object that will be stringified by the router.
-
-##### `replaceState(state, pathname, query)`
-Replaces the current URL with a new one, without affecting the length of the history (like a redirect).
-
-###### arguments
-- `state` - the location state.
-- `pathname` - the full URL with or without the query.
-- `query` - an object that will be stringified by the router.
-
-##### `go(n)`
-Go forward or backward in the history by `n` or `-n`.
-
-##### `goBack()`
-Go back one entry in the history.
-
-##### `goForward()`
-Go forward one entry in the history.
-
-##### `createPath(pathname, query)`
-Stringifies the query into the pathname, using the router's config.
-
-##### `createHref(pathname, query)`
-Creates a URL, using the router's config. For example, it will add `#/` in front of the `pathname` for hash history.
-
-##### `isActive(pathname, query, indexOnly)`
-Returns `true` or `false` depending on if the current path is active. Will be true for every route in the route branch matched by the `pathname` (child route is active, therefore parent is too), unless `indexOnly` is specified, in which case it will only match the exact path.
-
-###### arguments
-- `pathname` - the full URL with or without the query.
-- `query` - if specified, an object containing key/value pairs that must be active in the current query - explicit `undefined` values require the corresponding key to be missing or `undefined` in the current query
-- `indexOnly` - a boolean (default: `false`).
-
-#### Examples
-```js
-import { History } from 'react-router'
-
-React.createClass({
-  mixins: [ History ],
-  render() {
-    return (
-      <div>
-        <div onClick={() => this.history.pushState(null, '/foo')}>Go to foo</div>
-        <div onClick={() => this.history.replaceState(null, 'bar')}>Go to bar without creating a new history entry</div>
-        <div onClick={() => this.history.goBack()}>Go back</div>
-     </div>
-   )
- }
-})
-```
-
-Let's say you are using bootstrap and want to get `active` on those `li` tags for the Tabs:
-
-```js
-import { Link, History } from 'react-router'
-
-const Tab = React.createClass({
-  mixins: [ History ],
-  render() {
-    const isActive = this.history.isActive(this.props.to, this.props.query, this.props.onlyActiveOnIndex)
-    const className = isActive ? 'active' : ''
-    return <li className={className}><Link {...this.props}/></li>
-  }
-})
-
-// Use it just like <Link/>, and you'll get an anchor wrapped in an `li` with
-// an automatic `active` class on both when appropriate. Add `onlyActiveOnIndex`
-// to trigger <IndexLink/> behavior.
-<Tab to="/" onlyActiveOnIndex>Home</Tab>
-<Tab to="about">About</Tab>
-<Tab href="foo">Foo</Tab>
-```
-
-#### But I’m using Classes
-> Notice how we never told you to use ES6 classes? :)
-
-https://twitter.com/soprano/status/610867662797807617
-
-If you aren't happy using `createClass` for a handful of components in your app for the sake of the `History` mixin, have a couple of options:
-
-- Pass `this.props.history` from your route components down to the components that need it.
-- Use context
-
-```js
-import { PropTypes } from 'react-router'
-
-class MyComponent extends React.Component {
-  doStuff() {
-    this.context.history.pushState(null, '/some/path')
-  }
-}
-
-MyComponent.contextTypes = { history: PropTypes.history }
-```
-
-- [Make your history a module](/docs/guides/advanced/NavigatingOutsideOfComponents.md)
-- Create a higher order component, we might end up shipping with this and deprecating history, just haven't had the time to think it through all the way.
-
-```js
-function connectHistory(Component) {
-  return React.createClass({
-    mixins: [ History ],
-    render() {
-      return <Component {...this.props} history={this.history} />
-    }
-  })
-}
-
-// other file
-import connectHistory from './connectHistory'
-
-class MyComponent extends React.Component {
-  doStuff() {
-    this.props.history.pushState(null, '/some/where')
-  }
-}
-
-export default connectHistory(MyComponent)
-```
-
-
-
-## RouteContext Mixin
-The RouteContext mixin provides a convenient way for route components to set the route in context. This is needed for routes that render elements that want to use the [Lifecycle mixin](#lifecycle) to prevent transitions.
-
-It simply adds `this.context.route` to your component.
+## History Mixin [deprecated]
+Deprecated, please see the `CHANGES.md`.
 
+## RouteContext Mixin [deprecated]
+Deprecated, please see the `CHANGES.md`.
 
 
 ## Utilities
 
-## `useRoutes(createHistory)`
-Returns a new `createHistory` function that may be used to create history objects that know about routing.
-
-- listen((error, nextState) => {})
-- listenBeforeLeavingRoute(route, (nextLocation) => {})
-- match(location, (error, redirectLocation, nextState) => {})
-- isActive(pathname, query, indexOnly=false)
-
+## `useRoutes(createHistory)` [deprecated]
 
 ## `match({ routes, location, ...options }, cb)`
 
@@ -706,4 +596,4 @@ One or many [`Routes`](#route) or [`PlainRoutes`](#plainroute).
 
 
 ## PropTypes
-Coming so soon!
+TODO (Pull Requests Welcome)
diff --git a/docs/guides/advanced/ConfirmingNavigation.md b/docs/guides/advanced/ConfirmingNavigation.md
@@ -1,57 +1,21 @@
 # Confirming Navigation
 
-React Router provides a [`routerWillLeave` lifecycle hook](/docs/Glossary.md#routehook) that React [component](/docs/Glossary.md#component)s may use to prevent a transition from happening or to prompt the user before leaving a [route](/docs/Glossary.md#route). [`routerWillLeave`](/docs/API.md#routerwillleavenextlocation) 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](/docs/Glossary.md#routecomponent)s.
+You can prevent a transition from happening or prompt the user before leaving a [route](/docs/Glossary.md#route) with a leave hook.
 
 ```js
-import { Lifecycle } from 'react-router'
-
 const 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?'
+  contextTypes: {
+    router: React.PropTypes.object
   },
 
-  // ...
-
-})
-```
-
-If you are using ES6 classes for your components, you can use [react-mixin](https://github.com/brigand/react-mixin) to add the `Lifecycle` mixin to your component, but we recommend using `React.createClass` for components that set up router lifecycle hooks.
-
-If you need a [`routerWillLeave`](/docs/API.md#routerwillleavenextlocation) hook in a deeply nested component, simply use the [`RouteContext`](/docs/API.md#routecontext-mixin) mixin in your [route component](/docs/Glossary.md#routecomponent) to put the `route` in context.
-
-```js
-import { Lifecycle, RouteContext } from 'react-router'
-
-const Home = React.createClass({
-
-  // Home should provide its route in context
-  // for descendants further down the hierarchy.
-  mixins: [ RouteContext ],
-
-  render() {
-    return <NestedForm />
-  }
-
-})
-
-const NestedForm = React.createClass({
-
-  // Descendants use the Lifecycle mixin to get
-  // a routerWillLeave method.
-  mixins: [ Lifecycle ],
+  componentDidMount() {
+    this.context.router.setLeaveHook(this.props.route, this.routerWillLeave)
+  },
 
   routerWillLeave(nextLocation) {
+    // return false to prevent a transition w/o prompting the user,
+    // or return a string to allow the user to decide:
     if (!this.state.isSaved)
       return 'Your work is not saved! Are you sure you want to leave?'
   },
diff --git a/docs/guides/advanced/NavigatingOutsideOfComponents.md b/docs/guides/advanced/NavigatingOutsideOfComponents.md
@@ -1,6 +1,6 @@
 # Navigating Outside of Components
 
-While route components get `this.props.router`, and `Router` puts on context `this.context.router` to navigate around, many apps want to be able to navigate outside of their components. They can do that with the history the app gives to `Router`.
+While you can use `this.context.router` to navigate around, many apps want to be able to navigate outside of their components. They can do that with the history the app gives to `Router`.
 
 ```js
 // your main file that renders a Router
