sugarcrm_emp 0.10.0

data/lib/sugarcrm/associations/association_collection.rb

@@ -0,0 +1,141 @@
+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
+  
+    attr_reader :collection
+    
+    # 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
+     
+    # return any added elements
+    def added
+      load
+      @collection - @original
+    end
+    
+    # return any removed elements
+    def removed
+      load
+      @original - @collection
+    end
+    
+    # Removes a 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
+    alias :remove :delete
+
+    # 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)
+      @owner.update_association_cache_for(@association, record, :add)
+      record.update_association_cache_for(record.associations.find!(@owner).link_field, @owner, :add)
+      result && self
+    end
+    alias :add :<<
+    
+    # delegate undefined methods to the @collection array
+    # E.g. contact.cases should behave like an array and allow `length`, `size`, `each`, etc.
+    def method_missing(method_name, *args, &block)
+      load
+      @collection.send(method_name.to_sym, *args, &block)
+    end
+    
+    # respond correctly for delegated methods
+    def respond_to?(method_name)
+      load
+      return true if @collection.respond_to? method_name
+      super
+    end
+    
+    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
+      reload
+      true
+    end
+    
+    protected
+    
+    # Loads related records for the given association
+    def load_associated_records
+      array = @owner.class.session.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?
+      @owner.associate!(target, opts)
+    end
+    
+    # Removes a relationship between the current object and the target    
+    def disassociate!(target)
+      @owner.associate!(target,{:delete => 1})
+    end
+
+    alias :relate! :associate!
+    
+  end
+end

data/lib/sugarcrm/associations/association_methods.rb

@@ -0,0 +1,91 @@
+module SugarCRM; module AssociationMethods
+
+  module ClassMethods
+  end
+
+  # Saves all modified associations.
+  def save_modified_associations!
+    @association_cache.values.each do |collection|
+      if collection.changed?
+        collection.save!
+      end
+    end
+    true
+  end
+  
+  # Returns the module link fields hash
+  def link_fields
+    self.class._module.link_fields
+  end
+  
+  # Creates a relationship between the current object and the target object
+  # The current and target records will have a relationship set
+  # i.e. account.associate!(contact) would link account and contact
+  # In contrast to using account.contacts << contact, this method doesn't load the relationships
+  # before setting the new relationship.
+  # This method is useful when certain modules have many links to other modules: not loading the
+  # relationships allows one to avoid a Timeout::Error
+  def associate!(target,opts={})
+    targets = Array.wrap(target)
+    targets.each do |t|
+      association = @associations.find!(t)
+      response = self.class.session.connection.set_relationship(
+        self.class._module.name, self.id, 
+        association.link_field, [t.id], opts
+      )
+      if response["failed"] > 0
+        raise AssociationFailed, 
+        "Couldn't associate #{self.class._module.name}: #{self.id} -> #{t}: #{t.id}!" 
+      end
+      # We need to update the association cache for any changes we make.
+      if opts[:delete] == 1
+        update_association_cache_for(association.link_field, t, :delete)
+        t.update_association_cache_for(association.link_field, self, :delete)
+      else
+        update_association_cache_for(association.link_field, t, :add)
+        t.update_association_cache_for(t.associations.find!(self).link_field, self, :add)
+      end
+    end
+    true
+  end
+  alias :relate! :associate!
+    
+  # Removes a relationship between the current object and the target object
+  def disassociate!(target)
+    associate!(target,{:delete => 1})
+  end
+  alias :unrelate! :disassociate!
+    
+  protected
+
+  # Generates the association proxy methods for related modules
+  def define_association_methods
+    @associations = Associations.register(self)
+    return if association_methods_generated?
+    self.class.association_methods_generated = true
+  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
+
+end; end

data/lib/sugarcrm/associations/associations.rb

