Mega documentation update (shakacode#1103)

docs/LICENSE.md → LICENSE.md

@@ -1,6 +1,6 @@
 # The MIT License (MIT)
 
-Copyright (c) 2017 Justin Gordon and ShakaCode, http://www.shakacode.com
+Copyright (c) 2017, 2018 Justin Gordon and ShakaCode, http://www.shakacode.com
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

SUMMARY.md

@@ -1,50 +1,63 @@
-# Table of Content
+# Table of Contents
 
-### **Rails**
-  + [Rails Assets](./docs/additional-reading/rails-assets.md)
++ [Home](./README.md)
+
+## **Basics**
+  + [React on Rails Basic Installation Tutorial](./docs/tutorial.md)
+  + [Webpack Configuration](./docs/basics/webpack-configuration.md)
+  + [How React on Rails Works](./docs/basics/how-react-on-rails-works.md)
+  + [Recommended Project Structure](./docs/basics/recommended-project-structure.md)
+  + [Rails Context](./docs/basics/rails-context-generator-functions.md)
+  + [Caching and Performance: React on Rails Pro](https://github.com/shakacode/react_on_rails/wiki).
+  + [Deployment](docs/basics/deployment.md).
+  + [React on Rails Internationalization (I18n, localization)](docs/basics/i18n.md)
+  + [RSpec Test Helpers Configuration](docs/basics/rspec-configuration.md)
+  + [Upgrading React on Rails](docs/basics/upgrading-react-on-rails.md)
+
+## **API**
+  - [View Helpers API](./docs/api/view-helpers-api.md)
+  - [JavaScript API](./docs/api/javascript-api.md)
+  - [Redux Store API](./docs/api/redux-store-api.md)
+
+## **Additional Details**
+  + [Migration from react-rails](./docs/basics/migrating-from-react-rails.md)
+  + [Generator Details](docs/basics/generator-details.md)
+  + [Updating Dependencies](./docs/additional-reading/updating-dependencies.md)
+  + [Manual Installation Overview](docs/misc-pending/manual-installation-overview.md)
+
+## **Rails**
   + [Rails Engine Integration](./docs/additional-reading/rails-engine-integration.md)
   + [Rails View Rendering from Inline JavaScript](./docs/additional-reading/rails_view_rendering_from_inline_javascript.md)
-  + [RSpec Configuration](./docs/additional-reading/rspec-configuration.md)
   + [Turbolinks](./docs/additional-reading/turbolinks.md)
-  + [React on Rails Internationalization (I18n)](https://github.com/shakacode/react_on_rails/blob/master/docs/basics/i18n.md)
+  + [Rails Assets](docs/misc-pending/rails-assets.md)
+  + [Converting a Rails 5 API only app to a Rails app](./docs/additional-reading/convert-rails-5-api-only-app.md)
 
-### **Javascript**
+## **Javascript**
   + [Node Dependencies, NPM, and Yarn](./docs/additional-reading/node-dependencies-and-npm.md)
   + [Babel](./docs/additional-reading/babel.md)
   + [React Router](./docs/additional-reading/react-router.md)
   + [React & Redux](./docs/additional-reading/react-and-redux.md)
-  + [Webpack](./docs/additional-reading/webpack.md)
-  + [Webpack Configuration](./docs/additional-reading/webpack.md)
-  + [Webpack Cookbook](https://christianalfoni.github.io/react-webpack-cookbook/index.html)
-  + [Developing with the Webpack Dev Server](docs/additional-reading/webpack-dev-server.md)
-  + [Node Server Rendering](./docs/additional-reading/node-server-rendering.md)
+  + [Webpack Tips](./docs/additional-reading/webpack-tips.md)
   + [Server Rendering Tips](./docs/additional-reading/server-rendering-tips.md)
-  + [Code Splitting](./docs/additional-reading/code-splitting.md)
+  + [Code Splitting](docs/misc-pending/code-splitting.md)
   + [AngularJS Integration and Migration to React on Rails](./docs/additional-reading/angular-js-integration-migration.md)
-  + [Webpack, the Asset Pipeline, and Using Assets w/ React](./docs/additional-reading/rails-assets-relative-paths.md)
 
-### **Development**
-  + [React on Rails Basic Installation Tutorial](./docs/tutorial.md)
-  + [Installation Overview](./docs/basics/installation-overview.md)
-  + [Migration from react-rails](./docs/basics/migrating-from-react-rails.md)
-  + [Recommended Project Structure](./docs/additional-reading/recommended-project-structure.md)
-  + [Generator Tips](./docs/basics/generator.md)
-  + [Hot Reloading of Assets For Rails Development](./docs/additional-reading/hot-reloading-rails-development.md)
+## **Deployment**
   + [Heroku Deployment](./docs/additional-reading/heroku-deployment.md)
   + [Elastic Beanstalk Deployment](./docs/additional-reading/elastic-beanstalk.md)
-  + [Updating Dependencies](./docs/additional-reading/updating-dependencies.md)
 
-### **API**
-  + [JavaScript API](./docs/api/javascript-api.md)
-  + [Ruby API](./docs/api/ruby-api.md)
+## Older, Non-Webpack Docs
   + [Setting up Hot Reloading during Rails Development, API docs](./docs/api/ruby-api-hot-reload-view-helpers.md)
+  + [Developing with the Webpack Dev Server](./docs/additional-reading/webpack-dev-server.md)
+  + [Webpack, the Asset Pipeline, and Using Assets w/ React](./docs/additional-reading/rails-assets-relative-paths.md)
+  + [Hot Reloading of Assets For Rails Development](./docs/additional-reading/hot-reloading-rails-development.md)
 
-### **[CONTRIBUTING](CONTRIBUTING.md)**
+## **[CONTRIBUTING](CONTRIBUTING.md)**
   + [Generator Testing](./docs/contributor-info/generator-testing.md)
   + [Linting](./docs/contributor-info/linters.md)
   + [Releasing](./docs/contributor-info/releasing.md)
 
-### **Misc**
+## **Misc**
   + [Tips](./docs/additional-reading/tips.md)
   + [Changelog](./CHANGELOG.md)
   + [Projects](./PROJECTS.md)

docs/additional-reading/convert-rails-5-api-only-app.md

@@ -0,0 +1,19 @@
+# Convert Rails 5 API only app to a Rails app
+
+1. Go to the directory where you created your app
+
+```bash
+$ rails new your-current-app-name
+```
+
+Rails will start creating the app and will skip the files you have already created. If there is some conflict then it will stop and you need to resolve it manually. be careful at this step as it might replace you current code in conflicted files.
+
+2. Resolve conflicts
+
+```
+1. Press "d" to see the difference
+2. If it is only adding lines then press "y" to continue
+3. If it is removeing some of your code then press "n" and add all additions manually
+```
+
+3. Run `bundle install` and follow [the instructions for installing into an existing Rails app](../basics/installation-into-an-existing-rails-app.md).*

docs/additional-reading/credits.md

@@ -0,0 +1,10 @@
+## Authors
+
+[The Shaka Code team!](http://www.shakacode.com/about/)
+
+The origins of the project began with the need to do a rich JavaScript interface for a ShakaCode's client. The choice to use Webpack and Rails is described in [Fast Rich Client Rails Development With Webpack and the ES6 Transpiler](http://www.railsonmaui.com/blog/2014/10/03/integrating-webpack-and-the-es6-transpiler-into-an-existing-rails-project/).
+
+The gem project started with [Justin Gordon](https://github.com/justin808/) pairing with [Samnang Chhun](https://github.com/samnang) to figure out how to do server rendering with Webpack plus Rails. [Alex Fedoseev](https://github.com/alexfedoseev) then joined in. [Rob Wise](https://github.com/robwise), [Aaron Van Bokhoven](https://github.com/aaronvb), and [Andy Wang](https://github.com/yorzi) did the bulk of the generators. Many others have [contributed](https://github.com/shakacode/react_on_rails/graphs/contributors).
+
+The gem was initially inspired by the [react-rails gem](https://github.com/reactjs/react-rails).
+

docs/additional-reading/rails-assets-relative-paths.md

@@ -77,7 +77,7 @@ Note: _You can output these files in the asset pipeline wherever you see fit. My
 
 Lastly, we will set the publicPath to our file(s). This will be the endpoint on our rails web server that you can visit to reach the asset (if you don't know how this works, read the [intro](#using-webpack-bundled-assets-with-the-rails-asset-pipeline)). If you've been following the previous steps, you know that we set our outputPath for our assets to be absolute at `app/assets/webpack/webpack-assets/`, which your rails app should end up hosting at `/assets/webpack-assets/file-name+hash.ext` when the server is run.
 
-Note: _If you're having a hard time figuring out what an asset's path will be on your rails server, simply run `rake assets:precompile` and `cd public/`. The path from there to your file will then be the path/url on your web server to that asset. On top of this, it is also a good idea to check out [this doc](./rails-assets.md) to understand how `react_on_rails` allows us to access these files after precompilation, when Rails applies another hash onto the asset._
+Note: _If you're having a hard time figuring out what an asset's path will be on your rails server, simply run `rake assets:precompile` and `cd public/`. The path from there to your file will then be the path/url on your web server to that asset. On top of this, it is also a good idea to check out [this doc](../misc-pending/rails-assets.md) to understand how `react_on_rails` allows us to access these files after precompilation, when Rails applies another hash onto the asset._
 
 Our publicPath setting will match the path to our outputted assets on our rails web server. Given our assets in this example will be outputted to `/app/assets/webpack/webpack-assets/` and hosted at `/assets/webpack-assets/`, our publicPath would be:
 
@@ -192,4 +192,4 @@ module.exports = {
 };
 ```
 
-If you'd like to understand how react_on_rails handles these bundled assets after asset precompilation and in production mode, check out: [Rails Assets](./rails-assets.md).
+If you'd like to understand how react_on_rails handles these bundled assets after asset precompilation and in production mode, check out: [Rails Assets](../misc-pending/rails-assets.md).

docs/additional-reading/server-rendering-tips.md

@@ -9,10 +9,8 @@ Be sure to use mini_racer. See [issues/428](https://github.com/shakacode/react_o
 - You can conditionally avoid running code that references document by passing in a boolean prop to your top level react
   component. Since the passed in props Hash from the view helper applies to client and server side code, the best way to
   do this is to use a generator function.
-- If you're serious about server rendering, it's worth the effort to have different entry points for client and server rendering. It's worth the extra complexity.
-- You can enable node server rendering if you want. See more information here: https://github.com/shakacode/react_on_rails/blob/master/docs/additional-reading/node-server-rendering.md
-
-The point is that you have separate files for top level client or server side, and you pass some extra option indicating that rendering is happening server side.
+- If you're serious about server rendering, it's worth the effort to have different entry points for client and server rendering. It's worth the extra complexity. The point is that you have separate files for top level client or server side, and you pass some extra option indicating that rendering is happening server side.
+- You can enable Node.js server rendering via [React on Rails Pro](https://github.com/shakacode/react_on_rails/wiki).
 
 ## Troubleshooting Server Rendering
 

docs/additional-reading/webpack.md

@@ -18,5 +18,5 @@ Webpack v2 makes this very convenient! See:
 * [Implicit Common Vendor Chunk](https://webpack.js.org/guides/code-splitting-libraries/#implicit-common-vendor-chunk)
 * [Manifest File](https://webpack.js.org/guides/code-splitting-libraries/#manifest-file)
 
-
-
+## Webpack v4
+Webpack v4 is heartily recommended. If you need help with migrating your project to Webpack v4, please contact me, [[email protected]](mailto:[email protected]).

docs/api/javascript-api.md

@@ -1,5 +1,25 @@
 # 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!
+## CSRF protection
+
+Rails has built-in protection for Cross-Site Request Forgery (CSRF), see [Rails Documentation](http://guides.rubyonrails.org/security.html#cross-site-request-forgery-csrf). To nicely utilize this feature in JavaScript requests, React on Rails provides two helpers that can be used as following for POST, PUT or DELETE requests:
+
+```js
+import ReactOnRails from 'react-on-rails';
+
+// reads from DOM csrf token generated by Rails in <%= csrf_meta_tags %>
+csrfToken = ReactOnRails.authenticityToken();
+
+// compose Rails specific request header as following { X-CSRF-Token: csrfToken, X-Requested-With: XMLHttpRequest }
+header = ReactOnRails.authenticityHeaders(otherHeader);
+```
+
+If you are using [jquery-ujs](https://github.com/rails/jquery-ujs) for AJAX calls, then these helpers are not needed because the [jquery-ujs](https://github.com/rails/jquery-ujs) library updates header automatically, see [jquery-ujs documentation](https://robots.thoughtbot.com/a-tour-of-rails-jquery-ujs#cross-site-request-forgery-protection).
+
+
+
+## API
+
+The best source of docs is the main [ReactOnRails.js](https://github.com/shakacode/react_on_rails/node_package/src/ReactOnRails.js) file. Here's a quick summary. No guarantees that this won't be outdated!
 
 ```js
   /**