extjs-mvc 0.2.6 → 0.2.7

data/README.rdoc

@@ -1,37 +1,47 @@
 = mvc
 
 
-A collection of helpers, MVC mixins and PORs (plain-old-ruby-object) to assist with auto-generating ExtJS javascript component definitions.
+A collection of helpers, MVC mixins and PORs (plain-old-ruby-object) to assist with auto-generating ExtJS Stores (Ext.data.Store) including its associated DataReader (Ext.data.JsonReader, Ext.data.XmlReader) and DataWriter (Ext.data.JsonWriter, Ext.data.XmlWriter).  Also contains a helper for rendering javascript component definitions via partials.
 
 
 ===Installation
-
-    % gem sources -a http://gems.github.com (you only have to do this once)
+	% sudo gem install gemcutter
+	% gem tumble   (only have to do this once, adds gemcutter as primary gem-source)
     % sudo gem install extjs-mvc
 
-In <tt>environment.rb</tt>
+<p><b>Rails Installation:</b></p>
+In <tt>environment.rb</tt>, 
 
     Rails::Initializer.run do |config|
         config.gem "extjs-mvc"
     end
 
+<p><b>Merb installation:</b></p>
+In <tt>config/dependencies.rb</tt>, Add extjs-mvc as a new dependency
+	
+	dependency "extjs-mvc"
 
-=== An ActiveRecord mixin:  ExtJS::Model
+=== An ORM Model mixin:  ExtJS::Model
+extjs-mvc contains Model mixin named <tt>ExtJS::Model</tt> which works for <b>three</b> popular ORM frameworks, ActiveRecord, DataMapper and MongoMapper.  The API for each framework is identical.
 
-include it in your model.  Use the class-method <tt>extjs_fields</tt> to specify those
+Simply include the mixin into your model.  Use the class-method <tt>extjs_fields</tt> to specify those
 fields with will be used to render the <tt>Ext.data.Record.create</tt> field-def'n.
+
     class User < ActiveRecord::Base
       include ExtJS::Model
 
       extjs_fields :exclude => [:password, :password_confirmation]
-      # OR
+      # OR 
       extjs_fields :name, :description
-      # OR
+      # OR define a column as a Hash
+	  extjs_fields :description, :name => {"sortDir" => "ASC"}, :created_at => {"dateFormat" => "c"}
+	  #
       extjs_fields :name, :description, :parent => [:name, :date]
-      # this would configure associated columns with names like "parent__name" and "parent__date")
+      # this would configure associated columns with names like:
+ 		[...{name: "parent_name", mapping: "parent.name"}, {name: "parent_date", mapping: "parent.date"}...]
     end
 
-In script/console
+In <tt>irb</tt> console:
     >> User.extjs_fields
     >> User.extjs_record
     => { "idProperty"=>"id", "fields"=>[
@@ -42,13 +52,13 @@ In script/console
        ]}
 
 === An ActionController mixin:  ExtJS::Controller
-
+The <tt>extjs-mvc</tt> Gem includes a framework agnostic Controller mixin which works with both Rails and Merb.
 <b>usage:</b>
 
     class UsersController < ActionController::Base
         include ExtJS::Controller
     end
-
+	
 === View Helper:  ExtJS::Helpers::Component
 
 <b>usage:</b>

data/VERSION

@@ -1 +1 @@
-0.2.6
+0.2.7

data/lib/model/active_record.rb

@@ -1,9 +1,12 @@
+##
+# ActiveRecord adapter to ExtJS::Model mixin.
+#
 module ExtJS
   module Model
     module ClassMethods
       
       def extjs_primary_key
-        self.primary_key
+        self.primary_key.to_sym
       end
       
       def extjs_column_names
@@ -14,7 +17,21 @@ module ExtJS
         self.columns_hash
       end
       
-      def extjs_render_column(col)
+      ##
+      # determine if supplied Column object is nullable
+      # @param {ActiveRecord::ConnectionAdapters::Column}
+      # @return {Boolean}
+      #
+      def extjs_allow_blank(col)
+        col.null
+      end
+      
+      ##
+      # determine datatype of supplied Column object
+      # @param {ActiveRecord::ConnectionAdapters::Column}
+      # @return {Symbol}
+      #
+      def extjs_type(col)
         type = col.type
         case type
           when :datetime || :date || :time || :timestamp
@@ -23,17 +40,28 @@ module ExtJS
             type = :string
           when :integer
             type = :int
+          when :decimal
+            type = :float
         end
-        {:name => col.name, :allowBlank => (col.primary) ? true : col.null, :type => type}        
+        type
       end
       
