entangled 0.0.20 → 0.0.21

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 47e523fb330c5b6afaf2a591a5b182cb0f7bb6cd
-  data.tar.gz: c2f08b77e3c57ba6f7ac7141b52f7bb4c2cfd286
+  metadata.gz: a57bb2d361ca6fc01d21e41081913491ec6d3f96
+  data.tar.gz: 8e76dffbad36c6d4f5ce3189852c054d919bbe36
 SHA512:
-  metadata.gz: c31e87f3e09508d7c56361af3e828f84da4c0156b7ad9763fe3d888dfc2038c5ef3d1df2dbdbf473f6173707f44625d8da37dbaba59ea6e7d69d3fc2992ae85b
-  data.tar.gz: 102f1d094bd646896aade1752327b3edbe0eaea578b1e904572e6ad206d7e701acd369b74950630fc38308a7fc0ab828c4351b4e3f66e1fcc160849d780982e2
+  metadata.gz: 313a25571895c0076d87989f4efae4cda3d8642255fa930844b02306b12f2dca7d6d5d5236ca8778d64588a5f55e8f555fc2c44a9d9155e1276e0f7b57339a99
+  data.tar.gz: 0fd5d35de6ee95bdb9f77b1a21df7959b17e19048dcd19e6bea3794ebb9e1980cf4c22ff589a51320fca923c08bf01d55a471531083b51a0f60a59a8f7a2d0c1

data/README.md

@@ -6,7 +6,7 @@ Real time is important. Users have come to expect real time behavior from every
 
 Entangled stores and syncs data from ActiveRecord instantly across every device. It is a layer behind your models and controllers that pushes updates to all connected clients in real time. It is cross-browser compatible and offers real time validations.
 
-Currently, Entangled runs on Rails 4.2 in the back end and Angular in the front end.
+Currently, Entangled runs on Rails 4.2 and Ruby 2.0 in the back end, and Angular 1.3 in the front end.
 
 ## Installation
 Add this line to your application's Gemfile:
@@ -299,6 +299,101 @@ $scope.message.$save(function() {
 
 Note that `$valid()` and `$invalid()` should only be used after $saving a resource, i.e. in the callback of `$save`, since they don't actually invoke server side validations. They only check if a resource contains errors.
 
+#### Associations
+What if you want to only fetch and subscribe to children that belong to a specific parent? Or maybe you want to create a child in your front end and assign it to a specific parent?
+
+Entangled currently supports one `belongs_to` association per model.
+
+For example, imagine the following Parent > Children relationship in your models:
+
+```ruby
+class Parent < ActiveRecord::Base
+  include Entangled::Model
+  entangle
+
+  has_many :children
+end
+
+class Child < ActiveRecord::Base
+  include Entangled::Model
+  entangle
+
+  belongs_to :parent
+end
+```
+
+To reflect this in your front end, you just need to add three things to your app:
+
+- Nest your routes so that they resemble the parent/child relationship:
+
+```ruby
+sockets_for :parents do
+  sockets_for :children
+end
+```
+
+- Adjust the `index` and `create` actions in your `ChildrenController` so that they look like this:
+
+```ruby
+class ChildrenController < ApplicationController
+  include Entangled::Controller
+
+  # Fetch children of specific parent
+  def index
+    broadcast do
+      @children = Parent.find(params[:parent_id]).children
+    end
+  end
+
+  # Create child of specific parent
+  def create
+    broadcast do
+      @child = Parent.find(params[:parent_id]).children.create(child_params)
+    end
+  end
+
+  # show, update and destroy don't need to be nested
+end
+```
+
+- Lastly, inform your Angular parent service about the association:
+
+```javascript
+app.factory('Parent', function(Entangled) {
+  // Instantiate Entangled service
+  var entangled = new Entangled('ws://localhost:3000/parents');
+
+  // Set up association  
+  entangled.hasMany('children');
+
+  return entangled;
+});
+```
+
+This makes a `children()` function available on your parent records on which you can chain all other functions to fetch/manipulate data:
+
+```javascript
+Parent.find(1, function(parent) {
+  parent.children().all(function(children) {
+    // children here all belong to parent with id 1
+  });
+
+  parent.children().find(1, function(child) {
+    // child has id 1 and belongs to parent with id 1
+  });
+
+  parent.children().create({ foo: 'bar' }, function(child) {
+    // child has been persisted and associated with parent
+  });
+
+  // etc
+});
+```
+
+This is the way to go if you want to fetch records that only belong to a certain record, or create records that should belong to a parent record. In short, it is ideal to scope records to parent records.
+
+Naturally, all nested records are also synced in real time across all connected clients.
+
 #### Persistence
 Just as with ActiveRecord's `persisted?` method, you can use `$persisted()` on an object to check if it was successfully stored in the database.
 
@@ -319,7 +414,6 @@ The following features are to be implemented next:
 - Offline capabilities - when client is disconnected, put websocket interactions in a queue and dequeue all once connected again
 - Support for authentication
 - Support for associations
-- Remove angular dependencies from bower package (they're currently all being downloaded as well when doing bower install)
 - On Heroku (maybe in production in general), objects are always in different order depending on their attributes
 - Add $onChange listener to objects
 - Add diagram on how it works to Readme

data/entangled.gemspec

@@ -21,6 +21,7 @@ Gem::Specification.new do |s|
   s.add_development_dependency 'bundler', '~> 1.7'
   s.add_development_dependency 'rake', '~> 10.0'
   s.add_development_dependency 'rspec-rails', '~> 3.2'
+  s.add_development_dependency 'shoulda-matchers', '~> 2.6'
   s.add_development_dependency 'sqlite3', '~> 1.3'
   s.add_development_dependency 'byebug', '~> 3.5'
   s.add_development_dependency 'bourne', '~> 1.6'

data/entangled.js

@@ -1 +1 @@
-angular.module("entangled",[]).factory("Entangled",function(){var e=function(e,r){for(var t in e)e.hasOwnProperty(t)&&(this[t]=e[t]);this.webSocketUrl=r};e.prototype.$save=function(e){var r=this;if(this.id){var t=new WebSocket(r.webSocketUrl+"/"+r.id+"/update");t.onopen=function(){t.send(JSON.stringify(r))},t.onmessage=function(t){if(t.data){var o=JSON.parse(t.data);if(o.resource)for(key in o.resource)r[key]=o.resource[key]}e&&e(r)}}else{var t=new WebSocket(r.webSocketUrl+"/create");t.onopen=function(){t.send(JSON.stringify(r))},t.onmessage=function(t){if(t.data){var o=JSON.parse(t.data);if(o.resource)for(key in o.resource)r[key]=o.resource[key]}e&&e(r)}}},e.prototype.$update=function(e,r){for(var t in e)e.hasOwnProperty(t)&&(this[t]=e[t]);this.$save(r)},e.prototype.$destroy=function(e){var r=new WebSocket(this.webSocketUrl+"/"+this.id+"/destroy");r.onopen=function(){r.send(null),e&&e()}},e.prototype.$valid=function(){return!(this.errors&&Object.keys(this.errors).length)},e.prototype.$invalid=function(){return!this.$valid()},e.prototype.$persisted=function(){return!!this.id};var r=function(r,t){this.all=[];for(var o=0;o<r.length;o++){var s=new e(r[o],t);this.all.push(s)}},t=function(e){this.webSocketUrl=e};return t.prototype["new"]=function(r){return new e(r,this.webSocketUrl)},t.prototype.all=function(t){var o=new WebSocket(this.webSocketUrl);o.onmessage=function(s){if(s.data.length){var n=JSON.parse(s.data);if(n.resources)this.resources=new r(n.resources,o.url);else if(n.action)if("create"===n.action)this.resources.all.push(new e(n.resource,o.url));else if("update"===n.action){for(var i,a=0;a<this.resources.all.length;a++)this.resources.all[a].id===n.resource.id&&(i=a);this.resources.all[i]=new e(n.resource,o.url)}else if("destroy"===n.action){for(var i,a=0;a<this.resources.all.length;a++)this.resources.all[a].id===n.resource.id&&(i=a);this.resources.all.splice(i,1)}else console.log("Something else other than CRUD happened..."),console.log(n)}t(this.resources.all)}},t.prototype.create=function(e,r){var t=this["new"](e);t.$save(r)},t.prototype.find=function(r,t){var o=this.webSocketUrl,s=new WebSocket(o+"/"+r);s.onmessage=function(r){if(r.data.length){var s=JSON.parse(r.data);s.resource&&!s.action?this.resource=new e(s.resource,o):s.action?"update"===s.action?this.resource=new e(s.resource,o):"destroy"===s.action&&(this.resource=void 0):(console.log("Something else other than CRUD happened..."),console.log(s))}t(this.resource)}},t});
+angular.module("entangled",[]).factory("Entangled",function(){var e=function(e,t,r){for(var o in e)e.hasOwnProperty(o)&&(this[o]=e[o]);this.webSocketUrl=t,r&&(this[r]=function(){return new s(this.webSocketUrl+"/"+this.id+"/"+r)})};e.prototype.$save=function(e){if(this.id){var t=new WebSocket(this.webSocketUrl+"/"+this.id+"/update");t.onopen=function(){t.send(JSON.stringify(this))}.bind(this),t.onmessage=function(t){if(t.data){var r=JSON.parse(t.data);if(r.resource)for(key in r.resource)this[key]=r.resource[key]}this[this.hasMany]=new s(this.webSocketUrl+"/"+this.id+"/"+this.hasMany),e&&e(this)}.bind(this)}else{var t=new WebSocket(this.webSocketUrl+"/create");t.onopen=function(){t.send(JSON.stringify(this))}.bind(this),t.onmessage=function(t){if(t.data){var s=JSON.parse(t.data);if(s.resource)for(key in s.resource)this[key]=s.resource[key]}e&&e(this)}.bind(this)}},e.prototype.$update=function(e,t){for(var s in e)e.hasOwnProperty(s)&&(this[s]=e[s]);this.$save(t)},e.prototype.$destroy=function(e){var t=new WebSocket(this.webSocketUrl+"/"+this.id+"/destroy");t.onopen=function(){t.send(null),e&&e()}},e.prototype.$valid=function(){return!(this.errors&&Object.keys(this.errors).length)},e.prototype.$invalid=function(){return!this.$valid()},e.prototype.$persisted=function(){return!!this.id};var t=function(t,s,r){this.all=[];for(var o=0;o<t.length;o++){var i=new e(t[o],s,r);this.all.push(i)}},s=function(e){this.webSocketUrl=e};return s.prototype.hasMany=function(e){this.hasMany=e},s.prototype["new"]=function(t){return new e(t,this.webSocketUrl,this.hasMany)},s.prototype.all=function(s){var r=new WebSocket(this.webSocketUrl);r.onmessage=function(o){if(o.data.length){var i=JSON.parse(o.data);if(i.resources)this.resources=new t(i.resources,r.url,this.hasMany);else if(i.action)if("create"===i.action)this.resources.all.push(new e(i.resource,r.url,this.hasMany));else if("update"===i.action){for(var n,a=0;a<this.resources.all.length;a++)this.resources.all[a].id===i.resource.id&&(n=a);this.resources.all[n]=new e(i.resource,r.url,this.hasMany)}else if("destroy"===i.action){for(var n,a=0;a<this.resources.all.length;a++)this.resources.all[a].id===i.resource.id&&(n=a);this.resources.all.splice(n,1)}else console.log("Something else other than CRUD happened..."),console.log(i)}s(this.resources.all)}.bind(this)},s.prototype.create=function(e,t){var s=this["new"](e);s.$save(t)},s.prototype.find=function(t,s){var r=this.webSocketUrl,o=new WebSocket(r+"/"+t);o.onmessage=function(t){if(t.data.length){var o=JSON.parse(t.data);o.resource&&!o.action?this.resource=new e(o.resource,r,this.hasMany):o.action?"update"===o.action?this.resource=new e(o.resource,r,this.hasMany):"destroy"===o.action&&(this.resource=void 0):(console.log("Something else other than CRUD happened..."),console.log(o))}s(this.resource)}.bind(this)},s});

data/lib/entangled/controller.rb

@@ -42,15 +42,9 @@ module Entangled
         instance_variable_get(:"@#{resource_name}")
       end
 
-      # Channel name for single resource, used in show action
-      def member_channel
-        member.channel
-      end
-
-      # Channel name for collection of resources, used in index
-      # action
-      def collection_channel
-        model.channel
+      # Infer channel from current path
+      def channel
+        request.path
       end
 
       # Close the connection to the DB so as to
@@ -94,7 +88,7 @@ module Entangled
             # has to be "@tacos"
             if collection
               redis_thread = Thread.new do
-                redis.subscribe collection_channel do |on|
+                redis.subscribe channel do |on|
                   # Broadcast messages to all connected clients
                   on.message do |channel, message|
                     tubesock.send_data message
@@ -135,7 +129,7 @@ module Entangled
             # The variable name, in this example, has to be "@taco"
             if member
               redis_thread = Thread.new do
-                redis.subscribe member_channel do |on|
+                redis.subscribe channel do |on|
                   # Broadcast messages to all connected clients
                   on.message do |channel, message|
                     tubesock.send_data message

data/lib/entangled/model.rb

@@ -55,12 +55,6 @@ module Entangled
         [:create, :update, :destroy]
       end
 
-      # The inferred channel name. For example, if the class name
-      # is DeliciousTaco, the inferred channel name is "delicious_tacos"
-      def channel
-        name.underscore.pluralize
-      end
-
       # Creates callbacks in the extented model
       def create_hook(name)
         send :"after_#{name}", -> { publish(name) }
@@ -79,13 +73,40 @@ module Entangled
         attributes.merge(errors: errors).as_json
       end
 
-      # The inferred channel name for a single record
-      # containing the inferred channel name from the class
-      # and the record's id. For example, if it's a
-      # DeliciousTaco with the id 1, the inferred channel
-      # name for the single record is "delicious_tacos/1"
-      def channel
-        "#{self.class.channel}/#{self.to_param}"
+      # The channel name for a single record containing the
+      # inferred channel name from the class and the record's
+      # id. For example, if it's a DeliciousTaco with the id 1,
+      # the member channel for the single record is "delicious_tacos/1".
+      # Nesting is automatically applied through the use of
+      # the collection channel.
+      # 
+      # The member channel has to be the same as the path to
+      # the resource's show action, including a leading
+      # forward slash
+      def member_channel
+        "#{collection_channel}/#{self.to_param}"
+      end
+
+      # The inferred channel name for the collection. For example,
+      # if the class name is DeliciousTaco, the collection channel
+      # is "delicious_tacos".
+      # 
+      # If the model belongs to another model, the channel is nested
+      # accordingly. For example, if a child belongs to a parent,
+      # the child's collection channel is "parents/1/children".
+      # 
+      # The collection channel has to be the same as the path to
+      # the resource's index action, including a leading forward slash
+      def collection_channel
+        belongs_to_assocations = self.class.reflect_on_all_associations(:belongs_to)
+        own_channel = self.class.name.underscore.pluralize
+
+        if belongs_to_assocations.any?
+          parent = send(belongs_to_assocations.first.name)
+          "#{parent.member_channel}/#{own_channel}"
+        else
+          "/#{own_channel}"
+        end
       end
 
       private
@@ -96,13 +117,13 @@ module Entangled
       def publish(action)
         # Publish to model's channel
         redis.publish(
-          self.class.channel,
+          collection_channel,
           json(action)
         )
 
         # Publish to record#s channel
         redis.publish(
-          channel,
+          member_channel,
           json(action)
         )
       end

data/lib/entangled/version.rb

@@ -1,3 +1,3 @@
 module Entangled
-  VERSION = "0.0.20"
+  VERSION = "0.0.21"
 end

data/spec/dummy/app/controllers/items_controller.rb

@@ -0,0 +1,39 @@
+class ItemsController < ApplicationController
+  include Entangled::Controller
+
+  def index
+    broadcast do
+      @items = List.find(params[:list_id]).items
+    end
+  end
+
+  def create
+    broadcast do
+      @item = List.find(params[:list_id]).items.create(item_params)
+    end
+  end
+
+  def show
+    broadcast do
+      @item = Item.find(params[:id])
+    end    
+  end
+
+  def update
+    broadcast do
+      @item = Item.find(params[:id])
+      @item.update(item_params)
+    end
+  end
+
+  def destroy
+    broadcast do
+      Item.find(params[:id]).destroy
+    end
+  end
+
+private
+  def item_params
+    params.require(:item).permit(:name, :complete)
+  end
+end

data/spec/dummy/app/controllers/lists_controller.rb

@@ -0,0 +1,32 @@
+class ListsController < ApplicationController
+  include Entangled::Controller
+
+  def index
+    broadcast do
+      @lists = List.all
+    end
+  end
+
+  def create
+    broadcast do
+      @list = List.create(list_params)
+    end
+  end
+
+  def show
+    broadcast do
+      @list = List.find(params[:id])
+    end
+  end
+
+  def destroy
+    broadcast do
+      List.find(params[:id]).destroy
+    end
+  end
+
+private
+  def list_params
+    params.require(:list).permit(:name)
+  end
+end

data/spec/dummy/app/models/item.rb

@@ -0,0 +1,6 @@
+class Item < ActiveRecord::Base
+  include Entangled::Model
+  entangle
+
+  belongs_to :list, required: true
+end

data/spec/dummy/app/models/list.rb

@@ -0,0 +1,6 @@
+class List < ActiveRecord::Base
+  include Entangled::Model
+  entangle
+
+  has_many :items, dependent: :destroy
+end

data/spec/dummy/db/migrate/20150314054548_create_lists.rb

@@ -0,0 +1,9 @@
+class CreateLists < ActiveRecord::Migration
+  def change
+    create_table :lists do |t|
+      t.string :name
+
+      t.timestamps null: false
+    end
+  end
+end

data/spec/dummy/db/migrate/20150314055847_create_items.rb

@@ -0,0 +1,11 @@
+class CreateItems < ActiveRecord::Migration
+  def change
+    create_table :items do |t|
+      t.string :name
+      t.boolean :complete, default: false
+      t.integer :list_id
+
+      t.timestamps null: false
+    end
+  end
+end

data/spec/dummy/db/schema.rb

@@ -11,7 +11,7 @@
 #
 # It's strongly recommended that you check this file into your version control system.
 
-ActiveRecord::Schema.define(version: 20150223004852) do
+ActiveRecord::Schema.define(version: 20150314055847) do
 
   create_table "barfoos", force: :cascade do |t|
     t.text     "body"
@@ -37,6 +37,20 @@ ActiveRecord::Schema.define(version: 20150223004852) do
     t.datetime "updated_at", null: false
   end
 
+  create_table "items", force: :cascade do |t|
+    t.string   "name"
+    t.boolean  "complete",   default: false
+    t.integer  "list_id"
+    t.datetime "created_at",                 null: false
+    t.datetime "updated_at",                 null: false
+  end
+
+  create_table "lists", force: :cascade do |t|
+    t.string   "name"
+    t.datetime "created_at", null: false
+    t.datetime "updated_at", null: false
+  end
+
   create_table "messages", force: :cascade do |t|
     t.text     "body"
     t.datetime "created_at", null: false

data/spec/dummy/public/app/app.js

@@ -10,10 +10,19 @@ angular.module('entangledTest', [
     .when('/', {
       templateUrl: 'views/messages/index.html',
       controller: 'MessagesCtrl'
-    }).when('/messages/:id', {
+    })
+    .when('/messages/:id', {
       templateUrl: 'views/messages/show.html',
       controller: 'MessageCtrl'
     })
+    .when('/lists', {
+      templateUrl: 'views/lists/index.html',
+      controller: 'ListsCtrl'
+    })
+    .when('/lists/:id', {
+      templateUrl: 'views/lists/show.html',
+      controller: 'ListCtrl'
+    })
     .otherwise({
       redirectTo: '/'
     });

data/spec/dummy/public/app/controllers/list.js

@@ -0,0 +1,16 @@
+'use strict';
+
+angular.module('entangledTest')
+
+.controller('ListCtrl', function($scope, $routeParams, List) {
+  List.find($routeParams.id, function(list) {
+    $scope.$apply(function() {
+      $scope.list = list;
+      $scope.list.items().all(function(items) {
+        $scope.$apply(function() {
+          $scope.items = items;
+        });
+      });
+    });
+  });
+});

data/spec/dummy/public/app/controllers/lists.js

@@ -0,0 +1,23 @@
+'use strict';
+
+angular.module('entangledTest')
+
+.controller('ListsCtrl', function($scope, List) {
+  $scope.list = List.new();
+
+  $scope.create = function() {
+    $scope.list.$save(function() {
+      $scope.list = List.new();
+    });
+  };
+
+  $scope.destroy = function(list) {
+    list.$destroy();
+  };
+
+  List.all(function(lists) {
+    $scope.$apply(function() {
+      $scope.lists = lists;
+    });
+  });
+});