@@ -0,0 +1,61 @@
+module SugarCRM
+  # Holds all the associations for a given class
+  class Associations
+    # Returns an array of Association objects
+    class << self
+      def register(owner)
+        associations = Associations.new
+        owner.link_fields.each_key do |link_field|
+          associations << Association.new(owner,link_field)
+        end
+        associations
+      end
+    end
+    
+    attr :associations
+    
+    def initialize
+      @associations = Set.new
+      self
+    end
+    
+    # Returns the proxy methods of all the associations in the collection
+    def proxy_methods
+      @associations.inject([]) { |pm,a|
+        pm = pm | a.proxy_methods
+      } 
+    end
+    
+    # Looks up an association by object, link_field, or method.
+    # Raises an exception if not found
+    def find!(target)
+      @associations.each do |a|
+        return a if a.include? target
+      end
+      raise InvalidAssociation, "Could not lookup association for: #{target}"
+    end
+
+    # Looks up an association by object, link_field, or method.
+    # Returns false if not found
+    def find(association)
+      begin
+        find!(association)
+      rescue InvalidAssociation
+        false
+      end
+    end
+    alias :include? :find
+          
+    # delegate undefined methods to the @collection array
+    # E.g. contact.cases should behave like an array and allow `length`, `size`, `each`, etc.
+    def method_missing(method_name, *args, &block)
+      @associations.send(method_name.to_sym, *args, &block)
+    end
+    
+    # respond correctly for delegated methods
+    def respond_to?(method_name)
+      return true if @associations.respond_to? method_name
+      super
+    end
+  end
+end

data/lib/sugarcrm/associations.rb

@@ -0,0 +1,5 @@
+require 'sugarcrm/associations/association'
+require 'sugarcrm/associations/associations'
+require 'sugarcrm/associations/association_cache'
+require 'sugarcrm/associations/association_methods'
+require 'sugarcrm/associations/association_collection'

data/lib/sugarcrm/attributes/attribute_methods.rb

@@ -0,0 +1,203 @@
+module SugarCRM; module AttributeMethods
+
+  module ClassMethods
+    # Returns a hash of the module fields from the module
+    def attributes_from_module
+      fields = {}.with_indifferent_access
+      self._module.fields.keys.sort.each do |k|
+        fields[k] = nil
+      end
+      fields
+    end
+    # Returns the table name for a given attribute
+    def table_name_for(attribute)
+      table_name = self._module.table_name
+      if attribute.to_s =~ /_c$/
+        table_name = self._module.custom_table_name
+      end
+      table_name
+    end
+    # Takes a condition like: [:zip, ["> 75000", "< 80000"]]
+    # and flattens it to: ["accounts.zip > 75000", "accounts.zip < 80000"]
+    def flatten_conditions_for(condition)
+      conditions = []
+      attribute, attribute_conditions = condition
+      # Make sure we wrap the attribute condition in an array for EZ handling...
+      Array.wrap(attribute_conditions).each do |attribute_condition| 
+        # parse operator in cases where: 
+        #   :attribute => '>= some_value', 
+        #   :attribute => "LIKE '%value%'", 
+        # fallback to '=' operator as default]
+        operator = attribute_condition.to_s[/^([!<>=]*(LIKE|IS|NOT|\s)*)(.*)$/,1].strip!
+        # Default to = if we can't resolve the condition.
+        operator ||= '=' 
+        # Extract value from query
+        value = $3
+        unless attribute_condition.class == FalseClass
+          if attribute_condition.class == TrueClass
+            # fix value for checkboxes: users can pass true as condition, should be converted to '1' (false case for checkboxes is treated separately below)
+            value = (attribute_condition.class == TrueClass ? '1' : '0')
+          end
+          
+          # TODO: Write a test for sending invalid attribute names.  
+          # strip single quotes
+          value = value.strip[/'?([^']*)'?/,1] 
+          conditions << "#{table_name_for(attribute)}.#{attribute} #{operator} \'#{value}\'"
+        else
+          # When a user creates a custom checkbox field, a column is added to the *_cstm table for that module (e.g. contacts_cstm for Contacts module).
+          # Each time a new record is created, the value of the checkbox will be stored in that _cstm table.
+          # However, records that exsited before that field was created are absent from the _cstm table.
+          # To return the expected results when a user is searching for records with an unchecked checkbox, we must return all records that aren't present in
+          # the _cstm table with a value of 1 (returning the record with 0 in the table will ignore the pre-existing records).
+          # Here, we create the appropriate query that will return all records that don't have a value of "true" in the checkbox field.
+          conditions << "#{self._module.table_name}.id NOT IN (SELECT id_c FROM #{table_name_for(attribute)} WHERE #{table_name_for(attribute)}.#{attribute} #{operator} 1)"
+        end
+      end
+      conditions
+    end
+  end
+    
+  # Determines if attributes or associations have been changed
+  def changed?
+    return true if attributes_changed?
+    return true if associations_changed?
+    false
+  end
+  
+  def destroyed?
+    @attributes[:deleted]
+  end
+  
+  def attributes_changed?
+    @modified_attributes.length > 0
+  end
+  
+  # Is this a new record?
+  def new?
+    @attributes[:id].blank?
+  end
+  alias :new_record? :new?
+  
+  # List the required attributes for save
+  def required_attributes
+    self.class._module.required_fields
+  end
+  alias :required_fields :required_attributes
+  
+  def to_model
+    self
+  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
+    # 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
+      def #{k}\?
+        has_attribute\? :#{k}
+      end
+      ?
+    end
+    
+    # return the (polymorphic) parent record corresponding to the parent_id and parent_type attributes
+    # (an example of parent polymorphism can be found in the Note module)
+    if (@attributes.keys.include? 'parent_id') && (@attributes.keys.include? 'parent_type')
+      self.class.module_eval %Q?
+      def parent
+        (self.class.session.namespace_const.const_get @attributes['parent_type'].singularize).find(@attributes['parent_id'])
+      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!(opts={})
+    options = { :validate => true }.merge(opts)
+    if options[:validate]
+      # Complain if we aren't valid
+      raise InvalidRecord, @errors.full_messages.join(", ") unless valid?
+    end
+    # Send the save request
+    response = self.class.session.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
+  
+  def has_attribute?(key)
+    @attributes.has_key? key
+  end
+  
+end; end
+  