+      ##
+      # return a simple, normalized list of AR associations having the :name, :type and association class
+      # @return {Array}
+      #
       def extjs_associations
         if @extjs_associations.nil?
           @extjs_associations = {}
           self.reflections.keys.each do |key|
             assn = self.reflections[key]
             type = (assn.macro === :has_many) ? :many : assn.macro
-            @extjs_associations[key.to_sym] = {:name => key, :type => type}
+            @extjs_associations[key.to_sym] = {
+              :name => key, 
+              :type => type, 
+              :class => assn.class_name.constantize,
+              :foreign_key => assn.association_foreign_key
+            }
           end
         end        
         @extjs_associations

data/lib/model/base.rb

@@ -5,9 +5,19 @@ module ExtJS
       model.send(:extend, ClassMethods)
       model.send(:include, InstanceMethods)
       model.class_eval do
+        ##
+        # @config {Array} List of DataReader fields to render.  This should probably not be a cattr_accessor
+        # since it's only used internally.  The user adds fields via the Class method extjs_fields instead.
+        #
         cattr_accessor :extjs_record_fields
+        ##
+        # @config {String} extjs_mapping_template This a template used to render mapped field-names.
+        # One could use the Rails standard "{association}[{property}]" as well.
+        #
+        cattr_accessor :extjs_mapping_template
       end
       model.extjs_record_fields = []
+      model.extjs_mapping_template = "_{property}"
     end
 
     ##
@@ -15,28 +25,39 @@ module ExtJS
     #
     module InstanceMethods
       
-      def to_record
-        pk = self.class.extjs_primary_key
-        assns = self.class.extjs_associations
+      ##
+      # Converts a model instance to a record compatible with ExtJS
+      # @params {Mixed} params A list of fields to use instead of this Class's extjs_record_fields
+      #
+      def to_record(*params)
+        
+        fields  = (params.empty?) ? self.class.extjs_record_fields : self.class.process_fields(*params)
+        assns   = self.class.extjs_associations
+        pk      = self.class.extjs_primary_key
         
-        data = {pk => self.send(pk)}
-        self.class.extjs_record_fields.each do |f|
-          if refl = assns[f]
+        # build the initial field data-hash
+        data    = {pk => self.send(pk)}
+         
+        fields.each do |field|
+          if refl = assns[field[:name]] || assns[field[:name].to_sym]
             if refl[:type] === :belongs_to
-              assn = self.send(f)
-              data[f] = (assn) ? assn.to_record : {} # <-- a thing was requested, give emtpy thing.
+              assn = self.send(field[:name])
+              if assn.respond_to?(:to_record)
+                data[field[:name]] = assn.send(:to_record, *[field[:fields]])
+              elsif (field[:fields])
+                data[field[:name]] = {}
+                field[:fields].each do |property|
+                  data[field[:name]][property] = assn.send(property) if assn.respond_to?(property)
+                end
+              else
+                data[field[:name]] = {} # belongs_to assn that doesn't respond to to_record and no fields list
+              end
             elsif refl[:type] === :many
-              data[f] = self.send(f).collect {|r| r.to_record}  #CAREFUL!!!!!!!!!!!!1
+              data[field[:name]] = self.send(field[:name]).collect {|r| r.to_record}  #CAREFUL!!!!!!!!!!!!1
             end
-          elsif f.is_a? Array
-            value = self
-            f.each do |method|
-              value = value.send(method)
-              break if value.nil?
-            end
-            data[f.join('__')] = value
           else
-            data[f] = self.send(f)
+            value = self.send(field[:name])
+            data[field[:name]] = value.respond_to?(:to_record) ? value.to_record : value
           end
         end
         data
@@ -51,66 +72,154 @@ module ExtJS
       # render AR columns to Ext.data.Record.create format
       # eg: {name:'foo', type: 'string'}
       #
-      def extjs_record
-        
+      def extjs_record(*fields)
         if self.extjs_record_fields.empty?
-          self.extjs_record_fields = self.extjs_column_names
+          self.extjs_fields(*self.extjs_column_names)
         end
-
-        pk = self.extjs_primary_key
-        columns = self.extjs_columns_hash
-        associations = self.extjs_associations
         
