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. The RubyAMF Rails plugin must be installed prior to installing RubyAMF::Quickly

        ./script/plugin install git://github.com/pillowfactory/rubyamf_quickly.git

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.

ActionScript Generator

The action_script 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: ./script/generate action_script org.pillowfactory

On a Rails project with a single ActiveRecord model, Person.rb, and a single controller, PeopleController.rb, 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.

* regenerated every time generator is run

Runtime Assistance

By default, RubyAMF::Quickly adds a couple of helpers to the RubyAMF request cycle.

1. Parameter Filtering - This before_filter merges any remoting request parameters into the standard controller params hash.
2. Default Exception Handling - Using the Rails 2 rescue_from method, any unhandled Exceptions will be converted to a RubyAMF FaultObject that will trigger an ActionScript FaultEvent.

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 Person.rb ActiveRecord class, a PeopleController#create Rails controller/action, and the generated ActionScript classes as described above, the following ActionScript code will save a Person 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 Person.as ActionScript class that corresponds to the ActiveRecord Person.rb with two database attributes: name and favorite_number. The Remote.people.create method streamlines the definition and "caching" of Flex RemoteObjects. The Remote property, "people" corresponds to the name of the Rails controller we’re targeting; PeopleController. 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 person[name] and person[favorite_number]. You’ll want to note the use of myPerson.toParams() when constructing the request "hash." toParams() is defined on the generated PersonBase.as class that returns another anonymous object with the corresponding attributes and values. The request "hash" could have also been defined without using the toParams() method as {person: {name: ‘foo’, favoriteNumber: 7}}, but the toParams() method provides additional functionality. toParams() also accepts an array of properties to exclude. For example, {person: myPerson.toParams(‘name’)} 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 © 2008 Luke Pillow, released under the MIT license