SWX RUBY

The Ruby implementation of SWX RPC

Beta 0.7

What is SWX?

SWX is the native data format for the Flash Platform.

SWX RPC is a remote procedure call protocol encoded in SWX. It's simple enough that you can get up and running with it in about five minutes. SWX RPC is perfect for building mashups (with easy-to-use APIs for Flickr, Twitter, and others), mobile applications (Flash Lite 2.0 and 2.1), and other data-driven Flash sites and applications.

What is SWX Ruby?

SWX Ruby is the Ruby implementation of SWX RPC. It allows Rubyists to leverage their Ruby skills to build data-driven Flash applications using the wonderfully simple SWX data format. The current beta version assembles AVM1 SWF files (compatible with Flash 8 and below). By its 1.0 release, SWX Ruby will also assemble AVM2 SWF files.

The SWX Ruby silent movie demonstrates the use of service classes in a Rails app; it is also possible to use SWX Ruby directly in your Rails controllers. See usage for further explanation.

Hello World in Three Steps

Service Class
ActionScript Code
Make a Sandwich?

Features

Performance: SWX Ruby is Ruby's fastest library for exchanging data with Flash
Simplicity: Less than 400 lines of the world's most endearing language
Dependability: 100% RSpec coverage of core classes

To Do

Documentation! Check out the RDOCs
Support for SWX Service Explorer
Third party APIs (Flickr, Jaiku, Twitter, etc.)—anyone wanna pitch in?
render :swx => @foo (Rails controller integration) Blog Post
Caching support (C10K for SWX data anyone?)
Flash 9 bytecode assembler
Offer as a Ruby Gem as well

Get It

See the RDOCs for up-to-date installation instructions.

Rails Usage (Gem usage is covered in the RDOCs)

To get started, you first need to install the SWX Ruby Rails plugin in your rails app (see the RDOCs for installation instructions). The plugin’s install script will create the following for you:

An app/services folder
A couple example service classes in the services folder
A config file at config/swx.yml
The SWX Gateway controller
A route in routes.rb to route requests to ’/swx’ to the SWX Gateway controller

Once the plugin is installed, you’re ready to start building SWX capability into your Rails application.

The SWX Ruby Rails plugin can integrate with a Rails application in two ways:

Service classes that (by default) reside in app/services
Rails controllers (render :swx => ‘my data’)

A developer may use one or both of these methods depending on the needs of the application. Continue reading for a basic explanation of each method.

Note: The ActionScript demonstrated in the following examples uses the native loadMovie method to retrieve SWX data. For a more robust API, check out the SWX ActionScript Library.

Method 1: Using Service Classes

Service classes reside in app/services. Service classes can be moved to a different location by changing services_path in the config/swx.yml file (generated by the plugin installer).

Service classes are usually vanilla Ruby classes. The SWX Ruby gateway instantiates these classes and exposes their public instance methods. The return value of an instance method (array, string, integer, hash, etc.) will be returned to Flash.

Here is an example of a basic SWX service class (app/services/hello_world.rb):

          class HelloWorld
            def just_say_the_words
              'Hello World!'
            end
          end

And the ActionScript necessary to connect to it (assumes a MovieClip on stage with instance name 'loader'):

          loader.serviceClass = "HelloWorld";
          loader.method = "justSayTheWords";
          loader.debug = true;
          loader.loadMovie("http://localhost:3000/swx", "POST");
          
          function onEnterFrame() {
           trace(loader.result);
          }

Gotcha
Notice that the method name is underscored (just_say_the_words) in the service class but camel-cased (justSayTheWords) in the ActionScript snippet. The SWX Ruby gateway performs the conversion automatically, allowing us to follow ActionScript convention in our ActionScript and Ruby convention in our service classes. It is therefore not possible to call a camel-cased method on a service class.

Gotcha

For security purposes, SWX service classes are stuffed inside of the SwxServiceClasses namespace. So the location of the HelloWorld service class would be SwxServiceClasses::HelloWorld. This could bite you if you try to do any core extensions inside of your service classes.

Let’s say you wanted to extend Array from within your service class file (app/services/hello_world.rb):
            class HelloWorld
              def just_say_the_words
                'Hello World!'
              end
            
              # ... other methods ...
            end
            
            class Array
              def empty?
                # implementation
              end
            end
          
This code would actually be defining the class SwxServiceClasses::Array not reopening Ruby's inbuilt Array class. But this is easily worked around by using #class_eval:
            class HelloWorld
              def just_say_the_words
                'Hello World!'
              end
            
              # ... other methods ...
            end
            
            Array.class_eval do
              def empty?
                # implementation
              end
            end
          
Since the Array class is not found in the SwxServiceClasses namespace, the call to #class_eval walks up the object tree until Ruby's Array class is located.

Method 2: Rails Controller Integration

Simply call render :swx => 'my swx data' from a Rails controller and SWX Ruby will send back a SWX file containing 'my swx data'.

The SWX Ruby Rails plugin also registers a MIME type for SWX files. This enables you to serve up your SWX data in RESTful style:

          # in config/routes.rb
          ActionController::Routing::Routes.draw do |map|
            map.connect '/restful.:format', :controller => 'Restful'
            map.connect '/restful', :controller => 'Restful'
          end
          
          # in app/controllers/restful_controller.rb
          class RestfulController  
            def index
              respond_to do |format|
                format.html { render :text => 'not a swx request' }
                format.swx  { render :swx => 'a swx request' }
              end
            end
          end

With the preceding code in your app, pull up http://localhost:3000/restful in a browser. You'll see 'not a swx request'. Then open Flash, place an empty MovieClip on stage with an instance name of 'loader', and place the following ActionScript in frame 1:

          loader.loadMovie("http://localhost:3000/restful.swx", "GET");
          
          function onEnterFrame() {
           trace(loader.result);
          }

Preview the Flash movie and the Output panel will begin tracing 'a swx request'.