Working with Channels

Overview

Channels give you a way to broadcast information from anywhere in your rails application. Lets say you have a list of recent posts. You wish to update this list on your user's browser in real time whenever the list changes. On the server side, you could broadcast the new list to a 'posts' channel. On the client side, you could subscribe to the 'posts' channel and update the list whenever a new list is received.

Creating a Channel

You do not need to explicitly create a channel. The channel will be automatically created the first time a client subscribes to the channel or a message is broadcasted to the channel on the server. If no clients are subscribed when a message is broadcasted, the message will not be sent.

Broadcasting to a Channel

You can broadcast to a channel from anywhere in a Rails application using the following code:

WebsocketRails[:channel_name].trigger(:event_name, object_to_send)

This code can be placed inside of a standard rails controller, a WebsocketRails controller, or even an ActiveRecord model.

Subscribing to a Channel

Subscribing to a channel on the client side returns a new dispatcher object that will send and receive events on the channel that it is subscribed to. You can work with the new channel dispatcher object exactly like the standard dispatcher.

// connect to server like normal
var dispatcher = new WebSocketRails('localhost:3000/websocket');

// subscribe to the channel
var channel = dispatcher.subscribe('channel_name');

// You can also pass an object to the subscription event
// var channel = dispatcher.subscribe({channel: 'channel_name', foo: 'bar'});

// bind to a channel event
channel.bind('event_name', function(data) {
  console.log('channel event received: ' + data);
});

// unbind to a channel event
channel.unbind('event_name');

Review the WebSocketRails client guide for more information on working with the dispatcher.

Triggering Channel Events from the Client

If you trigger a channel event on the client, it will be sent out to every other connected client to that channel.

channel.trigger('event_name', object_to_send);

Channel Events and the Event Router

Channel events currently happen outside of the Event Router flow. They are meant for broadcasting events to a group of connected clients simultaneously. If you wish to handle events with actions on the server, trigger the event on the main dispatcher and specify which controller action should handle it using the Event Router.

Channel internal events

By adding

WebsocketRails::EventMap.describe do
...  
  namespace :websocket_rails do 
    subscribe :subscribe, to: WebsocketRailsController, with_method: :client_subscribed
    subscribe :subscribe_private, to: WebsocketRailsController, with_method: :client_subscribed_to_private
  end
...
end

to your events.rb configuration

You can then use the object you passed in the subscribe function of the client side in the client_subscribed function.