action_cable_notifications 0.1.5 → 0.1.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 77099f72f8abc9a8cdddad94a14066bacf6ed237
-  data.tar.gz: 7912095ef91683daa7a35a5ae951b06674d57ee7
+  metadata.gz: af4258aa0ac4cfba0b3f42a7aab2db6d91daf7a3
+  data.tar.gz: b2493f00d932a61c9ea7ecaabad17fa43bb25dc0
 SHA512:
-  metadata.gz: 1dc22ba6426f9b2f06ef710e6908bb97eac861c6fd0d6810cf887e21814d1531621fcde8ab6a12ccdd75a2a0152f069100ad5b3d75d977cd221db148197c6e7c
-  data.tar.gz: d079cacae3eb059499f1f008928dd677be4aefbc873420b647a7db588b47f13d6d24fc506bae64395363b292f9fcde29e1d30a6a16f9dd20463ca11f367ac302
+  metadata.gz: cb152248983ea3678b5b2933046a8604cd23ff16de46191709117fafa687a24272cc2bb7f5f6ab3e737ef22f9cd96553e1f21a34ea64c484a0f74a0e41e33029
+  data.tar.gz: 6f19980552466b17e0ab2cdf6424cf86e620e6afdff01c71bb71a9fd6d815acd4d7108580dc59fff69d540620baa38f36561dd0743cf9e136865e715ea53fe99

data/README.md

