= SWX Ruby 0.7

Primary Repo: http://github.com/meekish/swxruby

=== What is SWX?

SWX is the native data format for the Flash Platform.

SWX RPC is a remote procedure call protocol encoded in SWX and a viable alternative to XML and Flash Remoting. 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. Official web site at http://swxformat.org

=== 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. Official web site at http://swxruby.org

=== Installation

==== Gem

gem install swxruby

  Note: The SWX Ruby gem declares 'json_pure' as a dependency. json_pure
  is the pure Ruby variant of the JSON gem. If you have a C compiler and 
  would like better performance then do 'gem install json'

==== Rails plugin

After installing the gem, do:

  swxruby --rails PATH_TO_ROOT_OF_YOUR_RAILS_APP

This will unpack a plugin into your Rails app. For further explanation of the files installed, see 'Rails Usage' below.

<b>Living on the Edge:</b> The Rails init script (init.rb) sits in the root of the SWX Ruby tree, thus you can simply throw the git HEAD into vendor/plugins/swxruby to run the plugin on edge.

  git clone git://github.com/meekish/swxruby.git vendor/plugins/swxruby
  ruby vendor/plugins/swxruby/install.rb

=== Gem Usage (For Merb, Camping, Sinatra, et al.)

Require the SWX Ruby gem

  require 'rubygems'
  require 'swxruby'

Define a service class in the SwxServiceClasses namespace

  module SwxServiceClasses
    class Simple
      def echo_data(data)
        data
      end
    end
  end
  
Start making calls to SwxGateway#process

  @swx_bytecode = SwxGateway.process(:serviceClass => 'Simple', :method => 'echo_data', :args => 'Hello World!', :debug => true)
  # => Returns a binary string of SWX bytecode containing the result of SwxServiceClasses::Simple.new.echo_data('Hello World!')
  
Use your framework's preferred method to wrap the swx bytecode in a file shell and send it on its way. Here's how Rails and Merb do it:

  send_data(@swx_bytecode, :filename => 'data.swf', :type => 'application/swf', :disposition => 'inline')
  
==== Example of Gem Usage

Here's a full Merb app (this and a Flash client are included in examples/standalone/)  

  # standalone.rb
  
  require 'rubygems'
  require 'swxruby'

  # Service Class
  class SwxServiceClasses::HelloMerb
    def just_say_the_words
      'Hello from Merb!'
    end
  end

  # Merb Application
  Merb::Router.prepare { |r| r.match('/').to(:controller => 'swx_ruby', :action =>'gateway') }

  class SwxRuby < Merb::Controller
    def gateway
      send_data(SwxGateway.process(params), :filename => 'data.swf', :type => 'application/swf', :disposition => 'inline')
    end
  end
  
  # Fire it up with 'merb -I standalone.rb' and you're off!
  
=== Rails Plugin Usage

When running as a Rails plugin, SWX Ruby will look for your service classes in
RAILS_ROOT/app/services. Simply create standard Ruby classes and drop them
in this folder. SWX Ruby will instantiate your service class (while forcing
it into the SwxServiceClasses namespace), call the specified method, and
send the response back to the Flash Player.

Take a peek at services/hello_world.rb for a working service class example.
Alright, alright, I'll just show it to you here:

  # hello_world.rb----------------------------------------
  # Class and method names follow standard Ruby convention
  class HelloWorld
  	# Service class methods are instance methods.
  	def just_say_the_words
  		'Hello World!'
  	end
  end
  #-------------------------------------------------------

Here's an example to call HelloWorld#just_say_the_words from Flash 
(place a MovieClip on stage with an instance name of 'loader' and
fire up your Rails development server):

  //------------------------------------------------------
  loader.serviceClass = "HelloWorld";
  // Method names follow ActionScript convention 
  // (converted to underscored server-side)
  loader.method = "justSayTheWords";
  loader.debug = true;
  loader.loadMovie("http://localhost:3000/swx", "POST");

  function onEnterFrame() {
   // Will output 'Hello World!' once the SWX file is loaded.
   trace(loader.result);
  }
  //------------------------------------------------------

When you're ready for some robust ActionScriptery, head to 
http://swxformat.org/download to grab the SWX ActionScript library.

Oh yeah, you may return ActiveRecord objects from your service classes; 
SWX Ruby will happily serialize them for you. Go ahead, give it a try!

NOTE: You may notice some Security Sandbox Violations when testing the example
above in the Flash IDE. Rest assured, this is OK. Visit 
http://swxformat.org/132 for further explanation.

=== Get In Touch

Please post bug reports/suggestions to http://groups.google.com/group/swxruby