This page applies to an older version of Orbited (Version 0.3) For info on the current version see the main documentation.
Intro to Orbited with Ruby
This tutorial will demonstrate how the Orbited client API interacts with the Orbited daemon. The great thing about Ruby is the interactive shell, and Orbited is no special case. By the end of this tutorial you will have sent real-time events from the interactive Ruby shell to specific browser windows.
Prerequisites
Orbited
This tutorial assumes you have already installed Orbited. If you haven’t then check out the tutorial on Installing Orbited.
JSON
The ruby-orbited client requires the json gem. This demo doesn’t actually deal with JSON, but we still need to satisfy the dependency. You must install Ruby gems first, then you can execute the command gem install json to download and install the json gem.
ruby-orbited
ruby-orbited is a Ruby implementation of the client-side orbit protocol. This Orbited client can be downloaded: ruby-orbited. Right-click on the link and select “save as” to save the file to an empty directory orbitedtest.
Tutorial
First off, we need to start up the Orbited daemon. This can be done by running the command orbited in a console or command window. You should see a note that a configuration file wasn’t found. Orbited looks for the default config file orbited.cfg in the directory where you run the command. You can also specify a config file as the first argument when running the daemon. The console output should look like this (with a few more messages):
orbited.cfg could not be found. Using default configuration 2007-10-20 05:12:45,705 - Router - INFO - register_static, /_/admin_screen/static/, [...] 2007-10-20 05:12:45,774 - OrbitedDaemon - INFO - Listening on port 9000
This indicates that the Orbited daemon is listening for incoming HTTP connections on port 8000 and incoming orbit connections on port 9000. Now open a browser window and visit the URL http://localhost:8000/_/about. This page should display something similar to the following:
Orbited 0.2.0
Python 2.5 (r25:51908, Sep 19 2006, 09:52:17) [MSC v.1310 32 bit (Intel)] on win32
This indicates that you have successfully made contact with the Orbited server. Now point your browser to the URL http://localhost:8000/demo?user=user&session=0&transport=basic. This page will seem to hang and you’ll see a Loading message in your browser’s status. If you visited the URL in a browser window that had a previous page, you may still see the contents of that previous page. Don’t worry though, this is normal behavior.
The next step is to open an interactive Ruby shell by typing the command irb. Make sure you are in the directory orbitedtest before entering the interactive shell.
irb(main):001:0> require "ruby-orbited"
=> true
irb(main):002:0> client = SimpleOrbit::Client.new("localhost", 9000)
=> #<SimpleOrbit::Client:0x2e195a4 @addr="localhost", @connected=false, @socket=
nil, @port=9000, @id=0>
irb(main):003:0> user_key = "user, 0, /demo"
=> "user, 0, /demo"
irb(main):004:0> client.connect()
=> #<TCPSocket:0x2e179e8>
irb(main):005:0> client.event([ user_key ], "Hello from Ruby!<br>", false)
=> "Success\r\nid: 1\r\n\r\n"
The first two lines require the Orbited client API and create a client object. The third line is the user key we use to identify the browser window we want to communicate with. If you recall, we accessed /demo?user=user&session=0&transport=basic This indicates that the location to which we are sending is /demo, the username is user, and the session key is 0. Therefore the unique key identifying that browser window is "user, 0, /demo". The last line is where we actually send the event. The client.event function takes 2 arguments and a third optional argument. The first argument is a list of unique user keys that determine the recipients of the event. The second argument is the event data itself, and the third argument which we specify as false determines wether we wish to encode the data in the JSON format. We want to send raw HTML so we don’t encode the data.
At this point you can try sending events to user keys that you know don’t exist and see what sort of response you get. You can also send events to multiple open browsers simply by including each recipient user key in the first argument to the event function.
Conclusion
Now you have some idea of how orbit works. Granted, most applications will need interaction more complex then raw HTML. The main use case of Orbited is to send data that is interpreted by JavaScript. Then JavaScript can do the appropriate action based on the contents of the event. A good place to go from here is the RailsChat Tutorial. It will show you how to weave Ruby, JavaScript, and Orbited together into a meaningful application.