Merge pull request #371 from shakacode/docs-overhaul

Docs overhaul

docs/additional-reading/webpack-dev-server.md

@@ -0,0 +1,16 @@
+## Developing with the Webpack Dev Server
+One of the benefits of using webpack is access to [webpack's dev server](https://webpack.github.io/docs/webpack-dev-server.html) and its [hot module replacement](https://webpack.github.io/docs/hot-module-replacement-with-webpack.html) functionality.
+
+The webpack dev server with HMR will apply changes from the code (or styles!) to the browser as soon as you save whatever file you're working on. You won't need to reload the page, and your data will still be there. Start foreman as normal (it boots up the Rails server *and* the webpack HMR dev server at the same time).
+
+  ```bash
+  foreman start -f Procfile.dev
+  ```
+
+Open your browser to [localhost:3000](http://localhost:3000). Whenever you make changes to your JavaScript code in the `client` folder, they will automatically show up in the browser. Hot module replacement is already enabled by default.
+
+Note that **React-related error messages are possibly more helpful when encountered in the dev server** than the Rails server as they do not include noise added by the React on Rails gem.
+
+### Adding Additional Routes for the Dev Server
+As you add more routes to your front-end application, you will need to make the corresponding API for the dev server in `client/server.js`. See our example `server.js` from our [tutorial](https://github.com/shakacode/react-webpack-rails-tutorial/blob/master/client%2Fserver-express.js).
+

docs/api/javascript-api.md

@@ -0,0 +1,37 @@
+# ReactOnRails JavaScript API
+The best source of docs is the main [ReactOnRails.js](node_package/src/ReactOnRails.js) file. Here's a quick summary. No guarantees that this won't be outdated!
+
+```js
+  /**
+   * Main entry point to using the react-on-rails npm package. This is how Rails will be able to
+   * find you components for rendering.
+   * @param components (key is component name, value is component)
+   */
+  register(components)
+
+  /**
+   * Allows registration of store generators to be used by multiple react components on one Rails
+   * view. store generators are functions that take one arg, props, and return a store. Note that
+   * the setStore API is different in tha it's the actual store hydrated with props.
+   * @param stores (key is store name, value is the store generator)
+   */
+  registerStore(stores)
+
+  /**
+   * Allows retrieval of the store by name. This store will be hydrated by any Rails form props.
+   * Pass optional param throwIfMissing = false if you want to use this call to get back null if the
+   * store with name is not registered.
+   * @param name
+   * @param throwIfMissing Defaults to true. Set to false to have this call return undefined if
+   *        there is no store with the given name.
+   * @returns Redux Store, possibly hydrated
+   */
+  getStore(name, throwIfMissing = true )
+
+  /**
+   * Set options for ReactOnRails, typically before you call ReactOnRails.register
+   * Available Options:
+   * `traceTurbolinks: true|false Gives you debugging messages on Turbolinks events
+   */
+  setOptions(options)
+```

docs/api/ruby-api-hot-reload-view-helpers.md

@@ -0,0 +1,41 @@
+## Hot Reloading View Helpers
+The `env_javascript_include_tag` and `env_stylesheet_link_tag` support the usage of a webpack dev server for providing the JS and CSS assets during development mode. See the [shakacode/react-webpack-rails-tutorial](https://github.com/shakacode/react-webpack-rails-tutorial/) for a working example.
+
+The key options are `static` and `hot` which specify what you want for static vs. hot. Both of these params are optional, and support either a single value, or an array.
+
+static vs. hot is picked based on whether `ENV["REACT_ON_RAILS_ENV"] == "HOT"`
+
+```erb
+ <%= env_stylesheet_link_tag(static: 'application_static',
+                             hot: 'application_non_webpack',
+                             media: 'all',
+                             'data-turbolinks-track' => true)  %>
+
+ <!-- These do not use turbolinks, so no data-turbolinks-track -->
+ <!-- This is to load the hot assets. -->
+ <%= env_javascript_include_tag(hot: ['http://localhost:3500/vendor-bundle.js',
+                                      'http://localhost:3500/app-bundle.js']) %>
+
+ <!-- These do use turbolinks -->
+ <%= env_javascript_include_tag(static: 'application_static',
+                                hot: 'application_non_webpack',
+                                'data-turbolinks-track' => true) %>
+```
+
+See application.html.erb for usage example and [application.html.erb](https://github.com/shakacode/react-webpack-rails-tutorial/blob/master/app%2Fviews%2Flayouts%2Fapplication.html.erb)
+
+Helper to set CSS and JS assets depending on if we want static or "hot", which means from the Webpack dev server.
+
+In this example, `application_non_webpack` is simply a CSS asset pipeline file which includes styles not placed in the webpack build. The same can be said for `application_non_webpack` for JS files. Note, the suffix is not used in the helper calls.
+
+We don't need styles from the webpack build, as those will come via the JavaScript include tags.
+
+The key options are `static` and `hot` which specify what you want for static vs. hot. Both of
+these params are optional, and support either a single value, or an array.
+
+```erb
+ <%= env_stylesheet_link_tag(static: 'application_static',
+                             hot: 'application_non_webpack',
+                             media: 'all',
+                             'data-turbolinks-track' => true)  %>
+```

docs/api/ruby-api.md

@@ -0,0 +1,3 @@
+PENDING:
+
+Should we document the view helpers here concisely?

docs/basics/generator.md

@@ -0,0 +1,50 @@
+- [Generator](#generator)
+  - [Understanding the Organization of the Generated Client Code](#understanding-the-organization-of-the-generated-client-code)
+  - [Redux](#redux)
+    - [Multiple React Components on a Page with One Store](#multiple-react-components-on-a-page-with-one-store)
+  - [Using Images and Fonts](#using-images-and-fonts)
+
+The `react_on_rails:install` generator combined with the example pull requests of generator runs will get you up and running efficiently. There's a fair bit of setup with integrating Webpack with Rails. Defaults for options are such that the default is for the flag to be off. For example, the default for `-R` is that `redux` is off, and the default of `-b` is that `skip-bootstrap` is off.
+
+Run `rails generate react_on_rails:install --help` for descriptions of all available options:
+
+```
+Usage:
+  rails generate react_on_rails:install [options]
+
+Options:
+  -R, [--redux], [--no-redux]                          # Install Redux gems and Redux version of Hello World Example
+  -S, [--server-rendering], [--no-server-rendering]    # Add necessary files and configurations for server-side rendering
+
+Runtime options:
+  -f, [--force]                    # Overwrite files that already exist
+  -p, [--pretend], [--no-pretend]  # Run but do not make any changes
+  -q, [--quiet], [--no-quiet]      # Suppress status output
+  -s, [--skip], [--no-skip]        # Skip files that already exist
+
+Description:
+    Create react on rails files for install generator.
+```
+
+For a clear example of what each generator option will do, see our generator results repo: [Generator Results](https://github.com/shakacode/react_on_rails-generator-results/blob/master/README.md). Each pull request shows a git "diff" that highlights the changes that the generator has made. Another good option is to create a simple test app per the [Tutorial](docs/tutorial.md).
+
+### Understanding the Organization of the Generated Client Code
+The generated client code follows our organization scheme. Each unique set of functionality, is given its own folder inside of `client/app/bundles`. This encourages for modularity of *domains*.
+
+Inside of the generated "HelloWorld" domain you will find the following folders:
+
++  `startup`: two types of files, one that return a container component and implement any code that differs between client and server code (if using server-rendering), and a `clientRegistration` file that exposes the aforementioned files (as well as a `serverRegistration` file if using server rendering). These registration files are what webpack is using as an entry point.
++ `containers`: "smart components" (components that have functionality and logic that is passed to child "dumb components").
++ `components`: includes "dumb components", or components that simply render their properties and call functions given to them as properties by a parent component. Ultimately, at least one of these dumb components will have a parent container component.
+
+You may also notice the `app/lib` folder. This is for any code that is common between bundles and therefore needs to be shared (for example, middleware).
+
+### Redux
+If you have used the `--redux` generator option, you will notice the familiar additional redux folders in addition to the aforementioned folders. The Hello World example has also been modified to use Redux.
+
+Note the organizational paradigm of "bundles". These are like application domains and are used for grouping your code into webpack bundles, in case you decide to create different bundles for deployment. This is also useful for separating out logical parts of your application. The concept is that each bundle will have it's own Redux store. If you have code that you want to reuse across bundles, including components and reducers, place them under `/client/app/lib`.
+
+### Using Images and Fonts
+The generator has amended the folders created in `client/assets/` to Rails's asset path. We recommend that if you have any existing assets that you want to use with your client code, you should move them to these folders and use webpack as normal. This allows webpack's development server to have access to your assets, as it will not be able to see any assets in the default Rails directories which are above the `/client` directory.
+
+Alternatively, if you have many existing assets and don't wish to move them, you could consider creating symlinks from client/assets that point to your Rails assets folders inside of `app/assets/`. The assets there will then be visible to both Rails and webpack.

docs/basics/migrating-from-react-rails.md

@@ -0,0 +1,17 @@
+## Migrate From react-rails
+If you are using [react-rails](https://github.com/reactjs/react-rails) in your project, it is pretty simple to migrate to [react_on_rails](https://github.com/shakacode/react_on_rails).
+
+- Remove the 'react-rails' gem from your Gemfile.
+
+- Remove the generated lines for react-rails in your application.js file.
+
+```
+//= require react
+//= require react_ujs
+//= require components
+```
+
+- Follow our getting started guide: https://github.com/shakacode/react_on_rails#getting-started.
+
+Note: If you have components from react-rails you want to use, then you will need to port them into react_on_rails which uses webpack instead of the asset pipeline.
+