active_force 0.6.1 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: f78cd5f272f46a14d23431270acbfa2d6b8226b3
-  data.tar.gz: e38b5c4f75717978e8862e974a0f8464b52fc1cb
+  metadata.gz: f65b3ee4d09a2cc85b6ff35e563104b90e35ef2e
+  data.tar.gz: 865295aff9ee4dfc2962fa13225d41041f3100d1
 SHA512:
-  metadata.gz: 3953499253bd6e0adbb2b5f9aaf8dc1a2d33d3b08048284b2f4e517954870ae48f83694fb6e4243b1c3d98c3375f2238ad238f420c523ebea65306f64dafa329
-  data.tar.gz: 4cf78d28885b7b7562c6f21a1f457680d2006709f3b2f8ea89c5ee4ed9c72b5f7f74843cd7ccdd35a82e661687263cfa284d1df14c5f9eb3a68caf52adb97082
+  metadata.gz: 54eac72eb1033454434c97b997810587004df5655134574a445f8826318c69eda74783f2a902bd75cffe4addd88a41b49b93451029284d2002ca4c2928c3c988
+  data.tar.gz: 509928a1158a20cb8122efa37d98e893bf762ad1b9cf7329f35cf68ffed269fcd738a4613357bf4ec3830e86cffa6002b9d153baf6689356f555f5836f9b0248

data/CHANGELOG.md

@@ -1,6 +1,9 @@
 # Changelog
 
 ## Not released
