action_cable_notifications 0.1.26 → 0.1.27

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 128e7b1e0ecccea4d7e4fe2dcf659e51e99eb618
-  data.tar.gz: 31a94217b247da02df04bc12adaad216caa9fe24
+  metadata.gz: bbf5459391f70a5ea26fcbe49d73d658ee0018e1
+  data.tar.gz: 139cee45492e3dbac434fa59428784ee779ffc14
 SHA512:
-  metadata.gz: 2e27bee4eb7e04565e158b1d3f846bca3ac6257aced6a4d8168f1110c9b9ea8a4e144e7db882ae0da4ed9fdb5bbec77ba0ebaf1d93873ed33f4db830ff8bdaed
-  data.tar.gz: b0ab50fcad5961c25c9be9e368be89d2440927830c06015583f663334b98b92ad6cfb04dfeb6d105693f6403f4fd7ef554d11d8297cde06b5fa6a8c57f93c50f
+  metadata.gz: f81b284758a85fb93d2c189ae4ec8b4f642ba4855309534017e0f3def93260851545d35a23a4ea5a1ba125c58c331c9df50cc29d9fa939e563786b272a1c9164
+  data.tar.gz: dbdf1d02cc3bc63458ddc7e460f8e47a48d58031a2b6008ca22943b1fc1a84fbda856962241dba5e43ad3b8773a1d018a4954aaf2563248935758f9b4641f885

data/README.md

