react_on_rails 2.0.0.beta.1 → 2.0.0.beta.2

data/docs/additional_reading/react-and-redux.md

@@ -0,0 +1,36 @@
+# Communication between React Components and Redux Reducers
+
+## Communication Between Components
+See https://facebook.github.io/react/tips/communicate-between-components.html
+
+# Redux Reducers
+Documentation of generated Redux code for reducers.
+
+## Example
+The `helloWorld/reducers/index.jsx` example that results from running the generator with the Redux option may be slightly confusing because of its simplicity. For clarity, what follows is a more fleshed-out example of what a reducer might look like:
+
+```javascript
+import usersReducer from './usersReducer';
+import blogPostsReducer from './blogPostsReducer';
+import commentsReducer from './commentsReducer';
+// ...
+
+import { $$initialState as $$usersState } from './usersReducer';
+import { $$initialState as $$blogPostsState } from './blogPostsReducer';
+import { $$initialState as $$commentsState } from './commentsReducer';
+// ...
+
+export default {
+  $$usersStore: usersReducer,
+  $$blogPostsStore: blogPostsReducer,
+  $$commentsStore: commentsReducer,
+  // ...
+};
+
+export const initalStates = {
+  $$usersState,
+  $$blogPostsState,
+  $$commentsState,
+  // ...
+};
+```

data/docs/additional_reading/react_router.md

