Merge pull request #87 from jwalton/master

Documentation for nagivateAction.

README.md

@@ -1,12 +1,12 @@
-# flux-router-component 
+# flux-router-component
 
 [![npm version](https://badge.fury.io/js/flux-router-component.svg)](http://badge.fury.io/js/flux-router-component)
 [![Build Status](https://travis-ci.org/yahoo/flux-router-component.svg?branch=master)](https://travis-ci.org/yahoo/flux-router-component)
 [![Dependency Status](https://david-dm.org/yahoo/flux-router-component.svg)](https://david-dm.org/yahoo/flux-router-component)
 [![devDependency Status](https://david-dm.org/yahoo/flux-router-component/dev-status.svg)](https://david-dm.org/yahoo/flux-router-component#info=devDependencies)
 [![Coverage Status](https://coveralls.io/repos/yahoo/flux-router-component/badge.png?branch=master)](https://coveralls.io/r/yahoo/flux-router-component?branch=master)
 
-Provides navigational React components (`NavLink`) and router mixin (`RouterMixin`) for applications built with [Flux](http://facebook.github.io/react/docs/flux-overview.html) architecture.  Please check out [examples](https://github.com/yahoo/flux-router-component/tree/master/examples) of how to use these components.
+Provides navigational React components (`NavLink`), router mixin (`RouterMixin`), and action `navigateAction` for applications built with [Flux](http://facebook.github.io/react/docs/flux-overview.html) architecture.  Please check out [examples](https://github.com/yahoo/flux-router-component/tree/master/examples) of how to use these components.
 
 ## Context and Expected Context Methods
 
@@ -34,6 +34,10 @@ An example of such context is the `ComponentContext` provided by [fluxible-plugi
 
 [Docs](https://github.com/yahoo/flux-router-component/blob/master/docs/router-mixin.md)
 
+## navigateAction
+
+[Docs](https://github.com/yahoo/flux-router-component/blob/master/docs/navigateAction.md)
+
 
 ## History Management (Browser Support and Hash-Based Routing)
 Considering different application needs and [different browser support levels for pushState](http://caniuse.com/#search=pushstate), this library provides the following options for browser history management:

docs/navigateAction.md

@@ -0,0 +1,22 @@
+# navigateAction
+
+`navigateAction` is an action which will load a new route and update the URL of your application.  You can call this action directly to update the URL of your application.  It is also invoked indirectly when a user clicks on a [`NavLink`](./navlink.md).
+
+`navigateAction` expects a `{method, url}` object as a payload, where `method` is the HTTP method used to retrieve the URL (e.g. 'get'.)
+
+If no matching route is found, `navigateAction` will call the callback with an error where `err.status` is set to 404.
+
+If a route is successfully matched, `navigateAction` will first dispatch a `CHANGE_ROUTE_START` event, with route data as the payload (see below).  `navigateAction` will then try to find an action associated with the route from the route config; this can either be an action function or the name of an action function (retrieved with `context.getAction(name)`.)  If an action is found, it is executed, with route data as the payload.  `navigateAction` finally will dispatch a `CHANGE_ROUTE_SUCCESS` event, or `CHANGE_ROUTE_FAILURE` event if the route's action returns an error.
+
+## Route Data
+
+`navigateAction` passes a route data structure as the payload for all events and as the payload for any called actions.  This consists of:
+
+| Field Name | Description                             |
+|------------|-----------------------------------------|
+| name       | The name of the matched route.          |
+| url        | The actual URL that was matched.        |
+| params     | Parameters parsed from the route.       |
+| query      | Query parameters parsed from the URL. Note that if a query parameter occurs multiple times, the value in this hash will be an array. |
+| config     | The configuation for the route.         |
+| navigate   | The payload passed to `navigateAction`. |

docs/navlink.md

@@ -1,5 +1,6 @@
 # NavLink
-`NavLink` is the a React component for navigational links.  When the link is clicked, NavLink will dispatch `NAVIGATE` action to flux dispatcher.  The dispatcher can then dispatch the action to the stores that can handle it.
+`NavLink` is the a React component for navigational links.  When the link is clicked, NavLink will execute a [navigateAction]('./navigateAction.md').  Stores can register for `CHANGE_ROUTE_SUCCESS` handlers if they are interested
+in navigation events.
 
 | Prop Name | Prop Type | Description |
 |------------|---------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|