Skip to content
This repository was archived by the owner on Oct 19, 2018. It is now read-only.

Commit 6de8f3e

Browse files
catmandocatmando
committed
initial rewrite
1 parent d6cdccc commit 6de8f3e

File tree

1 file changed

+37
-189
lines changed

1 file changed

+37
-189
lines changed

‎README.md‎

Lines changed: 37 additions & 189 deletions
Original file line numberDiff line numberDiff line change
@@ -11,215 +11,67 @@
1111
It lets you write reactive UI components, with Ruby's elegance using the tried
1212
and true React.js engine. :heart:
1313

14-
[**Visit Our Documentation Site For The Full Story**](https://reactive-ruby.github.io)
14+
[**Visit reactrb.org For The Full Story**](https://reactrb.org)
1515

16-
### What's this Reactive Ruby?
16+
### Important current react.rb gem users please [read this!](#Road-Map)
1717

18-
Reactive Ruby started as a fork of the original react.rb gem, and has since been
19-
merged back into react.rb's master branch. It aims to take react.rb a few steps
20-
further by embracing it's 'Ruby-ness'.
18+
## Installation
2119

22-
Reactive-Ruby is maturing, but is still a work in progress. Currently it is
23-
being used in a large rails app. However the gem itself has no dependency on
24-
rails, and there are people using the gem in other environments.
20+
Install the gem, or load the js library
2521

26-
Stable react.rb can be found in the
27-
[0-3-stable](https://github.com/zetachang/react.rb/tree/0-3-stable) branch.
22+
+ add gem 'reactive-ruby' to your gem file or
23+
+ gem install reactive-ruby or
24+
+ install or load via cdn [inline-reactive-ruby](https://github.com/reactive-ruby/inline-reactive-ruby)
2825

29-
## Quick Overview
30-
31-
A react app is built from one or more trees of components. React components can
32-
live side by side with other non-react html and javascript. A react component is
33-
just like a rails view or a partial. Reactive-Ruby takes advantage of these
34-
features by letting you add Reactive-Ruby components as views, and call them
35-
directly from your controller like any other view.
36-
37-
By design Reactive-Ruby allows reactive components to be easily added to
38-
existing Rails projects, as well in new development.
39-
40-
Components are first rendered to HTML on the server (called pre-rendering) this
41-
is no different from what happens when your ERB or HAML templates are translated
42-
to HTML.
43-
44-
A copy of the react engine, and your components follows the rendered HTML to the
45-
browser, and then when a user interacts with the page, it is updated on the
46-
client.
47-
48-
The beauty is you now have one markup description, written in the same language
49-
as your server code, that works both as the HTML template and as an interactive
50-
component.
51-
52-
See the [wiki](https://github.com/zetachang/react.rb/wiki) for more details.
53-
54-
## Using React.rb with Rails
55-
56-
### Installation
57-
58-
In your Gemfile:
59-
60-
```ruby
61-
gem 'reactive-ruby'
62-
gem 'react-rails', '~> 1.3.2'
63-
gem 'opal-rails'
64-
gem 'therubyracer', platforms: :ruby # Required for prerendering
65-
# for JRuby you need the below line instead
66-
# gem 'therubyrhino, platforms: :jruby
67-
68-
```
69-
70-
Run `bundle install` and restart your rails server.
71-
72-
### Both Client & Server Side Assets (Components)
73-
74-
Your react components will go into the `app/views/components/` directory of your
75-
rails app.
76-
77-
Within your `app/views` directory you need to create a `components.rb` manifest.
78-
Files required in `app/views/components.rb` will be made available to the server
79-
side rendering system as well as the browser.
80-
81-
```
82-
# app/views/components.rb
83-
require 'opal'
84-
require 'reactive-ruby'
85-
require_tree './components'
86-
```
87-
88-
### Client Side Assets
89-
90-
In `assets/javascript/application.rb` require your components manifest as well
91-
as any additional browser only assets.
26+
For gem installation its highly recommended to read [the getting started section at reactrb.org](http://reactrb.org/docs/getting-started.html)
9227

93-
```
94-
# assets/javascript/application.rb
95-
# Require files that are browser side only.
96-
97-
# Make components available by requiring your components.rb manifest.
98-
require 'components'
99-
100-
# 'react_ujs' tells react in the browser to mount rendered components.
101-
require 'react_ujs'
102-
103-
# Finally, require your other javascript assets. jQuery for example...
104-
require 'jquery' # You need both these files to access jQuery from Opal.
105-
require 'opal-jquery' # They must be in this order.
106-
```
107-
108-
### Rendering Components
109-
110-
Components may be rendered directly from a controller action by simply following
111-
a naming convention. To render a component from the `home#show` action, create a
112-
component class named `Show`. For details on how to override this behavior, and how the the module tree is searched for
113-
the class see the next section.
114-
115-
```ruby
116-
# app/views/components/home/show.rb
117-
module Components
118-
module Home
119-
class Show
120-
include React::Component # will create a new component named Show
121-
122-
optional_param :say_hello_to
123-
124-
def render
125-
puts "Rendering my first component!"
126-
127-
# render "hello" with optional 'say_hello_to' param
128-
"hello #{say_hello_to if say_hello_to}"
129-
end
130-
end
131-
end
132-
end
133-
```
134-
135-
Call `render_component` in the controller action passing in any params (React
136-
props), to render the component:
137-
138-
```ruby
139-
# controllers/home_controller.rb
140-
class HomeController < ApplicationController
141-
def show
142-
# render_component uses the controller name to find the 'show' component.
143-
render_component say_hello_to: params[:say_hello_to]
144-
end
145-
end
146-
```
147-
148-
Make sure your routes file has a route to your home#show action. Visit that
149-
route in your browser and you should see 'Hello' rendered.
150-
151-
Open up the js console in the browser and you will see a log showing what went
152-
on during rendering.
153-
154-
Have a look at the sources in the console, and notice your ruby code is there,
155-
and you can set break points etc.
156-
157-
### Changing the top level component name and search path
158-
159-
You can control the top level component name and search path.
28+
## Quick Overview
16029

161-
By default the component class name is inferred from the controller method rendering the component.
162-
You can also specify the component name explicitly in the `render_component` method.
163-
`render_component "Blatz` will search the for a component class named `Blatz`
164-
regardless of the name of the controller method.
30+
React.rb components are ruby classes that inherit from `React::Component::Base` or include `React::Component`.
16531

166-
Searching for components works like this: Given a controller named
167-
"Foo" then react.rb will search for a module named `Foo` containing the component.
168-
If this fails all modules will be searched (i.e. the name of the controller will be
169-
ignored.) In either case the search begins at the outer most scope until a match is made.
32+
`React::Component` provides a complete DSL to generate html, and event handlers, and has full set of class macros to define states, parameters, and lifecycle callbacks.
17033

171-
Thus for example given a controller named `Foo`, components could be found in the `Foo` module,
172-
the `Components::Foo` module, in the outer most scope, or in any nested module.
173-
The way the search works allows for small projects that do not need a lot
174-
of name spacing, and also allows components to be shared across several controllers.
34+
Each react component class has a render method that generates the markup for that component.
17535

176-
Saying `render_component "::Blatz"` will only search the outer scope, while
177-
`"::Bar::Blatz"` will look only in the module `Bar` for a class named `Blatz`.
36+
Each react component class defines a new **tag** in the DSL that works just like built-in html tags, so react components can render other react components.
17837

38+
As events occur, components update their state, which causes them to rerender, and perhaps pass new parameters to lower level components, thus causing them to rerender.
17939

180-
## Integration with Sinatra
40+
Under the hood the actual work is effeciently done by the [React.js](http://facebook.github.io/react/) engine.
18141

182-
See the [sinatra example](https://github.com/zetachang/react.rb/tree/master/example/sinatra-tutorial).
42+
React.rb components are *isomorphic* meaning they can run on the server as well as the client. This means that the initial expansion of the component tree to markup is done server side, just like ERB, or HAML templates. Then the same code runs on the client and will respond to any events.
18343

184-
## Contextual Code
44+
React.rb integrates well with Rails, Sinatra, and simple static sites, and can be added to existing web pages very easily, or it can be used to deliver complete websites.
18545

186-
Sometimes it may be necessary to run code only on the server or only in the
187-
browser. To execute code only during server side rendering:
46+
## Why ?
18847

189-
```ruby
190-
if React::IsomorphicHelpers.on_opal_server?
191-
puts 'Hello from the server'
192-
end
193-
```
48+
+ *Single Language:* Use Ruby everywhere, no JS, markup languages, or JSX
49+
+ *Powerful DSL:* Describe HTML and event handlers with a minimum of fuss
50+
+ *Ruby Goodness:* Use all the features of Ruby to create reusable, maintainable UI code
51+
+ *React Simplicity:* Nothing is taken away from the React.js model
52+
+ *Enhanced Features:* Enhanced parameter and state management and other new features
53+
+ *Plays well with Others:* Works with other frameworks, Rails, Sinatra or in static web pages
19454

195-
To execute code only in the browser:
55+
# Problems, Questions, Issues
19656

197-
```ruby
198-
if React::IsomorphicHelpers.on_opal_client?
199-
puts 'Hello from the browser'
200-
end
201-
```
57+
+ [Stack Overflow](http://stackoverflow.com/questions/tagged/react.rb) tag `react.rb` for specific problems.
58+
+ [Gitter.im](https://gitter.im/zetachang/react.rb) for general questions, discussion, and interactive help.
59+
+ [Github Issues](https://github.com/zetachang/react.rb/issues) for bugs, feature enhancements, etc.
60+
+
20261

203-
## Typical Problems
62+
# Road Map
20463

205-
`Uncaught TypeError: Cannot read property 'toUpperCase' of undefined` This
206-
means the thing you are trying to render is not actually a react component.
207-
Often is because the top level component name is wrong. For example if you are
208-
in controller Foo and the method is `bar`, but you have named the component
209-
Foo::Bars then you would see this message.
64+
The original react.rb gem is still available as the [0-3-stable branch.](https://github.com/zetachang/react.rb/tree/0-3-stable)
21065

211-
## Turning off Prerendering
66+
Many new features, bug fixes, and improvements are incoporated in the reactive-ruby.gem built currently on the [0-7-stable branch.](https://github.com/zetachang/react.rb/tree/0-7-stable)
21267

213-
Sometimes its handy to switch off prerendering. Add `?no_prerender=1` ... to
214-
your url.
68+
Our plan is to do one more upgrade on the reactive-ruby gem which will be designated version 0.8.0.
21569

70+
From 0.9.0 and beyond we will return to using the react.rb gem for releases, and reactive-ruby will be a meta gem that depends only on react.rb >= 0.9.x.
21671

217-
## TODOS / Work arounds / Issues
72+
Version 0.9.0 of react.rb will **not** be 100% backward compatible with 0.3.0 so its very important to begin your upgrade process now by upgrading to 0.7.0.
21873

219-
* Documentation
220-
* Should load the RubyRacer, or at least report an error if the RubyRacer is not
221-
present
222-
* Get everything to autoload what it needs (i.e. much less config setup)
74+
Please let us know either at [Gitter.im](https://gitter.im/zetachang/react.rb) or [via an issue](https://github.com/zetachang/react.rb/issues) if you have specific concerns with the upgrade from 0.3.0 to 0.9.0.
22375

22476
## Developing
22577

@@ -240,12 +92,8 @@ To run the above examples project yourself:
24092

24193
This project is still in early stage, so discussion, bug report and PR are
24294
really welcome :wink:. We check in often at
243-
https://gitter.im/zetachang/react.rb ask for @catmando as David is on leave
244-
right now.
245-
246-
## Contact
95+
https://gitter.im/zetachang/react.rb
24796

248-
We check in often at https://gitter.im/zetachang/react.rb ask for @catmando.
24997

25098
## License
25199

0 commit comments

Comments
 (0)