dima-ruboss4ruby 1.1.0 → 1.1.1

data/generators/ruboss_yaml_scaffold/ruboss_yaml_scaffold_generator.rb

@@ -29,15 +29,19 @@ class RubossYamlScaffoldGenerator < RubiGen::Base
         end
         line = model[0].camelcase + " " + line
         puts 'running: ruboss_scaffold ' + line
-        RubiGen::Scripts::Generate.new.run(["ruboss_scaffold"] + line.split)
+        RubiGen::Scripts::Generate.new.run(line.split, :generator => 'ruboss_scaffold', 
+          :gae => options[:gae])
         puts 'done ...'
       end
-      RubiGen::Scripts::Generate.new.run(["ruboss_main_app"])
+      RubiGen::Scripts::Generate.new.run([], :generator => 'ruboss_main_app', :gae => options[:gae])
     end
   end
 
   protected
-  def banner
-    "Usage: #{$0} #{spec.name}" 
+  def add_options!(opt)
+    opt.separator ''
+    opt.separator 'Options:'
+    opt.on("--gae", "Generate Google App Engine Python classes in addition to Ruboss Flex resources.", 
+      "Default: false") { |v| options[:gae] = v }
   end
 end

data/lib/ruboss4ruby.rb

@@ -1,8 +1,12 @@
+# Sets up all the relevant configuration options and brings together 
+# patches for Rails, Merb, ActiveRecord and Data Mapper.
+#
+# Loads Ruboss specific rake tasks if appropriate.
 module Ruboss4Ruby
 
   # :stopdoc:
-  VERSION = '1.1.0'
-  RUBOSS_FRAMEWORK_VERSION = '1.1.0'
+  VERSION = '1.1.1'
+  RUBOSS_FRAMEWORK_VERSION = '1.1.1'
   LIB_DIR = File.join(File.dirname(__FILE__), 'ruboss4ruby/')
   # :startdoc:
 
@@ -54,7 +58,10 @@ elsif defined?(ActionController::Base)
 
   ActionView::Base.send :include, SWFHelper unless ActionView::Base.included_modules.include?(SWFHelper)  
 
+  # We mess with default +render+ implementation a bit to add support for expressions
+  # such as format.fxml { render :fxml => @foo }
   module ActionController
+    # Override render to add support for render :fxml
     class Base
       alias_method :old_render, :render unless method_defined?(:old_render)
 
@@ -72,6 +79,8 @@ elsif defined?(ActionController::Base)
     end
   end
 
+  # It is possible to pass metadata with any Ruboss model. This module adds support for
+  # extracting that metadata into the standard params hash.
   module Ruboss4RubyController
     private
 
@@ -89,7 +98,11 @@ elsif defined?(ActionController::Base)
   end
   
   module ActiveRecord
+    # ActiveRecord named scopes are computed *before* ruboss4ruby gem gets loaded
+    # this patch addresses that and makes sure +to_fxml+ calls are properly
+    # delegated
     module NamedScope
+      # make sure we properly delegate +to_fxml+ calls to the proxy
       class Scope
         delegate :to_fxml, :to => :proxy_found
       end

data/lib/ruboss4ruby/active_foo.rb

@@ -1,4 +1,15 @@
-#ActiveRecord+ActiveSupport specific patches
+# There's a number of things that ActiveRecord/ActiveSupport and the rest of the family get
+# ~wrong~ from the point of view of Flex clients.
+#
+# Some of these things are:
+# * Date formats
+# * XML format (Flex *really* doesn't like dashes in XML messages)
+# * Errors (we need to be more specific and communicate what went wrong *where*) 
+#
+# This is where we try to fix this stuff.
+#
+# Some of the things that are done can be called _monkey_ _patching_ while others can
+# be called extensions. Caveat emptor.
 
 # Flex friendly date, datetime formats
 ActiveSupport::CoreExtensions::Date::Conversions::DATE_FORMATS.merge!(:flex_date => "%Y/%m/%d")