+* Rails4-style conditional has_many associations  ([Dan Olson][])
+* Add `#includes` query method to eager load has_many association.  ([Dan Olson][])
+* Add `#includes` query method to eager load belongs_to association. ([#65][])
 * SObject#destroy method.
 
 ## 0.6.1
@@ -72,11 +75,15 @@
 [#14]: https://github.com/ionia-corporation/active_force/issues/14
 [#15]: https://github.com/ionia-corporation/active_force/issues/15
 [#19]: https://github.com/ionia-corporation/active_force/issues/19
+[#20]: https://github.com/ionia-corporation/active_force/issues/20
 [#21]: https://github.com/ionia-corporation/active_force/issues/21
 [#24]: https://github.com/ionia-corporation/active_force/issues/24
 [#26]: https://github.com/ionia-corporation/active_force/issues/26
 [#28]: https://github.com/ionia-corporation/active_force/issues/28
+[#29]: https://github.com/ionia-corporation/active_force/issues/29
 [#30]: https://github.com/ionia-corporation/active_force/issues/30
+[#33]: https://github.com/ionia-corporation/active_force/issues/33
+[#65]: https://github.com/ionia-corporation/active_force/issues/65
 [Pablo Oldani]: https://github.com/olvap
 [Armando Andini]: https://github.com/antico5
 [José Piccioni]: https://github.com/lmhsjackson

data/README.md

@@ -3,6 +3,7 @@
 [![Code Climate](http://img.shields.io/codeclimate/github/ionia-corporation/active_force.svg)](https://codeclimate.com/github/ionia-corporation/active_force)
 [![Dependency Status](http://img.shields.io/gemnasium/ionia-corporation/active_force.svg)](https://gemnasium.com/ionia-corporation/active_force)
 [![Test Coverage](https://codeclimate.com/github/ionia-corporation/active_force/badges/coverage.svg)](https://codeclimate.com/github/ionia-corporation/active_force)
+[![Inline docs](http://inch-ci.org/github/ionia-corporation/active_force.png?branch=master)](http://inch-ci.org/github/ionia-corporation/active_force)
 [![Chat](http://img.shields.io/badge/chat-gitter-brightgreen.svg)](https://gitter.im/ionia-corporation/active_force)
 
 # ActiveForce
@@ -10,9 +11,6 @@
 A ruby gem to interact with [SalesForce][1] as if it were Active Record. It
 uses [Restforce][2] to interact with the API, so it is fast and stable.
 
- [1]: http://www.salesforce.com
- [2]: https://github.com/ejholmes/restforce
-
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -27,12 +25,18 @@ Or install it yourself as:
 
     $ gem install active_force
 
-If you want restforce logging on a rails app:
+## Setup credentials
 
-```ruby
-#Add this to initializers/restforce.rb
-Restforce.log = true if Rails.env.development?
-```
+[Restforce][2] is used to interact with the API, so you will need to setup
+environment variables to set up credentials.
+
+    SALESFORCE_USERNAME       = your-email@gmail.com
+    SALESFORCE_PASSWORD       = your-sfdc-password
+    SALESFORCE_SECURITY_TOKEN = security-token
+    SALESFORCE_CLIENT_ID      = your-client-id
+    SALESFORCE_CLIENT_SECRET  = your-client-secret
+
+You might be interested in [dotenv-rails][3] to set up those in development.
 
 ## Usage
 
@@ -41,11 +45,11 @@ class Medication < ActiveForce::SObject
 
   field :name,             from: 'Name'
 
-  field :max_dossage  # from defaults to "Max_Dossage__c" 
+  field :max_dossage  # defaults to "Max_Dossage__c"
   field :updated_from
 
   ##
-  # Table name is infered from class name.
+  # Table name is inferred from class name.
   #
   # self.table_name = 'Medication__c' # default one.
 
@@ -78,7 +82,7 @@ Altenative you can try the generator. (requires setting up the connection)
 
     rails generate active_force_model Medication__c
 
-### Relationships
+### Associations
 
 #### Has Many
 
@@ -86,19 +90,17 @@ Altenative you can try the generator. (requires setting up the connection)
 class Account < ActiveForce::SObject
   has_many :pages
 
-  # Use option parameters in the declaration.
+  # Use optional parameters in the declaration.
 
   has_many :medications,
-    where: "Discontinued__c > #{ Date.today.strftime("%Y-%m-%d") }" \
-           "OR Discontinued__c = NULL"
+    scoped_as: ->{ where("Discontinued__c > ? OR Discontinued__c = ?", Date.today.strftime("%Y-%m-%d"), nil) }
 
   has_many :today_log_entries,
     model: DailyLogEntry,
-    where: { date: Time.now.in_time_zone.strftime("%Y-%m-%d") }
+    scoped_as: ->{ where(date: Time.now.in_time_zone.strftime("%Y-%m-%d") }
 
   has_many :labs,
-    where: "Category__c = 'EMR' AND Date__c <> NULL",
-    order: 'Date__c DESC'
+    scoped_as: ->{ where("Category__c = 'EMR' AND Date__c <> NULL").order('Date__c DESC') }
 
 end
 ```
@@ -113,6 +115,25 @@ class Page < ActiveForce::SObject
 end
 ```
 
+### Querying
+
+You can retrieve SObject from the database using chained conditions to build
+the query.
+
+```ruby
+Account.where(web_enable: 1, contact_by: ['web', 'email']).limit(2)
+#=> this will query "SELECT Id, Name, WebEnable__c
+#                    FROM Account
+#                    WHERE WebEnable__C = 1 AND ContactBy__c IN ('web','email')
+#                    LIMIT 2
+```
+
+It is also possible to eager load associations:
+
+```ruby
+Comment.includes(:post)
+```
+
 ### Model generator
 
 When using rails, you can generate a model with all the fields you have on your SFDC table by running:
@@ -128,3 +149,8 @@ When using rails, you can generate a model with all the fields you have on your
 5. Create new pull request so we can talk about it.
 6. Once accepted, please add an entry in the CHANGELOG and rebase your changes
    to squash typos or corrections.
+
+ [1]: http://www.salesforce.com
+ [2]: https://github.com/ejholmes/restforce
+ [3]: https://github.com/bkeepers/dotenv
+

data/lib/active_attr/dirty.rb

@@ -17,5 +17,8 @@ module ActiveAttr
       end
     end
 
+    def attributes_and_changes
+      attributes.select{ |attr, key| changed.include? attr }
+    end
   end
 end

data/lib/active_force/active_query.rb

@@ -48,6 +48,14 @@ module ActiveForce
       where(conditions).limit 1
     end
 
+    def includes(*relations)
+      relations.each do |relation|
+        association = sobject.associations[relation]
+        fields Association::EagerLoadProjectionBuilder.build association
+      end
+      self
+    end
+
     private
 
     def build_condition(args, other=[])
@@ -98,14 +106,31 @@ module ActiveForce
 
     def build_conditions_from_hash(hash)
       hash.map do |key, value|
-        "#{mappings[key]} = #{enclose_value value}"
+        applicable_predicate mappings[key], value
+      end
+    end
+
+    def applicable_predicate(attribute, value)
+      if value.is_a? Array
+        in_predicate attribute, value
+      else
+        eq_predicate attribute, value
       end
     end
 
+    def in_predicate(attribute, values)
+      escaped_values = values.map &method(:enclose_value)
+      "#{attribute} IN (#{escaped_values.join(',')})"
+    end
+
+    def eq_predicate(attribute, value)
+      "#{attribute} = #{enclose_value value}"
+    end
+
     def enclose_value value
       case value
       when String
-        "'#{value}'"
+        "'#{quote_string(value)}'"
       when NilClass
         'NULL'
       else
@@ -113,6 +138,11 @@ module ActiveForce
       end
     end
 
+    def quote_string(s)
+      # From activerecord/lib/active_record/connection_adapters/abstract/quoting.rb, version 4.1.5, line 82
+      s.gsub(/\\/, '\&\&').gsub(/'/, "''")
+    end
+
     def result
       sfdc_client.query(self.to_s)
     end

data/lib/active_force/association.rb

@@ -1,24 +1,28 @@
 require 'active_force/association/association'
+require 'active_force/association/eager_load_projection_builder'
+require 'active_force/association/relation_model_builder'
 require 'active_force/association/has_many_association'
 require 'active_force/association/belongs_to_association'
 
 module ActiveForce
   module Association
-    module ClassMethods
-
-      def has_many relation_name, options = {}
-        HasManyAssociation.new(self, relation_name, options)
-      end
+    def associations
+      @associations ||= {}
+    end
 
-      def belongs_to relation_name, options = {}
-        BelongsToAssociation.new(self, relation_name, options)
+    # i.e name = 'Quota__r'
+    def find_association name
+      associations.values.detect do |association|
+        association.represents_sfdc_table? name
       end
-
     end
 
-    def self.included mod
-      mod.extend ClassMethods
+    def has_many relation_name, options = {}
+      associations[relation_name] = HasManyAssociation.new(self, relation_name, options)
     end
 
+    def belongs_to relation_name, options = {}
+      associations[relation_name] = BelongsToAssociation.new(self, relation_name, options)
+    end
   end
 end

data/lib/active_force/association/association.rb

@@ -1,32 +1,47 @@
 module ActiveForce
   module Association
     class Association
+      extend Forwardable
+      def_delegators :relation_model, :build
 
-      attr_accessor :options
+      attr_accessor :options, :relation_name
 
-      def initialize parent, relation_name, options
-        @parent = parent
+      def initialize parent, relation_name, options = {}
+        @parent        = parent
         @relation_name = relation_name
-        @options = options
-        build
+        @options       = options
+        define_relation_method
       end
 
       def relation_model
-        @options[:model] || @relation_name.to_s.singularize.camelcase.constantize
+        options[:model] || relation_name.to_s.singularize.camelcase.constantize
       end
 
       def foreign_key
-        @options[:foreign_key] || default_foreign_key
+        options[:foreign_key] || default_foreign_key
       end
 
-      private
+      def relationship_name
+        options[:relationship_name] || relation_model.table_name
+      end
 
-      def build
-        define_relation_method
+      ###
+      # Does this association's relation_model represent
+      # +sfdc_table_name+? Examples of +sfdc_table_name+
+      # could be 'Quota__r' or 'Account'.
+      def represents_sfdc_table?(sfdc_table_name)
+        name = sfdc_table_name.sub(/__r\z/, '').singularize
+        relationship_name.sub(/__c\z|__r\z/, '') == name
       end
 
+      def sfdc_association_field
+        relationship_name.gsub /__c\z/, '__r'
+      end
+
+      private
+
       def infer_foreign_key_from_model(model)
-        name = model.custom_table_name? ? model.name : model.table_name
+        name = model.custom_table? ? model.name : model.table_name
         "#{name.downcase}_id".to_sym
       end
     end

data/lib/active_force/association/belongs_to_association.rb

@@ -1,8 +1,6 @@
 module ActiveForce
   module Association
-
     class BelongsToAssociation < Association
-
       private
 
       def default_foreign_key
@@ -19,11 +17,10 @@ module ActiveForce
         end
 
         @parent.send :define_method, "#{_method}=" do |other|
-          send "#{ association.foreign_key }=", other.id
+          send "#{ association.foreign_key }=", other.nil? ? nil : other.id
           association_cache[_method] = other
         end
       end
     end
-
   end
 end

data/lib/active_force/association/eager_load_projection_builder.rb

@@ -0,0 +1,60 @@
+module ActiveForce
+  module Association
+    class EagerLoadProjectionBuilder
+      class << self
+        def build(association)
+          new(association).projections
+        end
+      end
+
+      attr_reader :association
+
+      def initialize(association)
+        @association = association
+      end
+
+      def projections
+        klass = association.class.name.split('::').last
+        builder_class = ActiveForce::Association.const_get "#{klass}ProjectionBuilder"
+        builder_class.new(association).projections
+      rescue NameError
+        raise "Don't know how to build projections for #{klass}"
+      end
+    end
+
+    class AbstractProjectionBuilder
+      attr_reader :association
+
+      def initialize(association)
+        @association = association
+      end
+
+      def projections
+        raise "Must define #{self.class.name}#projections"
+      end
+    end
+
+    class HasManyAssociationProjectionBuilder < AbstractProjectionBuilder
+      ###
+      # Use ActiveForce::Query to build a subquery for the SFDC
+      # relationship name. Per SFDC convention, the name needs
+      # to be pluralized
+      def projections
+        match = association.sfdc_association_field.match /__r\z/
+        # pluralize the table name, and append '__r' if it was there to begin with
+        relationship_name = association.sfdc_association_field.sub(match.to_s, '').pluralize + match.to_s
+        query = Query.new relationship_name
+        query.fields association.relation_model.fields
+        ["(#{query.to_s})"]
+      end
+    end
+
+    class BelongsToAssociationProjectionBuilder < AbstractProjectionBuilder
+      def projections
+        association.relation_model.fields.map do |field|
+          "#{ association.sfdc_association_field }.#{ field }"
+        end
+      end
+    end
+  end
+end

data/lib/active_force/association/has_many_association.rb

@@ -1,7 +1,6 @@
 module ActiveForce
   module Association
     class HasManyAssociation < Association
-
       private
 
       def default_foreign_key
@@ -10,13 +9,24 @@ module ActiveForce
 
       def define_relation_method
         association = self
-        @parent.send :define_method, @relation_name do
-          association_cache.fetch __method__ do
+        _method = @relation_name
+        @parent.send :define_method, _method do
+          association_cache.fetch _method do
             query = association.relation_model.query
-            query.options association.options
-            association_cache[__method__] = query.where association.foreign_key => self.id
+            if scope = association.options[:scoped_as]
+              if scope.arity > 0
+                query.instance_exec self, &scope
+              else
+                query.instance_exec &scope
+              end
+            end
+            association_cache[_method] = query.where association.foreign_key => self.id
           end
         end
+
+        @parent.send :define_method, "#{_method}=" do |associated|
+          association_cache[_method] = associated
+        end
       end
     end
   end