Using the JavaScript Client

Overview

The JavaScript client gives you a quick and easy way to handle events in the browser. It supports several transport methods including WebSockets and HTTP streaming. The client will select the best available transport for you based on the current web browser.

If you ran the installation generator you should already have the client required in your app/assets/javascripts/application.js manifest file. If you prefer, you can require the client manually like so:

//= require websocket_rails/main

Connecting to the server

You connect to the server by creating a new WebSocketRails object and passing it the server address.

var dispatcher = new WebSocketRails('localhost:3000/websocket');

/!\ Be sure the host is the same as your browser if you want to get devise session working !

Notice the lack of a protocol prefix on the server URL. Do not add http:// or ws:// to the URL that you pass to the new dispatcher. WebSocketRails will choose the best available transport for you and prepend the correct prefix automatically.

The on_open callback

If you wish to execute a function immediately after the connection is open, you can attach to the on_open callback.

dispatcher.on_open = function(data) {
  console.log('Connection has been established: ', data);
  // You can trigger new server events inside this callback if you wish.
}

Other standard WebSocket server events can be handled by binding to the events 'connection_closed' and 'connection_error'

dispatcher.bind('connection_closed', function(data) {
  console.log('connection is closed');
});

Triggering an event on the server

Events are triggered on the server using the trigger method. The trigger method takes the event name to trigger and an object that will be serialized as JSON and sent to the server with the event.

var comment = {
  title: 'This post was awful',
  body: 'really awful',
  post_id: 9
}
dispatcher.trigger('comments.create', comment);

The comment object will be decoded from JSON on the server and available as a Hash. You can also pass plain strings and boolean values as well.

This example also demonstrated a namespaced event. You can read more about routing namespaced events on the server side in the documentation for the Event Router.

Success and Failure Callbacks for Events

The .trigger method now takes success and failure callback functions. These functions can be triggered by the action processing the event on the server.

var success = function(response) {
  console.log("Wow it worked: "+response.message);
}

var failure = function(response) {
  console.log("That just totally failed: "+response.message);
}

var object_to_send = { data: 'test' }

dispatcher.trigger('some_event', object_to_send, success, failure); 

Read more about triggering the success and failure callbacks in the WebsocketRails Controllers Wiki.

Binding to an event

You can bind to events sent by the server using the aptly named bind method.

function addCommentToDom(comment) {
  console.log('just received new comment: ' + comment.title);
}
dispatcher.bind('comments.new', addCommentToDom);

Unbinding to an event

You can also unbind to an event when you no longer need to listen to it by using the unbind method.

dispatcher.unbind('comments.new');

Channels

More information on working with channels is available on the Channel Wiki Page.