data/lib/sugarcrm/attributes/attribute_serializers.rb

@@ -0,0 +1,55 @@
+module SugarCRM; module AttributeSerializers
+  
+  protected
+    
+  # Serializes the id
+  def serialize_id
+    {:name => "id", :value => id.to_s}
+  end
+
+  # Converts the attributes hash into format recognizable by Sugar
+  # { :last_name => "Smith"} 
+  # becomes
+  # { :last_name => {:name => "last_name", :value => "Smith"}}
+  def serialize_attributes
+    attr_hash = {}
+    @attributes.each_pair do |name,value|
+      attr_hash[name] = serialize_attribute(name,value)
+    end
+    attr_hash[:id] = serialize_id unless new?
+    attr_hash
+  end
+
+  # Converts the modified_attributes hash into format recognizable by Sugar
+  # {:last_name => {:old => "Smit", :new => "Smith"}} 
+  # becomes
+  # {:last_name => {:name => "last_name", :value => "Smith"}}  
+  def serialize_modified_attributes
+    attr_hash = {}
+    @modified_attributes.each_pair do |name,hash|
+      attr_hash[name] = serialize_attribute(name,hash[:new])
+    end
+    attr_hash[:id] = serialize_id unless new?
+    attr_hash
+  end
+  
+  # Un-typecasts the attribute - false becomes "0", 5234 becomes "5234", etc.
+  def serialize_attribute(name,value)
+    attr_value = value
+    attr_type  = attr_type_for(name) 
+    case attr_type
+    when :bool
+      attr_value = 0
+      attr_value = 1 if value
+    when :datetime, :datetimecombo
+      begin
+        attr_value = value.strftime("%Y-%m-%d %H:%M:%S")
+      rescue
+        attr_value = value
+      end
+    when :int
+      attr_value = value.to_s
+    end
+    {:name => name, :value => attr_value}
+  end
+end; end

data/lib/sugarcrm/attributes/attribute_typecast.rb

