diff options
Diffstat (limited to 'lib')
4 files changed, 58 insertions, 0 deletions
diff --git a/lib/assets/javascripts/cable/connection.js.coffee b/lib/assets/javascripts/cable/connection.js.coffee index 87fd038a6f..464f0c1ff7 100644 --- a/lib/assets/javascripts/cable/connection.js.coffee +++ b/lib/assets/javascripts/cable/connection.js.coffee @@ -1,3 +1,4 @@ +# Encapsulate the cable connection held by the consumer. This is an internal class not intended for direct user manipulation. class Cable.Connection constructor: (@consumer) -> @open() diff --git a/lib/assets/javascripts/cable/connection_monitor.js.coffee b/lib/assets/javascripts/cable/connection_monitor.js.coffee index 1f8ce4eb20..cac65d9043 100644 --- a/lib/assets/javascripts/cable/connection_monitor.js.coffee +++ b/lib/assets/javascripts/cable/connection_monitor.js.coffee @@ -1,3 +1,5 @@ +# Responsible for ensuring the cable connection is in good health by validating the heartbeat pings sent from the server, and attempting +# revival reconnections if things go astray. Internal class, not intended for direct user manipulation. class Cable.ConnectionMonitor identifier: Cable.PING_IDENTIFIER diff --git a/lib/assets/javascripts/cable/subscription.js.coffee b/lib/assets/javascripts/cable/subscription.js.coffee index b60033098a..5b024d4e15 100644 --- a/lib/assets/javascripts/cable/subscription.js.coffee +++ b/lib/assets/javascripts/cable/subscription.js.coffee @@ -1,3 +1,48 @@ +# A new subscription is created through the Cable.Subscriptions instance available on the consumer. +# It provides a number of callbacks and a method for calling remote procedure calls on the corresponding +# Channel instance on the server side. +# +# An example demonstrates the basic functionality: +# +# App.appearance = App.cable.subscriptions.create "AppearanceChannel", +# connected: -> +# # Called once the subscription has been successfully completed +# +# appear: -> +# @perform 'appear', appearing_on: @appearingOn() +# +# away: -> +# @perform 'away' +# +# appearingOn: -> +# $('main').data 'appearing-on' +# +# The methods #appear and #away forward their intent to the remote AppearanceChannel instance on the server +# by calling the `@perform` method with the first parameter being the action (which maps to AppearanceChannel#appear/away). +# The second parameter is a hash that'll get JSON encoded and made available on the server in the data parameter. +# +# This is how the server component would look: +# +# class AppearanceChannel < ApplicationCable::Channel +# def subscribed +# current_user.appear +# end +# +# def unsubscribed +# current_user.disappear +# end +# +# def appear(data) +# current_user.appear on: data['appearing_on'] +# end +# +# def away +# current_user.away +# end +# end +# +# The "AppearanceChannel" name is automatically mapped between the client-side subscription creation and the server-side Ruby class name. +# The AppearanceChannel#appear/away public methods are exposed automatically to client-side invocation through the @perform method. class Cable.Subscription constructor: (@subscriptions, params = {}, mixin) -> @identifier = JSON.stringify(params) diff --git a/lib/assets/javascripts/cable/subscriptions.js.coffee b/lib/assets/javascripts/cable/subscriptions.js.coffee index 884257a12d..e1dfff7511 100644 --- a/lib/assets/javascripts/cable/subscriptions.js.coffee +++ b/lib/assets/javascripts/cable/subscriptions.js.coffee @@ -1,3 +1,11 @@ +# Collection class for creating (and internally managing) channel subscriptions. The only method intended to be triggered by the user +# us Cable.Subscriptions#create, and it should be called through the consumer like so: +# +# @App = {} +# App.cable = Cable.createConsumer "http://example.com/accounts/1" +# App.appearance = App.cable.subscriptions.create "AppearanceChannel" +# +# For more details on how you'd configure an actual channel subscription, see Cable.Subscription. class Cable.Subscriptions constructor: (@consumer) -> @subscriptions = [] @@ -7,6 +15,8 @@ class Cable.Subscriptions params = if typeof channel is "object" then channel else {channel} new Cable.Subscription this, params, mixin + # Private + add: (subscription) -> @subscriptions.push(subscription) @notify(subscription, "initialized") |