@@ -1,8 +1,13 @@
 # ActionCableNotifications
 [![Gem Version](https://badge.fury.io/rb/action_cable_notifications.svg)](https://badge.fury.io/rb/action_cable_notifications)
 
+## Description
 **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!!**
 
+This gem provides realtime sync of Model data between a Rails 5 app and its web clients. It was inspired in [meteor's](https://www.meteor.com/) [ddp](https://github.com/meteor/meteor/tree/devel/packages/ddp) and [minimongo](https://github.com/meteor/meteor/tree/devel/packages/minimongo) for data syncing and client side storage. It uses new Rails 5 Action Cable to communicate with the server and sync collections in realtime.
+
+Check the sample [todo app](/examples/todo-vuejs) that uses this gem with [VueJS](http://vuejs.org/) for rendering. Will try to upload more examples shortly.
+
 ## Usage
 
 ### Server side
@@ -11,10 +16,12 @@ On **server-side**, create a new channel (`rails g cahnnel Test`) or modify exis
 ```ruby
 class TestChannel < ApplicationCable::Channel
 
-  include ActionCableNotifications::Streams
+  include ActionCableNotifications::Channel
 
   def subscribed
-    stream_notifications_for Users, include_initial: true, scope: [:all, [:limit, 5], [:order, :id]]
+    stream_notifications_for Customer
+    # Can have more than one ActiveRecord model streaming per channel
+    stream_notifications_for Invoice, scope: { limit: 5, order: :id, select: [:id, :customer_id, :seller_id, :amount] }
   end
 
   def unsubscribed
@@ -35,24 +42,103 @@ stream_notifications_for(model, options = {}, &block)
 {
   actions: [:create, :update, :destroy],     # Controller actions to attach to
   broadcasting: model.model_name.collection, # Name of the pubsub stream
-  callback: nil,                             # Same as http://edgeapi.rubyonrails.org/classes/ActionCable/Channel/Streams.html
-  coder: nil,                                # Pass `coder: ActiveSupport::JSON` to decode messages as JSON before passing to the callback.
-                                             # Defaults to `coder: nil` which does no decoding, passes raw messages.
-  include_initial: false,                    # Send all records to the subscriber upon connection
   params: params,                            # Params sent during subscription
-  scope: :all                                # Default collection scope
+  scope: :all                                # Default collection scope. Can be an Array or Hash
 }
 ```
-* 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:
+On **client-side**, you will need to create a subscription to the channel and then you can instantiate a **Store** and one or more **Collections** to keep the data synced with the server. You can register more than one store per application and more than one collection per store.
+
+```javascript
+App.testChannel = App.cable.subscriptions.create("TestChannel", {
+  connected: function() {
+    return console.log("Connected")
+  },
+  disconnected: function() {
+    return console.log("Disconnected")
+  }
+}
+
+// Create a store
+store = App.cableNotifications.registerStore('storeName')
+
+// Create the collections and sync them with the server using testChannel
+customersCollection = store.registerCollection('customers', App.testChannel)
+invoicesCollection = store.registerCollection('invoices', App.testChannel)
+```
+
+That's it! Now you have customers and invoices collections available in your clients. Data will be available as an array in customersCollection.data and invoicesCollection.data objects.
+
+#### Stores
+Stores are groups of collections. They hold a list of available collections and its options for syncing with the server using channels subscriptions. They expose the following methods:
+
+##### registerCollection(collectionName, channelSubscription, tableName)
+Called to register a new collection into the store. **collectionName** must be unique in the store. **channelSubscription** specifies which channel to use to sync with the server. Multiple collections can share the same channel for syncing. If no channel is specified, the collection will work standalone. You can always turn on syncing for a collection later using *syncToChannel* method.
+
+By default, *collectionName* is used on the server side to identify the table on the DB. If you are using a different tablename, you can specify it in the *tableName* parameter.
+
+Example:
+```javascript
+customersCollection = store.registerCollection('customers', App.testChannel)
+```
+
+##### syncToChannel()
+Used to sync a standalone collection with the server using a channel.
+```javascript
+store.syncToChannel(App.testChannel, customersCollection)
+```
+
+#### Collections
+Collections is where data is stored on clients. Collections can be standalone or synced with the server using channel subcriptions.
+
+The registered collection object expose some methods to give easy access to data stored on clients. It uses [lodash](https://lodash.com) for data manipulation, so you can check its documentation for details on parameters.
+
+##### fetch(parameters)
+Retrieves data from the server. You can specify a hash of parameters to send to server.
+```javascript
+invoicesCollection.fetch({limit: 10, where: 'amount>100'})
+```
+##### filter(selector)
+Filter data already present in the client and return all records that met the field values specified in *selector* parameter. You can specify a hash of options or a callback function.
+```javascript
+invoices = invoicesCollection.where({customer_id: 14})
+```
+##### find(selector)
+Same as filter but returns only the first record found.
+```javascript
+invoice = invoicesCollection.find({customer_id: 14})
+```
+##### create(fields)
+Create a new record having the specified field values and sync it with the server.
+```javascript
+invoice = invoicesCollection.create({customer_id: 14, seller_id: 5, amount: 100})
+```
+##### update(selector, fields)
+Updates an existing record identified by *selector* with the specified field values and sync it with the server.
+```javascript
+invoice = invoicesCollection.update({id: 55},{seller_id: 6, amount: 150})
+```
+##### upsert(selector, fields)
+If an existing record cannot be found for updating, a new record is created with the specified fields.
+```javascript
+invoice = invoicesCollection.upsert({id: 55},{seller_id: 6, amount: 150})
+```
+##### destroy(selector)
+Destroys an existing record identified by *selector* and sync it with the server.
+```javascript
+invoicesCollection.destroy({id: 55})
+```
+
+### Server sent messages:
+
+Received data will have the following format:
 
 #### Initial values for collection
 ```javascript
 {
   collection: 'users',
-  msg: 'add_collection',
+  msg: 'upsert_many',
   data: [
     {
       id: 1,

data/app/assets/javascripts/action_cable_notifications/collection.coffee

@@ -68,6 +68,9 @@ class CableNotifications.Collection
     else
       _.filter(@data, selector)
 
+  filter: (selector={}) ->
+    @where(selector)
+
   # Find a record
   find: (selector={}, options={}) ->
     record = _.find(@data, selector)

data/lib/action_cable_notifications/channel.rb

@@ -96,7 +96,8 @@ module ActionCableNotifications
     def stream_notifications_for(model, options = {})
       # Default options
       options = {
-        broadcasting: model.model_name.collection
+        broadcasting: model.model_name.collection,
+        params: nil
       }.merge(options)
 
       # These options cannot be overridden

data/lib/action_cable_notifications/version.rb

@@ -1,3 +1,3 @@
 module ActionCableNotifications
-  VERSION = '0.1.26'
+  VERSION = '0.1.27'
 end

metadata

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