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');

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

Channel Join & Part Events

To enable subscriber events, place config.broadcast_subscriber_events = true in your main websocket_rails.rb file. If subscriber events are enabled, WebsocketRails will trigger subscriber_join and subscriber_part whenever a new client joins or leaves the channel. These events will be triggered on all other clients who are currently subscribed to that channel. If you have configured the UserManager, the current_user object will be sent with the event.

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

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

channel.bind('subscriber_join', function(user){
    console.log(user +' has joined the channel!');
});
channel.bind('subscriber_part', function(user){
    console.log(user +' has left the channel!');
});

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.