sugarcrm 0.8.2 → 0.9.0

data/README.rdoc

@@ -12,17 +12,17 @@ RubyGem for interacting with SugarCRM via REST.
 
 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).email_addresses.  
-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.  
+Instead of SugarCRM.connection.get_entry("Users", "1"), you can use SugarCRM::User.find(1).  There is also support for collections à la SugarCRM::User.find(1).email_addresses, or SugarCRM::Contact.first.meetings << new_meeting.  ActiveRecord style finders are in place, with limited support for conditions and joins. 
 
 == FEATURES/PROBLEMS:
 
-* Supports all v2 API calls
-* Supports saving of Module specific objects.
-* 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 SugarCRM.connection object.
+* Works with all v2 API calls
+* Supports creation, saving, and deletion of SugarCRM specific objects.
+* Validations, typecasting, and serialization of boolean, date, and integer fields
+* Query, update and delete records from collections! 
+* ActiveRecord style finders!
+* Auto-generation of SugarCRM specific objects.  When a connection is established, get_available_modules is called and the resultant modules are turned into SugarCRM::Module classes.  
+* If you want to use the vanilla API, you can access the methods directly on the SugarCRM.connection object.
 
 == SYNOPSIS:
 
@@ -50,32 +50,58 @@ e.g. SugarCRM::Contacts.find_by_title("VP of Sales") will work, but SugarCRM::Co
   
   # Check if an object is valid (i.e. if it has the required fields to save)
   u.valid?
-  
+    
   # Access the errors collection
   u.errors
   
+  # Show the fields required to save
+  u.required_attributes
+  
   # Delete an Account
   a = SugarCRM::Account.find_by_name("JAB Funds Ltd.")
   a.delete
 
-  # Retrieve all Email Addresses assigned to a particular user.
+  # Retrieve all Email Addresses assigned to a particular User.
   SugarCRM::User.find_by_user_name('sarah').email_addresses
   
-  # Retrieve all email addresses on an Account
+  # Retrieve all Email Addresses on an Account
   SugarCRM::Account.find_by_name("JAB Funds Ltd.").contacts.each do |contact|
     contact.email_addresses.each do |email|
-      puts "#{email.email_address}" unless email.opt_out == "1"
+      puts "#{email.email_address}" unless email.opt_out == true
     end
   end
   
-  # Look up the fields for a given module
-  SugarCRM::Module.find("Accounts").fields
+  # Add a Meeting to a Contact
+  c = SugarCRM::Contact.first
+  c.meetings << SugarCRM::Meeting.new({
+    :name => "Product Introduction", 
+    :date_start => DateTime.now,
+    :duration_hours => 1
+  })
+  c.save!
   
-  # Look up the relationships for a given module
-  SugarCRM::Module.find("Accounts").link_fields
+  # Add a Contact to an Account
+  a = SugarCRM::Account.find_by_name("JAB Funds Ltd.")
+  c = SugarCRM::Contact.new
+  c.last_name = 'Doe'
+  a.contacts << c
+  a.save # or a.contacts.save
   
-  # Use the HTTP Connection and SugarCRM API to load the Admin user
-  SugarCRM.connection.get_entry("Users", 1)
+  # Check if an Account has a specific Contact associated with it
+  c = SugarCRM::Contact.find_by_last_name("Doe")
+  a = SugarCRM::Account.find_by_name("JAB Funds Ltd.")
+  a.contacts.include?(c)
+  
+  # Remove a Contact from an Account
+  c = SugarCRM::Contact.find_by_last_name("Doe")
+  a = SugarCRM::Account.find_by_name("JAB Funds Ltd.")
+  a.contacts.delete(c)
+  a.save # or a.contacts.save
+  
+  # Look up the Case with the smallest case number
+  SugarCRM::Case.first({
+    :order_by => 'case_number'
+  })
   
   # Retrieve the first 10 Accounts with a zip code between 10000 and 10500
   SugarCRM::Account.all({
@@ -83,6 +109,20 @@ e.g. SugarCRM::Contacts.find_by_title("VP of Sales") will work, but SugarCRM::Co
     :limit => '10',
     :order_by => 'billing_address_postalcode'
   })