@@ -1,30 +1,12 @@
 # ActionCableNotifications
 [![Gem Version](https://badge.fury.io/rb/action_cable_notifications.svg)](https://badge.fury.io/rb/action_cable_notifications)
 
-This gem is under develoment and is not ready for production usage.
+**This gem is being developed as part of an internal proyect. It's constantly changing and is not ready for production usage. Use at your own risk!!**
 
 ## Usage
-How to use my plugin.
 
-## Installation
-Add this line to your application's Gemfile:
-
-```ruby
-gem 'action_cable_notifications'
-```
-
-And then execute:
-```bash
-$ bundle
-```
-
-Or install it yourself as:
-```bash
-$ gem install action_cable_notifications
-```
-
-## Usage
-Create a new channel (`rails g cahnnel Test`) or modify existing one including `ActionCableNotifications::Streams` module. 
+### Server side
+On **server-side**, create a new channel (`rails g cahnnel Test`) or modify existing one including `ActionCableNotifications::Streams` module. 
 
 ```ruby
 class TestChannel < ApplicationCable::Channel
@@ -32,7 +14,7 @@ class TestChannel < ApplicationCable::Channel
   include ActionCableNotifications::Streams
 
   def subscribed
-    stream_notifications_for model, include_initial: true, scope: [:all, [:limit, 5], [:order, :id]]
+    stream_notifications_for Users, include_initial: true, scope: [:all, [:limit, 5], [:order, :id]]
   end
 
   def unsubscribed
@@ -41,7 +23,7 @@ class TestChannel < ApplicationCable::Channel
 end
 ```
 
-Method stream_notifications_for receives the following parameters: 
+Method `stream_notifications_for` receives the following parameters: 
 
 ```ruby
 stream_notifications_for(model, options = {}, &block)
@@ -63,8 +45,83 @@ stream_notifications_for(model, options = {}, &block)
 ```
 * block: **(Proc)** - Same as options[:callback]
 
+### Client side
+On **client-side**, use action_cable subscriptions as stated in the documentation. Received data will have the following format:
+
+#### Initial values for collection
+```javascript
+{
+  collection: 'users',
+  msg: 'add_collection',
+  data: [
+    {
+      id: 1,
+      username: 'username 1',
+      color: 'red'
+    },
+    {
+      id: 2,
+      username: 'username 2',
+      color: 'green'
+  ]
+}
+```
+
+#### Create event
+```javascript
+{
+  collection: 'users',
+  msg: 'create',
+  id: 3,
+  data: {
+    id: 3,
+    username: 'username 3'
+    color: 'blue'
+  }
+}
+```
+
+#### Update event
+Update event will only transmit changed fields for the model.
+```javascript
+{
+  collection: 'users',
+  msg: 'update',
+  id: 2,
+  data: {
+    color: 'light blue'
+  }
+}
+```
+
+#### Destroy event
+```javascript
+{
+  collection: 'users',
+  msg: 'destroy',
+  id: 2
+}
+```
+
+## Installation
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'action_cable_notifications'
+```
+
+And then execute:
+```bash
+$ bundle
+```
+
+Or install it yourself as:
+```bash
+$ gem install action_cable_notifications
+```
+
 ## Contributing
-Contribution directions go here.
+Contributions are welcome. We will be happy to receive issues, comments and pull-request to make this gem better.
 
 ## License
 The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).

data/lib/action_cable_notifications/callbacks.rb

@@ -3,61 +3,95 @@ module ActionCableNotifications
     extend ActiveSupport::Concern
 
     included do
-      # Options
+      # Action cable notification options storage
       class_attribute :ActionCableNotificationsOptions
       self.ActionCableNotificationsOptions = {}
 
+      # Register Callbacks
       after_update :notify_update
       after_create :notify_create
-      after_destroy :notify_destroy
+      before_destroy :notify_destroy
     end
 
     module ClassMethods
-      # Options setter
-      def action_cable_notification_options= ( broadcasting, options = nil )
+
+      #
+      # Sets or removes notificacions options for Active Record model
+      #
+      # @param [sym] broadcasting Topic name to broadcast in
+      # @param [hash] options Hash containing notification options
+      #
+      def broadcast_notifications_from ( broadcasting, options = nil )
         if options.present?
+          # Default options
+          options = {
+            actions: [:create, :update, :destroy],
+            scope: :all             # Default collection scope
+            }.merge(options)
+
           self.ActionCableNotificationsOptions[broadcasting.to_sym] = options
         else
           self.ActionCableNotificationsOptions.except! broadcasting.to_sym
         end
       end
 
-      # Options getter
-      def action_cable_notification_options ( broadcasting )
-        if broadcasting.present?
-          self.ActionCableNotificationsOptions[broadcasting.to_sym]
-        else
-          self.ActionCableNotificationsOptions
-        end
-      end
-
-      def scoped_collection ( scope )
-        Array(Array(scope).inject(self) {|o, a| o.try(*a)})
+      #
+      # Returns collection scoped as specified in parameters.
+      #
+      # @param [Array] scope Contains the scopes to be applied. For
+      # example: [[:limit, 5], [:order, :id]]
+      #
+      # @return [ActiveRecordRelation] Results fetched from the database
+      #
+      def scoped_collection ( scope=:all )
+        Array(scope).inject(self) {|o, a| o.try(*a)}
       end
 
+      #
+      # Retrieves initial values to be sent to clients upon subscription
+      #
+      # @param [Sym] broadcasting Name of broadcasting stream
+      #
+      # @return [Hash] Hash containing the results in the following format:
+      # {
+      #   collection: self.model_name.collection,
+      #   msg: 'add_collection',
+      #   data: self.scoped_collection(options[:scope])
+      # }
       def notify_initial ( broadcasting )
-        options = self.action_cable_notification_options( broadcasting )
-        {
-          collection: self.model_name.collection,
-          msg: 'add_collection',
-          data: self.scoped_collection(options[:scope])
-        }
+        options = self.ActionCableNotificationsOptions[broadcasting.to_sym]
+        if options.present?
+          {
+            collection: self.model_name.collection,
+            msg: 'add_collection',
+            data: self.scoped_collection(options[:scope])
+          }
+        end
       end
     end
 
+    #
+    # Broadcast notifications when a new record is created
+    #
     def notify_create
       self.ActionCableNotificationsOptions.each do |broadcasting, options|
-        # Checks if record is within scope before broadcasting
-        if self.class.scoped_collection(options[:scope]).include? self
-          ActionCable.server.broadcast broadcasting,
-            collection: self.model_name.collection,
-            msg: 'create',
-            id: self.id,
-            data: self
+        if options[:actions].include? :create
+          # Checks if record is within scope before broadcasting
+          if self.class.scoped_collection(options[:scope]).where(id: self.id)
+            ActionCable.server.broadcast broadcasting,
+              collection: self.model_name.collection,
+              msg: 'added',
+              id: self.id,
+              data: self
+          end
         end
       end
     end
 
+    #
+    # Broadcast notifications when a record is updated. Only changed
+    # field will be sent.
+    #
     def notify_update
       changes = {}
       self.changes.each do |k,v|
@@ -65,25 +99,38 @@ module ActionCableNotifications
       end
 
       self.ActionCableNotificationsOptions.each do |broadcasting, options|
-        # Checks if record is within scope before broadcasting
-        if self.class.scoped_collection(options[:scope]).include? self
-          ActionCable.server.broadcast broadcasting,
-            collection: self.model_name.collection,
-            msg: 'update',
-            id: self.id,
-            data: changes
+        if options[:actions].include? :update
+          # Checks if record is within scope before broadcasting
+          if self.class.scoped_collection(options[:scope]).where(id: self.id)
+            # XXX: Performance required. For small data sets this should be
+            # fast enough, but for large data sets this could be slow. As
+            # clients should have a limited subset of the dataset loaded at a
+            # time, caching the results already sent to clients in server memory
+            # should not have a big impact in memory usage but can improve
+            # performance for large data sets where only a sub
+            ActionCable.server.broadcast broadcasting,
+              collection: self.model_name.collection,
+              msg: 'changed',
+              id: self.id,
+              data: changes
+          end
         end
       end
     end
 
+    #
+    # Broadcast notifications when a record is destroyed.
+    #
     def notify_destroy
       self.ActionCableNotificationsOptions.each do |broadcasting, options|
-        # Checks if record is within scope before broadcasting
-        if self.class.scoped_collection(options[:scope]).include? self
-          ActionCable.server.broadcast broadcasting,
-            collection: self.model_name.collection,
-            msg: 'destroy',
-            id: self.id
+        if options[:actions].include? :destroy
+          # Checks if record is within scope before broadcasting
+          if self.class.scoped_collection(options[:scope]).where(id: self.id)
+            ActionCable.server.broadcast broadcasting,
+              collection: self.model_name.collection,
+              msg: 'removed',
+              id: self.id
+          end
         end
       end
     end

data/lib/action_cable_notifications/streams.rb

@@ -9,10 +9,8 @@ module ActionCableNotifications
     private
 
     def stream_notifications_for(model, options = {}, &block)
-      @model = model
-
       # Default options
-      @options = {
+      options = {
         actions: [:create, :update, :destroy],
         broadcasting: model.model_name.collection,
         callback: nil,
@@ -23,29 +21,29 @@ module ActionCableNotifications
         }.merge(options)
 
       # Checks if model already includes notification callbacks
-      if !@model.respond_to? :ActionCableNotificationsOptions
-        @model.send('include', ActionCableNotifications::Callbacks)
+      if !model.respond_to? :ActionCableNotificationsOptions
+        model.send('include', ActionCableNotifications::Callbacks)
+        # Set specified options on model
       end
 
-      # Set specified options on model
-      @model.send('action_cable_notification_options=', @options[:broadcasting], @options)
+      # Sets broadcast options if they are not already present in the model
+      if not model.ActionCableNotificationsOptions.key? options[:broadcasting]
+        model.broadcast_notifications_from options[:broadcasting], options
+      end
 
       # Start streaming
-      stream_from(@options[:broadcasting], options[:callback] || block, @options.slice(:coder))
+      stream_from(options[:broadcasting], options[:callback] || block, options.slice(:coder))
 
       # Transmit initial state if required
-      if @options[:include_initial]
+      if options[:include_initial]
         # XXX: Check if data should be transmitted
-        transmit @model.notify_initial @options[:broadcasting]
+        transmit model.notify_initial options[:broadcasting]
       end
 
     end
 
     def unsubscribed
       stop_all_streams
-
-      # Unset options for this channel on model
-      @model.send('action_cable_notification_options=', @options[:broadcasting], nil)
     end
 
   end

data/lib/action_cable_notifications/version.rb

@@ -1,3 +1,3 @@
 module ActionCableNotifications
-  VERSION = '0.1.5'
+  VERSION = '0.1.6'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: action_cable_notifications
 version: !ruby/object:Gem::Version
-  version: 0.1.5
+  version: 0.1.6
 platform: ruby
 authors:
 - ByS Sistemas de Control
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-08-30 00:00:00.000000000 Z
+date: 2016-09-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails