sugarcrm 0.7.2 → 0.7.7

data/README.rdoc

@@ -10,34 +10,39 @@ RubyGem for interacting with SugarCRM via REST.
 
 == Description:
 
-I've implemented all of the basic API calls that SugarCRM supports, and am actively building an abstraction layer
-on top of the basic API methods.  The end result will be ActiveRecord style finders and first class objects.  Some 
-of this functionality is included today. 
+A less clunky way to interact with SugarCRM via REST.
+
+I've built an abstraction layer on top of the SugarCRM REST API, instead of +get_entry("Users", "1")+ you can 
+call +SugarCRM::User.find(1)+.  There is also support for collections à la +SugarCRM::User.find(1).accounts+.  
+ActiveRecord style finders are in place, with limited support for conditions and joins 
+e.g. +SugarCRM::Contacts.find_by_title("VP of Sales")+ will work, but +SugarCRM::Contacts.find_by_title("VP of Sales", {:conditions => {:deleted => 0}})+ will not.  
 
 == FEATURES/PROBLEMS:
 
+* Supports all v2 API calls
 * Auto-generation of Module specific objects.  When a connection is established, get_available_modules is called and the resultant modules are turned into SugarCRM::Module classes.  
-* If you just want to use the vanilla API, you can access the methods directly on the connection object.
+* If you just want to use the vanilla API, you can access the methods directly on the SugarCRM.connection object.
 
 == SYNOPSIS:
 
   require 'sugarcrm'
+  
   # Establish a connection
   SugarCRM::Base.establish_connection("http://localhost/sugarcrm", 'user', 'password', {:debug => false})
 
-  # Retrieve a user by ID, using the SugarCRM::User Proxy object
-  SugarCRM::User.find(id)
-  
+  # Retrieve a user by user_name
+  SugarCRM::User.find_by_user_name("admin")
+
+  # Retrieve all Accounts owned by a particular user.
+  SugarCRM::User.find_by_user_name('sarah').accounts
+
   # Show a list of available modules
   SugarCRM.modules
   
-  # Use the HTTP for direct API calls
-  SugarCRM.connection.get_entry(1)
+  # Use the HTTP Connection and SugarCRM API to load the Admin user
+  SugarCRM.connection.get_entry("Users", 1)
 
