updated flux docs

Author: ryanflorence

docs/guides/flux.md

@@ -1,47 +1,80 @@
 React Router in a Flux App
 ==========================
 
-```js
-// router.js
-var routes = require('./routes');
-var Router = require('react-router');
-
-// we can create a router before "running" it
-var router = Router.create({
-  routes: routes,
-  location: Router.HistoryLocation
-});
+Circular Dependencies in Actions
+--------------------------------
 
-module.exports = router;
-```
+Oftentimes your actions need to call `transitionTo` on the router, you
+can't just require your router instance as a module into your actions
+because your routes require views which also require the actions,
+creating a cycle indirectly.
+
+`router.js -> routes.js -> SomeComponent.js -> actions.js -> router.js`
+
+To avoid this, you can do one of two things:
+
+1. Send the component to the action, think of it like `event.target` in
+   DOM events if it bothers you.
+
+    ```js
+    var SomeActionCreators = require('./SomeActionCreators');
+    var Something = React.createClass({
+      mixins: [ Router.Navigation ],
+      handleClick () {
+        SomeActionCreators.doStuff({ sourceComponent: this });
+      }
+    });
+    ```
+
+   and then in `SomeActionCreators.doStuff` call
+   `payload.sourceComponent.transitionTo(...)`
+
+2. Use some sort of application container, or module container for the
+   router instance.
+
+    ```js
+    // RouterContainer.js
+    var _router = null;
+    exports.set(router => _router = router);
+    exports.get(() => _router);
+    ```
+
+    ```js
+    // main bootstrap file, like main.js or whatever
+    var RouterContainer = require('./RouterContainer');
+    var routes = require('./routes');
+    RouterContainer.set(Router.create({ routes }));
+    ```
+
+   and then in your `ActionCreators.js`
+
+    ```js
+    var RouterContainer = require('./RouterContainer');
+    exports.doStuff = (payload) => {
+      // stuff
+      RouterContainer.get().transitionTo(...);
+    }
+    ```
+
+Handling route changes as actions
+---------------------------------
+
+If you'd like to handle route changes as actions, it could look
+something like this:
 
 ```js
-// SomeActions.js
-
-// and then action creators can require it like other
-// singletons in the app (or if you don't use singletons,
-// do something else with the router you created in
-// router.js)
-var router = require('../router');
-
-module.exports = {
-  doSomeTransitionThing: function () {
-    router.transitionTo('somewhere');
-  }
-};
+Router.run(routes, (Handler, state) => {
+  ActionCreators.changeRoute({ Handler, state });
+});
 ```
 
 ```js
-// main.js
-
-// finally, run it in your main script
-var React = require('react');
-var router = require('./router');
-router.run(function (Handler, state) {
-  // you might want to push the state of the router to a
-  // store for whatever reason
-  RouterActions.routeChange({routerState: state});
+// ActionCreators.js
+exports.changeRoute = (payload) => {
+  var { Handler } = payload;
   React.render(<Handler/>, document.body);
-});
+};
 ```
 
+This is not how we use the router with flux, but to each their own.
+