reactive-ruby 0.7.3 → 0.7.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 4e9023f2e2533170c453fff7af6571e8c95976b9
-  data.tar.gz: 74e2553bd21a054c5674f46f1ededa4d7b339093
+  metadata.gz: e6e7e4fc40600191b0985643a430eca77bbc7816
+  data.tar.gz: 35c09c919ba8ceaabd2165960fcc963a4f2c57c1
 SHA512:
-  metadata.gz: 341472a072828b2af26cb27ddfe4dfb2ef85dc1dea31af2df3a2fcdab8fc362a7d4b438afe605f89f71d20c5dbe4e2280e1e56c0b03f469f825b8945309530cf
-  data.tar.gz: 91e7a1556c9a53c5576c17194d0b416bbae63781e7180a802cfccec4fb8cf8ba409eed68ae208cc79ce83e1b76f6d52d6ba79bb8ecafc6d349682c29a2b339f4
+  metadata.gz: 6cc80309ecd3a8115eeef622a7f61e96188fc2e52e3e3b03ba6c5b6d672ccdd2588db5100894fb4763dd38e74f31737d76ff586337d7c65db0c2f92b63f2d7a2
+  data.tar.gz: b1321b290e26ca408b04143d0a3f29e4e0d5efd33b119224eeb9c2bdffc5d05410652cdd9e3cec0b4643faf08d6a6a0f1b957091d619d5bc63f4cd0ef2a94d83

data/Gemfile

@@ -1,3 +1,2 @@
 source 'https://rubygems.org'
 gemspec
-gem 'opal', :git => "https://github.com/catprintlabs/opal.git"

data/README.md

@@ -1,302 +1,140 @@
-# React.rb
+# Reactive-Ruby
 
