hyper-mesh 0.5.0 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: ed2a9b3886af2207f09a5e8ce3db7cb0383c2617
-  data.tar.gz: 3aacee91de89e22c2279324f4fc4e8ae91eb658d
+  metadata.gz: 06482f0ee34e8ee178f10efe5c5425a8fa0268fe
+  data.tar.gz: f8588709cf6970fae4b300418925533757421286
 SHA512:
-  metadata.gz: 029224667501009cc0e60988b14bbdfda286fa2f06ebf2f0d4ff78a07035925054724481dc538e0028b0a5952343f77f124ef463af3ad590d60bdab776bc621c
-  data.tar.gz: 2997bb5b724ded7d1ebbef695385161d49a75c52e86b9a1803e11e2c7dd04dcb4fad07fef5c94c0e0cbe6d09b83d020df3d942571d073f596aaa80abeb648e2c
+  metadata.gz: 4e34b870273c9e7dbaba3bc8788bd45e27cee418f272ec65957292656bfa76e51933d0e8bcf49ab178d93f5ba3dee8de36ead41229b3806f774494e8b9223eb9
+  data.tar.gz: ea01368f7c042bde2b004b17fa462829b2cfd6cd39d83c8542b50c3555a0f0eaaa62e4f47dd3f2c776848dfdf0e3f22020adc032ac71cbf6374a205a8c836484

data/README.md

@@ -63,7 +63,14 @@ class WordOfTheDay < React::Component::Base
       BUTTON { 'pick another' }.on(:click) { pick_entry! }
     end
   end
-```    
+```
+
+For more complete examples with *push* updates checkout any of the apps in the `examples` directory, or build your own in 5 minutes following one of the quickstart guides:
+
++ [Rails 5 with ActionCable](/docs/action_cable_quickstart.md)
++ [Using Pusher.com](/docs/pusher_quickstart.md)
++ [Using Pusher-Faker](/docs/pusher_quickstart.md)
++ [Using Simple Polling](/docs/simple_poller_quickstart.md)  
 
 ## Basic Installation and Setup
 
@@ -95,19 +102,18 @@ After restarting, and reloading your browsers you will see changes broadcast to
 
 For setting up the other possible transports following one of these guides:
 
-The easiest way to setup a true push transport is to use the Pusher-Fake gem.  Get started with this [guide.](docs/pusher_faker_quickstart.md)
++ [Rails 5 with ActionCable](/docs/action_cable_quickstart.md)
++ [Using Pusher.com](/docs/pusher_quickstart.md)
++ [Using Pusher-Faker](/docs/pusher_quickstart.md)
++ [Using Simple Polling](/docs/simple_poller_quickstart.md)
 
-or if you are already using Pusher follow this [guide.](docs/pusher_quickstart.md)
+## Advanced Configuration
 
-or if you are on Rails 5, and want to use ActionCable follow this [guide.](docs/action_cable_quickstart.md)
-
-## Basic Configuration
-
-For complete details on configuration settings go [here](/docs/configuration_details.md)
+The above guides will work in most cases, but for complete details on configuration settings go [here](/docs/configuration_details.md)
 
 ## ActiveRecord API
 
-HyperMesh uses a large subset of the ActiveRecord API modified only when necessary to accommodate the asynchronous nature of the client.
+HyperMesh uses a large subset of the ActiveRecord API modified only when necessary to accommodate the asynchronous nature of the client.  You can access your ActiveRecord models just like you would in models, controllers, or in ERB or HAML view templates.
 
 See this [guide](/docs/activerecord_api.md) for details.
 
@@ -115,7 +121,7 @@ See this [guide](/docs/activerecord_api.md) for details.
 
 ## Client Side Scoping
 
-By default scopes will be recalculated on the server.  To offload this to the client HyperMesh adds some features to the `ActiveRecord` `scope` method.  Details [here.](docs/client_side_scoping.md)  
+By default scopes will be recalculated on the server.  For simple scopes that do not use joins or includes no additional action needs to be taken to make scopes work with HyperMesh.  For scopes that do use joins, or if you want to offload the scoping computation from the server to the client read more [here.](docs/client_side_scoping.md)  
 
 ## Authorization
 
