|
| 1 | +# hyper-react |
| 2 | + |
| 3 | +[](https://gitter.im/reactrb/chat?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) |
| 4 | +[](https://travis-ci.org/ruby-hyperloop/hyper-react) |
| 5 | +[](https://codeclimate.com/github/reactrb/reactrb) |
| 6 | +[](https://badge.fury.io/rb/hyper-react) |
| 7 | + |
| 8 | +**hyper-react is an [Opal Ruby](http://opalrb.org) wrapper of |
| 9 | +[React.js library](https://facebook.github.io/react)**. |
| 10 | + |
| 11 | +It lets you write reactive UI components, with Ruby's elegance using the tried |
| 12 | +and true React.js engine. :heart: |
| 13 | + |
| 14 | +Visit [ruby-hyperloop.io](http://ruby-hyperloop.io) for the full story. |
| 15 | + |
| 16 | +### Important: `react.rb`, `reactive-ruby` and `reactrb` gems are **deprecated**. See [**UPGRADING**](UPGRADING.md) for details. |
| 17 | + |
| 18 | +## Installation |
| 19 | + |
| 20 | +Install the gem, or load the js library |
| 21 | + |
| 22 | +1. Add `gem 'hyper-react'` to your **Gemfile** |
| 23 | +2. Or `gem install hyper-react` |
| 24 | +3. Or install (or load via cdn) from [reactrb-express.js](http://github.com/ruby-hyperloop/reactrb-express) |
| 25 | + |
| 26 | +For gem installation it is highly recommended to read the [getting started](http://ruby-hyperloop.io/get_started/) and [installation](http://ruby-hyperloop.io/installation/) guides at [ruby-hyperloop.io.](http://ruby-hyperloop.io) |
| 27 | + |
| 28 | +## Quick Overview |
| 29 | + |
| 30 | +A component is a plain ruby class with a `#render` method defined. |
| 31 | + |
| 32 | +```ruby |
| 33 | +class HelloMessage |
| 34 | + def render |
| 35 | + React.create_element("div") { "Hello World!" } |
| 36 | + end |
| 37 | +end |
| 38 | + |
| 39 | +puts React.render_to_static_markup(React.create_element(HelloMessage)) |
| 40 | + |
| 41 | +# => '<div>Hello World!</div>' |
| 42 | +``` |
| 43 | + |
| 44 | +### React::Component |
| 45 | + |
| 46 | +You can simply include `React::Component` to get the power of a complete DSL to generate html markup, event handlers and it also provides a full set of class macros to define states, parameters, and lifecycle callbacks. |
| 47 | + |
| 48 | +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. |
| 49 | + |
| 50 | +```ruby |
| 51 | +require 'opal' |
| 52 | +require 'browser/interval' |
| 53 | +require 'opal-jquery' |
| 54 | +require 'react/react-source' |
| 55 | +require 'hyper-react' |
| 56 | +require 'react/top_level_render' |
| 57 | + |
| 58 | +class HelloWorld < React::Component::Base |
| 59 | + param :time, type: Time |
| 60 | + render do |
| 61 | + p do |
| 62 | + span { "Hello, " } |
| 63 | + input(type: :text, placeholder: "Your Name Here") |
| 64 | + span { "! It is #{params.time}"} |
| 65 | + end |
| 66 | + end |
| 67 | +end |
| 68 | + |
| 69 | +every(1) do |
| 70 | + Element["#example"].render do |
| 71 | + HelloWorld(time: Time.now) |
| 72 | + end |
| 73 | +end |
| 74 | +``` |
| 75 | + |
| 76 | +hyper-react components are *isomorphic* (or *univeral*) meaning they can run on the server as well as the client. |
| 77 | + |
| 78 | +hyper-react integrates well with Rails, Sinatra, and simple static sites, and can be added to existing web pages very easily. |
| 79 | + |
| 80 | +Under the hood the actual work is effeciently done by the [React.js](https://facebook.github.io/react) engine. |
| 81 | + |
| 82 | + |
| 83 | +## Why ? |
| 84 | + |
| 85 | ++ *Single Language:* Use Ruby everywhere, no JS, markup languages, or JSX |
| 86 | ++ *Powerful DSL:* Describe HTML and event handlers with a minimum of fuss |
| 87 | ++ *Ruby Goodness:* Use all the features of Ruby to create reusable, maintainable UI code |
| 88 | ++ *React Simplicity:* Nothing is taken away from the React.js model |
| 89 | ++ *Enhanced Features:* Enhanced parameter and state management and other new features |
| 90 | ++ *Plays well with Others:* Works with other frameworks, React.js components, Rails, Sinatra and static web pages |
| 91 | + |
| 92 | +## Problems, Questions, Issues |
| 93 | + |
| 94 | ++ [Stack Overflow](http://stackoverflow.com/questions/tagged/react.rb) tag `react.rb` for specific problems. |
| 95 | ++ [Gitter.im](https://gitter.im/reactrb/chat) for general questions, discussion, and interactive help. |
| 96 | ++ [Github Issues](https://github.com/reactrb/reactrb/issues) for bugs, feature enhancements, etc. |
| 97 | + |
| 98 | + |
| 99 | +## Roadmap |
| 100 | + |
| 101 | +Version 0.10.x **will not be** 100% backward compatible with 0.3.0 (`react.rb`) or 0.7.x (`reactive-ruby`). |
| 102 | + |
| 103 | +Please let us know either at [Gitter.im](https://gitter.im/reactrb/chat) or [via an issue](https://github.com/reactrb/reactrb/issues) if you have specific concerns with the upgrade from 0.3.0 to 0.10.x. |
| 104 | + |
| 105 | +## Developing |
| 106 | + |
| 107 | +`git clone` the project. |
| 108 | + |
| 109 | +To play with some live examples, refer to https://github.com/ruby-hyperloop/reactrb-examples. |
| 110 | + |
| 111 | +Note that these are very simple examples, for the purpose of showing how to configure the gem in various server environments. For more examples and information see [ruby-hyperloop.io.](http://ruby-hyperloop.io) |
| 112 | + |
| 113 | +## Testing |
| 114 | + |
| 115 | +1. Run `bundle exec rake test_app` to generate a dummy test app. |
| 116 | +2. `bundle exec appraisal install` to generate separate gemfiles for different environments. |
| 117 | +2. `bundle exec appraisal opal-0.10-react-15 rake` to run test for opal-0.10 & react-v0.15. |
| 118 | + |
| 119 | +## Contributions |
| 120 | + |
| 121 | +This project is still in early stage, so discussion, bug reports and PRs are |
| 122 | +really welcome :wink:. |
| 123 | + |
| 124 | + |
| 125 | +## License |
| 126 | + |
| 127 | +In short, hyper-react is available under the MIT license. See the LICENSE file for |
| 128 | +more info. |
0 commit comments