-[![Gem Version](https://badge.fury.io/rb/react.rb.svg)](http://badge.fury.io/rb/react.rb)
-[![Code Climate](https://codeclimate.com/github/zetachang/react.rb/badges/gpa.svg)](https://codeclimate.com/github/zetachang/react.rb)
+**Reactive-Ruby is an [Opal Ruby](http://opalrb.org) wrapper of [React.js library](http://facebook.github.io/react/)**.
 
-**React.rb is an [Opal Ruby](http://opalrb.org) wrapper of [React.js library](http://facebook.github.io/react/)**.
+It lets you write reactive UI components, with Ruby's elegance using the tried and true React.js engine. :heart:
 
-It lets you write reactive UI components, with Ruby's elegance and compiled to run in JavaScript. :heart:
+This fork of the original react.rb gem is a work in progress.  Currently it is being used in a large rails app, so until a better guide can be written we will just assume you will use it a rails app too.  However the gem itself has no dependency on rails, and there are people using the gem in other environments.
 
-## Installation
+## Quick Overview
 
-Currently this branch (0.8 in catprint labs) is being used with the following configuration.  
-It is suggested to begin with this
-set of gems which is known to work and then add / remove them as needed.  Let us know if you discover anything.
+A react app is built from one or more trees of components.  A react component can live side by side with other non-react html. A react component is just like a rails view or a partial.  Reactive-Ruby takes advantage of this by letting you add Reactive-Ruby components as views, and call them directly from your controller like any other view.
 
-Currently this has been tested to some extent with rails 3x and 4x
+Components are first rendered to HTML on the server (called pre-rendering) this is no different from what happens when your ERB or HAML templates are translated to HTML.  
 
-```ruby
-gem 'react-rails', git: "https://github.com/catprintlabs/react-rails.git", :branch => 'isomorphic-methods-support'  # you need this branch of react-rails
-gem 'opal', git: "https://github.com/catprintlabs/opal.git"
-gem 'opal-jquery', git: "https://github.com/catprintlabs/opal-jquery.git"  # optional if you are using jquery
-gem 'opal-rails'  # not sure if you need this in all cases
-gem 'opal-browser'  # gets you things like intervals (every method)
-gem 'opal-react', git: "https://github.com/catprintlabs/react.rb.git", :branch => 'opal-0.8'
-gem 'reactive_record', git: "https://github.com/catprintlabs/reactive-record.git", :branch => 'rails4'  # if you want to interface to active_record
-gem 'react-bootstrap-rails'  # if you want to use boot strap styles
-gem 'react-router-rails', '~>0.13.3'  # if you want a single page app router
-gem 'reactor-router', git: "https://github.com/catprintlabs/reactor-router.git"  # same as above
-```
+A copy of the react engine, and your components follows the rendered HTML to the browser, and then when a user interacts with the page, it is updated on the client.
 
-In addition
+The beauty is you now have one markup description, written in the same language as your server code, that works both as the HTML template and as an interactive component.
 
-```ruby
-# Gemfile
-# gem 'react-rails', git: "https://github.com/catprintlabs/react-rails.git" # include if you want integration with rails
-gem 'opal'
+By design Reactive-Ruby allows reactive components  to be easily added to existing Rails projects, as well in new development. 
 
-# gem 'opal', git: "https://github.com/catprintlabs/opal.git"  # use this if you are stuck on rails 3.x
-# gem 'opal-jquery', git: "https://github.com/catprintlabs/opal-jquery.git" # same as above
 
-# include if you want integration with rails
-# gem 'opal-rails' 
+## Installation and setup
 
-# while not absolutely necessary you will probably want this at least for timers and such
-# gem 'opal-browser'
+In your gem file:
 
-gem 'opal-react', git: "https://github.com/catprintlabs/react.rb.git", :branch => 'opal-0.8'
+```ruby
+gem 'reactive-ruby'
 
-# access active record models from opal!
-# gem 'reactive_record', git: "https://github.com/catprintlabs/reactive-record.git"  
+# the next three gems are for integration with rails (TODO - package these up as a reactive-rails gem)
 
-# include if you want to use bootstrap
-# gem 'react-bootstrap-rails' 
+gem 'therubyracer', platforms: :ruby # you need this for prerendering to work
+gem 'react-rails', git: "https://github.com/catprintlabs/react-rails.git", :branch => 'isomorphic-methods-support'  
+gem 'opal-rails'                      
 ```
 
-and in your Opal application,
+Your react components will go into the `app/views/components/` directory of your rails app.
 
-```ruby
-require "opal-react"
-require "react"
+In addition within your views directory you need a  `components.rb` manifest file like this:
 
-React.render(React.create_element('h1'){ "Hello World!" }, `document.body`)
 ```
-
-For a complete example covering most key features, as well as integration with a server (Sinatra, etc), see setup of [Examples](example/tutorial).  For additional information on integrating Opal with a server see the [official docs](http://opalrb.org/docs/) of Opal.
-
-## React Overview
-
-### Basics
-
-The biggest problem with react is that its almost too simple.
-
-In react you define components.  Components are simply classes that have a "render" method.   The render method "draws" a chunk of
-HTML.  
-
-Here is a very simple component:
-
-```ruby
-
+# app/views/components.rb
 require 'opal'
-require 'opal-react'
-
-class Hello
-  def render
-    "hello world"
-  end
-end
-
-# to use the component we first create an instance o
-
-Include the `React::Component` mixin in a class to turn it into a react component
-
-```ruby
-require 'opal'
-require 'opal-react'
-
-class HelloMessage
-
-  include React::Component                    # will create a new component named HelloMessage
-  
-  MSG = {great: 'Cool!', bad: 'Cheer up!'}
-
-  optional_param :mood
-  required_param :name
-  define_state   :foo, "Default greeting"
-
-  before_mount do                             # you can define life cycle callbacks inline
-    foo! "#{name}: #{MSG[mood]}" if mood      # change the state of foo using foo!, read the state using foo
-  end
-
-  after_mount :log                            # you can also define life cycle callbacks by reference to a method
-
-  def log
-    puts "mounted!"
-  end
-  
-  def render                                  # render method MUST return just one component  
-    div do                                    # basic dsl syntax component_name(options) { ...children... }                                    
-      span { "#{foo} #{name}!" }              # all html5 components are defined with lower case text
-    end
-  end
-end
-
-class App
-  include React::Component
-
-  def render
-    HelloMessage name: 'John', mood: :great   # new components are accessed via the class name
-  end
-end
+require 'reactive-ruby'
+require_tree './components'
+``` 
 
-# later we will talk about nicer ways to do this:  For now wait till doc is loaded
-# then tell React to create an "App" and render it into the document body.
+This pulls in the files that will be used both for server side and browser rendering.
 
-`window.onload = #{lambda {React.render(React.create_element(App), `document.body`)}}`
+Then your `assets/javascript/application.rb` file looks like this:
 
-# -> console says: mounted!
 ```
-
-* Callback of life cycle could be created through helpers `before_mount`, `after_mount`, etc
-* `this.props` is accessed through method `self.params`
-* Use helper method `define_state` to create setter & getter of `this.state` for you
-* For the detailed mapping to the original API, see [this issue](https://github.com/zetachang/react.rb/issues/2) for reference. Complete reference will come soon.
-
-### Element Building DSL
-
-As a replacement of JSX, include `React::Component` and you can build `React.Element` hierarchy without all the `React.create_element` noises.
-
-```ruby
-def render
-  div do
-    h1 { "Title" }
-    h2 { "subtitle"}
-    div(class_name: 'fancy', id: 'foo') { span { "some text #{interpolation}"} }
-    present FancyElement, fancy_props: '10'
-  end
-end
+#assets/javascript/application.rb
+# only put files that are browser side only.
+
+require 'components'  # this pulls in your components from the components.rb manifest file  
+require 'jquery'      # you need both these files to access jQuery from Opal
+require 'opal-jquery' # they must be in this order, and after the components require
+require 'browser'     # opal access to browser specific methods (such as setTimer)
+require 'react_ujs'   # this is required and is part of the prerendering system     
+# whatever else you might need here
 ```
 
-### Props validation
+Okay that is your setup.
 
-How about props validation? Inspired by [Grape API](https://github.com/intridea/grape), props validation rule could be created easily through `params` class method as below,
+Now for a simple component.  We are going to render this from the `show` method of the home controller. We want to use  convention over configuration so by default.  So the component will be the "Show" class, of the  "Home" module, 
+of the Components module.
 
 ```ruby
-class App
-  include React::Component
-
-  params do
-    requires :username, type: String
-    requires :enum, values: ['foo', 'bar', 'awesome']
-    requires :payload, type: Todo # yeah, a plain Ruby class
-    optional :filters, type: Array[String]
-    optional :flash_message, type: String, default: 'Welcome!' # no need to feed through `getDefaultProps`
-  end
+# app/views/components/home.rb
 
-  def render
-    div
-  end
-end
-```
+module Components 
+  module Home
+    class Show
 
-### Mixins
+      include React::Component   # will create a new component named Home
 
-Simply create a Ruby module to encapsulate the behavior. Example below is modified from the original [React.js Exmaple on Mixin](http://facebook.github.io/react/docs/reusable-components.html#mixins). [Opal Browser](https://github.com/opal/opal-browser) syntax are used here to make it cleaner.
+      export_component           # export the component name into the javascript space 
 
-```ruby
-module SetInterval
-  def self.included(base)
-    base.class_eval do
-      before_mount { @interval = [] }
-      before_unmount do
-        # abort associated timer of a component right before unmount
-        @interval.each { |i| i.abort }
+      def render  
+        puts "Rendering my first component!"
+        "hello"                  # render "hello" 
       end
-    end
-  end
-
-  def set_interval(seconds, &block)
-    @interval << $window.every(seconds, &block)
-  end
-end
-
-class TickTock
-  include React::Component
-  include SetInterval
 
-  define_state(:seconds) { 0 }
-
-  before_mount do
-    set_interval(1) { self.seconds = self.seconds + 1 }
-    set_interval(1) { puts "Tick!" }
-  end
-
-  def render
-    span do
-      "React has been running for: #{self.seconds}"
     end
   end
 end
-
-React.render(React.create_element(TickTock), $document.body.to_n)
-
-$window.after(5) do
-  React.unmount_component_at_node($document.body.to_n)
-end
-
-# => Tick!
-# => ... for 5 times then stop ticking after 5 seconds
 ```
 
-
-### A Simple Component
-
-A ruby class which define method `render` is a valid component.
-
+Components work just like views so put this in your home controller
 ```ruby
-class HelloMessage
-  def render
-    React.create_element("div") { "Hello World!" }
+# controllers/home_controller.rb
+class HomeController < ApplicationController
+  def show
+    render_component  # by default render_component will use the controller name to find the appropriate component
   end
 end
-
-puts React.render_to_static_markup(React.create_element(HelloMessage))
-
-# => '<div>Hello World!</div>'
 ```
 
-### More complicated one
+Make sure your routes file has a route to your home#show method, and you have done a bundle install.  Fire up your development server and you should see "hello world" displayed.
 
-To hook into native ReactComponent life cycle, the native `this` will be passed to the class's initializer. And all corresponding life cycle methods (`componentDidMount`, etc) will be invoked on the instance using the snake-case method name.
+Open up the js console in the browser and you will see a log showing what went on during the rendering.
 
-```ruby
-class HelloMessage
-  def initialize(native)
-    @native = Native(native)
-  end
+Have a look at the sources in the console, and notice your ruby code is there, and you can set break points etc.
 
-  def component_will_mount
-    puts "will mount!"
-  end
+## Typical Problems
 
-  def render
-    React.create_element("div") { "Hello #{@native[:props][:name]}!" }
-  end
-end
+`Uncaught TypeError: Cannot read property 'toUpperCase' of undefined`  This means the thing you are trying to render is not actually a react component.  Often is because the top level component name is wrong.  For example if you are in controller Foo and the method is `bar`, but you have named the component Foo::Bars then you would see this message.
 
-puts React.render_to_static_markup(React.create_element(HelloMessage, name: 'John'))
+## Turning off Prerendering
 
-# => will_mount!
-# => '<div>Hello John!</div>'
-```
-## Example
+Sometimes its handy to switch off prerendering.  Add `?no_prerender=1` ... to your url.
 
-* React Tutorial: see [example/react-tutorial](example/react-tutorial), the original CommentBox example.
-* TodoMVC: see [example/todos](example/todos), your beloved TodoMVC <3.
 
-## TODOS
+## TODOS / Work arounds / Issues
 
 * Documentation
-* API wrapping coverage of the original js library (pretty close though)
-* React Native?
+* Should load the RubyRacer, or at least report an error if the RubyRacer is not present
+* Get everything to autoload what it needs (i.e. much less config setup)
 
 ## Developing
 
-To run the test case of the project yourself.
+To run the above examples project yourself:
 
 1. `git clone` the project
+2. `cd example/tutorial`
 2. `bundle install`
 3. `bundle exec rackup`
-4. Open `http://localhost:9292` to run the spec
+4. Open `http://localhost`
 
 ## Contributions
 
 This project is still in early stage, so discussion, bug report and PR are really welcome :wink:.
+We check in often at https://gitter.im/zetachang/react.rb ask for @catmando as David is on leave right now. 
 
 ## Contact
 
-[David Chang](http://github.com/zetachang)
-[@zetachang](https://twitter.com/zetachang)
+We check in often at https://gitter.im/zetachang/react.rb ask for @catmando.
 
 ## License
 

data/example/tutorial/.gitignore

@@ -0,0 +1,17 @@
+# See https://help.github.com/articles/ignoring-files for more about ignoring files.
+#
+# If you find yourself ignoring temporary files generated by your text editor
+# or operating system, you probably want to add a global ignore instead:
+#   git config --global core.excludesfile '~/.gitignore_global'
+
+# Ignore bundler config.
+/.bundle
+
+# Ignore the default SQLite database.
+/db/*.sqlite3
+/db/*.sqlite3-journal
+
+# Ignore all logfiles and tempfiles.
+/log/*
+!/log/.keep
+/tmp

data/example/tutorial/Gemfile

@@ -0,0 +1,51 @@
+source 'https://rubygems.org'
+
+gem 'therubyracer', platforms: :ruby
+gem 'react-rails', git: "https://github.com/catprintlabs/react-rails.git", :branch => 'isomorphic-methods-support'  # you need this branch of react-rails
+gem 'opal-rails'       
+                # integrates opal with sprockets etc
+gem 'reactive-ruby', path: "../.."
+
+# Bundle edge Rails instead: gem 'rails', github: 'rails/rails'
+gem 'rails', '4.2.3'
+# Use sqlite3 as the database for Active Record
+gem 'sqlite3'
+# Use SCSS for stylesheets
+gem 'sass-rails', '~> 5.0'
+# Use Uglifier as compressor for JavaScript assets
+gem 'uglifier', '>= 1.3.0'
+# Use CoffeeScript for .coffee assets and views
+gem 'coffee-rails', '~> 4.1.0'
+# See https://github.com/rails/execjs#readme for more supported runtimes
+# gem 'therubyracer', platforms: :ruby
+
+# Use jquery as the JavaScript library
+gem 'jquery-rails'
+# Turbolinks makes following links in your web application faster. Read more: https://github.com/rails/turbolinks
+gem 'turbolinks'
+# Build JSON APIs with ease. Read more: https://github.com/rails/jbuilder
+gem 'jbuilder', '~> 2.0'
+# bundle exec rake doc:rails generates the API under doc/api.
+gem 'sdoc', '~> 0.4.0', group: :doc
+
+# Use ActiveModel has_secure_password
+# gem 'bcrypt', '~> 3.1.7'
+
+# Use Unicorn as the app server
+# gem 'unicorn'
+
+# Use Capistrano for deployment
+# gem 'capistrano-rails', group: :development
+
+
+group :development, :test do
+  # Call 'byebug' anywhere in the code to stop execution and get a debugger console
+  gem 'byebug'
+
+  # Access an IRB console on exception pages or by using <%= console %> in views
+  gem 'web-console', '~> 2.0'
+
+  # Spring speeds up development by keeping your application running in the background. Read more: https://github.com/rails/spring
+  gem 'spring'
+end
+