The Event Router

The installation generator will create the events.rb file in your config directory. You can edit this file to begin mapping client side events to controller actions.

Subscribe Events to Actions

You subscribe an event to a particular controller action using the subscribe method. You can specify the target controller in two ways: either using a Hash with keys :to and :with_method or using a String with syntax 'controller_name#method_name' where controller name is the controller class name, without the Controller suffix and using underscore_case.

subscribe :event_name, :to => EventController, :with_method => :action_method
# or the equivalent
subscribe :event_name, 'event#action_method'

if the target is not a top-level object

subscribe :event_name, :to => MyModule::EventController, :with_method => :action_method
# or the equivalent
subscribe :event_name, 'my_module/event#action_method'

This will route events triggered from the JavaScript client like the following:

dispatcher.trigger('event_name', object_to_send);

Namespaced Events

You can nest events underneath namespaces by using the namespace method.

namespace :comments do
  subscribe :create, :to => CommentController, :with_method => :create
end

This would route events triggered on the JavaScript client like the following:

dispatcher.trigger('comments.create', new_comment_object);

Built In Events

There are three built in events that are fired automatically by the dispatcher. The built in events are :client_connected, :connection_closed, and :client_disconnected. You can handle them however you like by subscribing to the appropriate event in your events.rb file.

# The :client_connected method is fired automatically when a new client connects
subscribe :client_connected, :to => ChatController, :with_method => :client_connected
# The :client_disconnected method is fired automatically when a client disconnects
subscribe :client_disconnected, :to => ChatController, :with_method => :delete_user
# The :connection_closed method is fired automatically when a client loses connection without sending a disconnect frame.
subscribe :connection_closed, :to => ChatController, :with_method => :delete_user

Subscribing Multiple Controllers to a Single Event

You can subscribe multiple controllers and actions to the same event to provide very clean event handling logic. The new message will be available in each controller using the message method discussed in the Controllers wiki page. The example below demonstrates subscribing to the :new_message event with one controller action to rebroadcast the message out to all connected clients and another controller action to log the message to a database.

subscribe :new_message, to: ChatController, with_method: :new_message
subscribe :new_message, to: ChatLogController, with_method: :log_message

Summing it all Up

All together, our completed events.rb file would look like:

# app/config/events.rb

WebsocketRails::EventMap.describe do
  # The :client_connected method is fired automatically when a new client connects
  subscribe :client_connected, to: ChatController, with_method: :client_connected

  # You can subscribe any number of controller actions to a single event
  subscribe :new_message, to: ChatController, with_method: :new_message
  subscribe :new_message, to: ChatLogController, with_method: :log_message

  subscribe :new_user, to: ChatController, with_method: :new_user
  subscribe :change_username, to: ChatController, with_method: :change_username

  namespace :product do
    subscribe :new, to: ProductController, with_method: :new_product
  end

  # The :client_disconnected method is fired automatically when a client disconnects
  subscribe :client_disconnected, to: ChatController, with_method: :delete_user
end