+  
+  # Retrieve all Accounts with a zip code
+  SugarCRM::Account.all({
+    :conditions => { :billing_address_postalcode => "<> NULL" }
+  })
+  
+  # Look up the fields for a given module
+  SugarCRM::Module.find("Accounts").fields
+  
+  # Look up the relationships for a given module
+  SugarCRM::Module.find("Accounts").link_fields
+  
+  # Use the HTTP Connection and SugarCRM API to load the Admin user
+  SugarCRM.connection.get_entry("Users", 1)
 
   # Retrieve all Accounts by user name (direct API method)
   SugarCRM.connection.get_entry_list(
@@ -101,7 +141,6 @@ e.g. SugarCRM::Contacts.find_by_title("VP of Sales") will work, but SugarCRM::Co
 == REQUIREMENTS:
 
 * >= activesupport 3.0.0 gem
-* json gem
 
 == INSTALL:
 

data/Rakefile

@@ -6,14 +6,11 @@ begin
   Jeweler::Tasks.new do |gem|
     gem.name = "sugarcrm"
     gem.summary = %Q{Ruby based REST client for SugarCRM}
-    gem.description = %Q{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 to provide ActiveRecord style finders and first class
-    objects.  Some of this functionality is included today.}
+    gem.description = %Q{A less clunky way to interact with SugarCRM via REST.  Instead of SugarCRM.connection.get_entry("Users", "1") you could use SugarCRM::User.find(1).  There is support for collections à la SugarCRM::User.find(1).email_addresses, or SugarCRM::Contact.first.meetings << new_meeting.  ActiveRecord style finders are in place, with limited support for conditions and joins.}
     gem.email = "carl.hicks@gmail.com"
     gem.homepage = "http://github.com/chicks/sugarcrm"
     gem.authors = ["Carl Hicks"]
     gem.add_development_dependency "shoulda", ">= 0"
-    gem.add_dependency "json", ">= 0"
     gem.add_dependency "activesupport", ">= 3.0"    
     # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
   end

data/VERSION

@@ -1 +1 @@
-0.8.2
+0.9.0

data/lib/sugarcrm.rb

@@ -1,13 +1,16 @@
+require 'net/https'
 require 'pp'
 require 'set'
+require 'uri'
 require 'rubygems'
 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/attributes'
+require 'sugarcrm/associations'
+require 'sugarcrm/dynamic_finder_match'
 require 'sugarcrm/module'
-require 'sugarcrm/request'
-require 'sugarcrm/response'
+require 'sugarcrm/base'
+

data/lib/sugarcrm/associations.rb

@@ -0,0 +1,2 @@
+require 'sugarcrm/associations/association_methods'
+require 'sugarcrm/associations/association_collection'

data/lib/sugarcrm/associations/association_collection.rb

@@ -0,0 +1,143 @@
+module SugarCRM
+  # A class for handling association collections.  Basically just an extension of Array
+  # doesn't actually load the records from Sugar until you invoke one of the public methods
+  class AssociationCollection
+    include Enumerable
+    
+    # creates a new instance of an AssociationCollection
+    # Owner is the parent object, and association is the target
+    def initialize(owner, association, preload=false)
+      @loaded     = false
+      @owner      = owner
+      @association= association
+      load if preload
+      self
+    end
+    
+    def changed?
+      return false unless loaded?
+      return true if added.length > 0
+      return true if removed.length > 0
+      false
+    end
+    
+    def loaded?
+      @loaded
+    end
+    
+    def load
+      load_associated_records unless loaded?
+    end
+    
+    def reload
+      load_associated_records
+    end
+    
+    def each(&block)
+      load
+      @collection.each(&block)
+    end
+    
+    # we should probably delegate this
+    def length
+      load
+      @collection.length
+    end
+        
+    # return any added elements
+    def added
+      load
+      @collection - @original
+    end
+    
+    # return any removed elements
+    def removed
+      load
+      @original - @collection
+    end
+    
+    # Removes an record from the collection, uses the id of the record as a test for inclusion.
+    def delete(record)
+      load
+      raise InvalidRecord, "#{record.class} does not have a valid :id!" if record.id.empty?
+      @collection.delete record
+    end
+
+    # Checks if a record is included in the current collection.  Uses id's as comparison
+    def include?(record)
+      load
+      @collection.include? record
+    end
+    
+    # Add +records+ to this association, saving any unsaved records before adding them.  
+    # Returns +self+ so method calls may be chained.
+    # Be sure to call save on the association to commit any association changes
+    def <<(record)
+      load
+      record.save! if record.new?
+      result = true
+      result = false if include?(record)
+      @collection << record
+      result && self
+    end
+    alias :add :<<
+    
+    def save
+      begin
+        save!
+      rescue
+        return false
+      end
+    end
+    
+    # Pushes collection changes to SugarCRM, and updates the state of the collection
+    def save!
+      load
+      added.each do |record|
+        associate!(record)
+      end
+      removed.each do |record|
+        disassociate!(record)
+      end
+      @original = @collection.dup
+      @original.freeze
+      true
+    end
+    
+    protected
+    
+    # Loads related records for the given association
+    def load_associated_records
+      array = SugarCRM.connection.get_relationships(@owner.class._module.name, @owner.id, @association.to_s)
+      @loaded = true
+      # we use original to track the state of the collection at start
+      @collection = Array.wrap(array).dup
+      @original   = Array.wrap(array).freeze
+    end  
+    
+    # Creates a relationship between the current object and the target
+    # Owner is the record the Collection is accessed from
+    # Target is the record we are adding to the collection
+    # i.e. user.email_addresses.associate!(EmailAddress.new(:email_address => "abc@abc.com"))
+    # user would be the owner, and EmailAddress.new() is the target
+    def associate!(target, opts={})
+      #target.save! if target.new?
+      response = SugarCRM.connection.set_relationship(
+        @owner.class._module.name, @owner.id, 
+        target.class._module.table_name, [target.id],
+        opts
+      )
+      raise AssociationFailed, 
+        "Couldn't associate #{@owner.class._module.name}: #{@owner.id} -> #{target.class._module.table_name}:#{target.id}!" if response["failed"] > 0
+      true
+    end
+    
+    # Removes a relationship between the current object and the target    
+    def disassociate!(target)
+      associate!(target,{:delete => 1})
+    end
+
+    alias :relate! :associate!
+    
+  end
+end

data/lib/sugarcrm/associations/association_methods.rb

@@ -0,0 +1,92 @@
+module SugarCRM; module AssociationMethods
+  
+  module ClassMethods
+    # Returns an array of the module link fields
+    def associations_from_module_link_fields
+      self._module.link_fields.keys
+    end
+  end
+  
+  attr :association_cache, false
+  
+  def association_cached?(association)
+    @association_cache.keys.include? association.to_sym
+  end
+  
+  def associations_changed?
+    @association_cache.values.each do |collection|
+      return true if collection.changed?
+    end
+    false
+  end
+  
+  protected
+  
+  def save_modified_associations
+    @association_cache.values.each do |collection|
+      if collection.changed?
+        return false unless collection.save
+      end
+    end
+    true
+  end
+  
+  def clear_association_cache
+    @association_cache = {}
+  end
+  
+  # Generates the association proxy methods for related modules
+  def define_association_methods
+    return if association_methods_generated?
+    @associations.each do |k|
+      self.class.module_eval %Q?
+      def #{k}
+        query_association :#{k}
+      end
+      ?
+      #seed_association_cache(k.to_syn)
+    end
+    self.class.association_methods_generated = true
+  end
+  
+#  def seed_association_cache(association)
+#    @association_cache[association] = AssociationCollection.new(self,association)
+#  end
+  
+  # Returns the records from the associated module or returns the cached copy if we've already 
+  # loaded it.  Force a reload of the records with reload=true
+  #
+  #  {"email_addresses"=>
+  #    {"name"=>"email_addresses",
+  #     "module"=>"EmailAddress",
+  #     "bean_name"=>"EmailAddress",
+  #     "relationship"=>"users_email_addresses",
+  #     "type"=>"link"},
+  #
+  def query_association(assoc, reload=false)
+    association = assoc.to_sym
+    return @association_cache[association] if association_cached?(association) && !reload
+    # TODO: Some relationships aren't fetchable via get_relationship (i.e users.contacts)
+    # even though get_module_fields lists them on the related_fields array.  This is most 
+    # commonly seen with one-to-many relationships without a join table.  We need to cook 
+    # up some elegant way to handle this.
+    collection = AssociationCollection.new(self,association,true)
+    # add it to the cache
+    @association_cache[association] = collection
+    collection
+  end
+
+  # Loads related records for the given association
+#  def load_associations_for(association)
+#    SugarCRM.connection.get_relationships(self.class._module.name, self.id, association.to_s)
+#  end
+  
+  # pushes an element to the association collection
+  def append_to_association(association, record)
+    collection = query_association(association)
+    collection << record
+    collection
+  end
+    
+  
+end; end

data/lib/sugarcrm/attributes.rb

@@ -0,0 +1,4 @@
+require 'sugarcrm/attributes/attribute_methods'
+require 'sugarcrm/attributes/attribute_validations'
+require 'sugarcrm/attributes/attribute_serializers'
+require 'sugarcrm/attributes/attribute_typecast'

data/lib/sugarcrm/attributes/attribute_methods.rb

@@ -0,0 +1,131 @@
+module SugarCRM; module AttributeMethods
+
+  module ClassMethods
+    # Returns a hash of the module fields from the module
+    # merges matching keys if another attributes hash is provided
+    def attributes_from_module_fields
+      fields = {}.with_indifferent_access
+      self._module.fields.keys.sort.each do |k|
+        fields[k] = nil
+      end
+      fields
+    end
+  end
+    
+  # TODO: Object.id is not being updated properly.  Figure out why...  
+  alias :pk :id
+  alias :primary_key :id
+  
+  # Determines if attributes or associations have been changed
+  def changed?
+    return true if attributes_changed?
+    return true if associations_changed?
+    false
+  end
+  
+  def attributes_changed?
+    @modified_attributes.length > 0
+  end
+  
+  # Is this a new record?
+  def new?
+    @attributes[:id].blank?
+  end
+  
+  # List the required attributes for save
+  def required_attributes
+    self.class._module.required_fields
+  end
+
+  protected
+  
+  # Merges attributes provided as an argument to initialize
+  # with attributes from the module.fields array.  Skips any
+  # fields that aren't in the module.fields array
+  #
+  # BUG: SugarCRM likes to return fields you don't ask for, and
+  # aren't fields on a module (i.e. modified_user_name).  This 
+  # royally screws up our typecasting code, so we handle it here.
+  def merge_attributes(attrs={})
+    # copy attributes from the parent module fields array
+    @attributes = self.class.attributes_from_module_fields
+    # populate the attributes with values from the attrs provided to init.
+    @attributes.keys.each do |name|
+      write_attribute name, attrs[name] if attrs[name]
+    end
+    # If this is an existing record, blank out the modified_attributes hash
+    @modified_attributes = {} unless new?
+  end
+  
+  # Generates get/set methods for keys in the attributes hash
+  def define_attribute_methods
+    return if attribute_methods_generated?
+    @attributes.keys.sort.each do |k|
+      self.class.module_eval %Q?
+      def #{k}
+        read_attribute :#{k}
+      end
+      def #{k}=(value)
+        write_attribute :#{k},value
+      end
+      ?
+    end
+    self.class.attribute_methods_generated = true
+  end
+
+  # Returns an <tt>#inspect</tt>-like string for the value of the
+  # attribute +attr_name+. String attributes are elided after 50
+  # characters, and Date and Time attributes are returned in the
+  # <tt>:db</tt> format. Other attributes return the value of
+  # <tt>#inspect</tt> without modification.
+  #
+  #   person = Person.create!(:name => "David Heinemeier Hansson " * 3)
+  #
+  #   person.attribute_for_inspect(:name)
+  #   # => '"David Heinemeier Hansson David Heinemeier Hansson D..."'
+  #
+  #   person.attribute_for_inspect(:created_at)
+  #   # => '"2009-01-12 04:48:57"'
+  def attribute_for_inspect(attr_name)
+    value = read_attribute(attr_name)
+    if value.is_a?(String) && value.length > 50
+      "#{value[0..50]}...".inspect
+    elsif value.is_a?(Date) || value.is_a?(Time)
+      %("#{value.to_s(:db)}")
+    else
+      value.inspect
+    end
+  end
+  
+  # Wrapper for invoking save on modified_attributes
+  # sets the id if it's a new record
+  def save_modified_attributes
+    # Complain if we aren't valid
+    raise InvalidRecord, errors.to_a.join(", ") if !valid?
+    # Send the save request
+    response = SugarCRM.connection.set_entry(self.class._module.name, serialize_modified_attributes)
+    # Complain if we don't get a parseable response back
+    raise RecordsaveFailed, "Failed to save record: #{self}.  Response was not a Hash" unless response.is_a? Hash
+    # Complain if we don't get a valid id back
+    raise RecordSaveFailed, "Failed to save record: #{self}.  Response did not contain a valid 'id'." if response["id"].nil?
+    # Save the id to the record, if it's a new record
+    @attributes[:id] = response["id"] if new?
+    raise InvalidRecord, "Failed to update id for: #{self}." if id.nil?
+    # Clear the modified attributes Hash
+    @modified_attributes = {}
+    true
+  end
+
+  # Wrapper around attributes hash
+  def read_attribute(key)
+    @attributes[key]
+  end
+  
+  # Wrapper around attributes hash
+  def write_attribute(key, value)
+    @modified_attributes[key] = { :old => @attributes[key].to_s, :new => value }
+    @attributes[key] = value
+  end
+  
+end; end
+