= RubyAMF::Quickly
 
The RubyAMF::Quickly plugin is intended to jump start any Flex on Rails project using RubyAMF.  

RubyAMF::Quickly has the following features:
 
* ActionScript Generator
 
* Runtime Assistance

== Installation

Install as Rails plugin. <em>The {RubyAMF Rails plugin}[http://rubyamf.googlecode.com] must be installed prior to 
installing RubyAMF::Quickly</em>

  ./script/plugin install git://github.com/pillowfactory/rubyamf_quickly.git 
  
<em>NOTE: The RubyAMF::Quickly plugin installation appends it's own configuration settings to the 
config/rubyamf_config.rb file.
The plugin's configuration defaults it's settings for the most natural Rails and Flex development as well as overrides
some of the default RubyAMF settings.  
All examples and following explanation are given using the RubyAMF::Quickly default configuration.</em>

== ActionScript Generator

The <tt>action_script</tt> generator creates both ActionScript models from the project's ActiveRecord models AND 
ActionScript remoting classes that correspond to the Rails controller classes.

Running the command: <tt>./script/generate action_script org.pillowfactory</tt>

On a Rails project with a single ActiveRecord model, <tt>Person.rb</tt>, and a single controller, 
<tt>PeopleController.rb</tt>, the following ActionScript classes will be generated:   

=== Model Classes
  RAILS_ROOT/app/flex/src/
    org/pillowfactory/models/Person.as                       => Add custom model behavior/properties here.
    org/pillowfactory/models/base/PersonBase.as*             => Contains properties and model helper methods.
    org/pillowfactory/models/base/Base.as                    => Superclass to all generated models.
    org/pillowfactory/models/helpers/Errors.as               => Implementation of the ActiveRecord Errors class.
    org/pillowfactory/models/helpers/Hash.as                 => Dynamic class with Ruby Hash-like methods.
      
=== Remoting Classes
  RAILS_ROOT/app/flex/src/
    org/pillowfactory/remoting/api/RemotePeople.as           => Add custom remote access methods here.
    org/pillowfactory/remoting/api/base/RemotePeopleBase.as* => Contains methods that correspond to PeopleController 
    actions.
    org/pillowfactory/remoting/api/base/RemoteBase.as        => Superclass for all Remote* classes.
    org/pillowfactory/remoting/Remote.as*                    => Provides static access to all remoting class methods.
    org/pillowfactory/remoting/helpers/RubyAMF.as            => Simple remoting helper for Rails controller/action 
    invocation.
  
<em>* regenerated every time generator is run</em>
      
== Runtime Assistance
    
By default, RubyAMF::Quickly adds a couple of helpers to the RubyAMF request cycle.
        
1. Parameter Filtering - This <tt>before_filter</tt> merges any remoting request parameters into the standard controller 
params hash.
2. Default Exception Handling -  Using the Rails 2 <tt>rescue_from</tt> method, any unhandled Exceptions will be 
converted to a RubyAMF <tt>FaultObject</tt> that will trigger an ActionScript <tt>FaultEvent</tt>.
    

== Quickly Concepts

The main idea behind RubyAMF::Quickly is to keep with the simplicity of Rails RESTful theme while maintaining a natural 
Flex development environment.  The core RubyAMF project allows bidirectional object graph messaging.  This method works, 
but is not conducive to reuse of existing Rails controller logic without "cluttering" things up with is_amf conditional 
logic. Again... this works, but is not the Rails way.  

RubyAMF::Quickly encourages a slightly different approach:  Send HTTP hash-like requests from Flex.  Let Rails respond 
to AMF requests with ActiveRecord object graphs.


== Example

Given a <tt>Person.rb</tt> ActiveRecord class, a <tt>PeopleController#create</tt> Rails controller/action, and the 
generated ActionScript classes as described above, the following ActionScript code will save a <tt>Person</tt> to the 
database.

  var myPerson:Person = new Person();
  myPerson.name = 'Foo';
  myPerson.favoriteNumber = 7;
  
  Remote.people.create({person: myPerson.toParams()}, myPersonResultHandler, myPersonFaultHandler)
  
This example uses the generated <tt>Person.as</tt> ActionScript class that corresponds to the ActiveRecord 
<tt>Person.rb</tt> with two database attributes: <tt>name</tt> and <tt>favorite_number</tt>.  The 
<tt>Remote.people.create</tt> method streamlines the definition and "caching" of Flex RemoteObjects.  The Remote 
property, "people" corresponds to the name of the Rails controller we're targeting; <tt>PeopleController</tt>.  The 
"create" method of "people" is the controller action to invoke.  Remote remoting action methods accept three parameters. 
 The first parameter is an anonymous object that serves as the hash-like "wrapper" that the parameters will be sent in.  
This is the equivalent of a standard HTML form input names of <tt>person[name]</tt> and 
<tt>person[favorite_number]</tt>.  You'll want to note the use of <tt>myPerson.toParams()</tt> when constructing the 
request "hash."  <tt>toParams()</tt> is defined on the generated <tt>PersonBase.as</tt> class that returns another 
anonymous object with the corresponding attributes and values.  The request "hash" could have also been defined without 
using the <tt>toParams()</tt> method as <tt>{person: {name: 'foo', favoriteNumber: 7}}</tt>, but the <tt>toParams()</tt> 
method provides additional functionality.  <tt>toParams()</tt> also accepts an array of properties to exclude.  For 
example, <tt>{person: myPerson.toParams('name')}</tt> would not include the name property and value in the request. The 
second and third parameters are the result and fault handlers to be called upon completion of the remoting request.


== More Documentation

The RubyAMF::Quickly::Config section that was appended to rubyamf_config.rb file has more documentation for 
configuration options supported by RubyAMF::Quickly.


Copyright (c) 2008 Luke Pillow, released under the MIT license