@@ -141,7 +147,7 @@ this results in an error like this:
 Exception raised while rendering #<TopLevelRailsComponent:0x53e>
     ReferenceError: Pusher is not defined
 ```  
-To resolve make sure you `require 'pusher'` in your application.js file if using pusher.
+To resolve make sure you `require 'pusher'` in your application.js file if using pusher.  **DO NOT** require pusher from your components manifest as this will cause prerendering to fail.
 
 - No create/update/destroy policies
 You must explicitly allow changes to the models to be made by the client. If you don't you will
@@ -177,11 +183,11 @@ You are still referencing the old reactive-ruby or reactrb gems either directly
 
 Sometimes you need to figure out what connections are available, or what attributes are readable etc.
 
-Its all to do with your policies, but perhaps you just need a little investigation.
+Its usually all to do with your policies, but perhaps you just need a little investigation.
 
 You can bring up a console within the controller context by browsing `localhost:3000/rr/console`
 
-*Note:  change `rr` to wherever you are mounting reactive record in your routes file.*
+*Note:  change `rr` to wherever you are mounting HyperMesh in your routes file.*
 
 *Note: in rails 4, you will need to add the gem 'web-console' to your development section*
 
@@ -219,6 +225,8 @@ You can of course simulate server side changes to your models through this conso
 
 ## Development
 
+HyperMesh is the merger of `reactive-record` and `synchromesh` gems.  As such a lot of the internal names are still using either ReactiveRecord or Synchromesh module names.
+
 The original `ReactiveRecord` specs were written in opal-rspec.  These are being migrated to
 use server rspec with isomorphic helpers.  There are about 170 of the original tests left and to run these you
 

data/docs/action_cable_quickstart.md

@@ -31,14 +31,11 @@ If you are already using ActionCable in your app that is fine, as HyperMesh will
 
 Otherwise go through the following steps to setup ActionCable.
 
-##### Make sure the `action_cable` js file in your assets
+##### Make sure the `action_cable` js file is required in your assets
 
-```javascript
-//app/assets/javascripts/application.js
-...
-//= require action_cable
-Opal.load('components');
-```
+Typically `app/assets/javascripts/application.js` will finish with a `require_tree .` and this will pull in the `cable.js` file which will pull in `action_cable.js`
+
+However at a minimum if `application.js` simply does a `require action_cable` that will be sufficient for HyperMesh.
 
 ##### Make sure you have a cable.yml file
 
@@ -74,6 +71,11 @@ If you don't already have a model to play with,  add one now:
 
 `bundle exec rake db:migrate`
 
+Move `app/models/word.rb` to `app/models/public/word.rb` and move
+`app/models/application_record.rb` to `app/models/public/application_record.rb`
+
+**Leave** `app/models/model.rb` where it is.  This is your models client side manifest file.
+
 Whatever model(s) you will plan to access on the client need to moved to the `app/models/public` directory.  This allows reactive-record to build a client side proxy for the models.  Models not moved will be completely invisible on the client side.
 
 **Important** in rails 5 there is also a base `ApplicationRecord` class, that all other models are built from.  This class must be moved to the public directory as well.

data/docs/activerecord_api.md

@@ -0,0 +1,73 @@
+## ActiveRecord API
+
+HyperMesh uses a subset of the standard ActiveRecord API to give your client side HyperReact components access to your server side models.
+
+### Class Methods
+
+`scope` and `default_scope`:  HyperMesh adds four new options to these methods: `joins`, `client`, `select` and `server`.  The `joins` option provides information on how the scope will be joined with other models.  The `client` and `select` options allow scoping to be done on the client side to offload this from the server, and the `server` option is there just for symmetry with the othe options.  See the [Client Side Scoping](/docs/client_side_scoping.md) page for more details.
+
+```ruby
+# the scope proc is executed on the server
+scope :active, -> () { where(completed: true) }
+
+# if the scope does a join (or include) this must be indicated
+# using the joins: option.
+scope :with_recent_comments,
+      -> { joins(:comments).where('comment.created_at >= ?', Time.now-1.week) },
+      joins: ['comments'] # or joins: 'comments'
+
+# the server side proc can be indicated by the server: option
+# an optional client side proc can be provided to compute the scope
+# locally at the client
+scope :completed,
+      server: -> { where(complete: true) }
+      client: -> { complete }
+```
+
+`unscoped` and `all`: These builtin scopes work just like standard ActiveRecord.
+
+```ruby
+Word.all.each { |word| LI { word.text }}
+```
+
+`belongs_to, has_many, has_one`:  These all work as on the server.  However it is important that you fully specify both sides of the relationship.  This is not always necessary on the server because ActiveRecord uses the table schema to work things out.
+
+```ruby
+class Todo < ActiveRecord::Base
+  belongs_to :assigned_to, class_name: 'User'
+end
+
+class User < ActiveRecord::Base
+  has_many :todos, foreign_key: 'assigned_to_id'
+end
+```
+
+`composed_of`: You can create aggregate models like ActiveRecord.
+
+`column_names`: returns a list of the database columns.
+
+`columns_hash`: returns the details of the columns specification.  Note that on the server `columns_hash` returns a hash of objects specifying column information.  On the client the entire structure is just one big hash of hashes.
+
+`abstract_class=`, `abstract_class?`, `primary_key`, `primary_key=`, `inheritance_column`, `inheritance_column=`, `model_name`: All work as on the server.  See ActiveRecord documentation for more info.
+
+`new`: Takes a hash of attributes and initializes a new unsaved record.  The values of any attributes not specified in the hash will be taken from the models default values specified in the `columns_hash`.
+
+If new is passed a native javascript object it will be treated as a hash and converted accordingly.
+
+`create`: Short hand for `new(...).save`.  See the `save` instance method for details on how saving is done.
+
+`limit` and `offset`: These builtin scopes behave as they do on the server:
+
+```ruby
+Word.offset(500).limit(20) # get words 500-519
+```
+
+`find`: takes an id and returns the corresponding record.
+
+`find_by`: takes single item hash indicating an attribute value pair to find.
+
+`find_by_...`: i.e. `find_by_first_name` these will find the first record with a matching attribute.
+
+```ruby
+Word.find_by_text('hello') # short for Word.find_by(text: 'hello')
+```

data/docs/client_side_scoping.md

@@ -2,15 +2,15 @@
 
 When the client receives notification that a record has changed HyperMesh finds the set of currently rendered scopes that might be effected, and requests them to be updated from the server.  
 
-On the server scopes are a useful way to structure code.  **On the client** scopes are vital as they limit the amount of data loaded, viewed, and updated on the client.  Consider a factory floor management system that shows *job* state as work flows through the factory.  There may be millions of jobs that a production floor browser is authorized to view, but at any time there are probably only 50 being shown.  Using ActiveRecord scopes is the way synchromesh keeps the data requested by the browser limited to a reasonable amount.  
+On the server scopes are a useful way to structure code.  **On the client** scopes are vital as they limit the amount of data loaded, viewed, and updated on the client.  Consider a factory floor management system that shows *job* state as work flows through the factory.  There may be millions of jobs that a production floor browser is authorized to view, but at any time there are probably only 50 being shown.  Using ActiveRecord scopes is the way HyperMesh keeps the data requested by the browser limited to a reasonable amount.  
 
 To make scopes work efficiently on the client HyperMesh adds some features to the ActiveRecord `scope` and `default_scope` macros.  Note you must use the `scope` macro (and not class methods) for things to work with HyperMesh.
 
 The additional features are accessed via the `:joins`, `:client`, and `:select` options.
 
-The `:joins` option tells the synchromesh client which models are joined with the scope.  *You must add a `:joins` option if the scope has any data base join operations in it, otherwise if a joined model changes, synchromesh will not know to update the scope.*
+The `:joins` option tells the HyperMesh client which models are joined with the scope.  *You must add a `:joins` option if the scope has any data base join operations in it, otherwise if a joined model changes, HyperMesh will not know to update the scope.*
 
-The `:client` option provides the client a way to update scopes without having to contact the server.  Unlike the `:joins` option this is an optimization and is not required for scopes to work.
+The `:client` and `:select` options provide the client a way to update scopes without having to contact the server.  Unlike the `:joins` option this is an optimization and is not required for scopes to work.
 
 ```ruby
 class Todo < ActiveRecord::Base