@@ -0,0 +1,45 @@
+# Using React Router
+React on Rails supports the use of React Router. Client-side code doesn't need any special configuration for the React on Rails gem. Implement React Router how you normally would.
+
+However, when attempting to use server-rendering, it is necessary to take steps that prevent rendering when there is a router error or redirect. In these cases, the client code should return an object containing the `error` and a `redirectLocation` instead of the React component. The `react_component` helper method in your Rails view will automatically detect that there was an error/redirect and handle it accordingly.
+
+If you are working with the HelloWorldApp created by the react_on_rails generator, then the code below corresponds to the module in `client/app/bundles/HelloWorld/startup/HelloWorldAppServer.jsx`.
+
+```js
+const RouterApp = (props, location) => {
+  const store = createStore(props);
+
+  let error;
+  let redirectLocation;
+  let routeProps;
+
+  // See https://github.com/rackt/react-router/blob/master/docs/guides/advanced/ServerRendering.md
+  match({ routes, location }, (_error, _redirectLocation, _routeProps) => {
+    error = _error;
+    redirectLocation = _redirectLocation;
+    routeProps = _routeProps;
+  });
+
+  // This tell react_on_rails to skip server rendering any HTML. Note, client rendering
+  // will handle the redirect. What's key is that we don't try to render.
+  // Critical to return the Object properties to match this { error, redirectLocation }
+  if (error || redirectLocation) {
+    return { error, redirectLocation };
+  }
+
+  // Important that you don't do this if you are redirecting or have an error.
+  return (
+    <Provider store={store}>
+      <RoutingContext {...routeProps} />
+    </Provider>
+  );
+};
+```
+
+For a fleshed out integration of react_on_rails with react-router, check out [React Webpack Rails Tutorial Code](https://github.com/shakacode/react-webpack-rails-tutorial), specifically the files:
+
+* [react-webpack-rails-tutorial/client/app/bundles/comments/routes/routes.jsx](https://github.com/shakacode/react-webpack-rails-tutorial/blob/master/client/app/bundles/comments/routes/routes.jsx)
+
+* [react-webpack-rails-tutorial/client/app/bundles/comments/startup/ClientRouterApp.jsx](https://github.com/shakacode/react-webpack-rails-tutorial/blob/master/client/app/bundles/comments/startup/ClientRouterApp.jsx)
+
+* [react-webpack-rails-tutorial/client/app/bundles/comments/startup/ServerRouterApp.jsx](https://github.com/shakacode/react-webpack-rails-tutorial/blob/master/client/app/bundles/comments/startup/ServerRouterApp.jsx)

data/docs/additional_reading/server_rendering_tips.md

@@ -0,0 +1,11 @@
+# Server Rendering Tips
+
+- Your code can't reference `document`. Server side JS execution does not have access to `document`, so jQuery and some
+  other libs won't work in this environment. You can debug this by putting in `console.log`
+  statements in your code.
+- 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.
+
+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 sie.

data/docs/additional_reading/tips.md

@@ -0,0 +1,10 @@
+# Tips
++ **DO NOT RUN `rails s`** and instead run 
+
+    `foreman start -f Procfile.dev`
+
+    to automatically start the webpack file watchers that will regenerate your JavaScript. Note, RSpec does not automatically rebuild the bundle files, so you could get incorrect results from your tests if you change the client code and do not rebuild the bundles. The same problem occurs when pulling down changes from GitHub and running tests without first rebuilding the bundles.
++ The default for rendering right now is `prerender: false`. **NOTE:**  Server side rendering does not work for some components that use an async setup for server rendering. You can configure the default for prerender in your config.
++ You can expose either a React component or a function that returns a React component. If you wish to create a React component via a function, rather than simply props, then you need to set the property "generator" on that helper invocation to true (or change the defaults). When that is done, the function is invoked with a single parameter of "props", and that function should return a React element.
++ Be sure you can first render your react component **client only** before you try to debug server rendering!
++ Open up the HTML source and take a look at the generated HTML and the JavaScript to see what's going on under the covers. Note that when server rendering is turned on, then you'll see the server rendered react components. When server rendering is turned off, then you'll only see the `div` element where the in-line JavaScript will render the component. You might also notice how the props you pass (a Ruby Hash) becomes in-line JavaScript on the HTML page.

data/docs/additional_reading/webpack.md

@@ -0,0 +1,46 @@
+# Entry Points and Globally Exposing Objects
+
+You should ensure you configure the entry points correctly for webpack.
+
+## When using React 0.14 and greater
+
+You need both include `react-dom/server` and `react` as values for `entry`, like this:
+
+```
+  entry: {
+
+    // See use of 'vendor' in the CommonsChunkPlugin inclusion below.
+    vendor: [
+      'babel-core/polyfill',
+      'jquery',
+      'jquery-ujs',
+      'react',
+      'react-dom',
+    ],
+```
+
+and you need to expose them:
+
+```
+      // React is necessary for the client rendering:
+      {test: require.resolve('react'), loader: 'expose?React'},
+      {test: require.resolve('react-dom'), loader: 'expose?ReactDOM'},
+      {test: require.resolve('jquery'), loader: 'expose?jQuery'},
+      {test: require.resolve('jquery'), loader: 'expose?$'},
+```
+
+`webpack.server.config.js` is similar, but substitute:
+
+```
+ entry: ['./yourCode', 'react-dom/server', 'react'],
+```
+
+and use this line rather than `{test: require.resolve('react-dom'), loader: 'expose?ReactDOM'},`:
+
+```
+   {test: require.resolve('react-dom/server'), loader: 'expose?ReactDOMServer'},
+```
+
+## When you use React 0.13
+
+You don't need to put in react-dom.

data/docs/code_of_conduct.md

@@ -0,0 +1,13 @@
+# Contributor Code of Conduct
+
+As contributors and maintainers of this project, we pledge to respect all people who contribute through reporting issues, posting feature requests, updating documentation, submitting pull requests or patches, and other activities.
+
+We are committed to making participation in this project a harassment-free experience for everyone, regardless of level of experience, gender, gender identity and expression, sexual orientation, disability, personal appearance, body size, race, ethnicity, age, or religion.
+
+Examples of unacceptable behavior by participants include the use of sexual language or imagery, derogatory comments or personal attacks, trolling, public or private harassment, insults, or other unprofessional conduct.
+
+Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct. Project maintainers who do not follow the Code of Conduct may be removed from the project team.
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by opening an issue or contacting one or more of the project maintainers.
+
+This Code of Conduct is adapted from the [Contributor Covenant](http://contributor-covenant.org), version 1.0.0, available at [http://contributor-covenant.org/version/1/0/0/](http://contributor-covenant.org/version/1/0/0/)

data/docs/coding-style/linters.md

@@ -0,0 +1,64 @@
+# Linters
+These linters support the [ShakaCode Style Guidelines](./style.md)
+
+## Autofix!
+
+If you haven't tried the autofix options for `jscs` and `rubocop`, you're seriously missing out!
+
+1. Be **SURE** you have a clean git status, as you'll want to review what the autofix does to your code!
+2. **Rubocop:**  Be sure to be in the right directory where you have Ruby files, probably the top level of your Rails project.
+  ```
+  rubocop -a
+  ```
+
+3. **JSCS:**: Be sure to be in the right directory where you have JS files.
+  ```
+  jscs -x .
+  ```
+
+Autofixing is a **HUGE** time saver!
+
+## ESLint
+
+### Configuring Rules
+
+Rules are configured with a 0, 1 or 2. Setting a rule to 0 is turning it off, setting it to 1 triggers a warning if that rule is violated, and setting it to 2 triggers an error.
+
+Rules can also take a few additional options. In this case, the rule can be set to an array, the first item of which is the 0/1/2 flag and the rest are options.
+
+See file [.eslintrc](../../client/.eslintrc) for examples of configuration
+
+### Specify/Override rules in code
+
+Rules can also be specified in the code file to be linted, as JavaScript comments. This can be useful when the rule is a one-off or is a override to a project-wide rule.
+
+For example, if your file assumes a few globals and you have the no-undef rule set in the .eslintrc file, you might want to relax the rule in the current file.
+
+```
+/* global $, window, angular */
+// rest of code
+```
+
+It's also useful to disable ESLint for particular lines or blocks of lines.
+
+```
+console.log('console.log not allowed'); // eslint-disable-line
+
+alert('alert not allowed'); // eslint-disable-line no-alert
+
+/* eslint-disable no-console, no-alert */
+console.log('more console.log');
+alert('more alert');
+/* eslint-enable no-console, no-alert */
+```
+
+You can disable all rules for a line or block, or only specific rules, as shown above.
+
+### Useful Reference Links
+
+* [Configuring ESLint](http://eslint.org/docs/user-guide/configuring.html#configuring-rules)
+* [ESLint quick start](http://untilfalse.com/eslint-quick-start/)
+* [RuboCop][https://github.com/bbatsov/rubocop]
+* [ESLint][http://eslint.org/] 
+* [JSCS][https://github.com/jscs-dev/node-jscs]
+

data/docs/coding-style/style.md

@@ -0,0 +1,42 @@
+# Code Style
+This document describes the coding style of [ShakaCode](http://www.shakacode.com). Yes, it's opinionated, as all style guidelines should be. We shall put as little as possible into this guide and instead rely on:
+
+* Use of linters with our standard linter configuration.
+* References to existing style guidelines that support the linter configuration.
+* Anything additional goes next.
+
+## Client Side JavaScript and React
+* Use [Redux](https://github.com/rackt/redux) for your flux store.
+* Use [Lodash](https://lodash.com/) rather than Underscore.
+* Place all JavaScript for the client app in `/client`
+* Organize your app into high level domains which map to JavaScript bundles. These are like mini-apps that live within your entire app. Create directories named like `/client/app/<bundle>` and configure Webpack to generate different corresponding bundles.
+* Carefully organize your React components into [Smart and Dumb Components](https://medium.com/@dan_abramov/smart-and-dumb-components-7ca2f9a7c7d0#.ygdkh1l7b):
+   1. "dumb" components that live in the `/client/app/<bundle>/components/` directories. These components should take props, including values and callbacks, and should not talk directly to Redux or any AJAX endpoints.
+   2. "smart" components that live in the `/client/app/<bundle>/containers/` directory. These components will talk to the Redux store and AJAX endpoints.
+* Place common code shared across bundles in `/client/app/libs` and configure Webpack to generate a common bundle for this one.
+* Prefix Immutable.js variable names and properties with `$$`. By doing this, you will clearly know that you are dealing with an Immutable.js object and not a standard JavaScript Object or Array.
+* Use ES6 classes rather than `React.createClass`.
+* Bind callbacks passed to react components with `_.bindAll` in the constructor unless you need to bind additional parameters. In that case, you can call `_.bind` within the rendering.
+
+## Style Guides to Follow
+Follow these style guidelines per the linter configuration. Basically, lint your code and if you have questions about the suggested fixes, look here:
+
+### Ruby Coding Standards
+* [RailsOnMaui Ruby Coding Standards](https://github.com/justin808/ruby)
+* [Ruby Documentation](http://guides.rubyonrails.org/api_documentation_guidelines.html)
+
+### JavaScript Coding Standards
+* [AirBnb Javascript](https://github.com/airbnb/javascript)
+* [JSDoc](http://usejsdoc.org/)
+
+### Git coding Standards
+* [Git Coding Standards](http://chlg.co/1GV2m9p)
+
+### Sass Coding Standards
+* [Sass Guidelines](http://sass-guidelin.es/) by [Hugo Giraudel](http://hugogiraudel.com/)
+* [Github Front End Guidelines](http://primercss.io/guidelines/)
+
+# Git Usage
+* Follow a github-flow model where you branch off of master for features.
+* Before merging a branch to master, rebase it on top of master, by using command like `git fetch; git checkout my-branch; git rebase -i origin/master`. Clean up your commit message at this point. Be super careful to communicate with anybody else working on this branch and do not do this when others have uncommitted changes. Ideally, your merge of your feature back to master should be one nice commit.
+* Run hosted CI and code coverage.

data/docs/contributing.md

@@ -0,0 +1,157 @@
+# Tips for Contributors
+*See [Releasing](../releasing.md) for instructions on releasing.*
+
+# IDE/IDE SETUP
+It's critical to configure your IDE/editor to ignore certain directories. Otherwise your IDE might slow to a crawl!
+
+* /coverage
+* /examples
+* /node_package/lib
+* /node_modules
+* /spec/dummy/app/assets/javascripts/generated
+* /spec/dummy/log
+* /spec/dummy/node_modules
+* /spec/dummy/tmp
+* /spec/react_on_rails/dummy-for-generators
+
+# Configuring your test app to use your local fork
+
+## Ruby Gem
+If you want to test the gem with an application before you release a new version of the gem, you can specify the path to your local version via your test app's Gemfile:
+
+```ruby
+gem "react_on_rails", path: "../path-to-react-on-rails"
+```
+
+Note that you will need to bundle install after making this change, but also that **you will need to restart your Rails application if you make any changes to the gem**.
+
+## NPM for react-on-rails
+First, be **sure** to build the NPM package
+
+    npm i
+    npm run build
+
+Use either npm-link (described below), or use a relative path in your `package.json`, like this:
+
+```js
+"react-on-rails": "../path-to-react-on-rails".
+```
+
+If you use a relative path, be sure to run `npm i` whenever you rebuild the node package.
+
+
+# Development Setup for Gem and Node Package Contributors
+
+## Checklist before Committing
+1. `rake`: runs all linters and specs (you need Docker setup, see below)
+2. Did you need any more tests for your change?
+3. Did you document your change? Update the README.md?
+
+## Dev Initial Setup
+
+### Prereqs
+After checking out the repo, making sure you have rvm and nvm setup (setup ruby and node), cd to `spec/dummy` and run `bin/setup` to install ruby dependencies. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+### Npm link
+
+By the following steps, the node package code of react-on-rails is directly coming from `node_package/lib`
+
+```sh
+cd <top level>
+npm link
+cd spec/dummy/client
+npm link react-on-rails
+```
+
+*Side note: It's critical to use the alias section of the webpack config to avoid the double inclusion error:*
+
+```js
+  resolve: {
+    alias: {
+      react: path.resolve('./node_modules/react'),
+    },
+  },
+```
+
+### Install npm dependencies and build the npm package for react-on-rails 
+
+```sh
+cd <top level>
+npm i
+npm run build
+cd spec/dummy
+npm i
+```
+
+### Run npm JS tests
+
+```sh
+cd <top level>
+npm test
+```
+
+### Run spec/dummy tests
+
+```sh
+cd spec/dummy
+npm run test
+```
+ 
+### Run most tests and linting
+
+```
+cd <top level>
+node_package/scripts/ci
+```
+
+
+### Starting the Dummy App
+To run the test app, it's **CRITICAL** to not just run `rails s`. You have to run `foreman start`. If you don't do this, then `webpack` will not generate a new bundle, and you will be seriously confused when you change JavaScript and the app does not change. If you change the webpack configs, then you need to restart foreman. If you change the JS code for react-on-rails, you need to run `node_package/scripts/build`. Since the react-on-rails package should be sym linked, you don't have to `npm i react-on-rails` after every change.
+
+### RSpec Testing
+Run `rake` for testing the gem and `spec/dummy`. Otherwise, the `rspec` command only works for testing within the sample apps, like `spec/dummy`.
+
+If you run `rspec` at the top level, you'll see this message: `require': cannot load such file -- rails_helper (LoadError)`
+
+After running a test, you can view the coverage results SimpleCov reports by opening `coverage/index.html`.
+
+### Debugging
+Start the sample app like this for some debug printing:
+
+```bash
+TRACE_REACT_ON_RAILS=true && foreman start
+```
+
+### Install Generator
+In your Rails app add this gem with a path to your fork.
+
+```
+gem 'react_on_rails', path: '../relative/path/to/react_on_rails'
+```
+
+The main installer can be run with ```rails generate react_on_rails:install```
+
+### Testing the Generator
+The generators are covered by generator tests using Rails's generator testing helpers, but it never hurts to do a sanity check and explore the API. See [generator_testing_script.md](generator_testing_script.md) for a script on how to run the generator on a fresh project.
+
+### Linting
+All linting is performed from the docker container for CI. You will need docker and docker-compose installed locally to lint code changes via the lint container. You can lint locally by running `node_package/scripts/lint`
+
+* [Install Docker Toolbox for Mac](https://www.docker.com/toolbox)
+* [Install Docker Compose for Linux](https://docs.docker.com/compose/install/)
+
+Once you have docker and docker-compose running locally, run `docker-compose build lint`. This will build the `reactonrails_lint` docker image and docker-compose `lint` container. The initial build is slow, but after the install, startup is very quick.
+
+### Linting Commands
+Run `rake -D docker` to see all docker linting commands for rake. `rake docker:lint` will run all linters. For individual rake linting commands please refer to `rake -D docker` for the list.
+
+You can run specific linting for directories or files by using `docker-compose run lint rubocop (file path or directory)`, etc.
+
+`docker-compose run lint bash` sets you up to run from the container command line. 
+
+### Docker CI - Test and Linting
+Docker CI and Tests containers have a xvfd server automatically started for headless browser testing with selenium and Firefox.
+
+Run `docker-compose build ci` to build the CI container. Run `docker-compose run ci` to start all rspec tests and linting. `docker-compose run --entrypoint=/bin/bash` will override the default CI action and place you inside the CI container in a bash session. This is what is run on Travis-CI.
+
+Run `docker-compose build tests` to build the tests container. Run `docker-compose run tests` to start all rspec tests.

data/docs/generator_testing.md

@@ -0,0 +1,20 @@
+# Generator Testing
+We create several applications that are examples of running the generator (see lib/generators/react_on_rails/install_generator.rb) with various different options. We can then run tests with these apps just like we would any Rails app and thus ensure that our generator makes apps that actually function properly.
+
+Special rake tasks in rakelib/examples.rake handle creating the example apps and running a special hidden generator (lib/generators/react_on_rails/dev_tests_generator.rb) that installs the tests we want to run for each app. These tests can be run manually like any Rails app, or they can be run via the `rake run_rspec:examples` command. There are also commands for running each app individually, i.e., `rake run_rspec:example_basic`.
+
+## Travis and Gemfiles
+We are currently using Travis for CI. Because of the way Travis works, it is not possible to `bundle install` multiple Gemfiles. Therefore, we have placed all dependencies for generated apps in the gem's main Gemfile. If you generate an app that has a new gem dependency in its Gemfile, you need to add that dependency to the main Gemfile or it will not work in CI.
+
+## Configuring what Apps are Generated
+You can specify additional apps to generate and test by adding to the rakelib/examples_config.yml file. The necessary build and test tasks will automatically be created for you dynamically at runtime.
+
+## More on the Rake Tasks
+In order to maximize efficiency, we took several steps to improve the performance of the rake tasks that utilize somewhat advanced rake functionality such as task dependencies, `file` tasks, task synthesizing, and concurrent tasks with `multitask`.
+
+For example, re-generating the app, running `npm install`, and re-generating the webpack bundles are all only done when they need to be done. Rake will also run certain tasks, including those that generate multiple applications, concurrently. When running `npm install`, this may produce strange-looking output due to the way the npm's console progress bar works. This is normal.
+
+For more insight, see:
+
+- [Avdi Grimm's series of articles on Rake](http://devblog.avdi.org/2014/04/30/learn-advanced-rake-in-7-episodes/)
+- [Martin Fowler's rake article](http://martinfowler.com/articles/rake.html)