react-rails 1.2.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 15df12f33d7eebb048c97c8cd0bb64e95ccce6aa
-  data.tar.gz: ed212e1fdfa9fd6aa5f401cf931e9d0d72a22d24
+  metadata.gz: fcffb8326ddf9468f84991dc075b824339192aa6
+  data.tar.gz: 732958fbaa2b917816cc4febcd340e4d439ac397
 SHA512:
-  metadata.gz: 426958555a561b2b3bd2ea3954919123b5f7cbc764892c426b3d461b43650384fc5f1d570a65eb8eec156aac9108f1917b98987cbeff71ce50ecce270220d10b
-  data.tar.gz: c2c7cd00745aa11c70c04295d6aeb8461777a1279dacafcc48df1ea2b4bffba025de5130953ba1c829f7c3e8350b26c79297f042d3cab42cf330b51eb3b01706
+  metadata.gz: 03572f213be4ef8de3be2a513fe56b8fe825f456e704271a785e2f8f9afbe8c0f12670809e441b0da1d1968bce0676db5d993333879dd9b6b126c4f32cf67680
+  data.tar.gz: 33c018c9e2dc905b5c3e505f75882344345e00ecfd8fb9a6aa4a8ee85468bd74a30fa44ca1b6a75105df06ae98c28c050f3b5c82d15d5aacd34a14b4c9c62640

data/README.md

@@ -9,7 +9,7 @@
 # react-rails
 
 