@@ -34,7 +34,7 @@ class Todo < ActiveRecord::Base
   # Now with_recent_comments will be re-evaluated whenever a Todo record, or a Comment
   # joined with a Todo change.
 
-  # Normally whenever synchromesh detects that a scope may be effected by a changed
+  # Normally whenever HyperMesh detects that a scope may be effected by a changed
   # model, it will request the scope be re-evaluated on the server.  To offload this
   # computation to the client provide a client side scope method:
 
@@ -46,7 +46,7 @@ class Todo < ActiveRecord::Base
   # The client proc is executed on each candidate record, and if it returns true the record
   # will be added to the scope.
 
-  # Instead of a client proc you can provide a select proc, which will receive the entire,
+  # Instead of a client proc you can provide a select proc, which will receive the entire
   # collection which can then be filtered and sorted.
 
   scope :sort_by_created_at,

data/docs/configuration_details.md

@@ -1,3 +1,14 @@
+# HyperMesh Configuration
+
+
+# ![](/work-in-progress-drinking.png) WARNING DOCS AND EXAMPLES ARE BEING REWRITTEN  MANY LINKS MAY BE BROKEN  STAY TUNED OR CHECK IN AT [![Join the chat at https://gitter.im/reactrb/chat](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/reactrb/chat?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) FOR MORE INFO 
+
+There are XXX parts to the HyperMesh configuration:
+
+1. Model classes
+2. Policies
+3. Push Transport
+
 ## Installation
 
 If you do not already have hyper-react installed, then use the reactrb-rails-generator gem to setup hyper-react, reactive-record and associated gems.