-        return {
-          "fields" => self.extjs_record_fields.collect {|f|
-            if columns[f.to_sym] || columns[f.to_s]
-              field = self.extjs_render_column(columns[f.to_sym] || columns[f.to_s])
-              field[:dateFormat] = "c" if field[:type] === :date  # <-- ugly hack for date
-              field
-            elsif assn = associations[f]
-              field = {:name => f, :allowBlank => true, :type => 'auto'}
-            elsif f.is_a? Array
-              field = {:name => f.join('__'), :type => 'auto'}
-            else # property is a method?
-              field = {:name => f, :allowBlank => true, :type => 'auto'}
+        associations  = self.extjs_associations
+        columns       = self.extjs_columns_hash
+        fields        = fields.empty? ? self.extjs_record_fields : self.process_fields(*fields)  
+        pk            = self.extjs_primary_key
+        rs            = []
+        
+        fields.each do |field|
+          field = field.dup
+          
+          if col = columns[field[:name]] || columns[field[:name].to_sym]  # <-- column on this model                
+            rs << self.extjs_field(field, col)      
+          elsif assn = associations[field[:name]] || associations[field[:name].to_sym]
+            assn_fields = field.delete(:fields) || nil
+            if assn[:class].respond_to?(:extjs_record)  # <-- exec extjs_record on assn Model.
+              record = assn[:class].send(:extjs_record, *[assn_fields])
+              rs.concat(record["fields"].collect {|assn_field| 
+                extjs_field(assn_field, :mapping => field[:name])
+              })
+            elsif assn_fields  # <-- :parent => [:id, :name]
+              rs.concat(assn_fields.collect {|assn_field| 
+                extjs_field(assn_field, :mapping => field[:name])
+              })
+            else  
+              rs << extjs_field(field)
+            end
+            
+            # attach association's foreign_key if not already included.
+            if (col = columns[assn[:foreign_key]] || columns[assn[:foreign_key].to_s]) && !rs.include?({:name => assn[:foreign_key].to_s})
+              rs << extjs_field({:name => assn[:foreign_key]}, col)
             end
-          },
+            
+          else # property is a method?
+            rs << extjs_field(field)
+          end
+        end
+        
+        return {
+          "fields" => rs,
           "idProperty" => pk
         }
       end
       
+      ##
+      # meant to be used within a Model to define the extjs record fields.
+      # eg:
+      # class User
+      #   extjs_fields :first, :last, :email => {"sortDir" => "ASC"}, :company => [:id, :name]
+      # end
+      #
       def extjs_fields(*params)
+        self.extjs_record_fields = self.process_fields(*params)
+      end
+      
+      ##
+      # Prepare a field configuration list into a normalized array of Hashes, {:name => "field_name"} 
+      # @param {Mixed} params
+      # @return Array
+      #
+      def process_fields(*params) 
+        params = [] if params.first.nil?
         options = params.extract_options!
+        
+        # Return immediately if pre-processed fields are detected.
+        # ie: [ [{:name => 'foo'}, {:name => 'bar'}] ]
+        # This is to handle the case where extjs_record and to_record are called recursively, in which case
+        # these fields have already been processed.
+        #
+        if params.length === 1 && params.first.kind_of?(Array) && !params.first.empty?
+          return params.first
+        end
+        
+        fields = []
         if !options.keys.empty?
           if excludes = options.delete(:exclude)
-            self.extjs_record_fields = self.extjs_column_names.reject {|c| excludes.find {|ex| c === ex.to_s}}.collect {|c| c}
+            fields = self.process_fields(self.extjs_column_names.reject {|c| excludes.find {|ex| c === ex.to_s}}.collect {|c| c})
           elsif only = options.delete(:only)
-            self.extjs_record_fields = only
+            fields = self.process_fields(only)
+          else
+            options.keys.each do |k|  # <-- :email => {"sortDir" => "ASC"}
+              if options[k].is_a? Hash
+                options[k][:name] = k.to_s
+                fields << options[k]
+              elsif options[k].is_a? Array # <-- :parent => [:id, :name]
+                fields << {
+                  :name => k.to_s,
+                  :fields => process_fields(*options[k])
+                }
+              end
+            end
           end
-          self.extjs_record_fields.concat(process_association_fields(options))
         elsif params.empty?
           return self.extjs_record_fields
         end
-
-        self.extjs_record_fields.concat(params) if !params.empty?
-
-        #Append primary key if it's not included
-        # I don't think we want to automatically include :id
-        # Chris
-        #self.extjs_record_fields << self.primary_key.to_sym if !self.extjs_record_fields.include?(self.primary_key.to_sym)
+        
+        unless params.empty?
+          fields.concat(params.collect {|f|
+            {:name => f.to_s}
+          })
+        end
+        fields
       end
       
       ##
-      # Prepare the config for fields with '.' in their names
+      # Render a column-config object
+      # @param {Hash/Column} field Field-configuration Hash, probably has :name already set and possibly Ext.data.Field options.
+      # @param {ORM Column Object from AR, DM or MM}
+      #
+      def extjs_field(field, config=nil)  
+        if config.kind_of? Hash
+          if mapping = config.delete(:mapping)
+            field.update( # <-- We use a template for rendering mapped field-names.
+              :name => mapping + self.extjs_mapping_template.gsub(/\{property\}/, field[:name]),
+              "mapping" => "#{mapping.to_s}.#{field[:name]}"
+            )
+          end
+          field.update(config) unless config.keys.empty?
+        elsif !config.nil?  # <-- Hopfully an ORM Column object.
+          field.update(
+            "allowBlank" => self.extjs_allow_blank(config),
+            "type" => self.extjs_type(config)
+          )
+          field["dateFormat"] = "c" if field["type"] === :date && field["dateFormat"].nil? # <-- ugly hack for date  
+        end  
+        field.update("type" => "auto") if field["type"].nil?
+        field
+      end
+
+      ##
+      # Returns an array of symbolized association names that will be referenced by a call to to_record
+      # i.e. [:parent1, :parent2]
       #
-      def process_association_fields(options)
-        results = []
-        options.each do |assoc, fields|
-          fields.each do |field|
-            results << [assoc, field]
+      def extjs_used_associations
+        if @extjs_used_associations.nil?
+          assoc = []
+          self.extjs_record_fields.each do |f|
+            #This needs to be the first condition because the others will break if f is an Array
+            if extjs_associations[f[:name]]
+              assoc << f[:name]
+            end
           end
+          @extjs_used_associations = assoc.uniq
         end
-        results
+        @extjs_used_associations
       end
     end
   end

data/lib/model/data_mapper.rb

@@ -1,3 +1,6 @@
+##
+# DataMapper adapter for ExtJS::Model mixin
+#
 module ExtJS
   module Model
     module ClassMethods
@@ -20,8 +23,11 @@ module ExtJS
         @extjs_columns_hash
       end
       
-      def extjs_render_column(col)
-        pk = self.key.first
+      def extjs_allow_blank(col)
+         (col === self.key.first) ? true : col.nullable?
+      end
+      
+      def extjs_type(col)
         type = ((col.type.respond_to?(:primitive)) ? col.type.primitive : col.type).to_s
         case type
           when "DateTime", "Date", "Time"
@@ -34,8 +40,7 @@ module ExtJS
             type = :int
           else
             type = "auto"
-        end 
-        {:name => col.name.to_s, :type => type, :allowBlank => (col === pk) ? true : col.nullable? }
+        end
       end
       
       def extjs_associations
@@ -43,8 +48,12 @@ module ExtJS
           @extjs_associations = {}
           self.relationships.keys.each do |key|
             assn = self.relationships[key]
-            type = (assn.options[:max].nil? && assn.options[:min].nil?) ? :belongs_to : (assn.options[:max] > 1) ? :many : nil 
-            @extjs_associations[key.to_sym] = {:name => key, :type => type}
+            @extjs_associations[key.to_sym] = {
+              :name => key, 
+              :type => type = (assn.options[:max].nil? && assn.options[:min].nil?) ? :belongs_to : (assn.options[:max] > 1) ? :many : nil ,
+              :class => assn.parent_model,
+              :foreign_key => assn.child_key.first.name
+            }
           end
         end
         @extjs_associations

data/lib/model/mongo_mapper.rb

@@ -1,3 +1,6 @@
+##
+# MongoMapper adapter to ExtJS::Model mixin
+#
 module ExtJS
   module Model
     ##
@@ -6,7 +9,7 @@ module ExtJS
     module ClassMethods
       
       def extjs_primary_key
-        "id"
+        :_id
       end
       
       def extjs_column_names
@@ -21,13 +24,18 @@ module ExtJS
         if @extjs_associations.nil?
           @extjs_associations = {}
           self.associations.keys.each do |key|
-            @extjs_associations[key.to_sym] = {:name => key, :type => self.associations[key].type}
+            @extjs_associations[key.to_sym] = {
+              :name => key, 
+              :type => self.associations[key].type,
+              :class => self.associations[key].class_name.constantize,
+              :foreign_key => self.associations[key].foreign_key
+            }
           end
         end
         @extjs_associations
       end
       
-      def extjs_render_column(col)
+      def extjs_type(col)
         type = col.type.to_s
         case type
           when "DateTime", "Date", "Time"
@@ -40,8 +48,11 @@ module ExtJS
             type = :int
           else
             type = "auto"
-        end 
-        {:name => col.name, :type => type, :allowBlank => (col.name === '_id') ? true : (col.options[:required] === true) ? false : true }
+        end
+      end
+      
+      def extjs_allow_blank(col)
+        (col.name === '_id') ? true : (col.options[:required] === true) ? false : true
       end
     end
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: extjs-mvc
 version: !ruby/object:Gem::Version 
-  version: 0.2.6
+  version: 0.2.7
 platform: ruby
 authors: 
 - Chris Scott
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-11-17 00:00:00 -05:00
+date: 2009-11-19 00:00:00 -05:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency