entangled 0.0.16 → 0.0.17

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 9c1338c6837e0167bc7fab4bf7f0ca67a2e572ba
-  data.tar.gz: 27dc18b0cb3570ae172c603baca469a8958ead45
+  metadata.gz: 620c93edc4a4892c41fe62cfd60cd448a245621e
+  data.tar.gz: d0cde74b9d171662e6bb716349a80eedcf943441
 SHA512:
-  metadata.gz: 89baa6f21fd914f7e8f6664a5712ac6af91891bb210b28be642c0b5acd36f6bf287e70a7a39888f2cf8e17397ed0bd3d1de06b66ea8bded1982d08946c7273e9
-  data.tar.gz: edcafa59d08bfedb94741745f7a6fb8365ff87a68fd8a83ac2409876bdd8601e0fd0bc9a9be40730a1a3ee5f035a173c2fc1d6eb4f8b4ae82e5d919c096d0a38
+  metadata.gz: 24ee4a89da4c1ff4dd462ea2b34f335cb9c05aea74488a6682e6ab6959e0388b3894262ff4adde9f15896c039f8de9a9015d0cce61e794e7a91fa322771493d0
+  data.tar.gz: 34d56b6e058a103daa410ca346e01165ff5de40eccab0c04c61c8ee5ec13029498f991106dc8b97d012fa1712123a3d93376bf0b73ba949703818143edb86747

data/README.md

@@ -2,11 +2,11 @@
 
 [![Codeship Status for dchacke/entangled](https://codeship.com/projects/9fe9a790-9df7-0132-5fb8-6e77ea26735b/status?branch=master)](https://codeship.com/projects/64679)
 
-Services like Firebase are great because they provide real time data binding between client and server. But they come at a price: You give up control over your backend. Wouldn't it be great to have real time functionality but still keep your beloved Rails backend? That's where Entangled comes in.
+Services like Firebase are great because they provide real time data binding between client and server. But they come at a price: You give up control over your back end. Wouldn't it be great to have real time functionality but still keep your beloved Rails back end? That's where Entangled comes in.
 
-Entangled is a layer behind your controllers and models that pushes updates to clients subscribed to certain channels in real time. For example, if you display a list of five messages on a page, if anyone adds a sixth message, everyone who is currently looking at that page will instantly see that sixth message being added to the list.
+Entangled stores and syncs data instantly across every device. It is a layer behind your controllers and models that pushes updates to all connected clients in real time. It is cross-browser compatible and even offers real time validations.
 
-The idea is that real time data binding should be the default, not an add-on. Entangled aims at making real time features as easy to implement as possible, while at the same time making your restful controllers thinner.
+Real time data binding should be the default, not an add-on. Entangled aims at making real time features as easy to implement as possible, while at the same time making your restful controllers thinner. All this without having to give up control over your back end.
 
 ## Installation
 Add this line to your application's Gemfile:
@@ -104,13 +104,14 @@ class MessagesController < ApplicationController
 
   def create
     broadcast do
-      Message.create(message_params)
+      @message = Message.create(message_params)
     end
   end
 
   def update
     broadcast do
-      Message.find(params[:id]).update(message_params)
+      @message = Message.find(params[:id])
+      @message.update(message_params)
     end
   end
 
@@ -131,8 +132,7 @@ Note the following:
 
 - All methods are wrapped in a new `broadcast` block needed to send messages to connected clients
 - The `index` method will expect an instance variable with the same name as your controller in the plural form (e.g. `@messages` in a `MessagesController`)
-- The `show` method will expect an instance variable with the singular name of your controller (e.g. `@message` in a `MessagesController`)
-- Instance variables only need to be assigned in `index` and `show` since these are the only methods that should be concerned with sending data to clients. All other methods only publish updates to the data clients are subscribed to through the callbacks added to the model, so no instance variables are needed
+- The `show`, `create` and `update` methods will expect an instance variable with the singular name of your controller (e.g. `@message` in a `MessagesController`)
 - Data sent to clients arrives as stringified JSON
 - Strong parameters are expected
 
@@ -146,13 +146,13 @@ $ redis-server
 
 Otherwise the channels won't work.
 
-If you store your Redis instance in `$redis` or `REDIS` (e.g. in an initializer), Entangled will use that assigned instance so that you can configure Redis just like you're used to. Otherwise, Entangled will instantiate Redis itself and use its standard settings.
+If you store your Redis instance in `$redis` or `REDIS` (e.g. in an initializer), Entangled will use that assigned instance so that you can configure Redis just like you're used to. Otherwise, Entangled will instantiate Redis itself and use its default settings.
 
 ### Database
 Depending on your app's settings, you might have to increase the pool size in your database.yml configuration file, since every new socket will open a new connection to your database.
 
 ## The Client
-You will need to configure your client to create Websockets and understand incoming requests on those sockets. If you use Angular for your frontend, you can use the Angular library from this repository. The use of Angular as counterpart of this gem is highly recommended, since its inherent two way data binding complements the real time functionality of this gem nicely.
+You will need to configure your client to create Websockets and understand incoming requests on those sockets. If you use Angular for your front end, you can use the Angular library from this repository. The use of Angular as counterpart of this gem is highly recommended, since its inherent two way data binding complements the real time functionality of this gem nicely.
 
 ### Installation
 You can either download or reference the file `entangled.js` from this repository, or simply install it with Bower:
@@ -174,25 +174,24 @@ Entangled is best used within Angular services. For example, consider a `Message
 
 ```javascript
 app.factory('Message', function(Entangled) {
-  var entangled = new Entangled('ws://localhost:3000/messages');
-
-  var Message = {
-    new: function(params) {
-      return entangled.new(params);
-    },
-    all: function(callback) {
-      return entangled.all(callback);
-    },
-    find: function(id, callback) {
-      return entangled.find(id, callback);
-    }
-  };
-
-  return Message;
+  return new Entangled('ws://localhost:3000/messages');
 });
 ```
 
-In the above example, first we inject Entangled into our service, then instantiate a new Entangled object. The Entangled object takes one argument when instantiated: the URL of your resource's index route (in this case, `/messages`). Then we add helper methods to our service. Note that the socket URL looks just like a standard restful URL with http, except that the protocol part has been switched with `ws` to use the websocket protocol. Also note that you need to use `wss` instead if you want to use SSL.
+In the above example, first we inject Entangled into our service, then instantiate a new Entangled object and return it. The Entangled object takes one argument when instantiated: the URL of your resource's index action (in this case, `/messages`). Note that the socket URL looks just like a standard restful URL with http, except that the protocol part has been switched with `ws` to use the websocket protocol. Also note that you need to use `wss` instead if you want to use SSL.
+
+The Entangled service come with these functions:
+
+- `new(params)`
+- `create(params, callback)`
+- `find(id, callback)`
+- `all(callback)`
+
+...and the following functions on returned objects:
+
+- `$save(callback)`
+- `$update(params, callback)`
+- `$destroy(callback)`
 
 In your controller, you could then inject that `Message` service and use it like so:
 
@@ -202,20 +201,21 @@ In your controller, you could then inject that `Message` service and use it like
 // set some default values
 $scope.message = Message.new();
 
+// To instantiate and save a message in one go
+Message.create({ body: 'text' }, function(message) {
+  $scope.$apply(function() {
+    $scope.message = message;
+  });
+});
+
 // To retrieve a specific message from the server
 // with id 1 and subscribe to its channel
-Message.find(1, function() {
+Message.find(1, function(message) {
   $scope.$apply(function() {
     $scope.message = message;
   });
 });
 
-// To create a new or update an existing message
-$scope.message.$save();
-
-// To destroy a message
-$scope.message.$destroy();
-
 // To retrieve all messages from the server and
 // subscribe to the collection's channel
 Message.all(function(messages) {
@@ -223,14 +223,83 @@ Message.all(function(messages) {
     $scope.messages = messages;
   });
 });
+
+// To store a newly instantiated or update an existing message.
+// If saved successfully, $scope.message is updated in place
+// with the attributes id, created_at and updated_at
+$scope.message.body = 'new body';
+$scope.message.$save(function() {
+  // Do stuff after save
+});
+
+// To update a newly instantiated or existing message in place.
+// If updated successfully, $scope.message is updated in place
+// with the attributes id, created_at and updated_at
+$scope.message.$update({ body: 'new body' }, function() {
+  // Do stuff after update
+});
+
+// To destroy a message
+$scope.message.$destroy(function() {
+  // Do stuff after destroy
+});
 ```
 
-`$save()`, `$destroy()`, `find()` and `all()` will interact with your server's controllers in real time.
+All functions above will interact with your server's controllers in real time.
 
 If data in your server's database changes, so will your scope variables - in real time, for all connected clients.
 
+### Available Functions
+A number of functions is attached to Entangled JavaScript objects. They basically mimic ActiveRecord's behavior in the back end to make the database more accessible in the front end.
+
+#### Validations
+Objects from the Entangled service automatically receive ActiveRecord's error messages from your model when you `$save()`. An additional property called `errors` containing the error messages is available, formatted the same way you're used to from calling `.errors` on a model in Rails.
+
+For example, consider the following scenario:
+
+```ruby
+# Message model (Rails)
+validates :body, presence: true
+```
+
+```javascript
+// Controller (Angular)
+$scope.message.$save(function() {
+  console.log($scope.message.errors);
+  // => { body: ["can't be blank"] }
+});
+```
+
+You could then display these error messages to your users.
+
+To check if a resource is valid, you can use `$valid()` and `$invalid()`. Both functions return booleans. For example:
+
+```javascript
+$scope.message.$save(function() {
+  // Check if record has no errors
+  if ($scope.message.$valid()) { // similar to ActiveRecord's .valid?
+    alert('Yay!');
+  }
+
+  // Check if record errors
+  if ($scope.message.$invalid()) { // similar to ActiveRecord's .invalid?
+    alert('Nay!');
+  }
+});
+```
+
+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.
+
+#### Persistence
+Just like with ActiveRecord's `persisted?` method, you can use `$persisted()` on an object to check if it was successfully stored in the database.
+
+```javascript
+$scope.message.$persisted();
+// => true or false
+```
+
 ## Planning Your Infrastructure
-This gem is best used for Rails apps that serve as APIs only and are not concerned with rendering views. A frontend separate from your Rails app, such as Angular with Grunt, is recommended.
+This gem is best used for Rails apps that serve as APIs only and are not concerned with rendering views, since Entangled controllers cannot render views. A front end separate from your Rails app is recommended, either in your Rails app's public directory, or a separate front end app altogether.
 
 ## Limitations
 The gem rely's heavily on convention over configuration and currently only works with restful style controllers as shown above. More customization will be available soon.
@@ -240,12 +309,13 @@ The gem rely's heavily on convention over configuration and currently only works
 2. Run `$ bundle install` in the root of the repo
 3. Run `$ bower install` and `$ npm install` in spec/dummy/public
 4. The back end example app resides in spec/dummy; you can run `rails` and `rake` commands in there if you prefix them with `bin/`, i.e. `$ bin/rails s` or `$ bin/rake db:schema:load`; run your tests in the root of the repo by running `$ rspec`
-5. The front end example app resides in spec/dummy/public. To look at it in your browser, cd into spec/dummy/public and run `$ bin/rails s`. Tests for this part of the app can be located under spec/dummy/public/test and are written with Jasmine. To run the tests, first run `$ bin/rails -e test` to start up the server in test mode, and then run `$ grunt test` in a new terminal tab. It's important to remember that changes you make to the server will not take effect until you restart the server since you're running it in the test environment!
-6. Write your tests
-7. Write your feature to make the tests pass
-8. Stage and commit your changes
-9. Push to a new feature branch in your repo
-10. Send me a pull request!
+5. The front end example app resides in spec/dummy/public. To look at it in your browser, cd into spec/dummy/public and run `$ bin/rails s`. Tests for this part of the app can be located under spec/dummy/public/test and are written with Jasmine. To run the tests, first run `$ bin/rails -e test` to start up the server in test mode, and then run `$ grunt test` in a new terminal tab. It's important to remember that changes you make to the server will not take effect until you restart the server since you're running it in the test environment! Also remember to prepare the test database by running `$ bin/rake db:test:prepare`
+6. The Entangled Angular service resides in spec/dummy/public/app/entangled/entangled.js. This is where you can make changes to the service; a copy of it, living in /entangled.js at the root of the repo, should be kept in sync for it to be available with Bower, so it's best if you replace this file with the one from the dummy app should have made any changes to the latter
+7. Write your tests
+8. Write your feature to make the tests pass
+9. Stage and commit your changes
+10. Push to a new feature branch in your repo
+11. Send me a pull request!
 
 ## Credits
 Thanks to [Ilias Tsangaris](https://github.com/iliastsangaris) for inspiring the name "Entanglement" based on [Quantum Entanglement](http://en.wikipedia.org/wiki/Quantum_entanglement) where pairs or groups of particles always react to changes as a whole, i.e. changes to one particle will result in immediate change of all particles in the group.

data/bower.json

@@ -1,6 +1,6 @@
 {
   "name": "entangled",
-  "version": "0.0.1",
+  "version": "0.0.6",
   "authors": [
     "Dennis Charles Hackethal <dennis.hackethal@gmail.com>"
   ],

data/entangled.gemspec

@@ -15,7 +15,7 @@ Gem::Specification.new do |s|
 
   s.files         = `git ls-files -z`.split("\x0")
   s.executables   = s.files.grep(%r{^bin/}) { |f| File.basename(f) }
-  s.test_files = Dir["spec/**/*"]
+  s.test_files    = `git ls-files -z spec`.split("\x0")
   s.require_paths = ["lib"]
 
   s.add_development_dependency 'bundler', '~> 1.7'

data/entangled.js

@@ -26,43 +26,83 @@ angular.module('entangled', [])
   // an existing, depending on whether or not
   // an id is present.
   Resource.prototype.$save = function(callback) {
-    console.log('Saving...');
-
     var that = this;
-    console.log(that);
 
     if (this.id) {
       // Update
-      console.log('Updating...');
       var socket = new WebSocket(that.webSocketUrl + '/' + that.id + '/update');
       socket.onopen = function() {
         socket.send(JSON.stringify(that));
+      };
 
-        if (callback) callback();
+      // Receive updated resource from server
+      socket.onmessage = function(event) {
+        if (event.data) {
+          var data = JSON.parse(event.data);
 
-        console.log('Updated');
+          // Assign/override new data (such as updated_at, etc)
+          if (data.resource) {
+            for (key in data.resource) {
+              that[key] = data.resource[key];
+            }
+          }
+        }
+
+        // Pass 'that' to callback for create
+        // function so that the create function
+        // can pass the created resource to its
+        // own callback; not needed for $save per se
+        if (callback) callback(that);
       };
     } else {
       // Create
-      console.log('Creating...');
       var socket = new WebSocket(that.webSocketUrl + '/create');
 
+      // Send attributes to server
       socket.onopen = function() {
-        console.log(socket);
         socket.send(JSON.stringify(that));
+      };
 
-        if (callback) callback();
+      // Receive saved resource from server
+      socket.onmessage = function(event) {
+        if (event.data) {
+          var data = JSON.parse(event.data);
 
-        console.log('Created');
+          // Assign/override new data (such as id, created_at,
+          // updated_at, etc)
+          if (data.resource) {
+            for (key in data.resource) {
+              that[key] = data.resource[key];
+            }
+          }
+        }
+
+        // Pass 'that' to callback for create
+        // function so that the create function
+        // can pass the created resource to its
+        // own callback; not needed for $save per se
+        if (callback) callback(that);
       };
     }
   };
 
+  // $update() updates a record in place
+  Resource.prototype.$update = function(params, callback) {
+    // Update object in memory
+    for (var key in params) {
+      // Skip inherent object properties
+      if (params.hasOwnProperty(key)) {
+        this[key] = params[key];
+      }
+    }
+
+    // Save object
+    this.$save(callback);
+  };
+
   // $destroy() will send a request to the server to
   // destroy an existing record.
   Resource.prototype.$destroy = function(callback) {
-    console.log('From $destroy: ', this);
-
     var socket = new WebSocket(this.webSocketUrl + '/' + this.id + '/destroy');
     socket.onopen = function() {
       // It's fine to send an empty message since the
@@ -74,6 +114,26 @@ angular.module('entangled', [])
     };
   };
 
+  // $valid() checks if any errors are attached to the object
+  // and return false if so, false otherwise. This doesn't actually
+  // invoke server side validations, so it should only be used
+  // after calling $save() to check if the record was successfully
+  // stored in the database
+  Resource.prototype.$valid = function() {
+    return !(this.errors && Object.keys(this.errors).length);
+  };
+
+  // $invalid() returns the opposite of $valid()
+  Resource.prototype.$invalid = function() {
+    return !this.$valid();
+  };
+
+  // $persisted() checks if the record was successfully stored
+  // in the back end's database
+  Resource.prototype.$persisted = function() {
+    return !!this.id;
+  };
+
   // Resources wraps all individual Resource objects
   // in a collection.
   var Resources = function(resources, webSocketUrl) {
@@ -119,22 +179,16 @@ angular.module('entangled', [])
 
         // If the collection of Resources was sent
         if (data.resources) {
-          console.log('Index');
-
           // Store retrieved Resources in property
           this.resources = new Resources(data.resources, socket.url);
         } else if (data.action) {
           if (data.action === 'create') {
             // If new Resource was created, add it to the
             // collection
-            console.log('Created');
-            console.log(this.resources);
-
             this.resources.all.push(new Resource(data.resource, socket.url));
           } else if (data.action === 'update') {
             // If an existing Resource was updated,
             // update it in the collection as well
-            console.log('Updated');
             var index;
 
             for (var i = 0; i < this.resources.all.length; i++) {
@@ -147,7 +201,6 @@ angular.module('entangled', [])
           } else if (data.action === 'destroy') {
             // If a Resource was destroyed, remove it
             // from Resources as well
-            console.log('Destroyed');
             var index;
 
             for (var i = 0; i < this.resources.all.length; i++) {
@@ -158,7 +211,7 @@ angular.module('entangled', [])
 
             this.resources.all.splice(index, 1);
           } else {
-            console.log('Something else happened...');
+            console.log('Something else other than CRUD happened...');
             console.log(data);
           }
         }
@@ -170,6 +223,12 @@ angular.module('entangled', [])
     };
   };
 
+  // Instantiate and persist a record in one go
+  Entangled.prototype.create = function(params, callback) {
+    var resource = this.new(params);
+    resource.$save(callback);
+  };
+
   // Find an individual Resource on the server
   Entangled.prototype.find = function(id, callback) {
     var webSocketUrl = this.webSocketUrl;
@@ -180,7 +239,6 @@ angular.module('entangled', [])
       if (event.data.length) {
         // Parse message and convert to JSON
         var data = JSON.parse(event.data);
-        console.log('Show');
 
         if (data.resource && !data.action) {
           // If the Resource was sent from the server,
@@ -190,18 +248,14 @@ angular.module('entangled', [])
           if (data.action === 'update') {
             // If the stored Resource was updated,
             // update it here as well
-            console.log('updated!');
-
             this.resource = new Resource(data.resource, webSocketUrl);
           } else if (data.action === 'destroy') {
             // If the stored Resource was destroyed,
             // remove it from here as well
-            console.log('destroyed!');
-
             this.resource = undefined;
           }
         } else {
-          console.log('something else happened...');
+          console.log('Something else other than CRUD happened...');
           console.log(data);
         }
       }