data/docs/pusher_faker_quickstart.md

@@ -1,15 +1,39 @@
-### Pusher-Fake
+### Pusher-Fake Quickstart
 
-You can also use the [Pusher-Fake](https://github.com/tristandunn/pusher-fake) gem while in development.  Setup is a little tricky.  First
-add `gem 'pusher-fake'` to the development and/or test section of your gem file. Then setup your config file:
+The [Pusher-Fake](https://github.com/tristandunn/pusher-fake) gem will provide a transport using the same protocol as pusher.com.  You can use it to locally test an app that will be put into production using pusher.com.
+
+#### 1 Add the Pusher, Pusher-Fake and HyperLoop gems to your Rails app
+
+- add `gem 'pusher'` to your Gemfile.
+- add `gem 'pusher-fake'` to the development and test sections of your Gemfile.
+
+If you have not already installed the `hyper-react` and `hyper-mesh` gems, then do so now using the [hyper-rails](https://github.com/ruby-hyperloop/hyper-rails) gem.
+
+- add `gem 'hyper-rails'` to your gem file (in the development section)
+- run `bundle install`
+- run `rails g hyperloop:install --all` (make sure to use the --all option)
+- run `bundle update`
+
+#### 2 Add the pusher js file to your application.js file
 
 ```ruby
-# typically config/initializers/HyperMesh.rb
+# app/assets/javascript/application.js
+...
+//= require 'hyper-mesh/pusher'
+//= require_tree .
+Opal.load('components');
+```
+
+#### 3 Set the transport
+
+Once you have HyperMesh, and pusher installed then add this initializer:
+```ruby
+# typically app/config/initializers/HyperMesh.rb
 # or you can do a similar setup in your tests (see this gem's specs)
 require 'pusher'
 require 'pusher-fake'
-# The app_id, key, and secret need to be assigned directly to Pusher
-# so PusherFake will work.
+# Assign any values to the Pusher app_id, key, and secret config values.
+# These can be fake values or the real values for your pusher account.
 Pusher.app_id = "MY_TEST_ID"      # you use the real or fake values
 Pusher.key =    "MY_TEST_KEY"
 Pusher.secret = "MY_TEST_SECRET"
@@ -26,3 +50,68 @@ HyperMesh.configuration do |config|
   }.merge(PusherFake.configuration.web_options)
 end
 ```
+
+#### 4 Try It Out  
+
+If you don't already have a model to play with,  add one now:
+
+`bundle exec rails generate model Word text:string`
+
+`bundle exec rake db:migrate`
+
+Move `app/models/word.rb` to `app/models/public/word.rb`
+
+**Leave** `app/models/model.rb` where it is.  This is your models client side manifest file.
+
+Whatever model(s) you will plan to access on the client need to moved to the `app/models/public` directory.  This allows reactive-record to build a client side proxy for the models.  Models not moved will be completely invisible on the client side.
+
+**Important** in rails 5 there is also a base `ApplicationRecord` class, that all other models are built from.  This class must be moved to the public directory as well.
+
+If you don't already have a component to play with,  here is a simple one (make sure you added the Word model):
+
+```ruby
+# app/views/components/app.rb
+class App < React::Component::Base
+
+  def add_new_word
+    # for fun we will use setgetgo.com to get random words!
+    HTTP.get("http://randomword.setgetgo.com/get.php", dataType: :jsonp) do |response|
+      Word.new(text: response.json[:Word]).save
+    end
+  end
+
+  render(DIV) do
+    SPAN { "Count of Words: #{Word.count}" }
+    BUTTON { "add another" }.on(:click) { add_new_word }
+    UL do
+      Word.each { |word| LI { word.text } }
+    end
+  end
+end
+```
+
+Add a controller:
+
+```ruby
+#app/controllers/test_controller.rb
+class TestController < ApplicationController
+  def app
+    render_component
+  end
+end
+```
+
+Add the `test` route to your routes file:
+
+```ruby
+#app/config/routes.rb
+
+  get 'test', to: 'test#app'
+
+```
+
+Fire up rails with `bundle exec rails s` and open your app in a couple of browsers.  As data changes you should see them all updating together.
+
+You can also fire up a rails console, and then for example do a `Word.new(text: "Hello").save` and again see any browsers updating.
+
+If you want to go into more details with the example check out [words-example](/docs/words-example.md)

data/docs/pusher_quickstart.md

@@ -1,17 +1,105 @@
-### Pusher Configuration
+### PusherQuickstart
 
-Add `gem 'pusher'` to your gem file, and add `//= require 'HyperMesh/pusher'` to your application.js file.
+[Pusher.com](https://pusher.com/) provides a production ready push transport for your App.  You can combine this with [Pusher-Fake](/docs/pusher_faker_quickstart.md) for local testing as well.  You can get a free pusher account and API keys at [https://pusher.com](https://pusher.com)
+
+#### 1 Add the Pusher and HyperLoop gems to your Rails app
+
+- add `gem 'pusher'` to your Gemfile.
+
+If you have not already installed the `hyper-react` and `hyper-mesh` gems, then do so now using the [hyper-rails](https://github.com/ruby-hyperloop/hyper-rails) gem.
+
+- add `gem 'hyper-rails'` to your gem file (in the development section)
+- run `bundle install`
+- run `rails g hyperloop:install --all` (make sure to use the --all option)
+- run `bundle update`
+
+#### 2 Add the pusher js file to your application.js file
 
 ```ruby
-# typically config/initializers/HyperMesh.rb
+# app/assets/javascript/application.js
+...
+//= require 'hyper-mesh/pusher'
+//= require_tree .
+Opal.load('components');
+```
+
+#### 3 Set the transport
+
+Once you have HyperMesh and pusher installed then add this initializer:
+```ruby
+# config/initializers/HyperMesh.rb
 HyperMesh.configuration do |config|
   config.transport = :pusher
+  config.channel_prefix = "HyperMesh"
   config.opts = {
-    app_id: '2xxxx2',
-    key:    'dxxxxxxxxxxxxxxxxxx9',
-    secret: '2xxxxxxxxxxxxxxxxxx2',
-    encrypted: false # optional defaults to true
+    app_id: "2....9",
+    key: "f.....g",
+    secret: "1.......3"
   }
-  config.channel_prefix = 'syncromesh' # or any other string you want
 end
 ```
+
+#### 4 Try It Out  
+
+If you don't already have a model to play with,  add one now:
+
+`bundle exec rails generate model Word text:string`
+
+`bundle exec rake db:migrate`
+
+Move `app/models/word.rb` to `app/models/public/word.rb`
+
+**Leave** `app/models/model.rb` where it is.  This is your models client side manifest file.
+
+Whatever model(s) you will plan to access on the client need to moved to the `app/models/public` directory.  This allows reactive-record to build a client side proxy for the models.  Models not moved will be completely invisible on the client side.
+
+**Important** in rails 5 there is also a base `ApplicationRecord` class, that all other models are built from.  This class must be moved to the public directory as well.
+
+If you don't already have a component to play with,  here is a simple one (make sure you added the Word model):
+
+```ruby
+# app/views/components/app.rb
+class App < React::Component::Base
+
+  def add_new_word
+    # for fun we will use setgetgo.com to get random words!
+    HTTP.get("http://randomword.setgetgo.com/get.php", dataType: :jsonp) do |response|
+      Word.new(text: response.json[:Word]).save
+    end
+  end
+
+  render(DIV) do
+    SPAN { "Count of Words: #{Word.count}" }
+    BUTTON { "add another" }.on(:click) { add_new_word }
+    UL do
+      Word.each { |word| LI { word.text } }
+    end
+  end
+end
+```
+
+Add a controller:
+
+```ruby
+#app/controllers/test_controller.rb
+class TestController < ApplicationController
+  def app
+    render_component
+  end
+end
+```
+
+Add the `test` route to your routes file:
+
+```ruby
+#app/config/routes.rb
+
+  get 'test', to: 'test#app'
+
+```
+
+Fire up rails with `bundle exec rails s` and open your app in a couple of browsers.  As data changes you should see them all updating together.
+
+You can also fire up a rails console, and then for example do a `Word.new(text: "Hello").save` and again see any browsers updating.
+
+If you want to go into more details with the example check out [words-example](/docs/words-example.md)