@@ -0,0 +1,44 @@
+module SugarCRM; module AttributeTypeCast
+
+  protected
+  
+  # Returns the attribute type for a given attribute
+  def attr_type_for(attribute)
+    fields = self.class._module.fields
+    field  = fields[attribute]
+    raise UninitializedModule, "#{self.class.session.namespace_const}Module #{self.class._module.name} was not initialized properly (fields.length == 0)" if fields.length == 0
+    raise InvalidAttribute, "#{self.class}._module.fields does not contain an entry for #{attribute} (of type: #{attribute.class})\nValid fields: #{self.class._module.fields.keys.sort.join(", ")}" if field.nil?
+    raise InvalidAttributeType, "#{self.class}._module.fields[#{attribute}] does not have a key for \'type\'" if field["type"].nil?
+    field["type"].to_sym
+  end
+
+  # Attempts to typecast each attribute based on the module field type
+  def typecast_attributes
+    @attributes.each_pair do |name,value|
+      # skip primary key columns
+      next if name == "id"
+      attr_type = attr_type_for(name)
+      
+      # empty attributes should stay empty (e.g. an empty int field shouldn't be typecast as 0)
+      if [:datetime, :datetimecombo, :int].include? attr_type && (value.nil? || value == '')
+        @attributes[name] = nil
+        next
+      end
+      
+      case attr_type
+      when :bool
+        @attributes[name] = (value == "1")
+      when :datetime, :datetimecombo
+        begin
+          @attributes[name] = DateTime.parse(value)
+        rescue
+          @attributes[name] = value
+        end
+      when :int
+        @attributes[name] = value.to_i
+      end
+    end
+    @attributes
+  end
+
+end; end

data/lib/sugarcrm/attributes/attribute_validations.rb

@@ -0,0 +1,62 @@
+module SugarCRM; module AttributeValidations
+  # Checks to see if we have all the neccessary attributes
+  def valid?
+    @errors = (defined?(HashWithIndifferentAccess) ? HashWithIndifferentAccess : ActiveSupport::HashWithIndifferentAccess).new
+    
+    self.class._module.required_fields.each do |attribute|
+      valid_attribute?(attribute)
+    end
+    
+    # for rails compatibility
+    def @errors.full_messages
+      # After removing attributes without errors, flatten the error hash, repeating the name of the attribute before each message:
+      # e.g. {'name' => ['cannot be blank', 'is too long'], 'website' => ['is not valid']}
+      # will become 'name cannot be blank, name is too long, website is not valid
+      self.inject([]){|memo, obj| memo.concat(obj[1].inject([]){|m, o| m << "#{obj[0].to_s.humanize} #{o}" })}
+    end
+    
+    # Rails needs each attribute to be present in the error hash (if the attribute has no error, it has [] as a value)
+    # Redefine the [] method for the errors hash to return [] instead of nil is the hash doesn't contain the key
+    class << @errors
+      alias :old_key_lookup :[]
+      def [](key)
+        old_key_lookup(key) || Array.new
+      end
+    end
+    
+    @errors.size == 0
+  end
+  
+  protected
+  
+  # TODO: Add test cases for validations
+  def valid_attribute?(attribute)
+    case attr_type_for(attribute)
+    when :bool
+      validate_class_for(attribute, [TrueClass, FalseClass])
+    when :datetime, :datetimecombo
+      validate_class_for(attribute, [DateTime])
+    when :int
+      validate_class_for(attribute, [Fixnum, Float])
+    else 
+      if @attributes[attribute].blank?
+        add_error(attribute, "cannot be blank")
+      end
+    end
+  end
+  
+  # Compares the class of the attribute with the class or classes provided in the class array
+  # returns true if they match, otherwise adds an entry to the @errors collection, and returns false
+  def validate_class_for(attribute, class_array)
+    return true if class_array.include? @attributes[attribute].class
+    add_error(attribute, "must be a #{class_array.join(" or ")} object (not #{@attributes[attribute].class})")
+    false  
+  end
+  
+  # Add an error to the hash
+  def add_error(attribute, message)
+    @errors[attribute] ||= []
+    @errors[attribute] = @errors[attribute] << message unless @errors[attribute].include? message
+    @errors
+  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'