-  # Lookup a user by name.  Find any associated accounts
-  SugarCRM::User.find_by_username('sarah').accounts
-  
-  # Same operation, but using the direct API calls
+  # Retrieve all Accounts by user name (direct API method)
   SugarCRM.connection.get_entry_list(
     "Users",
     "users.user_name = \'sarah\'",

data/VERSION

@@ -1 +1 @@
-0.7.2
+0.7.7

data/lib/sugarcrm/attribute_methods.rb

@@ -1,12 +1,14 @@
 module SugarCRM; module AttributeMethods
 
-  # Returns a hash of the module fields from the 
-  def attributes_from_module_fields
-    fields = {}
-    self.class._module.fields.keys.sort.each do |k|
-      fields[k.to_s] = nil
+  module ClassMethods
+    # Returns a hash of the module fields from the module
+    def attributes_from_module_fields
+      fields = {}
+      self._module.fields.keys.sort.each do |k|
+        fields[k.to_s] = nil
+      end
+      fields
     end
-    fields
   end
 
   # Generates get/set methods for keys in the attributes hash

data/lib/sugarcrm/base.rb

@@ -33,10 +33,242 @@ module SugarCRM; class Base
       @@connection = SugarCRM::Connection.new(url, user, pass, @debug)
     end
   
-    # Runs a find against the remote service
-    def find(id)
-      response = SugarCRM.connection.get_entry(self._module.name, id, {:fields => self._module.fields.keys})
+    def find(*args)
+      options = args.extract_options!
+      validate_find_options(options)
+
+      case args.first
+        when :first then find_initial(options)
+        when :all   then find_every(options)
+        else             find_from_ids(args, options)
+      end
+    end
+
+    # A convenience wrapper for <tt>find(:first, *args)</tt>. You can pass in all the
+    # same arguments to this method as you can to <tt>find(:first)</tt>.
+    def first(*args)
+      find(:first, *args)
+    end
+
+    # This is an alias for find(:all).  You can pass in all the same arguments to this method as you can
+    # to find(:all)
+    def all(*args)
+      find(:all, *args)
+    end
+
+    private 
+    
+    def find_initial(options)
+      options.update(:max_results => 1)
+      find_every(options)
+    end
+  
+    def find_from_ids(ids, options)
+      expects_array = ids.first.kind_of?(Array)
+      return ids.first if expects_array && ids.first.empty?
+
+      ids = ids.flatten.compact.uniq
+
+      case ids.size
+        when 0
+          raise RecordNotFound, "Couldn't find #{name} without an ID"
+        when 1
+          result = find_one(ids.first, options)
+          expects_array ? [ result ] : result
+        else
+          find_some(ids, options)
+      end
+    end
+  
+    def find_one(id, options)
+      if result = SugarCRM.connection.get_entry(self._module.name, id, {:fields => self._module.fields.keys})
+        result
+      else
+        raise RecordNotFound, "Couldn't find #{name} with ID=#{id}#{conditions}"
+      end
+    end
+    
+    def find_some(ids, options)
+      result = SugarCRM.connection.get_entries(self._module.name, ids, {:fields => self._module.fields.keys})
+
+      # Determine expected size from limit and offset, not just ids.size.
+      expected_size =
+        if options[:limit] && ids.size > options[:limit]
+          options[:limit]
+        else
+          ids.size
+        end
+
+      # 11 ids with limit 3, offset 9 should give 2 results.
+      if options[:offset] && (ids.size - options[:offset] < expected_size)
+        expected_size = ids.size - options[:offset]
+      end
+
+      if result.size == expected_size
+        result
+      else
+        raise RecordNotFound, "Couldn't find all #{name.pluralize} with IDs (#{ids_list})#{conditions} (found #{result.size} results, but was looking for #{expected_size})"
+      end
+    end
+    
+    def find_every(options)
+      find_by_sql(options)
     end
+        
+    def find_by_sql(options)
+      query = query_from_options(options)
+      SugarCRM.connection.get_entry_list(self._module.name, query, options)
+    end
+    
+    def query_from_options(options)
+      conditions = []
+      options[:conditions].each_pair do |column, value| 
+        conditions << "#{self._module.table_name}.#{column} = \'#{value}\'"
+      end
+      conditions.join(" AND ")
+    end
+    
+    # Enables dynamic finders like <tt>find_by_user_name(user_name)</tt> and <tt>find_by_user_name_and_password(user_name, password)</tt>
+    # that are turned into <tt>find(:first, :conditions => ["user_name = ?", user_name])</tt> and
+    # <tt>find(:first, :conditions => ["user_name = ? AND password = ?", user_name, password])</tt> respectively. Also works for
+    # <tt>find(:all)</tt> by using <tt>find_all_by_amount(50)</tt> that is turned into <tt>find(:all, :conditions => ["amount = ?", 50])</tt>.
+    #
+    # It's even possible to use all the additional parameters to +find+. For example, the full interface for +find_all_by_amount+
+    # is actually <tt>find_all_by_amount(amount, options)</tt>.
+    #
+    # Also enables dynamic scopes like scoped_by_user_name(user_name) and scoped_by_user_name_and_password(user_name, password) that
+    # are turned into scoped(:conditions => ["user_name = ?", user_name]) and scoped(:conditions => ["user_name = ? AND password = ?", user_name, password])
+    # respectively.
+    #
+    # Each dynamic finder, scope or initializer/creator is also defined in the class after it is first invoked, so that future
+    # attempts to use it do not run through method_missing.
+    def method_missing(method_id, *arguments, &block)
+      if match = DynamicFinderMatch.match(method_id)
+        attribute_names = match.attribute_names
+        super unless all_attributes_exists?(attribute_names)
+        if match.finder?
+          finder = match.finder
+          bang = match.bang?
+          # def self.find_by_login_and_activated(*args)
+          #   options = args.extract_options!
+          #   attributes = construct_attributes_from_arguments(
+          #     [:login,:activated],
+          #     args
+          #   )
+          #   finder_options = { :conditions => attributes }
+          #   validate_find_options(options)
+          #
+          #   if options[:conditions]
+          #     with_scope(:find => finder_options) do
+          #       find(:first, options)
+          #     end
+          #   else
+          #     find(:first, options.merge(finder_options))
+          #   end
+          # end
+          self.class_eval <<-EOS, __FILE__, __LINE__ + 1
+            def self.#{method_id}(*args)
+              options = args.extract_options!
+              attributes = construct_attributes_from_arguments(
+                [:#{attribute_names.join(',:')}],
+                args
+              )
+              finder_options = { :conditions => attributes }
+              validate_find_options(options)
+
+              #{'result = ' if bang}if options[:conditions]
+                with_scope(:find => finder_options) do
+                  find(:#{finder}, options)
+                end
+              else
+                find(:#{finder}, options.merge(finder_options))
+              end
+              #{'result || raise(RecordNotFound, "Couldn\'t find #{name} with #{attributes.to_a.collect {|pair| "#{pair.first} = #{pair.second}"}.join(\', \')}")' if bang}
+            end
+          EOS
+          send(method_id, *arguments)
+        elsif match.instantiator?
+          instantiator = match.instantiator
+          # def self.find_or_create_by_user_id(*args)
+          #   guard_protected_attributes = false
+          #
+          #   if args[0].is_a?(Hash)
+          #     guard_protected_attributes = true
+          #     attributes = args[0].with_indifferent_access
+          #     find_attributes = attributes.slice(*[:user_id])
+          #   else
+          #     find_attributes = attributes = construct_attributes_from_arguments([:user_id], args)
+          #   end
+          #
+          #   options = { :conditions => find_attributes }
+          #   set_readonly_option!(options)
+          #
+          #   record = find(:first, options)
+          #
+          #   if record.nil?
+          #     record = self.new { |r| r.send(:attributes=, attributes, guard_protected_attributes) }
+          #     yield(record) if block_given?
+          #     record.save
+          #     record
+          #   else
+          #     record
+          #   end
+          # end
+          self.class_eval <<-EOS, __FILE__, __LINE__ + 1
+            def self.#{method_id}(*args)
+              attributes = [:#{attribute_names.join(',:')}]
+              protected_attributes_for_create, unprotected_attributes_for_create = {}, {}
+              args.each_with_index do |arg, i|
+                if arg.is_a?(Hash)
+                  protected_attributes_for_create = args[i].with_indifferent_access
+                else
+                  unprotected_attributes_for_create[attributes[i]] = args[i]
+                end
+              end
+
+              find_attributes = (protected_attributes_for_create.merge(unprotected_attributes_for_create)).slice(*attributes)
+
+              options = { :conditions => find_attributes }
+
+              record = find(:first, options)
+
+              if record.nil?
+                record = self.new do |r|
+                  r.send(:attributes=, protected_attributes_for_create, true) unless protected_attributes_for_create.empty?
+                  r.send(:attributes=, unprotected_attributes_for_create, false) unless unprotected_attributes_for_create.empty?
+                end
+                #{'yield(record) if block_given?'}
+                #{'record.save' if instantiator == :create}
+                record
+              else
+                record
+              end
+            end
+          EOS
+          send(method_id, *arguments, &block)
+        end
+      else
+        super
+      end
+    end
+    
+    def all_attributes_exists?(attribute_names)
+      attribute_names.all? { |name| attributes_from_module_fields.include?(name) }
+    end
+    
+    def construct_attributes_from_arguments(attribute_names, arguments)
+      attributes = {}
+      attribute_names.each_with_index { |name, idx| attributes[name] = arguments[idx] }
+      attributes
+    end
+    
+    VALID_FIND_OPTIONS = [ :conditions, :include, :joins, :limit, :offset,
+                           :order, :select, :readonly, :group, :having, :from, :lock ]
+
+    def validate_find_options(options) #:nodoc:
+      options.assert_valid_keys(VALID_FIND_OPTIONS)
+    end
+    
   end
 
   # Creates an instance of a Module Class, i.e. Account, User, Contact, etc.
@@ -46,7 +278,7 @@ module SugarCRM; class Base
   # a call to Module.register_all
   def initialize(id=nil, attributes={})
     @id = id
-    @attributes = attributes_from_module_fields.merge(attributes)
+    @attributes = self.class.attributes_from_module_fields.merge(attributes)
     @associations = associations_from_module_link_fields
     define_attribute_methods
     define_association_methods
@@ -76,9 +308,10 @@ module SugarCRM; class Base
   def association_methods_generated?
     self.class.association_methods_generated
   end
-
+  
   Base.class_eval do
     include AttributeMethods
+    extend  AttributeMethods::ClassMethods
     include AssociationMethods
   end
 

data/lib/sugarcrm/connection.rb

@@ -11,7 +11,7 @@ Dir["#{File.dirname(__FILE__)}/connection/api/*.rb"].each { |f| load(f) }
 module SugarCRM; class Connection
 
   URL = "/service/v2/rest.php"
-  DONT_SHOW_DEBUG_FOR = [:get_available_modules]
+  DONT_SHOW_DEBUG_FOR = []
   RESPONSE_IS_NOT_JSON = [:get_user_id, :get_user_team_id]
   
   attr :url, true

data/lib/sugarcrm/dynamic_finder_match.rb

@@ -0,0 +1,41 @@
+module SugarCRM
+  class DynamicFinderMatch
+    def self.match(method)
+      df_match = self.new(method)
+      df_match.finder ? df_match : nil
+    end
+
+    def initialize(method)
+      @finder = :first
+      case method.to_s
+      when /^find_(all_by|last_by|by)_([_a-zA-Z]\w*)$/
+        @finder = :last if $1 == 'last_by'
+        @finder = :all if $1 == 'all_by'
+        names = $2
+      when /^find_by_([_a-zA-Z]\w*)\!$/
+        @bang = true
+        names = $1
+      when /^find_or_(initialize|create)_by_([_a-zA-Z]\w*)$/
+        @instantiator = $1 == 'initialize' ? :new : :create
+        names = $2
+      else
+        @finder = nil
+      end
+      @attribute_names = names && names.split('_and_')
+    end
+
+    attr_reader :finder, :attribute_names, :instantiator
+
+    def finder?
+      !@finder.nil? && @instantiator.nil?
+    end
+
+    def instantiator?
+      @finder == :first && !@instantiator.nil?
+    end
+
+    def bang?
+      @bang
+    end
+  end
+end

data/lib/sugarcrm/exceptions.rb

@@ -19,4 +19,7 @@ module SugarCRM
   
   class AttributeParsingError < RuntimeError
   end
+  
+  class RecordNotFound < RuntimeError
+  end
 end

data/lib/sugarcrm/module.rb

@@ -2,6 +2,7 @@ module SugarCRM
   # A class for handling SugarCRM Modules
   class Module
     attr :name, false
+    attr :table_name, false
     attr :klass, false
     attr :fields, false
     attr :link_fields, false
@@ -12,6 +13,7 @@ module SugarCRM
     def initialize(name)
       @name   = name
       @klass  = name.classify
+      @table_name = name.tableize
       @fields = {}
       @link_fields  = {}
       @fields_registered = false

data/lib/sugarcrm.rb

@@ -5,6 +5,7 @@ require 'active_support/core_ext'
 require 'sugarcrm/module_methods'
 require 'sugarcrm/base'
 require 'sugarcrm/connection'
+require 'sugarcrm/dynamic_finder_match'
 require 'sugarcrm/exceptions'
 require 'sugarcrm/module'
 require 'sugarcrm/request'

data/test/connection/test_get_available_modules.rb

@@ -3,7 +3,7 @@ require 'helper'
 class TestGetAvailableModules < Test::Unit::TestCase
   context "A SugarCRM.connection" do
     setup do
-      SugarCRM::Connection.new(URL, USER, PASS)
+      SugarCRM::Connection.new(URL, USER, PASS, {:debug => false})
     end
     should "return an array of modules when #get_modules" do
       assert_instance_of SugarCRM::Module, SugarCRM.connection.get_modules[0]

data/test/test_sugarcrm.rb

@@ -16,6 +16,10 @@ class TestSugarCRM < Test::Unit::TestCase
       assert SugarCRM::User.connection.logged_in?
     end
   
+    should "respond to self.attributes_from_modules_fields" do
+      assert_instance_of Hash, SugarCRM::User.attributes_from_module_fields
+    end
+  
     should "return an instance of itself when #new" do
       assert_instance_of SugarCRM::User, SugarCRM::User.new
     end
@@ -45,6 +49,16 @@ class TestSugarCRM < Test::Unit::TestCase
       assert_equal "sarah@example.com", u.email_addresses.first.email_address
     end
 
+    should "return an array of records when sent #find([id1, id2, id3])" do
+      users = SugarCRM::User.find(["seed_sarah_id", 1])
+      assert_equal "Administrator", users.last.title
+    end
+    
+    should "return an instance of User when sent User#find_by_username" do
+      u = SugarCRM::User.find_by_user_name("sarah")
+      assert_equal "sarah@example.com", u.email_addresses.first.email_address
+    end
+
   end
   
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: sugarcrm
 version: !ruby/object:Gem::Version 
-  hash: 7
+  hash: 13
   prerelease: false
   segments: 
   - 0
   - 7
-  - 2
-  version: 0.7.2
+  - 7
+  version: 0.7.7
 platform: ruby
 authors: 
 - Carl Hicks
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-11-13 00:00:00 -08:00
+date: 2010-11-14 00:00:00 -08:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -110,6 +110,7 @@ files:
 - lib/sugarcrm/connection/api/set_relationship.rb
 - lib/sugarcrm/connection/api/set_relationships.rb
 - lib/sugarcrm/connection/helper.rb
+- lib/sugarcrm/dynamic_finder_match.rb
 - lib/sugarcrm/exceptions.rb
 - lib/sugarcrm/module.rb
 - lib/sugarcrm/module_methods.rb