> cd rubyamf
rubyamf> ruby script/plugin install http://rubyamf.googlecode.com/svn/trunk/rubyamf

> mysql -u root -p
Enter password:
mysql> create database rubyamf;

development:
 adapter: mysql
 endocing: utf8
 database: rubyamf
 username: root
 password: yourpassword
 host: localhost

Making Sure it all Works

We're basically finished with rails for now. But before we call it good lets just make sure that it is running smoothly (and so we can look in awe of what we just did).

Boot up your rails server:

Now open up your favorite browser and make sure that RubyAMF is running by going to http://localhost:3000/rubyamf/gateway. You should see something like the following image.

If you do not get the above image and instead get prompted to download an AMF file you need to edit the app/controllers/rubyamf_controller.rb file. Open it up and change:

amf_response = if request.env['CONTENT_TYPE'].to_s.match(/x-amf/) 
    headers['Content-Type'] = "application/x-amf"
    RailsGateway.new.service(request.raw_post) #send the raw data throught the rubyamf gateway and create the response
  else 
    welcome_screen_html # load in some stub html
  end
send_data(amf_response, :type => 'application/x-amf')

To:

amf_response = if request.env['CONTENT_TYPE'].to_s.match(/x-amf/) 
    content_type  = "application/x-amf"
    RailsGateway.new.service(request.raw_post) #send the raw data throught the rubyamf gateway and create the response
  else 
    content_type = "text/html"
   welcome_screen_html # load in some stub html
  end
send_data(amf_response, :type => content_type, :disposition=>'inline')

Note: If you use the rubyamf controller fix suggested on the RAMF blog it will brake your application (thanks goes to Quest4 for figuring this one out). The above code is not official so use it at your own risk.

Now make sure our Messages controller is working by pointing your browser to http://localhost:3000/messages and witnessing this:

So far so good. Now what we need to do is to add some data into the database so our Flex app has something to retrieve. Lets do that by clicking the "New Message" link at http://localhost:3000/messages, typing a short message (this tutorial uses "Hello World"), and press the "Create" button. *Bam* you just added a new Message to the database.

Enough of Rails, lets dive into Flex

Flex

Setting up the Flex Project

Boot up Adobe Flex and create a new project. I named mine rubyamf for consistency but you could name it something else (like planctomyces). Click the "Next" button, not the "Finish" button. Set the output folder to the "bin" dir (you'll probably have to create this) in the "public" dir of your rails project. That is, \rubyamf\public\bin. Press "Next." Now make sure that your output folder URL is set to: http://localhost:3000/bin. Press "Finish." You now have a shiny new Flex project.

Adding services-config.xml

We need to create an XML file that will point your Flex project in the direction of your Rails project. This is called the "services-config.xml" file and it needs to be placed in the same folder as your MXML file. Create a new file via File > New > File and name it "services-config.xml"

Now for the code. Open up "services-config.xml" and add this code:

<?xml version="1.0" encoding="UTF-8"?>
 <services-config>
  <services>
   <service id="rubyamf-flashremoting-service" class="flex.messaging.services.RemotingService" messageTypes="flex.messaging.messages.RemotingMessage">
    <destination id="rubyamf">
     <channels>
      <channel ref="rubyamf"/>
     </channels>
     <properties>
      <source>*</source>
     </properties>
    </destination>
   </service>
  </services>
  <channels>
   <channel-definition id="rubyamf" class="mx.messaging.channels.AMFChannel">
    <endpoint uri="http://localhost:3000/rubyamf/gateway" class="flex.messaging.endpoints.AMFEndpoint"/>
   </channel-definition>
  </channels>
 </services-config>

Now we tell Flex to include "services-config.xml" when it compiles the application. To do this we need to add a command to the flex compiler. Do this by Project > Properties > Flex Compiler and adding -services "services-config.xml" to the "Additional compiler arguments" field.

Creating the UI

Now the fun part. Here's the Flex UI code to paste into the MXML file:

<?xml version="1.0" encoding="utf-8"?>
 <mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" layout="vertical">
  <mx:TextArea id="resultTxt"
   width="80%" height="30%" />
  <mx:Button id="getMessage"
   label="Get Messages" />
  <mx:TextArea id="createTxt"
   width="80%" height="30%" />
  <mx:Button id="createMessage"
   label="Create Message" />
 </mx:Application>

The above should look something like this:

The above is pretty and all but it's like a mannequin; looks good but it has no function. Lets give it a purpose and turn it into a real live lady. We'll do this by adding the RemoteObject code.

Between the <mx:Application> and <mx:TextArea /> tags add this:

 <mx:Script>
  <![CDATA[
   import mx.rpc.events.ResultEvent;
   import mx.rpc.events.FaultEvent;
   import mx.rpc.Fault;

   private function onFault(e:FaultEvent):void
   {
    resultTxt.text = e.fault.faultString;
   }
   private function onResult(e:ResultEvent):void
   {
    resultTxt.text = e.message.toString();
   }
  ]]>
 </mx:Script>
 
 <mx:RemoteObject id="messageService" fault="onFault(event)" 
  source="MessagesController" destination="rubyamf">
  <mx:method name="index" result="onResult(event)" />
  <mx:method name="create" result="onResult(event)" />
 </mx:RemoteObject>

• RemoteObject is where the magic occurs. This particular instance we chose to call id="messageService"
• source="MessagesController" is the name of the rails controller we want to communicate with. The actual name needs to be exactly the same as the ruby class name (open up app/controllers/messages_controller.rb)
• destination="rubyamf" maps to the channel-definition in the services-config.xml file we created earlier (which then points Flex to the rubyamf remoting endpoint).
• The two <mx:method /> tags map to two of the methods in the MessagesController class.

To call our methods we'll update the "click" event handlers of the two buttons in our UI. Add click="messageService.index.send();" to the "getMessage" button and click="messageService.create.send({text: createTxt.text});" to the "createMessage" button.

 <mx:Button id="getMessage"
  label="Get Messages"
  click="messageService.index.send();" />
  
 <mx:Button id="createMessage"
  label="Create Message" 
  click="messageService.create.send({text: createTxt.text});" />

Back to Rails

Tweaking messages_controller.rb

We're almost finished. All we have to do now is explain to our rails controller about AMF. We'll be polite and speak it's native language; ruby. Open up app/controllers/messages_controller.rb and add "format.amf { render :amf => @messages }" to the respond_to block of the index method.

 def index
     @messages = Message.find(:all)

     respond_to do |format|
       format.html # index.rhtml
       format.xml  { render :xml => @messages.to_xml }
       format.amf { render :amf => @messages }
     end
 end

The respond_to block tells our controller to act differently when different mediums are attempting to work with it. If a browser calls the index method the controller will spit out HTML but now if the Flash Player requests something the controller will spit out AMF. Perfect!

Updating the create method is a bit trickier. We add an if statement to check if AMF was sent, and if so, do some tricky stuff.

 def create
  if is_amf
   @message = Message.new({:text => params[0][:text]})
  else
   @message = Message.new(params[:message])
  end
 ...

Note: params[0][:text] was suggested by Peter Armstrong - thanks!

Then we add some code to the respond_to block that tells the controller to speak AMF if it's talking to the flash player.

 ...
  respond_to do |format|
    if @message.save
         flash[:notice] = 'Message was successfully created.'
         format.html { redirect_to message_url(@message) }
         format.xml  { head :created, :location => message_url(@message) }
   format.amf  { render :amf => "Message Saved" }
       else
         format.html { render :action => "new" }
         format.xml  { render :xml => @message.errors.to_xml }
   format.amf  { render :amf => @message.errors }
       end
     end
   end

Whew! That's it. We can test the app now.

Testing... (in awe)

First we need to start our server (or restart it).

Compile and run your Flex project. It should be running from the URL "http://localhost:3000/bin/rubyamf.html." Click on "Get Messages" and you should see something like this:

Type a message into the second text area ("We received data from RubyAMF, can we send data to it?"). Press the button and you should see:

Finished!

Yee-haw! By using the powers of RubyAMF we have just grabbed data from a database and written some right back at speeds much faster than XML or JSON. Plus, we still get a HTML front end for those types that fear flash.

Labels: actionscript 3.0, flex, programming, rubyamf, tutorial