react_on_rails 2.3.0 → 3.0.0.beta.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e35d64aa961c1e0fe508c3a7d8499b71f47f4e54
-  data.tar.gz: 6c4de485031ad25a5322b2e922799f90d8d152dd
+  metadata.gz: 5b1502f7743d3d66004e5f876204f48c83e0420b
+  data.tar.gz: 7373d3222c3344a3985c702d0db0b6f8944c751b
 SHA512:
-  metadata.gz: a43c74fcbd866357676a5b2916827728fb969384776a43d27a205eecd030058f829deb8e0ad2f9be7e29022c00083446326c0dad7ed7e3d5987633415754dbde
-  data.tar.gz: 57336349e02ed9f17b03b4cd58586da206a6763b49862ade9d92dae6ace06e4805bded4e3401ca074ed04e94d552700c834917b49a1ad7e348817385adf03aa8
+  metadata.gz: 87f66844af24dcf212c4e6537f4d30bd18f387e1926a013cdc413ecbbbba60a07b043a00f769ebfb7b5bf3d2da649ec106e41b5181e13c6b180c0e895b0b7f41
+  data.tar.gz: b0fb62a1879309db5de7e3d830015b432eee48766579a5f74c3dd910d077d226330257f2051ee64690c721ae75fda5a94b948adfaaa6d8a0484076e026ee84da

data/.rubocop.yml

@@ -38,18 +38,20 @@ Lint/AssignmentInCondition:
   Exclude:
     - 'spec/dummy/bin/spring'
 
-# Offense count: 2
 Lint/HandleExceptions:
   Exclude:
     - 'spec/dummy/bin/rails'
     - 'spec/dummy/bin/rake'
 
-# Offense count: 1
 Metrics/AbcSize:
-  Max: 24
+  Max: 26
+
+Metrics/CyclomaticComplexity:
+  Max: 7
+
+Metrics/PerceivedComplexity:
+  Max: 10
 
-# Offense count: 1
-# Configuration parameters: CountComments.
 Metrics/ClassLength:
   Max: 114
 
@@ -57,18 +59,12 @@ Metrics/ParameterLists:
   Max: 5
   CountKeywordArgs: false
 
-# Offense count: 9
-# Configuration parameters: CountComments.
 Metrics/MethodLength:
   Max: 41
 
-# Offense count: 1
-# Configuration parameters: CountComments.
 Metrics/ModuleLength:
-  Max: 150
+  Max: 180
 
-# Offense count: 3
-# Configuration parameters: AllowedVariables.
 Style/GlobalVars:
   Exclude:
     - 'spec/dummy/config/environments/development.rb'

data/CHANGELOG.md

