Merge pull request #2287 from nfl/feature/getIndexRoute

Document getIndexRoute

Author: mjackson

docs/API.md

@@ -68,7 +68,7 @@ A function used to convert an object from [`Link`](#link)s or calls to
 A function used to convert a query string into an object that gets passed to route component props.
 
 ##### `onError(error)`
-While the router is matching, errors may bubble up, here is your opportunity to catch and deal with them. Typically these will come from async features like [`route.getComponents`](#getcomponentscallback) and [`route.getChildRoutes`](#getchildrouteslocation-callback).
+While the router is matching, errors may bubble up, here is your opportunity to catch and deal with them. Typically these will come from async features like [`route.getComponents`](#getcomponentscallback), [`route.getIndexRoute`](#getindexroutecallback), and [`route.getChildRoutes`](#getchildrouteslocation-callback).
 
 ##### `onUpdate()`
 Called whenever the router updates its state in response to URL changes.
@@ -360,6 +360,19 @@ Please see the [Index Routes guide](/docs/guides/basics/IndexRoutes.md).
 #### Props
 All the same props as [Route](#route) except for `path`.
 
+##### `getIndexRoute(location, callback)`
+Same as `IndexRoute` but asynchronous, useful for
+code-splitting.
+
+###### `callback` signature
+`cb(err, component)`
+
+```js
+<Route path="courses/:courseId" getIndexRoute={(location, cb) => {
+  // do asynchronous stuff to find the index route
+  cb(null, Index)
+}}/>
+```
 
 
 ## IndexRedirect

docs/guides/advanced/DynamicRouting.md

@@ -10,7 +10,7 @@ A router is the perfect place to handle code splitting: it's responsible for set
 
 React Router does all of its [path matching](/docs/guides/basics/RouteMatching.md) and component fetching asynchronously, which allows you to not only load up the components lazily, *but also lazily load the route configuration*. You really only need one route definition in your initial bundle, the router can resolve the rest on demand.
 
-Routes may define [`getChildRoutes`](/docs/API.md#getchildrouteslocation-callback) and [`getComponents`](/docs/API.md#getcomponentslocation-callback) methods. These are asynchronous and only called when needed. We call it "gradual matching". React Router will gradually match the URL and fetch only the amount of route configuration and components it needs to match the URL and render.
+Routes may define [`getChildRoutes`](/docs/API.md#getchildrouteslocation-callback), [`getIndexRoute`](/docs/API.md#getindexroutelocation-callback), and [`getComponents`](/docs/API.md#getcomponentslocation-callback) methods. These are asynchronous and only called when needed. We call it "gradual matching". React Router will gradually match the URL and fetch only the amount of route configuration and components it needs to match the URL and render.
 
 Coupled with a smart code splitting tool like [webpack](http://webpack.github.io/), a once tireless architecture is now simple and declarative.
 
@@ -28,6 +28,12 @@ const CourseRoute = {
     })
   },
 
+  getIndexRoute(location, callback) {
+    require.ensure([], function (require) {
+      callback(null, require('./components/Index'))
+    })
+  },
+
   getComponents(location, callback) {
     require.ensure([], function (require) {
       callback(null, require('./components/Course'))