params.json

{"note":"Don't delete this file! It's used internally to help with page regeneration.","google":"UA-27751069-2","name":"websocket-rails","tagline":"Plug and play WebSocket support for ruby on rails.","body":"# Websocket-Rails\r\n\r\n[![Build Status](https://secure.travis-ci.org/DanKnox/websocket-rails.png)](https://secure.travis-ci.org/DanKnox/websocket-rails)\r\n\r\n**Now with streaming HTTP support for improved browser compatibility**\r\n\r\n## The Present\r\n\r\nStart treating client side events as first class citizens inside your Rails application with a built in WebSocket server. Sure, WebSockets aren't quite universal yet. That's why we also support streaming HTTP. Oh, and if you don't mind running a separate process, you can support just about any browser through Flash sockets without changing a line of code.\r\n\r\n## The Future\r\n\r\nThe long term goal for this project is simple. Reduce the need to move application logic on to the client while still providing the same level of interaction and responsiveness users have grown to expect from a modern web application. We hope to isolate the responsibility of JavaScript to the presentation layer and keep business logic nicely organized on the server.\r\n\r\n## Installation and Usage Guides\r\n\r\nCheck out the [Example Application](https://github.com/DanKnox/websocket-rails-Example-Project) for an example implementation.\r\n\r\n* [Installation\r\n  Guide](https://github.com/DanKnox/websocket-rails/wiki/Installation-and-Setup)\r\n* [Event\r\n  Router](https://github.com/DanKnox/websocket-rails/wiki/The-Event-Router)\r\n* [WebsocketRails Controllers](https://github.com/DanKnox/websocket-rails/wiki/WebsocketRails Controllers)\r\n* [Using the JavaScript\r\n  Client](https://github.com/DanKnox/websocket-rails/wiki/Using-the-JavaScript-Client)\r\n* [Using\r\n  Channels](https://github.com/DanKnox/websocket-rails/wiki/Working-with-Channels)\r\n* [The\r\n  DataStore](https://github.com/DanKnox/websocket-rails/wiki/Using-the-DataStore)\r\n* [Multiple Servers and Background Jobs](https://github.com/DanKnox/websocket-rails/wiki/Multiple-Servers-and-Background-Jobs)\r\n* [Standalone Server Mode](https://github.com/DanKnox/websocket-rails/wiki/Standalone-Server-Mode)\r\n\r\n## A Brief Tour\r\n\r\nMap events to controller actions using an Event Router.\r\n\r\n````ruby\r\nWebsocketRails::EventMap.describe do\r\n  namespace :tasks do\r\n    subscribe :create, :to => TaskController, :with_method => :create\r\n  end\r\nend\r\n````\r\n\r\nTrigger events using our JavaScript client.\r\n\r\n````javascript\r\nvar task = {\r\n  name: 'Start taking advantage of WebSockets',\r\n  completed: false\r\n}\r\n\r\nvar dispatcher = new WebSocketRails('localhost:3000/websocket');\r\n\r\ndispatcher.trigger('tasks.create', task);\r\n````\r\n\r\nHandle events in your controller.\r\n\r\n````ruby\r\nclass TaskController < WebsocketRails::BaseController\r\n  def create\r\n    # The `message` method contains the data received\r\n    task = Task.new message\r\n    if task.save\r\n      send_message :create_success, task, :namespace => :tasks\r\n    else\r\n      send_message :create_fail, task, :namespace => :tasks\r\n    end\r\n  end\r\nend\r\n````\r\n\r\nReceive the response in the client.\r\n\r\n````javascript\r\ndispatcher.bind('tasks.create_successful', function(task) {\r\n  console.log('successfully created ' + task.name);\r\n});\r\n````\r\n\r\nOr just attach success and failure callbacks to your client events.\r\n\r\n````javascript\r\nvar success = function(task) { console.log(\"Created: \" + task.name); }\r\n\r\nvar failure = function(task) {\r\n  console.log(\"Failed to create Product: \" + product.name)\r\n}\r\n\r\ndispatcher.trigger('products.create', success, failure);\r\n````\r\n\r\nThen trigger them in your controller:\r\n\r\n````ruby\r\ndef create\r\n  task = Task.create message\r\n  if task.save\r\n    trigger_success task\r\n  else\r\n    trigger_failure task\r\n  end\r\nend\r\n````\r\n\r\nIf you're feeling truly lazy, just trigger the failure callback with an\r\nexception.\r\n\r\n````ruby\r\ndef create\r\n  task = Task.create! message\r\n  trigger_success task # trigger success if the save went alright\r\nend\r\n````\r\n\r\nThat controller is starting to look pretty clean.\r\n\r\nNow in the failure callback on the client we have access to the record\r\nand the errors.\r\n\r\n````javascript\r\nvar failureCallback = function(task) {\r\n  console.log( task.name );\r\n  console.log( task.errors );\r\n  console.log( \"You have \" + task.errors.length + \" errors.\" );\r\n}\r\n````\r\n\r\n## Channel Support\r\n\r\nKeep your users up to date without waiting for them to refresh the page.\r\nSubscribe them to a channel and update it from wherever you please.\r\n\r\nTune in on the client side.\r\n\r\n````javascript\r\nchannel = dispatcher.subscribe('posts');\r\nchannel.bind('new', function(post) {\r\n  console.log('a new post about '+post.title+' arrived!');\r\n});\r\n````\r\n\r\nBroadcast to the channel from anywhere inside your Rails application. An\r\nexisting controller, a model, a background job, or a new WebsocketRails\r\ncontroller.\r\n\r\n````ruby\r\nlatest_post = Post.latest\r\nWebsocketRails[:posts].trigger 'new', latest_post\r\n````\r\n\r\n## Private Channel Support\r\n\r\nNeed to restrict access to a particular channel? No problem. We've got\r\nthat. \r\n\r\nPrivate channels give you the ability to authorize a user's\r\nsubscription using the authorization mechanism of your choice.\r\n\r\nJust tell WebsocketRails which channels you would like to make private and how you want to handle channel authorization in the\r\nevent router by subscribing to the `websocket_rails.subscribe_private`\r\nevent.\r\n\r\n````ruby\r\nWebsocketRails::EventMap.describe do\r\n  private_channel :secret_posts\r\n  \r\n  namespace :websocket_rails\r\n    subscribe :subscribe_private, :to => AuthenticationController, :with_method => :authorize_channels\r\n  end\r\n```` \r\n\r\nOr you can always mark any channel as private later on.\r\n\r\n````ruby\r\nWebsocketRails[:secret_posts].make_private\r\n````\r\n\r\nOn the client side, you can use the `dispatcher.subscribe_private()`\r\nmethod to subscribe to a private channel.\r\n\r\nRead the [Private Channel Wiki](https://github.com/DanKnox/websocket-rails/wiki/Using-Private-Channels) for more information on dealing with\r\nprivate channels.\r\n\r\n## Development\r\n\r\nThis gem is created and maintained by Dan Knox and Kyle Whalen under the MIT License.\r\n\r\nBrought to you by:\r\n\r\nThree Dot Loft LLC"}