@@ -3,11 +3,36 @@ All notable changes to this project will be documented in this file. Items under
 
 Contributors: please follow the recommendations outlined at [keepachangelog.com](http://keepachangelog.com/). Please use the existing headings and styling as a guide, and add a link for the version diff at the bottom of the file. Also, please update the `Unreleased` link to compare to the latest release version.
 
-## [Unreleased]
+## [3.0.0-beta.1]
+##### Added
+- Added helper `redux_store` and associated JavaScript APIs that allow multiple React components to use the same store. Thus, you initialize the store, with props, separately from the components.
+- Added forman to gemspec in case new dev does not have it globally installed. [#248](https://github.com/shakacode/react_on_rails/pull/248)
+  
+##### Breaking Change  
+- Calls to `react_component` should use a named argument of props. For example, change this:
+  ```ruby
+  <%= react_component("ReduxSharedStoreApp", {}, prerender: false, trace: true) %>
+  ```
+ 
+  to
+  ```ruby
+  <%= react_component("ReduxSharedStoreApp", props: {}, prerender: false, trace: true) %>
+  ```
+  You'll get a deprecation message to change this.
+- Renamed `ReactOnRails.configure_rspec_to_compile_assets` to `ReactOnRails::TestHelper.configure_rspec_to_compile_assets`. The code has also been optimized to check for whether or not the compiled webpack bundles are up to date or not and will not run if not necessary. If you are using non-standard directories for your generated webpack assets (`app/assets/javascripts/generated` and `app/assets/stylesheets/generated`) or have additional directories you wish the helper to check, you need to update your ReactOnRails configuration accordingly. See [documentation](https://github.com/shakacode/react_on_rails/blob/master/docs/additional_reading/rspec_configuration.md) for how to do this.  [#253](https://github.com/shakacode/react_on_rails/pull/253).
+  
+##### Migration
+- [spec/dummy/spec/rails_helper.rb](https://github.com/shakacode/react_on_rails/blob/master/spec%2Fdummy%2Fspec%2Frails_helper.rb#L36..38) for an example. Add this line to your `rails_helper.rb`:
+```ruby
+RSpec.configure do |config|
+  # Ensure that if we are running js tests, we are using latest webpack assets
+  ReactOnRails::TestHelper.configure_rspec_to_compile_assets(config)
+```
+- Change view helper calls to react_component to use the named param of `props`.
 
 ## [2.3.0] - 2016-02-01
 ##### Added
-- Added polyfills for `setInterval` and `setTimeout` in case other libraries expect these to exist. 
+- Added polyfills for `setInterval` and `setTimeout` in case other libraries expect these to exist.
 - Added much improved debugging for errors in the server JavaScript webpack file.
 - See [#244](https://github.com/shakacode/react_on_rails/pull/244/) for these improvements.
 
@@ -134,7 +159,7 @@ Best done with Object destructing:
 ##### Fixed
 - Fix several generator related issues.
 
-[Unreleased]: https://github.com/shakacode/react_on_rails/compare/2.3.0...HEAD
+[3.0.0-beta.1]: https://github.com/shakacode/react_on_rails/compare/2.3.0...3.0.0-beta.1
 [2.3.0]: https://github.com/shakacode/react_on_rails/compare/2.2.0...2.3.0
 [2.2.0]: https://github.com/shakacode/react_on_rails/compare/2.1.1...2.2.0
 [2.1.1]: https://github.com/shakacode/react_on_rails/compare/v2.1.0...2.1.1

data/README.md

@@ -28,12 +28,12 @@ Please see [Getting Started](#getting-started) for how to set up your Rails proj
 + *Normal Mode (React component will be rendered on client):*
 
   ```erb
-  <%= react_component("HelloWorldApp", @some_props) %>
+  <%= react_component("HelloWorldApp", props: @some_props) %>
   ```
 + *Server-Side Rendering (React component is first rendered into HTML on the server):*
 
   ```erb
-  <%= react_component("HelloWorldApp", @some_props, prerender: true) %>
+  <%= react_component("HelloWorldApp", props: @some_props, prerender: true) %>
   ```
 
 + The `component_name` parameter is a string matching the name you used to globally expose your React component. So, in the above examples, if you had a React component named "HelloWorldApp," you would register it with the following lines:
@@ -50,7 +50,7 @@ Please see [Getting Started](#getting-started) for how to set up your Rails proj
 
   ```ruby
     # Rails View
-    <%= react_component("HelloWorldApp", { name: "Stranger" })
+    <%= react_component("HelloWorldApp", props: { name: "Stranger" }) %>
   ```
 
   ```javascript
@@ -73,6 +73,7 @@ Please see [Getting Started](#getting-started) for how to set up your Rails proj
 + [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)
     - [Bootstrap Integration](#bootstrap-integration)
         + [Bootstrap via Rails Server](#bootstrap-via-rails-server)
@@ -122,7 +123,7 @@ We're definitely not doing that. With react_on_rails, webpack is mainly generati
 1. Add the following to your Gemfile and bundle install:
 
   ```ruby
-  gem "react_on_rails", "~> 2.0.0"
+  gem "react_on_rails", "~> 3"
   ```
 
 2. See help for the generator:
@@ -163,7 +164,7 @@ That will install the latest version and update your package.json.
 ## How it Works
 The generator installs your webpack files in the `client` folder. Foreman uses webpack to compile your code and output the bundled results to `app/assets/javascripts/generated`, which are then loaded by sprockets. These generated bundle files have been added to your `.gitignore` for your convenience.
 
-Inside your Rails views, you can now use the `react_component` helper method provided by React on Rails.
+Inside your Rails views, you can now use the `react_component` helper method provided by React on Rails. You can pass props directly to the react component helper. You can also initialize a Redux store with view helper `redux_store` so that the store can be shared amongst multiple React components. Your best best is to scan the code inside of the [/spec/dummy](spec/dummy) sample app.
 
 ### Client-Side Rendering vs. Server-Side Rendering
 In most cases, you should use the `prerender: false` (default behavior) with the provided helper method to render the React component from your Rails views. In some cases, such as when SEO is vital or many users will not have JavaScript enabled, you can enable server-rendering by passing `prerender: true` to your helper, or you can simply change the default in `config/initializers/react_on_rails`.
@@ -285,6 +286,56 @@ If you have used the `--redux` generator option, you will notice the familiar ad
 
 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`.
 
+#### Multiple React Components on a Page with One Store
+You may wish to have 2 React components share the same the Redux store. For example, if your navbar is a React component, you may want it to use the same store as your component in the main area of the page. You may even want multiple React components in the main area, which allows for greater modularity. In addition, you may want this to work with Turbolinks to minimize reloading the JavaScript. A good example of this would be something like an a notifications counter in a header. As each notifications is read in the body of the page, you would like to update the header. If both the header and body share the same Redux store, then this is trivial. Otherwise, we have to rely on other solutions, such as the header polling the server to see how many unread notifications exist.
+
+Suppose the Redux store is called `appStore`, and you have 3 React components that each need to connect to a store: `NavbarApp`, `CommentsApp`, and `BlogsApp`. I named them with `App` to indicate that they are the registered components.
+
+You will need to make function that can create the store you will be using for all components and register it via the `registerStore` method. Note, this is a **storeCreator**, meaning that it is a function that takes props and returns a store:
+
+```
+ReactOnRails.registerStore({
+  appStore
+});
+```
+
+When registering your component with React on Rails, you can get the store via `ReactOnRails.getStore`:
+
+```js
+// getStore will initialize the store if not already initialized, so creates or retrieves store
+const appStore = ReactOnRails.getStore("appStore");
+return (
+  <Provider store={appStore}>
+    <CommentsApp />
+  </Provider>
+);
+```
+
+From your Rails view, you can use the provided helper `redux_store(store_name, props)` to create a fresh version of the store (because it may already exist if you came from visiting a previous page). Note, for this example, since we're initializing this from the main layout, we're using a generic name of `@react_props`. This means in this case that Rails controllers would set `@react_props` to the properties to hydrate the Redux store.
+
+**app/views/layouts/application.html.erb**
+```erb
+...
+<% redux_store("appStore", @react_props) %>;
+<%= render_component("NavbarApp") %>
+yield
+...
+```
+
+Components are created as [stateless function(al) components](https://facebook.github.io/react/docs/reusable-components.html#stateless-functions). Since you can pass in initial props via the helper `redux_store`, you do not need to pass any props directly to the component. Instead, the component hydrates by connecting to the store.
+
+**_comments.html.erb**
+```erb
+<%= render_component("CommentsApp") %>
+```
+
+**_blogs.html.erb**
+```erb
+<%= render_component("BlogsApp") %>
+```
+
+*Note:* You will not be doing any partial updates to the Redux store when loading a new page. When the page content loads, React on Rails will rehydrate a new version of the store with whatever props are placed on the page.
+
 ### 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.
 

data/app/helpers/react_on_rails_helper.rb

@@ -7,30 +7,31 @@ require "react_on_rails/prerender_error"
 module ReactOnRailsHelper
   # react_component_name: can be a React component, created using a ES6 class, or
   #   React.createClass, or a
-  #     `generator function` that returns a React component
-  #       using ES6
-  #          let MyReactComponentApp = (props) => <MyReactComponent {...props}/>;
-  #       or using ES5
-  #          var MyReactComponentApp = function(props) { return <YourReactComponent {...props}/>; }
-  #    Exposing the react_component_name is necessary to both a plain ReactComponent as well as
-  #      a generator:
-  #    See README.md for how to "register" your react components.
-  #    See spec/dummy/client/app/startup/serverRegistration.jsx and
-  #      spec/dummy/client/app/startup/ClientRegistration.jsx for examples of this
-  # props: Ruby Hash or JSON string which contains the properties to pass to the react object
+  #    `generator function` that returns a React component
+  #      using ES6
+  #         let MyReactComponentApp = (props) => <MyReactComponent {...props}/>;
+  #      or using ES5
+  #         var MyReactComponentApp = function(props) { return <YourReactComponent {...props}/>; }
+  #   Exposing the react_component_name is necessary to both a plain ReactComponent as well as
+  #     a generator:
+  #   See README.md for how to "register" your react components.
+  #   See spec/dummy/client/app/startup/serverRegistration.jsx and
+  #     spec/dummy/client/app/startup/ClientRegistration.jsx for examples of this
   #
-  #  options:
-  #    prerender: <true/false> set to false when debugging!
-  #    trace: <true/false> set to true to print additional debugging information in the browser
-  #           default is true for development, off otherwise
-  #    replay_console: <true/false> Default is true. False will disable echoing server rendering
-  #                    logs to browser. While this can make troubleshooting server rendering difficult,
-  #                    so long as you have the default configuration of logging_on_server set to
-  #                    true, you'll still see the errors on the server.
-  #    raise_on_prerender_error: <true/false> Default to false. True will raise exception on server
-  #       if the JS code throws
-  #  Any other options are passed to the content tag, including the id.
-  def react_component(component_name, props = {}, options = {})
+  # options:
+  #   props: Ruby Hash or JSON string which contains the properties to pass to the react object. Do
+  #      not pass any props if you are separately initializing the store by the `redux_store` helper.
+  #   prerender: <true/false> set to false when debugging!
+  #   trace: <true/false> set to true to print additional debugging information in the browser
+  #          default is true for development, off otherwise
+  #   replay_console: <true/false> Default is true. False will disable echoing server rendering
+  #                   logs to browser. While this can make troubleshooting server rendering difficult,
+  #                   so long as you have the default configuration of logging_on_server set to
+  #                   true, you'll still see the errors on the server.
+  #   raise_on_prerender_error: <true/false> Default to false. True will raise exception on server
+  #      if the JS code throws
+  # Any other options are passed to the content tag, including the id.
+  def react_component(component_name, options = {}, other_options = nil)
     # Create the JavaScript and HTML to allow either client or server rendering of the
     # react_component.
     #
@@ -38,6 +39,9 @@ module ReactOnRailsHelper
     # (re-hydrate the data). This enables react rendered on the client to see that the
     # server has already rendered the HTML.
     # We use this react_component_index in case we have the same component multiple times on the page.
+
+    options, props = parse_options_props(component_name, options, other_options)
+
     react_component_index = next_react_component_index
     react_component_name = component_name.camelize # Not sure if we should be doing this (JG)
     dom_id = if options[:id].nil?
@@ -50,11 +54,14 @@ module ReactOnRailsHelper
     # The reason is that React is smart about not doing extra work if the server rendering did its job.
     turbolinks_loaded = Object.const_defined?(:Turbolinks)
 
-    data = { component_name: react_component_name,
-             props: props,
-             trace: trace(options),
-             expect_turbolinks: turbolinks_loaded,
-             dom_id: dom_id
+    props = {} if props.nil?
+
+    data = {
+      component_name: react_component_name,
+      props: props,
+      trace: trace(options),
+      expect_turbolinks: turbolinks_loaded,
+      dom_id: dom_id
     }
 
     component_specification_tag =
@@ -87,6 +94,25 @@ module ReactOnRailsHelper
     HTML
   end
 
+  # Separate initialization of store from react_component allows multiple react_component calls to
+  # use the same Redux store.
+  #
+  # store_name: name of the store, corresponding to your call to ReactOnRails.registerStores in your
+  #             JavaScript code.
+  # props: Ruby Hash or JSON string which contains the properties to pass to the redux storea.
+  def redux_store(store_name, props = {})
+    redux_store_data = { store_name: store_name,
+                         props: props }
+    @registered_stores ||= []
+    @registered_stores << redux_store_data
+
+    content_tag(:div,
+                "",
+                class: "js-react-on-rails-store",
+                style: ReactOnRails.configuration.skip_display_none ? nil : "display:none",
+                data: redux_store_data)
+  end
+
   def sanitized_props_string(props)
     props.is_a?(String) ? json_escape(props) : props.to_json
   end
@@ -144,6 +170,10 @@ module ReactOnRailsHelper
     @react_component_index += 1
   end
 
+  def props_string(props)
+    props.is_a?(String) ? props : props.to_json
+  end
+
   # Returns Array [0]: html, [1]: script to console log
   # NOTE, these are NOT html_safe!
   def server_rendered_react_component_html(options, props, react_component_name, dom_id)
@@ -155,12 +185,12 @@ module ReactOnRailsHelper
     # Make sure that we use up-to-date server-bundle
     ReactOnRails::ServerRenderingPool.reset_pool_if_server_bundle_was_modified
 
-    # Since this code is not inserted on a web page, we don't need to escape.
-    props_string = props.is_a?(String) ? props : props.to_json
+    # Since this code is not inserted on a web page, we don't need to escape props
 
     wrapper_js = <<-JS
 (function() {
-  var props = #{props_string};
+#{initialize_redux_stores}
+  var props = #{props_string(props)};
   return ReactOnRails.serverRenderReactComponent({
     name: '#{react_component_name}',
     domNodeId: '#{dom_id}',
@@ -196,6 +226,22 @@ module ReactOnRailsHelper
     # rubocop:enable Style/RaiseArgs
   end
 
+  def initialize_redux_stores
+    return "" unless @registered_stores.present?
+    declarations = "var reduxProps, store, storeGenerator;\n"
+    result = @registered_stores.each_with_object(declarations) do |redux_store_data, memo|
+      store_name = redux_store_data[:store_name]
+      props = props_string(redux_store_data[:props])
+      memo << <<-JS
+reduxProps = #{props};
+storeGenerator = ReactOnRails.getStoreGenerator('#{store_name}');
+store = storeGenerator(reduxProps);
+ReactOnRails.setStore('#{store_name}', store);
+      JS
+    end
+    result
+  end
+
   def raise_on_prerender_error(options)
     options.fetch(:raise_on_prerender_error) { ReactOnRails.configuration.raise_on_prerender_error }
   end
@@ -211,4 +257,37 @@ module ReactOnRailsHelper
   def replay_console(options)
     options.fetch(:replay_console) { ReactOnRails.configuration.replay_console }
   end
+
+  def parse_options_props(component_name, options, other_options)
+    other_options ||= {}
+    if options.is_a?(Hash) && options.key?(:props)
+      props = options[:props]
+      final_options = options.except(:props)
+      final_options.merge!(other_options) if other_options.present?
+    else
+      # either no props specified or deprecated
+      if other_options.present? || options.is_a?(String)
+        deprecated_syntax = true
+      else
+        options_has_no_reserved_keys =
+          %i(prerender trace replay_console raise_on_prerender_error).none? do |key|
+            options.key?(key)
+          end
+        deprecated_syntax = options_has_no_reserved_keys
+      end
+
+      if deprecated_syntax
+        puts "Deprecation: react_component now takes props as an explicity named parameter :props. "\
+          " Props as the second arg will be removed in a future release. Called for "\
+          "component_name: #{component_name}, controller: #{controller_name}, "\
+          "action: #{action_name}."
+        props = options
+        final_options = other_options
+      else
+        options ||= {}
+        final_options = options.merge(other_options)
+      end
+    end
+    [final_options, props]
+  end
 end

data/docs/additional_reading/rspec_configuration.md

@@ -1,19 +1,23 @@
 # RSpec Configuration
 Because you will probably want to run RSpec tests that rely on compiled webpack assets (typically, your integration/feature specs where `js: true`), you will want to ensure you don't accidentally run tests on missing or stale webpack assets. If you did use stale Webpack assets, you will get invalid test results as your tests do not use the very latest JavaScript code.
 
-ReactOnRails provides a helper method called `configure_rspec_to_compile_assets`. Call this method from inside of the `RSpec.configure` block in your `spec/rails_helper.rb` file, passing the config as an argument.
+ReactOnRails provides a helper method called `ReactOnRails::TestHelper.configure_rspec_to_compile_assets`. Call this method from inside of the `RSpec.configure` block in your `spec/rails_helper.rb` file, passing the config as an argument. See file [lib/react_on_rails/test_helper.rb](../../lib/react_on_rails/test_helper.rb) for more details. You can customize this to your particular needs by replacing any of the default components used by `ReactOnRails::TestHelper.configure_rspec_to_compile_assets`.
 
 ```ruby
 RSpec.configure do |config|
-  # Next line will ensure that assets are built if webpack -w is not running
-  ReactOnRails.configure_rspec_to_compile_assets(config)
+  # Next line will ensure that assets are built if webpack -w is not running to build the bundles
+  ReactOnRails::TestHelper.configure_rspec_to_compile_assets(config)
 ```
 
-You can pass an RSpec metatag as an optional second parameter to this helper method if you want this helper to run on examples other than where `js: true` (default). The helper will compile webpack files at most once per test run.
+You can pass an RSpec metatag as an optional second parameter to this helper method if you want this helper to run on examples other than where `js: true` (default). The helper will compile webpack files at most once per test run. The helper will not compile the webpack files unless they are out of date (stale).
 
-If you do not want to be slowed down by re-compiling webpack assets from scratch every test run, you can call `npm run build:client` (and `npm run build:server` if doing server rendering) to have webpack recompile these files in the background, which will be much faster. The helper looks for these processes and will abort recompiling if it finds them to be running.
+Please take note of the following:
+- This utility assumes your build tasks for the static generated files are `npm run build:client` and `npm run build:server` and do not have the `--watch` option enabled.
+- By default, the webpack processes look for the `app/assets/javascripts/generated` and `app/assets/stylesheets/generated` folders. If these folders are missing, are empty, or contain files with `mtime`s older than any of the files in your `client` folder, the helper will recompile your assets. You can override this inside of `config/initializers/react_on_rails.rb` by passing an array of filepaths (relative to the root of the app) to the `generated_assets_dirs` configuration option.
 
-If you want to use a testing framework other than RSpec, we suggest you implement similar logic.
+If you want to speed up the re-compiling process, you can call `npm run build:dev:client` (and `npm run build:dev:server` if doing server rendering) to have webpack run in "watch" mode and recompile these files in the background, which will be much faster when making incremental changes than compiling from scratch.
+
+If you want to use a testing framework other than RSpec, please submit let us know on the changes you need to do and we'll update the docs.
 
 ![2016-01-27_02-36-43](https://cloud.githubusercontent.com/assets/1118459/12611951/7c56d070-c4a4-11e5-8a80-9615f99960d9.png)
 

data/docs/additional_reading/turbolinks.md

@@ -2,6 +2,7 @@
 
 * See [Turbolinks on Github](https://github.com/rails/turbolinks)
 * Currently support 2.5.x of Turbolinks. We plan to update to Turbolinks 5 soon.
+* Turbolinks is currently included only via the Rails gem and the Rails manifest file rather than NPM. [Turbolinks Issue #658 ](https://github.com/rails/turbolinks/issues/658) discusses this.
 
 ## Why Turbolinks?
 As you switch between Rails HTML controller requests, you will only load the HTML and you will
@@ -55,3 +56,5 @@ TURBO: reactOnRailsPageLoaded
 ```
 
 We've noticed that Turbolinks doesn't work if you use the ruby gem version of jQuery and jQuery ujs. Therefore we recommend using the node packages instead. See the [tutorial app](https://github.com/shakacode/react-webpack-rails-tutorial) for how to accomplish this.
+
+![2016-02-02_10-38-07](https://cloud.githubusercontent.com/assets/1118459/12760060/6546e254-c999-11e5-828b-a8aaa473e5bd.png)