moar docs

Author: ryanflorence

doc/00 Guides/Path Matching.md

@@ -0,0 +1,2 @@
+# TODO
+

doc/01 Route Configuration/0 Route.md

@@ -9,8 +9,9 @@ Props
 The path used in the URL.
 
 It will concat with the parent route's path unless it starts with `/`.
-In which case you will need to use `childWillMatch` on the parent route
-so the router knows to keep going down the route tree.
+In which case you will need to use `absoluteChildPaths` on the parent
+route so the router knows to keep going down the route tree even though
+the parent path doesn't match the url.
 
 If left undefined, the router will try to match the child routes.
 
@@ -27,8 +28,8 @@ be rendered by the parent route component with `this.props.children`.
 ```js
 var routes = (
   <Route component={App}>
-    <Route path="groups" components={Groups}/>
-    <Route path="users" components={Users}/>
+    <Route path="groups" component={Groups}/>
+    <Route path="users" component={Users}/>
   </Route>
 );
 
@@ -47,12 +48,18 @@ var App = React.createClass({
 ### `components`
 
 Routes can define multiple components as an object of name:component
-pairs to be rendered when the path matches the url. They can be rendred
+pairs to be rendered when the path matches the url. They can be rendered
 by the parent route component with `this.props[name]`.
 
 #### Example
 
 ```js
+// think of it outside the context of the router, if you had pluggable
+// portions of your `render`, you might do it like this
+<App main={<Users/>} sidebar={<UsersSidebar/>}/>
+<App main={<Groups/>} sidebar={<GroupsSidebar/>}/>
+
+// So with the router its looks like this:
 var routes = (
   <Route component={App}>
     <Route path="groups" components={{main: Groups, sidebar: GroupsSidebar}}/>
@@ -89,6 +96,7 @@ var Users = React.createClass({
     );
   }
 });
+
 ```
 
 ### `getComponents(state, cb)`

doc/01 Route Configuration/Plain Route.md

@@ -1,5 +1,5 @@
 A route configuration object. `Router` turns JSX `<Route/>`s into
-these objects, but you can use them direclty if you prefer. All of the
+these objects, but you can use them directly if you prefer. All of the
 props are the same as `<Route/>` props, except those listed here.
 
 Props
@@ -13,7 +13,7 @@ An array of child routes, same as `children` in JSX route configs.
 
 Same as `childRoutes` but asynchronous and receives the location state.
 Useful for code-splitting and dynamic route matching (given some state
-or session data, return a different set of child routes).
+or session data to return a different set of child routes).
 
 #### `callback` signature
 
@@ -39,5 +39,20 @@ var myRoute = {
     cb(null, [announcementsRoute, gradesRoute, assignmentsRoute]);
   }
 };
+
+// navigation dependent child routes
+// can link with some state
+<Link to="/picture/123" state={{fromDashboard: true}}/>
+
+var myRoute = {
+  path: 'picture/:id',
+  getChildRoutes (state, cb) {
+    // state gets passed to `getChildRoutes`
+    if (state && state.fromDashboard)
+      cb(null, [dashboardPictureRoute])
+    else
+      cb(null, [pictureRoute])
+  }
+};
 ```
 

doc/02 Components/0 Router.md

@@ -11,6 +11,10 @@ history changes, `Router` will match a branch of its [`Routes`][Route],
 and render their configured [components][RouteComponent], with child
 route components nested inside the parents.
 
+### `routes`
+
+Alias for `children`.
+
 ### `history` (required)
 
 The [`History`][History] the router should set up and listen for changes
@@ -44,15 +48,6 @@ function createElement(Component, props) {
 }
 ```
 
-### `parseQueryString(queryString)`
-
-A custom prop to parse query strings differently than the default.
-
-### `stringifyQuery(obj)`
-
-A custom prop to stringify query objects that come from [`Links`][Link]
-and [`router.transitionTo()`][transitionTo].
-
 ### `onError(error)`
 
 While the router is matching, errors may bubble up, here

doc/03 History/0 Histories.md

@@ -1,5 +1,29 @@
 `Router` sets up a `History` and updates `Router` state when the
-`History` emits changes.  You can implement your own history, if you'd
-like to handle query parsing in a custom way, as soon as we decide what
-that API looks like ...
+`History` emits changes.  You can implement your own history, or create
+an instance of one with your own options for query parsing.
+
+```js
+// typical usage
+import BrowserHistory from 'react-router/lib/BrowserHistory';
+<Router history={BrowserHistory}/>
+```
+
+If you need to do your own query parsing:
+
+```js
+// note the `{ ... }` in the import statement...
+import { BrowserHistory } from 'react-router/lib/BrowserHistory';
+// ...this gives you a class instead of a singleton instance
+
+var history = new BrowserHistory({
+  parseQueryString(string) {
+    return customParse(string);
+  },
+  stringifyQuery(obj) {
+    return customStringify(obj);
+  }
+});
+
+var router = <Router history={history}/>;
+```
 

doc/03 History/HashHistory.md

@@ -16,9 +16,21 @@ For example: ` http://example.com/?lang=es#/messages?sort=date`,
 `lang=es` is invisible to a `HashHistory` router, but `sort=date` is
 recognized, and will be used as the query parameters.
 
+Using location state
+--------------------
+
+`HashHistory` shims the `state` features of `window.history.pushState`,
+but you have to opt-in because it puts a key in the URL and we didn't
+want a bunch of issues opened about it :P
+
+If you want to use the `location.state` features, opt-in. See the
+examples.
+
 Example
 -------
 
+Normal usage
+
 ```js
 import { Router } from 'react-router';
 import HashHistory from 'react-router/lib/HashHistory';
@@ -28,6 +40,25 @@ React.render((
     {/* ... */}
   </Router>
 ), document.body);
+```
+
+Opting in to the `state` features:
+
+```js
+// note the `{ ... }` syntax on the import
+import { HashHistory } from 'react-router/lib/HashHistory';
+
+// use the default key which is `_key`
+var history = new HashHistory({ queryKey: true });
+
+// use your own
+var history = new HashHistory({queryKey: 'k'});
+
+React.render((
+  <Router history={history}>
+    {/* ... */}
+  </Router>
+), document.body);
 ```
 
   [Histories]:#TODO