hyper-mesh 0.6.0 → 1.0.0.lap22

data/docs/client_side_scoping.md

@@ -1,103 +0,0 @@
-## ActiveRecord Scope Enhancement
-
-When the client receives notification that a record has changed Hyperloop 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 in the browser.  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 Hyperloop keeps the data requested by the browser limited to a reasonable amount.  
-
-To make scopes work efficiently on the client Hyperloop 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 Hyperloop.
-
-The additional features are accessed via the `:joins`, `:client`, and `:select` options.
-
-The `:joins` option tells the Hyperloop 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, Hyperloop will not know to update the scope.*
-
-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
-
-  # Standard ActiveRecord form:
-  # the proc will be evaluated as normal on the server, and as needed updates
-  # will be requested from the clients
-
-  scope :active, -> () { where(completed: true) }
-
-  # In the simple form the scope will be reevaluated if the model that is
-  # being scoped changes, and if the scope is currently being used to render data.
-
-  # If the scope joins with other data you will need to specify this by
-  # passing a relationship or array of relationships to the `joins` option.
-
-  scope :with_recent_comments,
-        -> { joins(:comments).where('comment.created_at >= ?', Time.now-1.week) },
-        joins: ['comments'] # or joins: 'comments'
-
-  # Now with_recent_comments will be re-evaluated whenever a Todo record, or a Comment
-  # joined with a Todo change.
-
-  # Normally whenever Hyperloop 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:
-
-  scope :with_recent_comments,
-        -> { joins(:comments).where('comment.created_at >= ?', Time.now-1.week) },
-        joins: ['comments']
-        client: -> { comments.detect { |comment| comment.created_at >= Time.now-1.week }
-
-  # 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
-  # collection which can then be filtered and sorted.
-
-  scope :sort_by_created_at,
-        -> { order('created_at DESC') }
-        select: -> { sort { |a, b| b.created_at <=> a.created_at }}
-
-  # To keep things tidy you can specify the server scope proc with the :server option
-
-  scope :completed,
-        server: -> { where(complete: true) }
-        client: -> { complete }
-
-  # The expressions in the joins array can be arbitrary sequences of relationships and
-  # scopes such as 'comments.author'.  
-
-  scope :with_managers_comments,
-        server: -> { ... }
-        joins: ['comments.author', 'owner']
-        client: -> { comments.detect { |comment| comment.author == owner.manager }}}
-
-  # You can also use the client, select, server, and joins option with the default_scope macro
-
-  default_scope server: -> { where(deleted: false).order('updated_at DESC') }
-                select: -> { select { |r| !r.deleted }.sort { |a, b| b <=> a } }
-
-  # NOTE: it is highly recommend to provide a client proc with default_scopes.  Otherwise
-  # every change is going to require a server interaction regardless of what other client procs
-  # you provide.
-
-end
-```
-
-#### How it works
-
-Consider this scope on the Todo model
-
-```ruby
-scope :with_managers_comments,
-      server: -> { joins(owner: :manager, comments: :author).where('managers_users.id = authors_comments.id').distinct },
-      client: -> { comments.detect { |comment| comment.author == owner.manager }}
-      joins: ['comments.author', 'owner']
-```
-
-The joins 'comments.author' relationship is inverted so that we have User 'has_many' Comments which 'belongs_to' Todos.
-
-Thus we now know that whenever a User or a Comment changes this may effect our with_managers_comments scope
-
-Likewise 'owner' becomes User 'has_many' Todos.
-
-Lets say that a user changes teams and now has a new manager.  This means according to the relationships that the
-User model will change (i.e. there will be a new manager_id in the User model) and thus all Todos belonging to that
-User are subject to evaluation.
-
-While the server side proc efficiently delivers all the objects in the scope, the client side proc just needs to incrementally update the scope.

data/docs/configuration_details.md

@@ -1,33 +0,0 @@
-# Hyperloop Configuration
-
-TODO will this be replaced by readme from hyper-configuration gem?
-
-There are parts to the Hyperloop configuration:
-
-1. Model classes
-2. Policies
-3. Push Transport
-
-## Configuration
-
-Add an initializer like this:
-
-```ruby
-# for rails this would go in: config/initializers/Hyperloop.rb
-Hyperloop.configuration do |config|
-  config.transport = :simple_poller # or :none, action_cable, :pusher - see below)
-end
-# for a minimal setup you will need to define at least one channel, which you can do
-# in the same file as your initializer.
-# Normally you would put these policies in the app/policies/ directory
-class ApplicationPolicy
-  # allow all clients to connect to the Application channel
-  regulate_connection { true } # or always_allow_connection for short
-  # broadcast all model changes over the Application channel *DANGEROUS*
-  regulate_all_broadcasts { |policy| policy.send_all }
-end
-```
-
-A minimal Hyperloop configuration consists of a simple initializer file, and at least one *Policy* class that will *authorize* who gets to see what.
-
-The initializer file specifies what transport will be used.  Currently you can use [Pusher](http://pusher.com), ActionCable (if using Rails 5), Pusher-Fake (for development) or a Simple Poller for testing etc.

data/docs/pusher_faker_quickstart.md

@@ -1,56 +0,0 @@
-### Pusher-Fake Quickstart
-
-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-component` and `hyper-model` 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
-# app/assets/javascript/application.js
-...
-//= require 'hyper-model/pusher'
-//= require_tree .
-Opal.load('components');
-```
-
-#### 3 Set the transport
-
-Once you have Hyperloop, and pusher installed then add this initializer:
-```ruby
-# typically app/config/initializers/Hyperloop.rb
-# or you can do a similar setup in your tests (see this gem's specs)
-require 'pusher'
-require 'pusher-fake'
-# 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"
-# The next line actually starts the pusher-fake server (see the Pusher-Fake readme for details.)
-require 'pusher-fake/support/base' # if using pusher with rspec change this to pusher-fake/support/rspec
-# now copy over the credentials, and merge with PusherFake's config details
-Hyperloop.configuration do |config|
-  config.transport = :pusher
-  config.channel_prefix = "Hyperloop"
-  config.opts = {
-    app_id: Pusher.app_id,
-    key: Pusher.key,
-    secret: Pusher.secret
-  }.merge(PusherFake.configuration.web_options)
-end
-```
-
-#### 4 Try It Out  
-
-TODO include try_it_out partial

data/docs/pusher_quickstart.md

@@ -1,44 +0,0 @@
-### PusherQuickstart
-
-[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-component` and `hyper-model` 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
-# app/assets/javascript/application.js
-...
-//= require 'hyper-model/pusher'
-//= require_tree .
-Opal.load('components');
-```
-
-#### 3 Set the transport
-
-Once you have Hyperloop and pusher installed then add this initializer:
-```ruby
-# config/initializers/Hyperloop.rb
-Hyperloop.configuration do |config|
-  config.transport = :pusher
-  config.channel_prefix = "Hyperloop"
-  config.opts = {
-    app_id: "2....9",
-    key: "f.....g",
-    secret: "1.......3"
-  }
-end
-```
-
-#### 4 Try It Out  
-
-TODO add try_it_out partial

data/docs/simple_poller_quickstart.md

@@ -1,31 +0,0 @@
-### Simple Poller Quickstart
-
-The easiest push transport is the built-in simple poller.  This is great for demos or trying out Hyperloop but because it is constantly polling it is not suitable for production systems or any kind of real debug or test activities.
-
-#### 1 Add the HyperLoop gems to your Rails app
-
-If you have not already installed the `hyper-component` and `hyper-model` 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 Set the transport
-
-Once you have Hyperloop installed then add this initializer:
-```ruby
-#config/initializers/hyperloop.rb
-Hyperloop.configuration do |config|
-  config.transport = :simple_poller
-  # options
-  # config.opts = {
-  #   seconds_between_poll: 5, # default is 0.5 you may need to increase if testing with Selenium
-  #   seconds_polled_data_will_be_retained: 1.hour  # clears channel data after this time, default is 5 minutes
-  # }
-end
-```
-
-#### 3 Try It Out  
-
-TODO add try_it_out partial

data/docs/todo-example.md

@@ -1,118 +0,0 @@
-TODO not sure where this example should go?
-
-Lets look at part of a very simple Todo application with one model:
-
-```ruby
-# app/models/public/todo.rb  <- public models are accessible on the client
-class Todo < ActiveRecord::Base
-  scope :active ->() { where(completed: true) }
-  scope :complete ->() { where(completed: false) }
-end
-```
-
-To show our Todo's we might have a very simple app like this:
-
-```ruby
-# app/views/components/app.rb
-class App < Hyperloop::Component
-
-  define_state scope: :active        
-  define_state new_todo: Todo.new
-
-  def todos  # display our list of todos
-    ul do
-      Todo.send(state.scope).each do |todo|
-        li do
-          status(todo); todo.title.span; delete_button(todo)
-        end
-      end
-    end
-  end
-
-  def status(todo) # display / change the status
-    checkbox(type: :checkbox, checked: todo.completed)
-    .on(:click) do
-      todo.completed = !todo.completed
-      todo.save
-    end
-  end
-
-  def delete_button(todo) # delete a todo
-    button { "delete!" }.on(:click) { todo.destroy }
-  end
-
-  def save_new_todo  # save a new todo
-    state.new_todo.save
-    state.new_todo! Todo.new
-  end
-
-  def link(to) # display a link to a scope
-    button { to }.on(:click) { state.scope! to }
-  end
-
-  render do # render everything
-    div do
-      todos
-      input(value: state.new_todo.title)
-      .on(:change) { |e| state.new_todo.title = e.target.value }
-      .on(:key_down) { |e| save_new_todo if e.key_code == 13 }
-      div { link(:all); link(:active); link(:complete) }
-    end
-  end
-end
-```
-
-Finally we will need a controller:
-
-```ruby
-class HomeController < ApplicationController
-  def app
-    render_component
-  end
-end
-```
-
-Except for configuration that is our complete App.  When the page loads it will show all the todos currently in the database.  As the user changes the state of the Todos (or adds more) the changes will be persisted via the Todo model.
-
-In order to have the changes on one browser be synchronized across all browsers we have to set up some *policies* to define the desired behavior.  Here is a very simple policy without any protection:
-
-```ruby
-#app/policies/application_policy.rb
-class ApplicationPolicy
-  always_allow_connection  # any browser may connect
-  regulate_all_broadcasts &:send_all # send all changes from all models
-  allow_change(to: :all, on: [:create, :update, :destroy])
-end
-```
-
-That is it!
-
-Lets walk through what happens users interact with the system.
-
-When the page first renders (on the server) our `App` component executes (on the server) and renders the initial view.  This is no different from the normal rendering cycle of any rails view, the only difference is we are using `Ruby` as our templating language.
-
-Compare the lines:
-```ruby
-ul do
-  Todo.send(state.scope).each do |todo|
-    li do
-      status(todo); todo.title.span; delete_button(todo)
-    end
-  end
-end
-```
-to the equivilent html.erb file:
-```html
-<ul>
-  <% Todo.send(@scope).each do |todo| %>
-    <li>
-      ...
-    </li>
-  <% end %>
-</ul>
-```
-The only difference is your brain doesn't hurt from all the syntactic context switching.
-
-So the server builds a pile of html and dumps it the browser as normal, but once on the browser we have the exact same ruby code running their as well.  It will automatically add all of event handlers (`on(:click), on(:change)`, etc), and as the events occur the underlying react.js system will cause portions of our code to rerender.
-
-Also during the client load any connections allowed to the browser will be established so that changes in the server database made by other sources will get broadcast to us.

data/docs/word_game.md

@@ -1,28 +0,0 @@
-TODO: delete?
-
-## The 5 Letter Word Game in Hyperloop
-
-We are going to implement a simple game (that is actually quite fun to play) using HyperMesh.
-
-In the 5 letter word game two players each secretly pick a 5 letter word that have 5 different letters.  *truck* and *knife* for example.
-
-Each player guesses a word, and the other player responds with the number of correct letters.
-
-Players continue to take turns until a player guesses the other players word.
-
-Because we are playing on a computer we are going to add some additional rules.
-
-Instead of playing until one of the players correctly guesses a word, we will play until both players correctly guess a word, or one of the players concedes.
-
-Players win by having the *fewest* points.
-
-Points are calculated as follows:
-
-+ 2 points for each guess
-+ 2 points for conceding
-+ 1 point if a player miscalculates the number of correct letters in the other players guess.  The app will give the other player the true answer anyway.
-+ 3 points if a player asks the app to guess a word.  The app will always guess an optimal word (i.e. given all the previous guesses, the app will calculate a word that could be correct.)
-
-In addition the players agree on a time per turn.  If time runs out then the app will guess, and the player will get 3 points instead of 2 (i.e. the last rule above will apply.)
-
-Each

data/docs/words-example.md

@@ -1,67 +0,0 @@
-TODO: not sure where this should go?
-
-## Random Words example
-
-This is the example app used by the quick start guides, and if you want to dive deeper this is the place to be.
-
-If you have not already done so, follow any one of the quick start guides to set up the basic system.  Make sure to follow the steps in the last section and add a `Word` model, a `App` component, and a controller and route.
-
-### The initial component:
-
-Your initial component should look like this:
-
-```ruby
-# app/views/components/app.rb
-class App < Hyperloop::Component
-
-  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
-```
-
-Before going further lets understand exactly what is going on here.
-
-1) Our controller has a method named `app`, so by convention Reactrb will look for a
-component class named `App`, which it finds and *mounts* where ever the the *layout* yields to the view.  
-
-Take a second to look at your `application.html.erb` and find the `<%= yield %>`.  That is the normal rails way of
-indicating where the view requested by the controller (in the case our component) should be rendered.
-
-2) The component is rendered on the server like any other view.  The `render` callback defines exactly what to render.  
-
-
-```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!
-    word = Word.new(text: '')
-    Word << word # force our local list to update before the save
-    HTTP.get("http://randomword.setgetgo.com/get.php", dataType: :jsonp) do |response|
-      word.text = response.json[:Word]
-      word.save
-    end
-  end
-
-  render(DIV) do
-    SPAN { "Count of Words: #{Word.count}" }
-    BUTTON { "add another" }.on(:click) { add_new_word }
-    UL do
-      Word.sort.each { |word| LI { word.text.empty? ? 'loading...' : word.text } }
-    end
-  end
-end
-```