@@ -7,10 +18,17 @@ ActiveSupport::CoreExtensions::Time::Conversions::DATE_FORMATS.merge!(:flex_date
 Hash::XML_FORMATTING['date'] = Proc.new { |date| date.to_s(:flex_date) }
 Hash::XML_FORMATTING['datetime'] = Proc.new { |datetime| datetime.to_s(:flex_datetime) }
 
+# ActiveSupport specific patches. More specifically we add +to_fxml+ methods to Array and
+# Hash conversion modules
 module ActiveSupport
+  # refer to: http://api.rubyonrails.org/ for more details
   module CoreExtensions
+    # Add Flex friendly +to_fxml+ to Hash conversions
     module Hash
+      # refer to: http://api.rubyonrails.org/ for more details
       module Conversions
+        
+        # Flex friendly XML format, no dashes, etc
         def to_fxml(options = {})
           options.merge!(:dasherize => false)
           options[:indent] ||= 2
@@ -65,8 +83,11 @@ module ActiveSupport
         end
       end
     end
+    # Add Flex friendly to_fxml to array conversions
     module Array
+      # refer to: http://api.rubyonrails.org/ for more details
       module Conversions
+        # Flex friendly XML format (no dashes, etc)
         def to_fxml(options = {})
           raise "Not all elements respond to to_fxml" unless all? { |e| e.respond_to? :to_fxml }
 
@@ -102,9 +123,13 @@ module ActiveSupport
   end
 end
 
+# Flex friendly ActiveRecord patches. More specifically XML serialization improvements.
+# These won't override whatever you may normally do with XML, hence there's Flex specific
+# name for this stuff +to_fxml+.
 module ActiveRecord
-  # Flex friendly XML serialization patches
+  # refer to: http://api.rubyonrails.org/ for more details
   module Serialization
+    # Enforces Flex friendly options on XML and delegates processing to standard +to_xml+
     def to_fxml(options = {}, &block)
       options.merge!(:dasherize => false)
       default_except = [:crypted_password, :salt, :remember_token, :remember_token_expires_at]
@@ -116,14 +141,17 @@ module ActiveRecord
   # Change the xml serializer so that '?'s are stripped from attribute names.
   # This makes it possible to serialize methods that end in a question mark, like 'valid?' or 'is_true?'
   class XmlSerializer
+    # Strips '?' from serialized method names
     def add_tag(attribute)
       builder.tag!(
         dasherize? ? attribute.display_name.dasherize : attribute.display_name,
         attribute.value.to_s,
         attribute.decorations(!options[:skip_types])
       )
-    end    
+    end
+    # Strips '?' from serialized method names
     class Attribute
+      # Strips '?' from serialized method names
       def display_name
         @name.gsub('?','')
       end
@@ -133,6 +161,7 @@ module ActiveRecord
   # Add more extensive reporting on errors including field name along with a message
   # when errors are serialized to XML
   class Errors
+    # Flex friendly errors
     def to_fxml(options={})
       options[:root] ||= "errors"
       options[:indent] ||= 2

data/lib/ruboss4ruby/active_record_default_methods.rb

@@ -1,8 +1,21 @@
 module ActiveRecord
-  
+  #
+  # We also add support for serializing model methods along the lines of:
+  #
+  #   class Project < ActiveRecord::Base
+  #     default_methods :foobar
+  #
+  #     def foobar
+  #       'foobar'
+  #     end
+  #   end
+  #
+  # When you do +to_fxml+ on this model method foobar will be automatically
+  # serialized as a simple attribute
   class Base
     class << self
             
+      # default methods hook
       def default_methods(*args)
         methods = *args.dup
         module_eval <<-END 
@@ -11,7 +24,8 @@ module ActiveRecord
             end
           END
       end
-            
+      
+      # default methods hook
       def defaults_hash(already_included = [], ignore_default_methods = nil)
         defaults_hash = {:include => {}}
         unless ignore_default_methods
@@ -19,17 +33,17 @@ module ActiveRecord
         end
         defaults_hash
       end 
-
     end
-  
   end    
   
+  # Flex-friendly serialization patches
   module Serialization
     
     alias_method :xml_defaults_old_to_xml, :to_xml unless method_defined?(:xml_defaults_old_to_xml)
     
     alias_method :json_defaults_old_to_json, :to_json unless method_defined?(:json_defaults_old_to_json)
     
+    # adds support for default_methods to standard +to_xml+
     def to_xml(options = {}, &block)
       unless options[:ignore_defaults]
         unless options[:ignore_default_methods]
@@ -39,6 +53,7 @@ module ActiveRecord
       xml_defaults_old_to_xml(options, &block)
     end
     
+    # adds support for default_methods to standard +to_json+
     def to_json(options = {}, &block)
       unless options[:ignore_defaults]
         unless options[:ignore_default_methods]
@@ -47,8 +62,5 @@ module ActiveRecord
       end
       json_defaults_old_to_json(options, &block)      
     end
-    
   end
-    
- 
 end

data/lib/ruboss4ruby/active_record_tasks.rb

@@ -1,7 +1,10 @@
+# ActiveRecord specific Rake tasks. Namely, nice little extras such as:
+# - db:mysql:stage
+# - db:refresh
 require File.join(File.dirname(__FILE__), 'tasks')
 
-# these tasks are active record specific
-
+# stores local copy of the application environment ('production', 'test', etc)
+# so that appropriate values in config/database.yml are used
 APP_ENV = defined?(ENV['RAILS_ENV']) ? ENV['RAILS_ENV'] : ENV['MERB_ENV']
 
 namespace :db do
@@ -26,7 +29,10 @@ namespace :db do
       stage_database(db_names, admin_password, db_user_name, db_password)
     end
   end  
-    
+  
+  # Performs MySQL database set-up based on the username and password
+  # provided. Also updates Rails config/database.yml file with database
+  # username and password
   def stage_database(db_names, admin_password, db_user_name, db_password)
     sql_command = ""
     

data/lib/ruboss4ruby/configuration.rb

@@ -1,17 +1,45 @@
+# Interestingly enough there's no way to *just* upper-case or down-case first letter of a given
+# string. Ruby's own +capitalize+ actually downcases all the rest of the characters in the string
+# We patch the class to add our own implementation.
 class String
+  # Upper-case first character of a string leave the rest of the string intact
   def ucfirst
     self[0,1].capitalize + self[1..-1]
   end
   
+  # Down-case first character of a string leaving the rest of it intact
   def dcfirst
     self[0,1].downcase + self[1..-1]
   end
 end
 
 module Ruboss4Ruby
+  # Computes necessary configuration options from the environment. This can be used in Rails, Merb
+  # or standalone from the command line.
   module Configuration
     APP_ROOT = defined?(RAILS_ROOT) ? RAILS_ROOT : defined?(Merb) ? Merb.root : File.expand_path(".")
 
+    # Extract project, package, controller names from the environment. This will respect
+    # config/ruboss.yml if it exists, you can override all of the defaults there. The defaults are:
+    # - *base-package* same as project name downcased
+    # - *controller-name* 'ApplicationController'
+    #
+    # Here's a sample ruboss.yml file:
+    #
+    # Ruboss code generation configuration options
+    # 
+    # By default flex models, commands, controllers and components are genearated into
+    # app/flex/<your rails project name> folder. If you'd like to customize the target folder 
+    # (to say append a "com" package before your rails project name) uncomment the line below
+    # base-package must follow the usual flex package notation (a string separated by ".")
+    # 
+    # base-package: com.pomodo
+    # 
+    # Main ruboss controller is typically named AppicationController. This controller is created in 
+    # <base-package>.controllers folder. You can customize the name by uncommenting the following line 
+    # and changing the controller name.
+    # 
+    # controller-name: ApplicationController
     def extract_names(project = nil)
       if project
         project_name = project.camelcase.gsub(/\s/, '')
@@ -21,10 +49,12 @@ module Ruboss4Ruby
         project_name_downcase = project_name.downcase
       end
       
+      # give a chance to override the settings via ruboss.yml
       begin      
         config = YAML.load(File.open("#{APP_ROOT}/config/ruboss.yml"))
         base_package = config['base-package'] || project_name_downcase
         base_folder = base_package.gsub('.', '/').gsub(/\s/, '')
+        project_name = config['project-name'].camelcase.gsub(/\s/, '') || project_name
         controller_name = config['controller-name'] || "ApplicationController"
       rescue
         base_folder = base_package = project_name_downcase
@@ -33,10 +63,12 @@ module Ruboss4Ruby
       [project_name, project_name_downcase, controller_name, base_package, base_folder]
     end
 
+    # List files ending in *.as (ActionScript) in a given folder
     def list_as_files(dir_name)
       Dir.entries(dir_name).grep(/\.as$/).map { |name| name.sub(/\.as$/, "") }.join(", ")
     end
 
+    # List files ending in *.mxml in a given folder
     def list_mxml_files(dir_name)
       Dir.entries(dir_name).grep(/\.mxml$/).map { |name| name.sub(/\.mxml$/, "") }
     end

data/lib/ruboss4ruby/datamapper_foo.rb

@@ -1,9 +1,15 @@
 require 'builder'
 require Ruboss4Ruby::LIB_DIR + 'configuration'
 
+# Flex friendly DataMapper patches, more specifically we just add +to_xml+ on 
+# ValidationErrors class
 module DataMapper
+  # see DataMapper docs for more details
   module Validate
+    # By default DataMapper validation errors doesn't have +to_xml+ method. This is
+    # actually very useful when dealing with remote stateful clients such as Flex/AIR.
     class ValidationErrors
+      # Add Flex-friendly +to_xml+ implementation
       def to_xml
         xml = Builder::XmlMarkup.new(:indent => 2)
         xml.instruct! :xml, :version => "1.0", :encoding => "UTF-8"

data/lib/ruboss4ruby/rails/recipes.rb

@@ -1,7 +1,9 @@
-require 'find'
-
+# Adds Capistrano recipes for deploying Flex applications
+#
 # To use these recipes, add the following to your Capfile:
-# require 'ruboss4ruby/rails/recipes'
+#
+#   require 'ruboss4ruby/rails/recipes'
+require 'find'
 
 Capistrano::Configuration.instance(:must_exist).load do
   after "deploy:setup", "deploy:flex:setup"

data/lib/ruboss4ruby/rails/swf_helper.rb

@@ -1,3 +1,4 @@
+# Adds a little helper to make it easier empbedding SWFs in ERB templates.
 module SWFHelper
   
   # Creates a swfObject Javascript call.  You must include swfobject.js to use this.

data/lib/ruboss4ruby/tasks.rb

@@ -1,3 +1,4 @@
+# Rake tasks for building Ruboss-based Flex and AIR applications
 require 'rake'
 require 'ftools'
 require 'rexml/document'
@@ -6,6 +7,8 @@ require File.join(File.dirname(__FILE__), 'configuration')
 APP_ROOT = Ruboss4Ruby::Configuration::APP_ROOT
 
 namespace :ruboss do
+  # Compile the main Flex/AIR application using given executable to the given
+  # destination folder
   def compile_app(executable, destination, opts = '')
     app_properties = REXML::Document.new(File.open(File.join(APP_ROOT, ".actionScriptProperties")))
     app_properties.elements.each("*/applications/application") do |elm|
@@ -43,11 +46,13 @@ namespace :ruboss do
     end    
   end
   
+  # Find what the main application is based on .actionScriptProperties file
   def get_main_application
     app_properties = REXML::Document.new(File.open(File.join(APP_ROOT, ".actionScriptProperties")))
     app_properties.root.attributes['mainApplicationPath'].split("/").last
   end
   
+  # Get appropriate executable based on platform
   def get_executable(executable)
     if RUBY_PLATFORM =~ /mswin32/
       executable << '.exe'

data/rails_generators/ruboss_config/ruboss_config_generator.rb

@@ -1,4 +1,5 @@
 require 'open-uri'
+require File.join(File.dirname(__FILE__), '..', '..', 'lib', 'ruboss4ruby') if !defined?(Ruboss4Ruby)
 
 class RubossConfigGenerator < Rails::Generator::Base
   include Ruboss4Ruby::Configuration
@@ -97,18 +98,18 @@ class RubossConfigGenerator < Rails::Generator::Base
   end
 
   protected
-    def add_options!(opt)
-      opt.separator ''
-      opt.separator 'Options:'
-      opt.on("-m", "--main-only", "Only generate the main Flex/AIR application file.", 
-        "Default: false") { |v| options[:main_only] = v }
-      opt.on("-a", "--air", "Configure AIR project instead of Flex. Flex is default.", 
-        "Default: false") { |v| options[:air_config] = v }
-      opt.on("-s", "--skip-framework", "Don't fetch the latest framework binary. You'll have to link/build the framework yourself.", 
-        "Default: false") { |v| options[:skip_framework] = v }
-    end
+  def add_options!(opt)
+    opt.separator ''
+    opt.separator 'Options:'
+    opt.on("-m", "--main-only", "Only generate the main Flex/AIR application file.", 
+      "Default: false") { |v| options[:main_only] = v }
+    opt.on("-a", "--air", "Configure AIR project instead of Flex. Flex is default.", 
+      "Default: false") { |v| options[:air_config] = v }
+    opt.on("-s", "--skip-framework", "Don't fetch the latest framework binary. You'll have to link/build the framework yourself.", 
+      "Default: false") { |v| options[:skip_framework] = v }
+  end
 
-    def banner
-      "Usage: #{$0} #{spec.name}" 
-    end
+  def banner
+    "Usage: #{$0} #{spec.name}" 
+  end
 end

data/rails_generators/ruboss_config/templates/mainair-app.xml

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<application xmlns="http://ns.adobe.com/air/application/1.0">
+<application xmlns="http://ns.adobe.com/air/application/1.5">
 
 <!-- Adobe AIR Application Descriptor File Template.
 

data/rails_generators/ruboss_config/templates/ruboss_tasks.rake

@@ -1,5 +1,6 @@
 # if the gem is not installed system wide, we'll just skip the tasks
 begin
+  # this will load the latest ruboss4ruby gem version
   require 'ruboss4ruby/active_record_tasks'
 rescue LoadError
 end

data/rails_generators/ruboss_controller/ruboss_controller_generator.rb

@@ -1,3 +1,5 @@
+require File.join(File.dirname(__FILE__), '..', '..', 'lib', 'ruboss4ruby') if !defined?(Ruboss4Ruby)
+
 class RubossControllerGenerator < Rails::Generator::Base
   include Ruboss4Ruby::Configuration
   
@@ -23,9 +25,4 @@ class RubossControllerGenerator < Rails::Generator::Base
         "#{command_controller_name}.as")
     end
   end
-
-  protected
-    def banner
-      "Usage: #{$0} #{spec.name}" 
-    end
 end