-`react-rails` makes it easy to use [React](http://facebook.github.io/react/) and [JSX](http://facebook.github.io/react/docs/jsx-in-depth.html) 
+`react-rails` makes it easy to use [React](http://facebook.github.io/react/) and [JSX](http://facebook.github.io/react/docs/jsx-in-depth.html)
 in your Ruby on Rails (3.2+) application. `react-rails` can:
 
 - Provide [various `react` builds](#reactjs-builds) to your asset bundle
@@ -17,13 +17,14 @@ in your Ruby on Rails (3.2+) application. `react-rails` can:
 - [Render components into views and mount them](#rendering--mounting) via view helper & `react_ujs`
 - [Render components server-side](#server-rendering) with `prerender: true`
 - [Generate components](#component-generator) with a Rails generator
+- [Be extended](#extending-react-rails) with custom renderers, transformers and view helpers
 
 ## Installation
 
 Add `react-rails` to your gemfile:
 
 ```ruby
-gem 'react-rails', '~> 1.0'
+gem 'react-rails', '~> 1.3.0'
 ```
 
 Next, run the installation script:
@@ -82,27 +83,31 @@ See [VERSIONS.md](https://github.com/reactjs/react-rails/blob/master/VERSIONS.md
 After installing `react-rails`, restart your server. Now, `.js.jsx` files will be transformed in the asset pipeline.
 
 `react-rails` currently ships with two transformers, to convert jsx code -
- 
+
 * `BabelTransformer` using [Babel](http://babeljs.io), which is the default transformer.
 * `JSXTransformer` using `JSXTransformer.js`
 
+You can use the deprecated `JSXTransformer` by setting it in an application config:
+
+```ruby
+  config.react.jsx_transformer_class = React::JSX::JSXTransformer
+```
+
 #### BabelTransformer options
 
-You can use babel's [transformers](http://babeljs.io/docs/advanced/transformers/) and [custom plugins](http://babeljs.io/docs/advanced/plugins/), 
+You can use babel's [transformers](http://babeljs.io/docs/advanced/transformers/) and [custom plugins](http://babeljs.io/docs/advanced/plugins/),
 and pass [options](http://babeljs.io/docs/usage/options/) to the babel transpiler adding following configurations:
 
 ```ruby
 config.react.jsx_transform_options = {
   blacklist: ['spec.functionName', 'validation.react'], # default options
   optional: ["transformerName"],  # pass extra babel options
-  whitelist: ["useStrict"] # even more options    
+  whitelist: ["useStrict"] # even more options
 }
 ```
 Under the hood, `react-rails` uses [ruby-babel-transpiler](https://github.com/babel/ruby-babel-transpiler), for transformation.
-  
-#### JSXTransformer options
 
-To use old JSXTransformer you can use `React::JSX.transformer_class = React::JSX::JSXTransformer`
+#### JSXTransformer options
 
 You can use JSX `--harmony` or `--strip-types` options by adding a configuration:
 
@@ -199,6 +204,22 @@ end
 - On MRI, you'll get a deadlock with `pool_size` > 1
 - If you're using JRuby, you can increase `pool_size` to have real multi-threaded rendering.
 
+### Rendering components instead of views
+
+Components can also be prerendered directly from a controller action with the custom `component` renderer. For example:
+
+```ruby
+class TodoController < ApplicationController
+  def index
+    @todos = Todo.all
+    render component: 'TodoList', props: { todos: @todos }, tag: 'span'
+  end
+end
+```
+
+This custom renderer behaves the same as a normal view renderer and accepts the usual arguments - `content_type`, `layout`, `location` and `status`.
+By default, your current layout will be used and the component, rather than a view, will be rendered in place of `yield`.
+
 ### Component generator
 
 `react-rails` ships with a Rails generator to help you get started with a simple component scaffold. 
@@ -230,7 +251,7 @@ var Post = React.createClass({
         <div>Title: {this.props.title}</div>
         <div>Body: {this.props.body}</div>
         <div>Published: {this.props.published}</div>
-        <div>Published By: {this.props.published_by}</div>
+        <div>Published By: {this.props.publishedBy}</div>
       </div>
     );
   }
@@ -301,3 +322,42 @@ Component = React.createClass
   render: ->
     `<ExampleComponent videos={this.props.videos} />`
 ```
+
+## Extending `react-rails`
+
+You can extend some of the core functionality of `react-rails` by injecting new implementations during configuration.
+
+### Custom Server Renderer
+
+`react-rails` depends on a renderer class for rendering components on the server. You can provide a custom renderer class to `config.react.server_renderer`. The class must implement:
+
+- `#initialize(options={})`, which accepts the hash from `config.react.server_renderer_options`
+- `#render(component_name, props, prerender_options)` to return a string of HTML
+
+`react-rails` provides two renderer classes: `React::ServerRendering::ExecJSRenderer` and `React::ServerRendering::SprocketsRenderer`.
+
+`ExecJSRenderer` offers two other points for extension:
+
+- `#before_render(component_name, props, prerender_options)` to return a string of JavaScript to execute _before_ calling `React.render`
+- `#after_render(component_name, props, prerender_options)` to return a string of JavaScript to execute _after_ calling `React.render`
+
+Any subclass of `ExecJSRenderer` may use those hooks (for example, `SprocketsRenderer` uses them to handle `console.*` on the server).
+
+### Custom View Helper
+
+`react-rails` uses a "helper implementation" class to generate the output of the `react_component` helper. The helper is initialized once per request and used for each `react_component` call during that request. You can provide a custom helper class to `config.react.view_helper_implementation`. The class must implement:
+
+- `#react_component(name, props = {}, options = {}, &block)` to return a string to inject into the Rails view
+- `#setup(rack_env)`, called when the helper is initialized at the start of the request
+- `#teardown(rack_env)`, called at the end of the request
+
+`react-rails` provides one implementation, `React::Rails::ComponentMount`.
+
+### Custom JSX Transformer
+
+`react-rails` uses a transformer class to transform JSX for the browser. The transformer is initialized once, at boot. You can provide a custom transformer to `config.react.jsx_transformer_class`. The transformer must implement:
+
+- `#initialize(options)`, where options is the value passed to `config.react.jsx_transform_options`
+- `#transform(code_string)` to return a string of transformed code
+
+`react-rails` provides two transformers, `React::JSX::JSXTransformer` and `React::JSX::BabelTransformer`.

data/lib/react/jsx.rb

@@ -9,7 +9,7 @@ module React
     DEFAULT_TRANSFORMER = BabelTransformer
     mattr_accessor :transform_options, :transformer_class, :transformer
 
-    # You can assign `React::JSX.transformer_class = `
+    # You can assign `config.react.jsx_transformer_class = `
     # to provide your own transformer. It must implement:
     # - #initialize(options)
     # - #transform(code) => new code

data/lib/react/rails.rb

@@ -1,5 +1,8 @@
 require 'react/rails/asset_variant'
 require 'react/rails/engine'
 require 'react/rails/railtie'
+require 'react/rails/render_middleware'
 require 'react/rails/version'
+require 'react/rails/component_mount'
 require 'react/rails/view_helper'
+require 'react/rails/controller_renderer'

data/lib/react/rails/component_mount.rb

@@ -0,0 +1,46 @@
+module React
+  module Rails
+    # This is the default view helper implementation.
+    # It just inserts HTML into the DOM (see {#react_component}).
+    #
+    # You can extend this class or provide your own implementation
+    # by assigning it to `config.react.view_helper_implementation`.
+    class ComponentMount
+      include ActionView::Helpers::TagHelper
+      include ActionView::Helpers::TextHelper
+      attr_accessor :output_buffer
+
+      # RenderMiddleware calls these hooks
+      # You can use them in custom helper implementations
+      def setup(env)
+      end
+
+      def teardown(env)
+      end
+
+      # Render a UJS-type HTML tag annotated with data attributes, which
+      # are used by react_ujs to actually instantiate the React component
+      # on the client.
+      def react_component(name, props = {}, options = {}, &block)
+        options = {:tag => options} if options.is_a?(Symbol)
+
+        prerender_options = options[:prerender]
+        if prerender_options
+          block = Proc.new{ concat React::ServerRendering.render(name, props, prerender_options) }
+        end
+
+        html_options = options.reverse_merge(:data => {})
+        html_options[:data].tap do |data|
+          data[:react_class] = name
+          data[:react_props] = (props.is_a?(String) ? props : props.to_json)
+        end
+        html_tag = html_options[:tag] || :div
+
+        # remove internally used properties so they aren't rendered to DOM
+        html_options.except!(:tag, :prerender)
+
+        content_tag(html_tag, '', html_options, &block)
+      end
+    end
+  end
+end

data/lib/react/rails/controller_renderer.rb

@@ -0,0 +1,18 @@
+class React::Rails::ControllerRenderer
+  include React::Rails::ViewHelper
+  include ActionView::Helpers::TagHelper
+  include ActionView::Helpers::TextHelper
+
+  attr_accessor :output_buffer
+
+  attr_reader :request
+  def initialize(options={})
+    @request = options[:request]
+  end
+
+  def call(name, options, &block)
+    props = options.fetch(:props, {})
+    options = options.slice(:data, :tag).merge(prerender: true)
+    react_component(name, props, options, &block)
+  end
+end

data/lib/react/rails/railtie.rb

@@ -4,7 +4,6 @@ module React
   module Rails
     class Railtie < ::Rails::Railtie
       config.react = ActiveSupport::OrderedOptions.new
-
       # Sensible defaults. Can be overridden in application.rb
       config.react.variant = (::Rails.env.production? ? :production : :development)
       config.react.addons = false
@@ -15,6 +14,8 @@ module React
       config.react.server_renderer_timeout    = 20  # seconds
       config.react.server_renderer            = nil # defaults to SprocketsRenderer
       config.react.server_renderer_options    = {}  # SprocketsRenderer provides defaults
+      # View helper implementation:
+      config.react.view_helper_implementation = nil # Defaults to ComponentMount
 
       # Watch .jsx files for changes in dev, so we can reload the JS VMs with the new JS code.
       initializer "react_rails.add_watchable_files", group: :all do |app|
@@ -23,15 +24,27 @@ module React
 
       # Include the react-rails view helper lazily
       initializer "react_rails.setup_view_helpers", group: :all do |app|
+        app.config.middleware.use(::React::Rails::RenderMiddleware)
         app.config.react.jsx_transformer_class ||= React::JSX::DEFAULT_TRANSFORMER
         React::JSX.transformer_class = app.config.react.jsx_transformer_class
         React::JSX.transform_options = app.config.react.jsx_transform_options
 
+        app.config.react.view_helper_implementation ||= React::Rails::ComponentMount
+        React::Rails::ViewHelper.helper_implementation_class = app.config.react.view_helper_implementation
         ActiveSupport.on_load(:action_view) do
           include ::React::Rails::ViewHelper
         end
       end
 
+      initializer "react_rails.add_component_renderer", group: :all do |app|
+        ActionController::Renderers.add :component do |component_name, options|
+          renderer = ::React::Rails::ControllerRenderer.new(request: request)
+          html = renderer.call(component_name, options)
+          render_options = options.merge(inline: html)
+          render(render_options)
+        end
+      end
+
       initializer "react_rails.bust_cache", group: :all do |app|
         asset_variant = React::Rails::AssetVariant.new({
           variant: app.config.react.variant,
@@ -43,7 +56,7 @@ module React
 
       end
 
-      config.before_initialize do |app|
+      initializer "react_rails.set_variant", after: :engines_blank_point, group: :all do |app|
         asset_variant = React::Rails::AssetVariant.new({
           variant: app.config.react.variant,
           addons: app.config.react.addons,

data/lib/react/rails/render_middleware.rb

@@ -0,0 +1,19 @@
+module React
+  module Rails
+    class RenderMiddleware
+      HELPER_IMPLEMENTATION_KEY = "react_rails.view_helper_implementation"
+      def initialize(app)
+        @app = app
+      end
+
+      def call(env)
+        new_helper = React::Rails::ViewHelper.helper_implementation_class.new
+        new_helper.setup(env)
+        env[HELPER_IMPLEMENTATION_KEY] = new_helper
+        response = @app.call(env)
+        new_helper.teardown(env)
+        response
+      end
+    end
+  end
+end

data/lib/react/rails/version.rb

@@ -1,6 +1,6 @@
 module React
   module Rails
     # If you change this, make sure to update VERSIONS.md
-    VERSION = '1.2.0'
+    VERSION = '1.3.0'
   end
 end

data/lib/react/rails/view_helper.rb

@@ -1,28 +1,18 @@
 module React
   module Rails
     module ViewHelper
-      # Render a UJS-type HTML tag annotated with data attributes, which
-      # are used by react_ujs to actually instantiate the React component
-      # on the client.
-      def react_component(name, props = {}, options = {}, &block)
-        options = {:tag => options} if options.is_a?(Symbol)
+      # This class will be used for inserting tags into HTML.
+      # It should implement:
+      #   - #setup(env)
+      #   - #teardown(env)
+      #   - #react_component(name, props, options &block)
+      # The default is {React::Rails::ComponentMount}
+      mattr_accessor :helper_implementation_class
 
-        prerender_options = options[:prerender]
-        if prerender_options
-          block = Proc.new{ concat React::ServerRendering.render(name, props, prerender_options) }
-        end
-
-        html_options = options.reverse_merge(:data => {})
-        html_options[:data].tap do |data|
-          data[:react_class] = name
-          data[:react_props] = (props.is_a?(String) ? props : props.to_json)
-        end
-        html_tag = html_options[:tag] || :div
-
-        # remove internally used properties so they aren't rendered to DOM
-        html_options.except!(:tag, :prerender)
-
-        content_tag(html_tag, '', html_options, &block)
+      def react_component(*args, &block)
+        impl_key = React::Rails::RenderMiddleware::HELPER_IMPLEMENTATION_KEY
+        helper_obj = request.env[impl_key]
+        helper_obj.react_component(*args, &block)
       end
     end
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: react-rails
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.3.0
 platform: ruby
 authors:
 - Paul O’Shannessy
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-08-19 00:00:00.000000000 Z
+date: 2015-09-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: appraisal
@@ -270,8 +270,11 @@ files:
 - lib/react/jsx/template.rb
 - lib/react/jsx.rb
 - lib/react/rails/asset_variant.rb
+- lib/react/rails/component_mount.rb
+- lib/react/rails/controller_renderer.rb
 - lib/react/rails/engine.rb
 - lib/react/rails/railtie.rb
+- lib/react/rails/render_middleware.rb
 - lib/react/rails/version.rb
 - lib/react/rails/view_helper.rb
 - lib/react/rails.rb